Linux Application Development

• Linux 2.6.x
• GCC 4.x.x
• Python 2.7
• SCons 2.2.0
• distcc (optional)
• ccache (optional)

To install all required Debian/Ubuntu packages, use the following:

sudo apt-get install linux-headers-2.6 gcc g++ make scons ccache libgl1-mesa-dev libxrandr-dev libxrandr:i38 libxinerama-dev libopenal1 libxrender-dev libxext-dev libc6-dev libx11-dev 

username@pc-name:~$ cd /usr/lib/x86_64-linux-gnu
username@pc-name:~/usr/lib/x86_64-linux-gnu$ sudo ln -s libXrandr.so.2 libXrandr.so	
					

For 64-bit Debian/Ubuntu, install additional packages to enable 32-bit cross-compilation:

sudo apt-get install gcc-multilib lib32gcc1 ia32-libs ia32-libs-dev lib32stdc++6 libc6-i386

1. Unpack the Unigine archive into a target directory, for example ~/UnigineSDK.
2. Run the install.py script to set Unigine development environment. (If installation was successful, uninstall.py script will appear).
   Shell commands

   username@pc-name:~$ cd UnigineSDK/
   username@pc-name:~/UnigineSDK$ ./install.py
   
   [ Unigine SDK installation script ]
   
   Do you really want to proceed with install? [Y/N]: y
   

   Notice

   In fact, this script only changes the following environment variables:

   • Adds to $PATH variable locations of the following directories: <UnigineSDK>/externs/bin;<UnigineSDK>/lib;<UnigineSDK>/bin.
   • Adds to $LD_LIBRARY_PATH variable locations of the following directories: <UnigineSDK>/externs/bin; <UnigineSDK>/lib.
3. Re-login to make the changes in ~/.profile take effect.
   Notice

   Make sure that your terminal takes environment variables into account.
   From the Terminal main menu, choose Edit > Profile Preferences > Title and Command and check Run command as a login shell box.

Apart from developing your project with UnigineScript, you can also customize the Unigine application C++ code. What exactly is available for customization depends on the version of Unigine SDK:

• With the limited binary/evaluation version you can only modify the following components:
  1. C++ plugins for the engine.
  2. The source code of Unigine-based sample applications.
  You can also modify the source code of Unigine Editor and high-level scripts (just like all other scripts, they do not require recompilation).
• If you have the full source version, you can modify the entire Unigine codebase:
  1. The C++ source code of the engine itself.
  2. All Unigine standalone tools.
  3. C++ plugins for the engine.
  4. Plugins for 3D editors.
     Notice

     You can build plugins for 3D editors only on Windows.
  5. The source code of Unigine-based sample applications.

After customizing the code, recompilation of Unigine application or its libraries is required.

To recompile both the Unigine engine (i.e. the dynamic library libUnigine_*.so) and application on its base (i.e. the binary executable main_*), you can use one of the following options. For Linux, 32-bit or 64-bit, debug or release, single or double coordinates precision versions can be compiled.

• For semi-automated compilation via the Build script (recommended):
  1. Open the console.
  2. Go to <UnigineSDK>/utils/ folder.
  3. Run the build.py.
     Shell commands

     username@pc-name:~$ cd UnigineSDK/utils
     username@pc-name:~/UnigineSDK/utils$ ./build.py

     By default, a Unigine library, a binary executable and a network plugin (release, single-precision versions) will be build for the native platform.
     You can change building options, if required. For example, to build the 32-bit double-precision version of the engine and all standalone tools, run the script with the following options:
     Shell commands

     username@pc-name:~/UnigineSDK/utils$ ./build.py --component=all --type=debug --bits=32 --precision=double

• For manual compilation via SCons (see the details):
  1. Open the console.
  2. Go to <UnigineSDK>/source/app/main directory.
  3. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER.
     Shell commands

     username@pc-name:~$ cd UnigineSDK/source/app/main
     username@pc-name:~/UnigineSDK/source/app/main$ scons

     By default, the debug, single-precision version of Unigine library and the binary executable will be built for the native platform.
     Notice

     After compiling for the first time, SCons automatically checks whether any modifications were made to the source engine code and recompiles the library only if necessary.

To run the built Unigine application, you need to specify compulsory start-up options (see details below).

To rebuild engine C++ plugins, perform one of the following:

• To rebuild a plugin automatically together with the engine, use the Build script. For example, to reduild the Network use the following:
  Shell commands

  username@pc-name:~/UnigineSDK/utils$ ./build.py --component=engine --plugin=Network --type=release --bits=32 
  							

