Configuring, Building and Cleaning


Back to Main Index

Introduction These are directories used by the current VortexGE distribution :
doc: contains documentation, tutorial and references
lib: contains source codes of the VortexGE Library
3rdParty: contains 3rd party files (headers, sources and build scripts)
buildScript: contains build scripts and configured files needed for building VortexGE
demo: contains demo applications
util: contains utility applications
libVGE.messages.cat: contains the library's internal message catalog files
media: contains media files (images and sounds)
rawBenchmark: contains benchmarking applications (raw benchmark only)

There is a project file for Anjuta IDE v1.2.3 IDE ("VortexGE.prj").
If you have the IDE, just open the project file.

Building in Other Directory
To build VortexGE in other directory, simply use the provided helper script "util/linktree" to mirror the VortexGE source tree. Here is an example of how to do that:
  1. Get the VortexGE tar-ball, lets say : VortexGE-0.6.0-3.tar.bz2
  2. Start from your home directory (assume '$' as your bash prompt), do these steps :
    $ mkdir tmp
    $ cd tmp
    $ tar -xjvpf <path-to-the-tar-ball>/VortexGE-0.6.0-3.tar.bz2
    $ mkdir build
    $ cd build
    $ ../VortexGE/util/linktree ../VortexGE
  3. That's all, now you've mirrored the VortexGE source tree in <your-home-dir-name>/tmp/build
Note that you can also use the "lndir" tool that come with almost all X distribution to mirror the directory.

Running the Configuration Script To list what options supported and what environment/shell variables used by the configuration script, simply type :
./configure --help
To run the configuration script in interactive mode, simply type :
./configure
at the console from the VortexGE main directory. In this interactive mode, after checking for prerequisites, you will be presented with either line by line questions or some dialogs (only if your system has the needed dialog program).

The first question will ask for the installation directory:

Installation directory [/usr/local/] ?

If you just press enter, then "/usr/local" will be used. If you write something then your choice will be used. Examples:

Installation directory [/usr/local/] ? /opt/vge-0.6.0-3
Installation directory [/usr/local/] ? /opt/VortexGE
etc...

Make sure that you enter a valid directory name since the configuration script will not check for it's validity, if you enter an invalid directory name then the generated build scripts might become invalid and might be dangerous !!!

VortexGE can also be configured in non interactive mode in which the CPU type will be auto detected and the default options will be used. In order to do this, simply type :
./configure --default
With this options you can also add one or more sub-option(s), such as:
./configure --default --enable-asm
./configure --default --disable-xmu
./configure --default --disable-shm --prefix=<target-installation-directory>
which will run the default configuration with some customization(s).

Make sure that you enter a valid directory name since the configuration script will not check for it's validity !!!

One can also perform interactive configuration and then save the options you have chosen to file (the default is "configure.dat") using this command :
./configure --fsave
In the future when you want to reconfigure using the same options you can simply type :
./configure --fload
VortexGE distribution come with the safe mode "configure.dat" file which has these settings :
Processor='Any i586 Compatible'
DetectPEx='N'
ColorMsgs='N'
UseXF86VM='N'
UseXShmEx='N'
UseXMuExt='N'
UseLibPng='N'
UseLibJpg='N'
UseLibTif='N'
UseLibGif='N'
InlineAsm='N'
UseDebugI='N'
BuildALib='N'
AlignedMO='Y'
QuadWrdMO='Y'
OptzLevel='2'
Note that there is no error checking in the configuration script to determine whether "configure.dat" contains the valid options. The safest way to create this configuration options file is to run the command "./configure --fsave" rather than to edit it manually.

The configuration script will check for the existence of GCC 4.x.x. If it is exist then additional compile options will be enabled.

(Re-)running "./configure" will overwrite any existing files, "lib/vconfig.h", "buildScript/Config" and "buildScript/VortexGE.spec". It means that all changes you have made manually inside those files will be gone.

The configuration displayer utility, "util/vge-config" can be used to display various VortexGE configuration options that can be of help when building application using VortexGE. Note that this script will be only available if "./configure" completed successfully.

After the configuration processes completed, all available build target can be displayed using :
make help
at the console from the VortexGE main directory.

Building the VortexGE Library

Default Build

To build the VortexGE library simply type :
make
at the console from the VortexGE main directory.

The VortexGE build scripts support parallel make, but they are not well tested. It is recommended to not use parallel make for now.

The configuration script will also enable PIC (Position Independent Code) build for shared library if the hardware platform is not an i386.
If it is not working well with your box, just open the generated makefile configuration file, "buildScript/Config" and edit the line which contains:
OPSO =
or :
OPSO = -fPIC -D__VGE_PIC_BUILD__
as needed.

Please read the "Build Macros" topic to learn about all build macros that can be used to control the behavior of VortexGE.

You can also build everything at once (the library, demo applications, tutorial applications, utility applications, benchmarking applications and the API documentation) by typing :
make all rbench apidoc
at the console from the VortexGE main directory.

