Building with the Python Build Scripts

For platforms without Visual Studio, the PathEngine source archives come with a python build script that serves to make a default build from the source code, with some dependency checking. The GCC based platform specific code packages enable the PathEngine run-time library to be built on various operating systems and architectures where the GCC toolchain is available as a standard compilation environment.

Motivation and scope

The python build scripts are provided as a quick way to get the source code to build, avoiding the complexities of cross-platform differences in makefile operation, and to demonstrate a baseline set of compile settings for each platform.

While the build scripts do include automatic dependency generation and checking (per source file), and should generally build the source code robustly, the scripts do have some rough edges, and are not intended to take the place of a fully featured build setup tool.

Requirements

The build scripts require python and GCC installed and on the search path. (The dependency generation code works by calling through to 'gcc -MM'.)

Python is generally included as standard with Linux and FreeBSD distributions.
If not then it can be downloaded and installed from www.python.org.
The build setup has been tested against Python versions 2.5 and 2.6, should also work with other 2.x releases.

Building the source code requires a reasonably standard compliant compiler (e.g. a recent version of GCC), with C and C++ standard libraries installed.

Contents of the platform archives

Python build scripts are provided with the platform specific code archives for the following platforms (by 'platform code'):

• GCCx86
• GCCx64
• Cell (setup for cross compilation)

These platform specific archives then include platform specific code directories, plus python build scripts and xml project configuration files.

The packages should be extracted over the top of the base full source package, ensuring that the release numbers for the two packages match.
The xml project configuration files will then be extracted into each project directory.

Where more than one of the above packages is installed files will be repeated and it is ok for these to be overwritten.

Setting environmental variables

Before building the source code, the following environmental variables need to be set:

• PATHENGINE_PLATFORM, set to PathEngine's platform code for the platform being built (see Platform Specific Source Code Archives)
• PATHENGINE_CONFIGURATION, set to either 'Release' or 'Debug'

Alternative platform codes for generating position independant code (with -fPIC)

On some Linux distributions (or on OSes), shared objects require the generation for position independant code, with the -fPIC option.
But this option can add some significant overhead, and is therefore not included by default.
Instead, additional platform codes have been added with the option enabled.
These additional codes are formed by adding an '_SO' suffix to the base platform code.

When building shared objects on distributions or OSes where the -fPIC option is required, use GCCx86_SO instead of GCCx86 or GCCx64_SO instead of GCCx64.

Building the run-time library

Change directory to 'SDKRoot/python/buildScripts' and type "python Make.py PathEngine".

After the first build the build scripts will check dependencies and only recompile objects that need to be recompiled.

Build result

The above build operation should generate a file 'PathEngine.so', in a directory created for 'SDKRoot/build/ Configuration _ platform /PathEngine', where Configuration is replaced by the configuration being built (e.g. 'Debug' or 'Release'), and platform is replaced by the code for the platform being built.
(So the build result for a debug build, on x64 Linux, is at 'SDKRoot/build/Debug_GCCx64/PathEngine/PathEngine.so'.)

This is a shared object binary, essentially the Linux equivalent of a Windows DLL.
Refer to Dynamic Linking on GCC Based Platforms for details about linking dynamically against this file.

Static linkage

Static libraries can also be found in directories under 'SDKRoot/build/', and these can be used for direct linkage to PathEngine.
Refer to Internal Organisation for information about the set of libraries required (but note that these have a '.a' extension in the GCC build setup as opposed to '.lib'), and then to Static Linkage for information about static linkage in general.

Although a run-time library .so is not required when using static linkage, use the command line for building the run-time library, nevertheless, as this will then generate all the required static libs.

Changing the compile command

Depending on how GCC is setup, it may be necessary to modify the compile command.
This can be done by modifying the compileCommand() function, in 'SDKRoot/code/buildScripts/PlatformConfig.py'.
(And this compile command can also be modified to change the level of optimisation, and so on.)

Forcing a full rebuild

Note that the build scripts don't check themselves as a dependency, so it may be necessary to perform a full rebuild after script changes.
This can be done by deleting all the intermediate directories generated by a previous build command.