PyKDE4 - Python Bindings for KDE4
Prev |  | Next

## Installing PyKDE4

### Install Documentation Only

If you already have PyKDE4 installed and only want to install or update the documentation, from the top-level directory run "installdocs.py" as root. For example:

        su -c"python installdocs.py"

This will only work if PyKDE4 is already installed. If you follow the installation procedure below, the documentation installation will be included automatically. You can also modify the location of the pykdedocs executable or html and example files by modifying installdocs.py.

### Packages

The easiest way to install PyKDE4 is from packages provided by your Linux distribution or by third parties. PyKDE4 is now included in the kdebindings section of the KDE4 SVN, so most distributions should have packages available.

The remainder of this section is for those who want to install from the PyKDE4 source tarball, or need to upgrade a distribution installation to get recent PyKDE4 enhancements or bug fixes.

### Requirements

PyKDE4 requires

- KDE4 - including header files (often in a kdelibs-devel package
- sip - a version later than September 2007 version 4.7 snapshots (4.7.4 preferred)
- PyQt4 - version 4.3 or later, compiled against the currently installed sip version
- PyQt4 sip files - These are required to generate the PyKDE4 C++ code. They're installed automatically if you compiled PyQt4 on your system. If you installed from a pre-built package, you may need a PyQt4 devel package for these files.

PyQt4 and sip tarballs are available from Riverbank Computing, as is the most recent PyKDE4 tarball.

### Configuring PyKDE4

PyKDE4 is configured for you machine by running

    python configure.py

As a normal user (not root), change (cd) to the top level PyKDE4 directory both to run configure.py and to run make and make install (below).

The option switches for configure.py are detailed at the end of this page - most people won't need them. configure.py will normally detect automatically:

- Whether sip and PyQt4 are installed and are compatible versions
- The location of KDE4 files (h files, libs) needed to build PyKDE4
- The location where PyKDE4 files will be installed

After determining your machine's setup, configure.py will generate the PyKDE4 C++ files using the sip program. This takes well under 5 minutes on most machines. configure.py will also determine the best way to structure the C++ files for your installed version of g++ (gcc).

Some versions of gcc after 4.0 (including 4.2.x) aren't capable of compiling the large files that are generated for PyKDE4 when concatenation (-c switch) is used. configure.py now defaults to generating individual files per class (-i switch is default). Use -c if you think concatenation will work on your system.

The options (see below) are whether sip concatenates all of the PyKDE4 code into one or two very large files per PyKDE4 module (for faster compilation) or generates a file-per-class for each module (somewhat slower, but still fairly speedy on recent gcc versions).

### Compiling and Installing

To compile PyKDE4, in the top level PyKDE4 directory, type (as a normal user - not root):

    make

PyKDE4 will require anywhere from less than 5 minutes to over 30 minutes to compile, depending on the speed of your machine and availaable memory. If PyKDE4's C++ files were concatenated, compiling may require that you have more than 256MB of memory installed. If available memory is low, you can use the switches detailed below to reduce memory requirements during compilation.

After PyKDE4 has successfully compiled, you will need to install PyKDE4 as the root user. Either change (su) to root, or as a normal user type:

    su -c"make install"

### Testing the Installation

If PyKDE4 configured, compiled and installed successfully, you are ready to test PyKDE4. A simple test that catches most build errors is (from the top level PyKDE4 directory):

    python importTest.py

This test simply imports each of the modules built. If any "missing symbol" errors prevent loading, report a bug. The fix is simple, but requires a recompile. This kind of problem should be extremely rare, and is dependent on how your distribution built KDE4 (the build is non-standard).

If importTest.py succeeds in importing all modules, you can beging coding, or start exploring the example programs and samples that PyKDE4 installed. pykdedocs should have installed in your executables path - that program provides access to example code, documentation (including this documentation) and tutorials about using PyKDE4.

You can issue a single command line to configure, compile, install and test PyKDE4 (you'll be prompted for your root password before installation takes place):

    python configure.py && make && su -c"make install" && python importTest.py

### PyKDE4 and KDE3/PyKDE3

PyKDE4 will co-exist with a PyKDE3 installation. It should also be possible to execute PyKDE4 programs from a KDE3 desktop if you have KDE4 also installed but not currently running (all of PyKDE4 development was done under KDE3).

### configure.py Options

configure.py has the following options, which are described below.

    Usage:
        python configure.py [-h] [-c] [-d dir] [-g] [-i] [-j #] [-k] {-L dir] [-n dir] [-o dir] [-r] [-u] [-v dir] [-w] [-x] [-z file]

    where:
        -h      displays this help message
        -c      concatenates each module's C/C++ source files
        -d dir  where the PyKDE modules will be installed [default /usr/lib/python/site-packages]
        -g      always release the GIL (SIP v3.x behaviour - default)
        -i      no concatenation of each module's C/C++ source files [default]
        -j #    splits the concatenated C++ source files into # pieces [default 1]
        -k dir  the KDE base directory
        -L dir  the library directory name [default lib]
        -n dir  the directory containing the KDE lib files
        -o dir  the directory containing the KDE header files
        -r      generates code with tracing enabled [default disabled]
        -u      build with debugging symbols
        -v dir  where the PyKDE .sip files will be installed [default /usr/share/sip/PyKDE4]
        -w      turn on KDE deprecated object warnings when compiling [default off]
        -z file the name of a file containing command line flags

- -h - displays the help message above
- -c - concatenates C++ source files.

  With this option, sip generates a single large source file for each module (2 files for kdeui and kio because of their size) instead of many small modules (basically one file per class otherwise.

  This speeds up compilation significantly - up to 80% faster with older gcc versions, less with newer versions. It can also cause gcc to freeze, and consumes a large amount of memory during compilation.

  PyKDE4's configure.py detects gcc versions which are problematical automatically, and disables concatenation for those gcc versions. Otherwise, concatenation is on by default. It can be turned off using the '-i' switch, or modified by using -j.

- -d dir - allows you to specify the directory where the PyKDE4 libraries will be installed. Normally this is /usr/lib/pythonX.Y/site-packages. configure.py detects the version info from the python interpreter that runs configure.py. You can specify an alternate location.
- -g - always release Python's GIL before calling a C++ function (default)
- -i - generate individual files instead of large concatenated files (see -c above). This is the default.
- -j # - split each module's C++ file into # pieces; can speed compilation on multicore systems
- -k dir - the KDE4 base directory; configure.py will normally find this for you
- -L dir - the directory containing system libs; configure.py will normally find this for you
- -n dir - the directory containing KDE4 libs; configure.py will normally find this for you
- -o dir - the directory containing KDE4 header (*.h) files; configure.py will normally find this for you
- -r- generates code with tracing enabled (default is disabled)
- -u - retain debugging symbols from compile/link
- -v dir - the directory where PyKDE4 sip files will be installed; these are required only for bindings that depend on PyKDE4 (as PyKDE4 depends on PyQt4); default is /usr/share/sip/PyKDE4
- -w - turn on KDE4 deprecated warnings during compilation; these are off by default
- -z file - you can put the command line flags in a separate file (one switch per line) and then specify that file with -z instead of putting the switches on the command line

PyKDE4 should build in most environments without the use of any switches at all.

Prev | Table of Contents | Next
General Information |  | Using PyKDE4