Note that any application that uses VortexGE library should not incorrectly interrupted/aborted (for example: via Ctrl-C) because the shared resource(s) used by the XShm and the VortexGE IPC may not deleted properly and can result in system resource lack. If any of those kind of applications is happen to incorrectly interrupted/aborted, use "ipcs" and then "ipcrm" command from console in order to remove the "unwanted" shared resources (or use the provided script, "util/ipcrem").

VortexGE has the abilities to disable Ctrl-C and Ctrl-Z using the functions :
void VEnableCtrlC(bool bEnabled)
void VEnableCtrlZ(bool bEnabled)
Both of them must be called manually as needed to prevent the user from aborting the application.

Static vs Shared Library

By default VortexGE will only build (and will always build) the shared library. However, the configuration script will ask if the user wants to build the static libary also.

If you don't want to build the shared library for some reasons, then after "./configure", just edit the generated makefile configuration file ("buildScript/Config"), and change the line :
BLDS = 1
to :
BLDS = 0
However by doing so, the distribution packages building (see the next section) will be failed. You must edit the spec file manually if you still want to build the distribution packages.

The helper executor "srun" can be used to run the demo applications without the need to set LD_LIBRARY_PATH manually, for examples :
./srun Test
./srun VirtualWalk VirtualWalk2
./srun tut01a

Disabling the Use of Precompiled Headers

If you do not want to use GCC's precompiled header (*.gch files) , then after "./configure", just edit the generated buildScript configuration file, "buildScript/Config" and change :
USE_GCH = 1
to :
USE_GCH = 0
GCC version 3.4.0 and above support precompiled header, however, there is no guarantee that precompiled header will work in your system.

3rd Party Libraries

VortexGE distribution carries some 3rd party library source files, they are :

  1. From X11R6.8.2/X.org source distribution, only the file needed for xf86vm extension support in X11 client is copied.
  2. From libTiMidity-0.1.0 MIDI to WAVE converter library.
  3. From Lua 5.1.1 embeddable scripting language.
The VortexGE configuration script will attempt to detect if your system has "libXxf86vm.so", and if it is VortexGE will use it instead of the "3rdParty/xf86vm/xf86vmode.c" file that came with VortexGE.

In case of the detection is failed (but you are absolutely sure that your system has "libXxf86vm.so", you can manually edit the generated buildScript configuration file, "buildScript/Config" and change the line :
HAS_LIBXXF86VM_SO = 0
to :
HAS_LIBXXF86VM_SO = 1
then also add a reference to "libXxf86vm.so" so that ULIB lookedlike :
ULIB = ... -lXxf86vm ....

If somehow the xf86vm support that came with VortexGE distribution doesn't work with your machine, you may try to :

  1. Use your system xf86vm extension support, even tough you may only have "libXxf86vm.a" and not "libXxf86vm.so" in your system (should be no problem in all x86 architectures).
  2. If the 1st step above is still not working, try to get the source distribution for your system X11 server and replace "xf86vmode.c" that came with VortexGE with the one that came from your system X11 source distribution. Note that different X11 distribution may need additional files to be copied in the "3rdParty/xf86vm" directory and may also need additional compile options.
The "3rdParty/xf86vm/xf86vmode.c" file which comes with VortexGE should works well with X11 servers from XFree86-4.3.x and XOrg-6.7.x distributions. It is not tested whether older version of X11 servers can also be used

Building the API Documentation To build the API documentation, simply type :
make apidoc
at the console from the VortexGE main directory.

Building the Library Distribution Packages To build the rpm packages simply type :
make rpm
or :
make rpm sign=y
if you have a gpg/pgp key and want to sign the packages.

Distributing the Packages
If you want to distribute the packages make sure that the generated "buildScript/VortexGE.spec" is edited and the line :
Packager: Original VortexGE tar-ball distribution
is changed to :
Packager: Your Name <your-e-mail@something.something>
<<< DO NOT put my name nor my e-mail address in that field >>>

Building The Applications

To build the demo applications simply type :
make demo
at the console from the VortexGE main directory, or type :
cd demo
make

To build the tutorial applications simply type :
make tutor
at the console from the VortexGE main directory, or type : cd doc/tutrefs/cc
make

To build the utility applications simply type :
make util
at the console from the VortexGE main directory, or type :
cd util
make

To build the benchmarking applications simply type :
make bench
at the console from the VortexGE main directory, or type :
cd rawBenchmark
make
The benchmark applications will do benchmarking of various method using plain C++, plain x86 assembly, MMX, and SSE.
These benchmarking applications are used when developing VortexGE, so normal users won't need to bother with it ;)

Cleaning Everything To erase all generated files, simply type :
allclean
./configure --clean
at the console from the VortexGE main directory.

Note that this command will not delete the saved configuration options. The default file for storing the options is "configure.dat", it can be changed by editing the content of the "ConfDtFile" variable in the file "buildScript/configure/special-constants.inc".


Back to Main Index