From: Francesc Alted Date: Sat, 2 Apr 2011 16:40:04 +0000 (+0200) Subject: A first restructuration of Compilation section. X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=5db0a3f45e6685130b04da24fcbf149bf40da28c;p=cython.git A first restructuration of Compilation section. --- diff --git a/docs/src/reference/compilation.rst b/docs/src/reference/compilation.rst index e62d9a99..f58fb53a 100644 --- a/docs/src/reference/compilation.rst +++ b/docs/src/reference/compilation.rst @@ -6,49 +6,48 @@ Compilation *********** -* Cython code, unlike Python, must be compiled. -* This happens in two stages: +Cython code, unlike Python, must be compiled. This happens in two stages: - * A ``.pyx`` file is compiles by Cython to a ``.c`` file. - * The ``.c`` file is compiled by a C comiler to a ``.so`` file (or a ``.pyd`` file on Windows) + * A ``.pyx`` file is compiles by Cython to a ``.c`` file. -* The following sub-sections describe several ways to build your extension modules. + * The ``.c`` file is compiled by a C comiler to a ``.so`` file (or a + ``.pyd`` file on Windows) -.. note:: The ``-a`` option - - * Using the Cython compiler with the ``-a`` option will produce a really nice HTML file of the Cython generated ``.c`` code. - * Double clicking on the highlighted sections will expand the code to reveal what Cython has actually generated for you. - * This is very useful for understanding, optimizing or debugging your module. +The following sub-sections describe several ways to build your +extension modules. ===================== From the Command Line ===================== -* Run the Cython compiler command with your options and list of ``.pyx`` files to generate:: +Run the Cython compiler command with your options and list of ``.pyx`` + files to generate. For example:: $ cython -a yourmod.pyx -* This creates a ``yourmod.c`` file. (and the -a switch produces a generated html file) -* Compiling your ``.c`` files will vary depending on your operating system. - - * Python documentation for writing extension modules should have some details for your system. +This creates a ``yourmod.c`` file (and the -a switch produces a +generated html file). -* Here we give an example on a Linux system:: +Compiling your ``.c`` files will vary depending on your operating +system. Python documentation for writing extension modules should +have some details for your system. Here we give an example on a Linux +system:: $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/usr/include/python2.5 -o yourmod.so yourmod.c - * ``gcc`` will need to have paths to your included header files and paths to libraries you need to link with. - * A ``yourmod.so`` file is now in the same directory. - * Your module, ``yourmod`` is available for you to import as you normally would. +[``gcc`` will need to have paths to your included header files and +paths to libraries you need to link with] +A ``yourmod.so`` file is now in the same directory and your module, +``yourmod``, is available for you to import as you normally would. ========= Distutils ========= -* Ensure Distutils is installed in your system. -* The following assumes a Cython file to be compiled called *hello.pyx*. -* Create a ``setup.py`` script:: +First, make sure that ``distutils`` package is installed in your +system. The following assumes a Cython file to be compiled called +*hello.pyx*. Now, create a ``setup.py`` script:: from distutils.core import setup from distutils.extension import Extension @@ -62,78 +61,40 @@ Distutils ext_modules = ext_modules ) -* Run the command ``python setup.py build_ext --inplace`` in your system's command shell. -* Your done.. import your new extension module into your python shell or script as normal. - -===== -SCons -===== - -to be completed... +Run the command ``python setup.py build_ext --inplace`` in your +system's command shell and you are done. Import your new extension +module into your python shell or script as normal. ========= Pyximport ========= -* For generating Cython code right in your pure python modulce:: +For generating Cython code right in your pure python module just type:: >>> import pyximport; pyximport.install() - >>> import helloworld + >>> import helloworld Hello World -* Use for simple Cython builds only. - - * No extra C libraries. - * No special build setup needed. +This allows you to automatically run Cython on every ``.pyx`` that +Python is trying to import. You should use this for simple Cython +builds only where no extra C libraries and no special building setup +is needed. -* Also has experimental compilation support for normal Python modules. +In the case that Cython fails to compile a Python module, *pyximport* +will fall back to loading the source modules instead. - * Allows you to automatically run Cython on every ``.pyx`` and ``.py`` module that Python imports. - - * This includes the standard library and installed packages. - * In the case that Cython fails to compile a Python module, *pyximport* will fall back to loading the source modules instead. - -* The ``.py`` import mechanism is installed like this:: +It is also possible to compile new ``.py`` modules that are being +imported (including the standard library and installed packages). For +using this feature, just tell that to ``pyximport``:: >>> pyximport.install(pyimport = True) - -.. note:: Authors - - Paul Prescod, Stefan Behnal - ==== Sage ==== -The Sage notebook allows transparently editing and -compiling Cython code simply by typing %cython at -the top of a cell and evaluate it. Variables and func- -tions defined in a Cython cell imported into the run- -ning session. - -.. todo:: Provide a link to Sage docs - - - - - - - - - - - - - - - - - - - - - - - - +The Sage notebook allows transparently editing and compiling Cython +code simply by typing %cython at the top of a cell and evaluate +it. Variables and functions defined in a Cython cell imported into the +running session. Please check `Sage documentation +` for details.