2. Building and Installing

This chapter provides information about how to build the kit yourself from the sources. You can skip this chapter if the kit is already installed on your system or if you are installing binary versions.

2.1. Building from the sources

The following instructions will build and install the full version of cgkit. You can also install the ‘light’ version by setting the variable INSTALL_CGKIT_LIGHT to True in your config file (just rename the file config_template.cfg to config.cfg and uncomment the corresponding line at the top of the file). Except for Python itself, installing the light version does not require any additional compiler, tool or library, you simply have to call

> python setup.py install

while being in the root directory of the cgkit sources. For installing the light version you can skip the remainder of this section, but read on if you actually want to install the full version.

The steps required to build the full version of the kit are the same on every platform. The build process assumes you have the following tools/libraries installed on your system:

  • Boost - Make sure that Boost is installed including Boost.Python (e.g. Mac users who are using MacPorts have to install the “+python” variant).
  • SCons
  • lib3ds (v1.x) - Optional. You need this if you want to import/export 3DS files.
  • CyberX3D - Optional. You need this if you want to import/export VRML or X3D files.
  • 3DxWare SDK - Optional (currently Windows only). You need this if you want to use a SpaceMouse or SpaceBall.
  • Wintab Programmer’s Kit - Optional (Windows only). You need this if you want to use a tablet (or similar device).
  • GloveSDK - Optional. You need this if you want to use a data glove. Note: Download the version 2 SDK from the Ultra series, this can also be used with older gloves. You could also use version 1, but some functionality won’t be available then.

If you have successfully installed the above tools and libraries you can proceed with building the kit. The first step is to get the cgkit sources. You can either download the source archive or check out the latest version from svn. The following build instructions apply to both versions.

The package consists of three parts:

  1. A pure C++ library that is independent of Python. This library is located in the supportlib directory.
  2. Python wrappers around the above C++ library (using Boost.Python). These wrappers are located in the wrappers directory.
  3. The actual Python package using the wrappers. The package is located in the cgkit directory. The command line tools are in the main directory and the :file:utilities` directory.

Part 2) and 3) is built and installed via the Python distutils (i.e. the setup.py script). But before you can do so, you have to build the C++ library manually using SCons.

Building the C++ support library:

The C++ library is located in the directory supportlib. The library uses SCons as its build system. If you have to customize the build process you can create a file cpp_config.cfg where you can set some build variables (e.g. adding search paths for include files). There is a template file cpp_config_template.cfg which you can use to create the actual config file. However, if you have installed every library in standard directories it may well be that you don’t need any config file at all. Eventually you can build the library by calling scons:

> cd supportlib
> # ...create & modify cpp_config.cpp if necessary...
> scons

If everything went fine you can see the result in the lib subdirectory (libcore.a on Linux and OSX or core.lib on Windows).

Building the Python wrappers:

The next step is to build and install the Python package. The package uses the distutils, so you will find the familiar setup.py script in the main directory. Customization of the build process can again be done in a file called config.cfg and config_pyXY.cfg where XY is the Python version you want to build against. The former file is always read whereas the latter is only read when building against that particular version of Python. There is a template file config_template.cfg which you can use to create your own config file. After setting up your configuration you can install the package with the usual procedure:

> cd ..  # if you were still in the supportlib directory
> python setup.py install

(see the manual Installing Python Modules in your Python documentation for more details about the distutils and how to proceed if you have any special requirements)

Please also have a look at section External dependencies for a list of third-party packages you might have to install before you can use cgkit. You can check cgkit and its dependencies with the script utilities/checkenv.py that is part of the source archive. For a more thorough test you can run the unit tests in the unittests directory.

A note to developers: You can build the package inplace by calling

> python setup.py build_ext --inplace

In this case, the resulting binaries will be placed directly in the cgkit directory which will then contain the entire package. Use the PYTHONPATH variable and add the path to the main directory if you want to use the inplace version from any other directory.

Table Of Contents

Previous topic

1. Introduction

Next topic

3. Tools

This Page