diff options
Diffstat (limited to 'sphinx/installation.rst')
| -rw-r--r-- | sphinx/installation.rst | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/sphinx/installation.rst b/sphinx/installation.rst new file mode 100644 index 0000000..3f9f823 --- /dev/null +++ b/sphinx/installation.rst @@ -0,0 +1,169 @@ +Installation +============ + +Downloading +----------- + +You can get the latest release of the SIP source code from +http://www.riverbankcomputing.com/software/sip/download. + +SIP is also included with all of the major Linux distributions. However, it +may be a version or two out of date. + + +Configuring +----------- + +After unpacking the source package (either a ``.tar.gz`` or a ``.zip`` file +depending on your platform) you should then check for any ``README`` files +that relate to your platform. + +Next you need to configure SIP by executing the ``configure.py`` script. For +example:: + + python configure.py + +This assumes that the Python interpreter is on your path. Something like the +following may be appropriate on Windows:: + + c:\python26\python configure.py + +If you have multiple versions of Python installed then make sure you use the +interpreter for which you wish SIP to generate bindings for. + +The full set of command line options is: + +.. program:: configure.py + +.. cmdoption:: --version + + Display the SIP version number. + +.. cmdoption:: -h, --help + + Display a help message. + +.. cmdoption:: --arch <ARCH> + + Binaries for the MacOS/X architecture ``<ARCH>`` will be built. This + option should be given once for each architecture to be built. Specifying + more than one architecture will cause a universal binary to be created. + +.. cmdoption:: -b <DIR>, --bindir <DIR> + + The SIP code generator will be installed in the directory ``<DIR>``. + +.. cmdoption:: -d <DIR>, --destdir <DIR> + + The SIP module will be installed in the directory ``<DIR>``. + +.. cmdoption:: -e <DIR>, --incdir <DIR> + + The SIP header file will be installed in the directory ``<DIR>``. + +.. cmdoption:: -k, --static + + The SIP module will be built as a static library. This is useful when + building the SIP module as a Python builtin (see :ref:`ref-builtin`). + +.. cmdoption:: -n, --universal + + The SIP code generator and module will be built as universal binaries + under MacOS/X. If the :option:`--arch <configure.py --arch>` option has + not been specified then the universal binary will include the ``i386`` and + ``ppc`` architectures. + +.. cmdoption:: -p <PLATFORM>, --platform <PLATFORM> + + Explicitly specify the platform/compiler to be used by the build system, + otherwise a platform specific default will be used. The + :option:`--show-platforms <configure.py --show-platforms>` option will + display all the supported platform/compilers. + +.. cmdoption:: -s <SDK>, --sdk <SDK> + + If the :option:`--universal <configure.py -n>` option was given then this + specifies the name of the SDK directory. If a path is not given then it is + assumed to be a sub-directory of ``/Developer/SDKs``. + +.. cmdoption:: -u, --debug + + The SIP module will be built with debugging symbols. + +.. cmdoption:: -v <DIR>, --sipdir <DIR> + + By default ``.sip`` files will be installed in the directory ``<DIR>``. + +.. cmdoption:: --show-platforms + + The list of all supported platform/compilers will be displayed. + +.. cmdoption:: --show-build-macros + + The list of all available build macros will be displayed. + +The ``configure.py`` script takes many other options that allows the build +system to be finely tuned. These are of the form ``name=value`` or +``name+=value``. The :option:`--show-build-macros <configure.py +--show-build-macros>` option will display each supported ``name``, although not +all are applicable to all platforms. + +The ``name=value`` form means that ``value`` will replace the existing value of +``name``. + +The ``name+=value`` form means that ``value`` will be appended to the existing +value of ``name``. + +For example, the following will disable support for C++ exceptions (and so +reduce the size of module binaries) when used with GCC:: + + python configure.py CXXFLAGS+=-fno-exceptions + +A pure Python module called ``sipconfig.py`` is generated by ``configure.py``. +This defines each ``name`` and its corresponding ``value``. Looking at it will +give you a good idea of how the build system uses the different options. It is +covered in detail in :ref:`ref-build-system`. + + +Configuring for MinGW +********************* + +SIP, and the modules it generates, can be built with MinGW, the Windows port of +GCC. You must use the :option:`--platform <configure.py -p>` command line +option to specify the correct platform. For example:: + + c:\python26\python configure.py --platform win32-g++ + + +Configuring for the Borland C++ Compiler +**************************************** + +SIP, and the modules it generates, can be built with the free Borland C++ +compiler. You must use the :option:`--platform <configure.py -p>` command line +option to specify the correct platform. For example:: + + c:\python26\python configure.py --platform win32-borland + +You must also make sure you have a Borland-compatible version of the Python +library. If you are using the standard Python distribution (built using the +Microsoft compiler) then you must convert the format of the Python library. +For example:: + + coff2omf python26.lib python26_bcpp.lib + + +Building +-------- + +The next step is to build SIP by running your platform's ``make`` command. For +example:: + + make + +The final step is to install SIP by running the following command:: + + make install + +(Depending on your system you may require root or administrator privileges.) + +This will install the various SIP components. |