Build instructions
From NeoWiki
This page is divided first into sections on operating system, then on the build tools used.
Table of contents |
Generic information
The engine and other auxiliary libraries are built as static libraries. Building as dynamic library is not supported at this point, as there are no benefits of dynamic linkage in this project (except for the webdriver for Java applets, which is a naturally a dynamic library).
All paths on this page are relative to the main neoengine distribution directory.
Build configuration
The engine build configuration is controlled through the /src/core/buildconfig.h header. In this header you can specify what parts of the engine you wish to include/exclude and set subsystem parameters. Make sure you look through this header and verify everything is set to values compatible with your project.
External libraries
NeoEngine 2 has no external dependencies for the core engine (except for underlying backend APIs like DirectX, OpenGL and OpenAL, which are optional components and can be disabled in the build configuration). However, the tools and test cases use wxWidgets.
- To build the tools and test cases, you need wxWidgets. Either get/compile your own library, or use the precompiled wxWidgets library we provide on the tigris.org project file downloads page
Windows
For Windows we provide build setups for Microsoft Visual C++ (7.1 and 8.0) and SCons (with GCC/MinGW or Microsoft C++). Dev-C++ and other free IDEs are not supported at this point, however this might change in the future if interest in these tools are sufficient.
- To build the Direct3D rendering backend, you need the DirectX 9.0b SDK (or later).
- To build the OpenAL audio backend, you need the OpenAL 1.0 SDK (or later).
MSVC++ 7.1
All solutions provide two build styles, Debug and Release. All solution files reside in the /build/msvc7.1 directory, and is split up into engine, application, test and tools. All libraries built will have a -debug suffix to the name to allow both debug and release builds to co-exist on the system. For example, a library output named foo.lib will be named foo-debug.lib in Debug builds.
Make sure you distribute the Microsoft C++ runtimes along with any binaries you make. These are the DLLs msvcr71.dll and msvcp71.dll, and it is recommended by Microsoft you do not rely on client systems having the correct versions of these DLLs.
Engine
To build the core engine, open up the engine.sln solution and build the styles you need (or batch build all). The engine library will be called neoengine.lib and installed in the /lib directory.
Application
To build the application utility library used by the test cases and the tools, open the application.sln solution and build the styles you need. The application library will be called neoapplication.lib and installed in the /lib directory.
Tools
To build the tool chain utilities, you must build the engine and application libraries first, then open the tools.sln solution and build the tools you need. Note that all tools are included in this solution, so do not try to build the tools for applications you do not use (like 3DSMax and Maya exporter plugins which need the SKDs for those packages).
3DSMax plugin
The 3DSMax integration utilizes the IGame exporter interface developed by Discreet. For versions 7 or later of 3DSMax this ships as part of the 3DSMax SDK, but for earlier versions it is a separate package which we provide in the /lib/igame directory of the neoengine distribution.
To build the 3DSMax plugin for 3DSMax 7 or later, you must set the include and library paths in the project or in VC++ to match the 3DSMax SDK version you want to build against.
To build against 3DSMax 5 or 6 you must set add the appropriate include and library directory in the project settings for the build configuration you want to use. The include directory is ../../../lib/igame/3dsmax6/include and the library directory is ../../../lib/igame/3dsmax6/lib (where you replace 3dsmax6 with 3dsmax5 for building against version 5).
When deploying the plugin, make sure you include the IGame DLL from the correct directory in /lib/igame (for versions 5 and 6), and the appropriate Microsoft C++ runtimes.
All tool executables and plugins are installed in the /bin directory.
Test cases
To build the test case applications, you must build the engine and application libraries first, then open the test.sln solution and build the appropriate application projects.
Since Visual C++ stores working directory path for debugging in the user preferences and not in the solution files, you must set the working directory in the project settings for each project you intend to run from inside VC++ since we don't distribute our local user preferences files.
MSVC++ 8.0
The same instructions as for MSVC++ 7.1 applies, except you should use the solutions provided in the /build/msvc8.0 directory.
Make sure you distribute the Microsoft C++ runtimes along with any binaries you make. These are the DLLs msvcr80.dll and msvcp80.dll, and it is recommended by Microsoft you do not rely on client systems having the correct versions of these DLLs.
SCons
SCons is a build system implemented in Python where the build scripts are written in Python and is therefor very powerful and easy to configure to suit your needs.
You can use the SCons build system together with the Microsoft C++ compiler both from the Visual C++/Studio line of products and the free optimizing compiler released by Microsoft. If you use the free compiler you also need to get the various SDKs for Windows (Platform SDK and optionally DirectX and OpenAL, links above).
You can also use SCons together with Minimalist GNU for Windows (MinGW) using the GNU Compiler Collection (GCC). Together with an editor like Emacs and the GNU debugger (gdb) you get a complete Free Software development environment.
(Due to the limitations of the command line length in Windows we use the Win32 API to get around this, hence the need for the Win32 Extensions to Python)
To install the SCons build system, start by downloading the packages and then install Python, the Win32 extensions and SCons, in that order. We recommend you put the python installation path in your system environment search path so you can run scons and python in a console without explicit paths.
The SCons build system is configured by the options available in the /build/scons/SConfig file (you must create this file yourself the first time you get sources from CVS by copying the file SConfig.template in the same directory). This file holds the default values used when invoking SCons. To override these values, use the command line and give values on the form option=value, for example scons debug=1 buildtools=0. The control options to build various components of the engine are prefixed build and all take boolean values (for example, "buildtools=0"). For further information regarding options and values see the SCons manual and the comments in the SConfig.template file.
Debug and release builds can coexist on a system. Debug builds have a suffix -debug on all target files.
Engine
The core engine will be built if the option buildengine is set to true. The engine library will be named libneoengine.a and installed in the /lib directory.
Application
The application utility library will be built if the option buildapplication is set to true. The application library will be named libneoapplication.a and installed in the /lib directory.
Tools
The tools libraries and programs will be built if the option buildtools is set to true. All programs will be installed in the /bin directory and libraries in the /lib directory.
Microsoft C++
The use the Microsoft compiler tools, either set the tools option to msvc in the SConfig, or give tools=msvc on the command line.
Make sure you distribute the Microsoft C++ runtimes along with any binaries you make. The versions depend on the version of the C++ toolkit you use, see sections above on MSVC++ builds.
MinGW / GCC
The use the MinGW compiler tools, either set the tools option to gnu in the SConfig, or give tools=gnu on the command line.
Linux
At the moment we only support building through SCons from the console.
SCons (GCC)
You can use the SCons build system together with the GNU Compiler Collection (GCC).
The SCons build system is configured by the options available in the /build/scons/SConfig file (you must create this file yourself the first time you get sources from CVS by copying the file SConfig.template in the same directory). This file holds the default values used when invoking SCons. To override these values, use the command line and give values on the form option=value, for example scons debug=1 buildtools=0. The control options to build various components of the engine are prefixed build and all take boolean values (for example, "buildtools=0"). For further information regarding options and values see the SCons manual and the comments in the SConfig.template file.
Debug and release builds can coexist on a system. Debug builds have a suffix -debug on all target files.
Engine
The core engine will be built if the option buildengine is set to true. The engine library will be named libneoengine.a and installed in the /lib directory.
Application
The application utility library will be built if the option buildapplication is set to true. The application library will be named libneoapplication.a and installed in the /lib directory.
Tools
The tools libraries and programs will be built if the option buildtools is set to true. All programs will be installed in the /bin directory and libraries in the /lib directory.
MacOS X
At the moment we only support building through XCode and not with SCons in the console. The engine supports both PowerPC and x86 architectures (universal binaries) and the precompiled wxWidgets library is built for both architectures (for the test cases and the tools).
XCode
Only XCode 2.1 or later is supported. All projects have two build configurations, debug and release. Libraries are put in /lib/debug or /lib/release depending on style used, and binaries in /bin/debug or /bin/release.
BEFORE BUILDING EACH OF THE PROJECTS FOR THE FIRST TIME, YOU MUST CHOOSE THE BUILD CONFIGURATION TO USE! This is due to a bug in XCode where it does not recognize a default configuration name other than Development. Or actually, it builds the correct configuration (debug), but uses the wrong configuration name when placing the build products (for example, the libraries end up in /lib/Development). You select the build style through the Project menu -> Select Active Build Configuration.
All project files reside in /build/xcode. Below, the <buildconfig> denotes the name of the active build configuration, i.e debug or release.
Engine
To build the engine, open the XCode project engine.xcodeproj and build the neoengine target. The final library will be named libneoengine.a and is installed in /lib/<buildconfig>.
Application
To build the application utility library, open the XCode project application.xcodeproj and build the neoapplication target. The final library will be named libneoapplication.a and is installed in /lib/<buildconfig>.
Tools
To build the tools, open the XCode project tools.xcodeproj. This project contains the toolslib utility library, and the various tools applications. Choose the appropriate target and build (the applications depend on the toolslib target, so it is safe to build the applications directly). The final libraries will be installed in /lib/<buildconfig> and the applications in /bin/<buildconfig>.
