[pypy-commit] pypy default: Document configuration environment variables

stefanor noreply at buildbot.pypy.org
Mon Feb 6 12:58:01 CET 2012

Author: Stefano Rivera <stefano at rivera.za.net>
Changeset: r52134:565fba5a3441
Date: 2012-02-06 13:57 +0200

Log:	Document configuration environment variables

	Add gc_info.rst, documenting minimark's configuration variables,
	link into tree. Add cpython compatibility variables to the pypy
	manpage. Add missing command line options to the pypy manpage. Link
	the manpage into the document tree.

diff --git a/pypy/doc/Makefile b/pypy/doc/Makefile
--- a/pypy/doc/Makefile
+++ b/pypy/doc/Makefile
@@ -81,6 +81,7 @@
 	      "run these through (pdf)latex."
+	python config/generate.py
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man"
diff --git a/pypy/doc/commandline_ref.rst b/pypy/doc/commandline_ref.rst
new file mode 100644
--- /dev/null
+++ b/pypy/doc/commandline_ref.rst
@@ -0,0 +1,10 @@
+Command line reference
+Manual pages
+.. toctree::
+   :maxdepth: 1
+   man/pypy.1.rst
diff --git a/pypy/doc/config/translation.log.txt b/pypy/doc/config/translation.log.txt
--- a/pypy/doc/config/translation.log.txt
+++ b/pypy/doc/config/translation.log.txt
@@ -2,4 +2,4 @@
 These must be enabled by setting the PYPYLOG environment variable.
 The exact set of features supported by PYPYLOG is described in
diff --git a/pypy/doc/garbage_collection.rst b/pypy/doc/garbage_collection.rst
--- a/pypy/doc/garbage_collection.rst
+++ b/pypy/doc/garbage_collection.rst
@@ -142,10 +142,9 @@
 So as a first approximation, when compared to the Hybrid GC, the
 Minimark GC saves one word of memory per old object.
-There are a number of environment variables that can be tweaked to
-influence the GC.  (Their default value should be ok for most usages.)
-You can read more about them at the start of
+There are :ref:`a number of environment variables
+<minimark-environment-variables>` that can be tweaked to influence the
+GC.  (Their default value should be ok for most usages.)
 In more detail:
@@ -211,5 +210,4 @@
   are preserved.  If the object dies then the pre-reserved location
   becomes free garbage, to be collected at the next major collection.
 .. include:: _ref.txt
diff --git a/pypy/doc/gc_info.rst b/pypy/doc/gc_info.rst
new file mode 100644
--- /dev/null
+++ b/pypy/doc/gc_info.rst
@@ -0,0 +1,53 @@
+Garbage collector configuration
+.. _minimark-environment-variables:
+PyPy's default ``minimark`` garbage collector is configurable through
+several environment variables:
+    The nursery size.
+    Defaults to ``4MB``.
+    Small values (like 1 or 1KB) are useful for debugging.
+    Major collection memory factor.
+    Default is ``1.82``, which means trigger a major collection when the
+    memory consumed equals 1.82 times the memory really used at the end
+    of the previous major collection.
+    Major collection threshold's max growth rate.
+    Default is ``1.4``.
+    Useful to collect more often than normally on sudden memory growth,
+    e.g. when there is a temporary peak in memory usage.
+    The max heap size.
+    If coming near this limit, it will first collect more often, then
+    raise an RPython MemoryError, and if that is not enough, crash the
+    program with a fatal error.
+    Try values like ``1.6GB``.
+    The major collection threshold will never be set to more than
+    ``PYPY_GC_MAX_DELTA`` the amount really used after a collection.
+    Defaults to 1/8th of the total RAM size (which is constrained to be
+    at most 2/3/4GB on 32-bit systems).
+    Try values like ``200MB``.
+    Don't collect while the memory size is below this limit.
+    Useful to avoid spending all the time in the GC in very small
+    programs.
+    Defaults to 8 times the nursery.
+    Enable extra checks around collections that are too slow for normal
+    use.
+    Values are ``0`` (off), ``1`` (on major collections) or ``2`` (also
+    on minor collections).
diff --git a/pypy/doc/index.rst b/pypy/doc/index.rst
--- a/pypy/doc/index.rst
+++ b/pypy/doc/index.rst
@@ -353,10 +353,12 @@
+   commandline_ref.rst
+   gc_info.rst
diff --git a/pypy/doc/man/pypy.1.rst b/pypy/doc/man/pypy.1.rst
--- a/pypy/doc/man/pypy.1.rst
+++ b/pypy/doc/man/pypy.1.rst
@@ -24,6 +24,9 @@
     Do not ``import site`` on initialization.
+    Don't add the user site directory to `sys.path`.
     Unbuffered binary ``stdout`` and ``stderr``.
@@ -39,6 +42,9 @@
     Ignore environment variables (such as ``PYTHONPATH``).
+    Disable writing bytecode (``.pyc``) files.
     Print the PyPy version.
@@ -84,6 +90,64 @@
         Optimizations to enabled or ``all``.
         Warning, this option is dangerous, and should be avoided.
+    Add directories to pypy's module search path.
+    The format is the same as shell's ``PATH``.
+    A script referenced by this variable will be executed before the
+    first prompt is displayed, in interactive mode.
+    If set to a non-empty value, equivalent to the ``-B`` option.
+    Disable writing ``.pyc`` files.
+    If set to a non-empty value, equivalent to the ``-i`` option.
+    Inspect interactively after running the specified script.
+    If this is set, it overrides the encoding used for
+    *stdin*/*stdout*/*stderr*.
+    The syntax is *encodingname*:*errorhandler*
+    The *errorhandler* part is optional and has the same meaning as in
+    `str.encode`.
+    If set to a non-empty value, equivalent to the ``-s`` option.
+    Don't add the user site directory to `sys.path`.
+    If set, equivalent to the ``-W`` option (warning control).
+    The value should be a comma-separated list of ``-W`` parameters.
+    If set to a non-empty value, enable logging, the format is:
+    *fname*
+        logging for profiling: includes all
+        ``debug_start``/``debug_stop`` but not any nested
+        ``debug_print``.
+        *fname* can be ``-`` to log to *stderr*.
+    ``:``\ *fname*
+        Full logging, including ``debug_print``.
+    *prefix*\ ``:``\ *fname*
+        Conditional logging.
+        Multiple prefixes can be specified, comma-separated.
+        Only sections whose name match the prefix will be logged.
+    ``PYPYLOG``\ =\ ``jit-log-opt,jit-backend:``\ *logfile* will
+    generate a log suitable for *jitviewer*, a tool for debugging
+    performance issues under PyPy.
+.. include:: ../gc_info.rst
+   :start-line: 5

More information about the pypy-commit mailing list