Commit 269eaa38 authored by scoder's avatar scoder Committed by GitHub

Merge pull request #2291 from gabrieldemarmiesse/compiler_options

Added the docs for the compiler options.
parents 1ee4d8b6 f61ed3e6
...@@ -29,94 +29,121 @@ class ShouldBeFromDirective(object): ...@@ -29,94 +29,121 @@ class ShouldBeFromDirective(object):
"Illegal access of '%s' from Options module rather than directive '%s'" "Illegal access of '%s' from Options module rather than directive '%s'"
% (self.options_name, self.directive_name)) % (self.options_name, self.directive_name))
# Include docstrings.
"""
The members of this module are documented using autodata in
Cython/docs/src/reference/compilation.rst.
See http://www.sphinx-doc.org/en/master/ext/autodoc.html#directive-autoattribute
for how autodata works.
Descriptions of those members should start with a #:
Donc forget to keep the docs in sync by removing and adding
the members in both this file and the .rst file.
"""
#: Whether or not to include docstring in the Python extension. If False, the binary size
#: will be smaller, but the ``__doc__`` attribute of any class or function will be an
#: empty string.
docstrings = True docstrings = True
# Embed the source code position in the docstrings of functions and classes. #: Embed the source code position in the docstrings of functions and classes.
embed_pos_in_docstring = False embed_pos_in_docstring = False
# Copy the original source code line by line into C code comments #: Copy the original source code line by line into C code comments
# in the generated code file to help with understanding the output. #: in the generated code file to help with understanding the output.
#: This is also required for coverage analysis.
emit_code_comments = True emit_code_comments = True
pre_import = None # undocumented # undocumented
pre_import = None
# Decref global variables in this module on exit for garbage collection. #: Decref global variables in each module on exit for garbage collection.
# 0: None, 1+: interned objects, 2+: cdef globals, 3+: types objects #: 0: None, 1+: interned objects, 2+: cdef globals, 3+: types objects
# Mostly for reducing noise in Valgrind, only executes at process exit #: Mostly for reducing noise in Valgrind, only executes at process exit
# (when all memory will be reclaimed anyways). #: (when all memory will be reclaimed anyways).
generate_cleanup_code = False generate_cleanup_code = False
# Should tp_clear() set object fields to None instead of clearing them to NULL? #: Should tp_clear() set object fields to None instead of clearing them to NULL?
clear_to_none = True clear_to_none = True
# Generate an annotated HTML version of the input source files. #: Generate an annotated HTML version of the input source files for debugging and optimisation purposes.
#: This has the same effect as the ``annotate`` argument in :func:`cythonize`.
annotate = False annotate = False
# When annotating source files in HTML, include coverage information from # When annotating source files in HTML, include coverage information from
# this file. # this file.
annotate_coverage_xml = None annotate_coverage_xml = None
# This will abort the compilation on the first error occurred rather than trying #: This will abort the compilation on the first error occurred rather than trying
# to keep going and printing further error messages. #: to keep going and printing further error messages.
fast_fail = False fast_fail = False
# Make all warnings into errors. #: Turn all warnings into errors.
warning_errors = False warning_errors = False
# Make unknown names an error. Python raises a NameError when #: Make unknown names an error. Python raises a NameError when
# encountering unknown names at runtime, whereas this option makes #: encountering unknown names at runtime, whereas this option makes
# them a compile time error. If you want full Python compatibility, #: them a compile time error. If you want full Python compatibility,
# you should disable this option and also 'cache_builtins'. #: you should disable this option and also 'cache_builtins'.
error_on_unknown_names = True error_on_unknown_names = True
# Make uninitialized local variable reference a compile time error. #: Make uninitialized local variable reference a compile time error.
# Python raises UnboundLocalError at runtime, whereas this option makes #: Python raises UnboundLocalError at runtime, whereas this option makes
# them a compile time error. Note that this option affects only variables #: them a compile time error. Note that this option affects only variables
# of "python object" type. #: of "python object" type.
error_on_uninitialized = True error_on_uninitialized = True
# This will convert statements of the form "for i in range(...)" #: This will convert statements of the form ``for i in range(...)``
# to "for i from ..." when i is a cdef'd integer type, and the direction #: to ``for i from ...`` when ``i`` is a C integer type, and the direction
# (i.e. sign of step) can be determined. #: (i.e. sign of step) can be determined.
# WARNING: This may change the semantics if the range causes assignment to #: WARNING: This may change the semantics if the range causes assignment to
# i to overflow. Specifically, if this option is set, an error will be #: i to overflow. Specifically, if this option is set, an error will be
# raised before the loop is entered, whereas without this option the loop #: raised before the loop is entered, whereas without this option the loop
# will execute until an overflowing value is encountered. #: will execute until an overflowing value is encountered.
convert_range = True convert_range = True
# Perform lookups on builtin names only once, at module initialisation #: Perform lookups on builtin names only once, at module initialisation
# time. This will prevent the module from getting imported if a #: time. This will prevent the module from getting imported if a
# builtin name that it uses cannot be found during initialisation. #: builtin name that it uses cannot be found during initialisation.
#: Default is True.
#: Note that some legacy builtins are automatically remapped
#: from their Python 2 names to their Python 3 names by Cython
#: when building in Python 3.x,
#: so that they do not get in the way even if this option is enabled.
cache_builtins = True cache_builtins = True
# Generate branch prediction hints to speed up error handling etc. #: Generate branch prediction hints to speed up error handling etc.
gcc_branch_hints = True gcc_branch_hints = True
# Enable this to allow one to write your_module.foo = ... to overwrite the #: Enable this to allow one to write ``your_module.foo = ...`` to overwrite the
# definition if the cpdef function foo, at the cost of an extra dictionary #: definition if the cpdef function foo, at the cost of an extra dictionary
# lookup on every call. #: lookup on every call.
# If this is false it generates only the Python wrapper and no override check. #: If this is false it generates only the Python wrapper and no override check.
lookup_module_cpdef = False lookup_module_cpdef = False
# Whether or not to embed the Python interpreter, for use in making a #: Whether or not to embed the Python interpreter, for use in making a
# standalone executable or calling from external libraries. #: standalone executable or calling from external libraries.
# This will provide a method which initialises the interpreter and #: This will provide a C function which initialises the interpreter and
# executes the body of this module. #: executes the body of this module.
#: See `this demo <https://github.com/cython/cython/tree/master/Demos/embed>`_
#: for a concrete example.
#: If true, the initialisation function is the C main() function, but
#: this option can also be set to a non-empty string to provide a function name explicitly.
#: Default is False.
embed = None embed = None
# In previous iterations of Cython, globals() gave the first non-Cython module # In previous iterations of Cython, globals() gave the first non-Cython module
# globals in the call stack. Sage relies on this behavior for variable injection. # globals in the call stack. Sage relies on this behavior for variable injection.
old_style_globals = ShouldBeFromDirective('old_style_globals') old_style_globals = ShouldBeFromDirective('old_style_globals')
# Allows cimporting from a pyx file without a pxd file. #: Allows cimporting from a pyx file without a pxd file.
cimport_from_pyx = False cimport_from_pyx = False
# max # of dims for buffers -- set lower than number of dimensions in numpy, as #: Maximum number of dimensions for buffers -- set lower than number of
# slices are passed by value and involve a lot of copying #: dimensions in numpy, as
#: slices are passed by value and involve a lot of copying.
buffer_max_dims = 8 buffer_max_dims = 8
# Number of function closure instances to keep in a freelist (0: no freelists) #: Number of function closure instances to keep in a freelist (0: no freelists)
closure_freelist_size = 8 closure_freelist_size = 8
......
...@@ -253,6 +253,50 @@ customize your build. ...@@ -253,6 +253,50 @@ customize your build.
.. autofunction:: Cython.Build.cythonize .. autofunction:: Cython.Build.cythonize
Compiler options
----------------
Compiler options can be set in the :file:`setup.py`, before calling :func:`cythonize`,
like this::
from distutils.core import setup
from Cython.Build import cythonize
from Cython.Compiler import Options
Options.docstrings = False
setup(
name = "hello",
ext_modules = cythonize("lib.pyx"),
)
Here are the options that are available:
.. autodata:: Cython.Compiler.Options.docstrings
.. autodata:: Cython.Compiler.Options.embed_pos_in_docstring
.. autodata:: Cython.Compiler.Options.emit_code_comments
.. pre_import
.. autodata:: Cython.Compiler.Options.generate_cleanup_code
.. autodata:: Cython.Compiler.Options.clear_to_none
.. autodata:: Cython.Compiler.Options.annotate
.. annotate_coverage_xml
.. autodata:: Cython.Compiler.Options.fast_fail
.. autodata:: Cython.Compiler.Options.warning_errors
.. autodata:: Cython.Compiler.Options.error_on_unknown_names
.. autodata:: Cython.Compiler.Options.error_on_uninitialized
.. autodata:: Cython.Compiler.Options.convert_range
.. autodata:: Cython.Compiler.Options.cache_builtins
.. autodata:: Cython.Compiler.Options.gcc_branch_hints
.. autodata:: Cython.Compiler.Options.lookup_module_cpdef
.. autodata:: Cython.Compiler.Options.embed
.. old_style_globals
.. autodata:: Cython.Compiler.Options.cimport_from_pyx
.. autodata:: Cython.Compiler.Options.buffer_max_dims
.. autodata:: Cython.Compiler.Options.closure_freelist_size
Distributing Cython modules Distributing Cython modules
---------------------------- ----------------------------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment