Stefano Rivera  committed 565fba5

Document configuration environment variables

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

  • Participants
  • Parent commits ad27050

Comments (0)

Files changed (7)

File pypy/doc/Makefile

 	      "run these through (pdf)latex."
+	python config/
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man"

File pypy/doc/commandline_ref.rst

+Command line reference
+Manual pages
+.. toctree::
+   :maxdepth: 1
+   man/pypy.1.rst

File pypy/doc/config/translation.log.txt

 These must be enabled by setting the PYPYLOG environment variable.
 The exact set of features supported by PYPYLOG is described in

File pypy/doc/garbage_collection.rst

 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:
   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

File pypy/doc/gc_info.rst

+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).

File pypy/doc/index.rst

+   commandline_ref.rst
+   gc_info.rst

File pypy/doc/man/pypy.1.rst

     Do not ``import site`` on initialization.
+    Don't add the user site directory to `sys.path`.
     Unbuffered binary ``stdout`` and ``stderr``.
     Ignore environment variables (such as ``PYTHONPATH``).
+    Disable writing bytecode (``.pyc``) files.
     Print the PyPy version.
         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