• To rebuild a plugin manually, use SCons:
  1. Go to the required directory inside <UnigineSDK>/source/plugins via the command line.
  2. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER to build with SCons.

  For example, to rebuild the Network plugin manually, perform the following:

  1. Go to <UnigineSDK>/source/plugins/Network directory via the command line.
  2. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER to build with SCons (see the details on available Network options).
     Notice

     To be run, the Network plugin requires setting -extern_plugin Network at the start-up (see details below).

To recompile the Unigine standalone tools (ResourceEditor, ImageDDS, Archiver, XmlTree, etc.), do one of the following:

• For semi-automatic compilation, use the Build script (recommended).
  Shell commands

  username@pc-name:~/UnigineSDK/utils$ ./build.py --component=tools --type=release --bits=32

• For manual compilation via SCons (see the details):
  1. Go to one of the directories inside <UnigineSDK>/source/tools/.
  2. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER to build the application (the binary executable).

Some specific functionality is not supported by the main Unigine application (for example, stereo rendering onto separate output devices, etc.) For that, you need to recompile separate binary executables.

To rebuild task-specific applications, perform one of the following:

• To rebuild, for example, an AppWall application automatically by using the Build script, perform the following:
  Shell commands

  username@pc-name:~/UnigineSDK/utils$ ./build.py --component=engine --plugin=AppWall --type=release --bits=32
  						

• To rebuild a task-specific application manually, use the following:
  1. Go to the required directory inside <UnigineSDK>/source/app/ via the command line.
  2. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER to build the application.
     Notice

     To be run, the application requires settings at the startup (see details below).
  For example, to recompile AppWall application (appwall_*) for several monitors (up to 6):
  1. Go to <UnigineSDK>/source/app/AppWall directory via the command line.
  2. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER to build the application.
  Notice

  See more details how to compile AppWall with a custom number of monitors and set them up.

Into Unigine SDK there are included sample applications that can be modified and used as templates to create your own applications.

• To rebuild GLAppSDL application that creates an SDL-based application and renders Unigine viewport into it in OpenGL mode:
  • Go to %UNIGINE_DIR%/source/samples/App/GLAppSDL directory.
  • Build with GNU Make using Makefile.
• To rebuild GLAppQt application that renders Unigine viewport into the Qt window in OpenGL mode:
  • Go to %UNIGINE_DIR%/source/samples/App/GLAppQt directory.
  • Run qmake tool by typing qmake.
  • Run make tool by typing make.

While Unigine scripts do not require recompilation, you may want to recompile the startup C++ code for your project that initializes the application runtime:

1. Go to <UnigineSDK>/source/app/main directory.
2. Customize main.cpp, if necessary.
3. Compile the application via SCons (see the details). SCons automatically checks whether any modifications were made and recompiles the application together with the engine only if necessary.
   Shell commands

   username@pc-name:~/UnigineSDK/source/app/main$ scons

Building the final release version of your application includes several additional steps, if compared to a development version. Here is the typical workflow:

1. Copy the development version of your project into a separate folder.
2. Prepare the final content to be used:
   1. To prevent the users from accessing the console, disable it by setting engine.console.setLock(1).
   2. Prepare the release version of configuration file.
   3. Compress all textures using ImageDDS tool.
   4. Delete all uncompressed textures.
   5. Delete VCS files.
   6. Compress XML files into a binary format using XmlTree tool. Binary format is more compact and is parsed faster.
   7. If necessary, pack your resources into ZIP or UNG using Archiver tool.
      Notice

      Archived resources can also be streamed. But it is strongly not recommended to archive terrain files, otherwise it will load with lags.
3. If necessary, cache the source code written in UnigineScript.
4. If necessary, rebuild the release version of Unigine engine (the binary executable together with dynamic libraries). You can skip this step if you did not modify the engine source code. Instead, use pre-compiled engine files included in the SDK. (Find them under <UnigineSDK>/bin and <UnigineSDK>/lib folders, respectively).
5. If necessary, use a launcher for your application. In case your project was created via the project generator in the SDK browser (New Project tab), you can use the generated launcher. Otherwise you can create your own launcher on basis of our realization. In this case, you can specify the following information in the application startup script (e.g. a shell script):
   • The binary executable to be used
   • Configuration file (with application screen resolution and other project settings) to be used
   • Path to the custom system script unigine.cpp (see the details)
   • Project to be loaded (name of the world)
   • Path to the Unigine default data (with all required shaders, default materials, properties, Unigine Editor scripts, etc.)
6. If necessary, make an installer that will install your application together with all dependencies.

To use C++ plugins after building them, you need to specify extern_plugin command line argument on the start-up. (The path is specified relative to the binary executable).

-extern_plugin plugin_name