Stefano Rivera avatar Stefano Rivera committed 565fba5

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.

Comments (0)

Files changed (7)

pypy/doc/Makefile

 	      "run these through (pdf)latex."
 
 man:
+	python config/generate.py
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man"

pypy/doc/commandline_ref.rst

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

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
-pypy/translation/c/src/debug.h.
+pypy/translation/c/src/debug_print.h.

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
-`pypy/rpython/memory/gc/minimark.py`_.
+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

pypy/doc/gc_info.rst

+Garbage collector configuration
+===============================
+
+.. _minimark-environment-variables:
+
+Minimark
+--------
+
+PyPy's default ``minimark`` garbage collector is configurable through
+several environment variables:
+
+``PYPY_GC_NURSERY``
+    The nursery size.
+    Defaults to ``4MB``.
+    Small values (like 1 or 1KB) are useful for debugging.
+
+``PYPY_GC_MAJOR_COLLECT``
+    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.
+
+``PYPY_GC_GROWTH``
+    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.
+
+``PYPY_GC_MAX``
+    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``.
+
+``PYPY_GC_MAX_DELTA``
+    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``.
+
+``PYPY_GC_MIN``
+    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.
+
+``PYPY_GC_DEBUG``
+    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).

pypy/doc/index.rst

    getting-started-dev.rst
    windows.rst
    faq.rst
+   commandline_ref.rst
    architecture.rst
    coding-guide.rst
    cpython_differences.rst
    garbage_collection.rst
+   gc_info.rst
    interpreter.rst
    objspace.rst
    __pypy__-module.rst

pypy/doc/man/pypy.1.rst

 -S
     Do not ``import site`` on initialization.
 
+-s
+    Don't add the user site directory to `sys.path`.
+
 -u
     Unbuffered binary ``stdout`` and ``stderr``.
 
 -E
     Ignore environment variables (such as ``PYTHONPATH``).
 
+-B
+    Disable writing bytecode (``.pyc``) files.
+
 --version
     Print the PyPy version.
 
         Optimizations to enabled or ``all``.
         Warning, this option is dangerous, and should be avoided.
 
+ENVIRONMENT
+===========
+
+``PYTHONPATH``
+    Add directories to pypy's module search path.
+    The format is the same as shell's ``PATH``.
+
+``PYTHONSTARTUP``
+    A script referenced by this variable will be executed before the
+    first prompt is displayed, in interactive mode.
+
+``PYTHONDONTWRITEBYTECODE``
+    If set to a non-empty value, equivalent to the ``-B`` option.
+    Disable writing ``.pyc`` files.
+
+``PYTHONINSPECT``
+    If set to a non-empty value, equivalent to the ``-i`` option.
+    Inspect interactively after running the specified script.
+
+``PYTHONIOENCODING``
+    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`.
+
+``PYTHONNOUSERSITE``
+    If set to a non-empty value, equivalent to the ``-s`` option.
+    Don't add the user site directory to `sys.path`.
+
+``PYTHONWARNINGS``
+    If set, equivalent to the ``-W`` option (warning control).
+    The value should be a comma-separated list of ``-W`` parameters.
+
+``PYPYLOG``
+    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
+
 SEE ALSO
 ========
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.