This document will provide some basic steps for building GTATools from source.
You should know in advance that gtatools is relatively difficult to build, so it will take some time and you might run into problems. You will still need some knowledge of building stuff from source. Be prepared to deal with errors and frustration, and bring some patience. Building gtatools is not for the faint of heart!
If you run into problems, first try to understand the error and try to fix it. Look at the section called "Troubleshooting" further down this document, it contains a few common errors and how to deal with them. If you can fix the error neither that way nor through googleing, feel free to send me an E-Mail or post in the GTA Forums thread.
Your mileage may vary.
You will need some tools to build gtatools. First, you will need a recent C++ compiler. On Linux, you should use GCC. I usually use GCC 4.9, although 4.8 and a few earlier versions should work fine. On Windows, you can either use a recent version of MinGW-w64 or Visual Studio 2013. The original MinGW (at least as of the time of this writing) as well as earlier versions of Visual Studio (definitely) will not work. The reason why you need such recent compilers is that gtatools uses lots of C++11 features that only modern compilers support.
To get gtatools' source code, you can try to download a snapshot from the GitHub page. But especially if you are on Linux, I recommend you check them out using Git instead. On Ubuntu, you can install Git like this:
sudo apt-get install git
You will also need at least CMake 3.0. You can download a binary for your system, or compile it from source.
If you are lucky, your distribution might have CMake 3.0 in their package repositories. At the time of this writing, even Ubuntu 14.04 still has only version 2.8 though.
You can compile CMake from source, or download the binary from their site. If you have an x86_64 system and downloaded the 32-bit version, you might need to download some 32-bit libraries first. On Ubuntu 14.04, you could try something like this:
sudo apt-get install libc6:i386 libsm6:i386 libxi6:i386
First, you will need to get the source code for gtatools. We will use the command-line version of Git here, although you could also download a snapshot directly from GitHub.
First, make a clone of the gtatools repository:
git clone https://github.com/alemariusnexus/gtatools.git gtatoolsSecondly, we will also clone the nxcommon repository (also on GitHub here). We will put it into the src subdirectory of the repository we just checked out:
cd gtatools/src
git clone https://github.com/alemariusnexus/nxcommon.git nxcommon
If you downloaded the snapshot from GitHub instead, just unzip it in that directory.
You should now have a directory nxcommon along with the likes of libgtaformats or libgta. libnxcommon will now be compiled automatically along with gtatools.
If you have never used CMake before, here's are some tips: The easiest thing is to use the GUI version called cmake-gui. When you run it, you must enter a directory for the source code (source directory) and one for the binaries (build directory). When you want to build a package with CMake, select the top-level directory that contains a file called CMakeLists.txt from its source package as the source directory. The build directory is where the binaries will be created and you can choose any empty directory for it.
You can then hit the configure button and select a generator and compilers. Choose what suits you. On Linux, you might want to use Unix Makefiles, on Windows maybe Visual Studio 2013 or MinGW Makefiles.
CMake will then present you with a big table of name-value pairs. These are variables, and you can use them to configure all kinds of options for the build (similar to the options of configure scripts on traditional Linux build systems). You can change them and then hit the "Configure" button again to apply changes.
Some useful CMake variables are CMAKE_BUILD_TYPE, which specifies the type of build (Debug/Release) you want to use. There's also CMAKE_INSTALL_PREFIX, which specifies where the libraries/programs/headers should be installed, e.g. when running make install. With Makefiles, if you get an error while running make and you want to know more about the actual commands executed by CMake, try enabling CMAKE_VERBOSE_MAKEFILE, which will especially show the compiler commands that make runs.
CMake will also show you a console with output from the configure process. Don't panic when you see some error messages there. You will probably have to change some CMake variables to tell CMake where to find external libraries, headers and the like.
You will most probably also have to enable advanced mode in CMake with the checkbox in the top-right of cmake-gui. This will show you lots of variables that were hidden before.
When you are finished setting up the CMake variables, and the configure process runs through without any errors, you can git the Generate button to create the actual build files (e.g. Makefiles or Visual Studio project files).
If you are using Windows, you can use the prebuilt dependencies linked on the main site.
The dependency package does not include Qt5. You will still need to download the Qt5 SDK, but they provide a very good binary SDK, so that's quite easy to install. See the section on Qt in the Linux paragraph below for more info.
You can try to fetch them yourself, but you will have to compile most of them from source, which is not funny at all. Believe me, I did it...
I don't provide prebuilt binaries for Linux because there are lots of small differences between Linux distributions and supporting them all is not easy. The following is a basic guide to get them all working. I will use Ubuntu 14.04 here, so you might have to change the commands and package names to suit your distribution.
Some libraries and stuff can be fetched from the package repository. Try:
sudo apt-get install build-essential libicu-dev liblua5.2-dev libcegui-mk2-dev libbullet-dev libglew-dev libsdl1.2-devDepending on which parts of gtatools you will build, you might not need all of them. If you only need libgtaformats for example (the library that contains all the GTA file support classes, but not the engine), you will only need build-essential and libicu-dev here.
Now we need to compile some packages from source.
libsquish is needed for all of gtatools, unless you don't want support for DXT-compressed TXD textures. The engine in libgta can support them without libsquish on virtually all modern GPUs, but gtatxd and gtatools-gui need it, among others.
Download libsquish here. At least until including version 1.11, libsquish has a tiny error in its source code that will prevent it from being built. You can apply this patch to it by running the following in the squish source directory:
patch < squish-climits.patchAlternatively, just add the line
#include <climits>on top of squish.h
Then you can compile it as usual, which will create the file libsquish.a:
make
If you want to use libgta (or gtatools-gui / gtatools-test, which build up on libgta), you will need the Bullet physics library. You need at least version 2.82. 2.81 will not work because of some experimental code in libgta (although you could probably just disable that code in libgta, it is not used yet anyway). Unless you are very lucky, you will therefore need to compile Bullet from source, too.
Generate the Makefiles using CMake in the usual way. You should turn off variables like BUILD_DEMOS, BUILD_CPU_DEMOS, BUILD_EXTRAS, USE_GLUT, USE_GRAPHICAL_BENCHMARK to eliminate sources of errors and speed up the compilation.
Then build it from the build directory the usual way:
makeYou can also install the resulting libraries and headers somewhere on the system (depending on where you install them, you might need to do this as root):
make installBullet's libraries are called libBulletCollision.a / .so, libBulletDynamics.a / .so, libLinearMath.a / .so and so on (.lib / .dll on Windows).
You need Google Test only when you want to built the automated unit test programs nxcommon-test and gtaformats-test (not gtatools-test!), which are disabled by default.
Download Google Test here. Generate the Makefiles using CMake in the usual way. Then, go to the build directory and run
makeThe build directory will now contain the libraries libtest.a and libgtest_main.a.
You need Qt only when you want to use gtatools-gui (the GUI tool that can display all kinds of GTA files and edit a few of them). All other stuff, including libgtaformats, libgta and gtatools-test don't need Qt. Both Qt5 and Qt4 are supported.
You can download Qt from the package archives of your system, but we will use the Qt5 SDK here, which is a bit easier to use with CMake. You can download it here. Just install it anywhere on your system.
Now that you have all the dependencies, you can try to configure gtatools in CMake. Set up an empty build directory and use the root folder of gtatools' repository as source folder. Don't panic, you might see quite a lot of errors. We have to change some variables to make it work.
If you use one of my prebuilt dependency packages, CMake will find many of the libraries automatically, but you have to add a new CMake variable to make this work. To do so, choose "Add Entry" on the top-right of cmake-gui and then add a variable of type PATH called CMAKE_PREFIX_PATH and set its value to the path of the unpacked dependency package's root directory (the directory containing bin, include and others).
First, you might want to change the CMAKE_BUILD_TYPE to "Debug", which helps a lot with debugging. You can then select which components of gtatools you want to build. if you only need libgtaformats, you can uncheck LIBGTA_BUILD, GTATOOLS_GUI_BUILD, GTAIMG_BUILD, GTATXD_BUILD and others. Some tools are disabled by default. For example, if you want to try gtatools-test (the demo program for the engine), enable GTATOOLS_TEST_BUILD.
If you want to use libgta or any other part of gtatools that depends on it, you will have to set NXCOMMON_BULLET_SUPPORT to on. If you want to use gtatools-gui, you will have to set NXCOMMON_QT_SUPPORT to either qt4 or qt5, depending on the version of Qt you're using. You might also find it helpful to enable NXCOMMON_EXCEPTION_POSITION_INFO, which will include a backtrace when exceptions are thrown on Linux.
You might also want to setup CMAKE_INSTALL_PREFIX to point to a directory in which gtatools will be installed. For Linux, you could use /usr/local or something in your home directory. On Windows, just anywhere on your disk.
Finally, and this is probably the most tedious part, you will have to tell CMake where to find the external libraries (dependencies). Look at the error messages from the configure process to find out which of these dependencies CMake did not find automatically. You will have to edit some *_LIBRARY variables to point to the *.a / *.so (Linux) or *.lib / *.dll (Windows) files of these libraries, and some *_INCLUDE_DIR variables to point to the include directory containing the headers of these libraries.
On Windows, if you use the precompiled dependency package, look for libraries in the lib folder of the dependency package, and include directories in the include folder.
For libraries that you built yourself, look for the .a / .so (Linux) or .lib / .dll (Windows) files in the folder you built them in. The include directory is usually their source folder or a subfolder called "include" (or similar).
As an example, to find the ICU libraries, search for files like libicuuc* and libicudata* / libicudt*. On Linux, if you have the locate utility installed, you could try something like this (some lines of output included):
alemariusnexus@nx-main:~$ sudo updatedb
alemariusnexus@nx-main:~$ locate libicuuc
/usr/lib/i386-linux-gnu/libicuuc.so.52
/usr/lib/i386-linux-gnu/libicuuc.so.52.1
/usr/lib/x86_64-linux-gnu/libicuuc.a
/usr/lib/x86_64-linux-gnu/libicuuc.so
/usr/lib/x86_64-linux-gnu/libicuuc.so.48
/usr/lib/x86_64-linux-gnu/libicuuc.so.48.1.1
/usr/lib/x86_64-linux-gnu/libicuuc.so.52
/usr/lib/x86_64-linux-gnu/libicuuc.so.52.1
alemariusnexus@nx-main:~$ locate libicudata
/usr/lib/i386-linux-gnu/libicudata.so.52
/usr/lib/i386-linux-gnu/libicudata.so.52.1
/usr/lib/x86_64-linux-gnu/libicudata.a
/usr/lib/x86_64-linux-gnu/libicudata.so
/usr/lib/x86_64-linux-gnu/libicudata.so.48
/usr/lib/x86_64-linux-gnu/libicudata.so.48.1.1
/usr/lib/x86_64-linux-gnu/libicudata.so.52
/usr/lib/x86_64-linux-gnu/libicudata.so.52.1
To find the include directory, try something like:
alemariusnexus@nx-main:~$ locate unistr.h
/usr/include/x86_64-linux-gnu/unicode/unistr.h
Using the example output of the locate commands above, you might change CMake variables as follows:
On Windows using the precompiled dependency package, the ICU libraries are called sicuucd.lib / sicudtd.dll.
Qt takes a bit of configuration. I will explain using the Qt5 SDK here. The process for Qt4 is different, if you use Qt4 or Qt5 without the SDK, just follow the error messages you get from the configure process.
You will first have to change the Qt5Core_DIR variable to a directory in the Qt5 SDK. On my computer, it is e.g. /home/alemariusnexus/Qt/5.3/gcc_64/lib/cmake/Qt5Core. Look for a similar directory in your Qt5 SDK. Afterwards, run the configure process again, and it will complain about variables Qt5OpenGL_DIR, Qt5LinguistTools_DIR and Qt5Widgets_DIR. You find these directories where you found the Qt5Core_DIR.
This should be enough for Qt.
Ok, the hardest stuff is done (probably). If you get some errors during compilation, there might be something wrong with your CMake configuration and you will have to adjust it. See the Troubleshooting section below.
If you use MinGW with Makefiles, follow the Linux guide below.
If you use Visual Studio, you can now open the Visual Studio project files in the build directory. gtatools.sln should contain all you need. You will get a storm of warnings: That's to be expected on Visual Studio, as long as there is no error among them.
You can now enter gtatools' build directory and just run
makeThis can take a few minutes to compile. You may want to use the -j option to enable multi-core support in make, which will speed up build time drastically. On my Intel Core i7 Quad-Core processor, I'm using
make -j9You can then install gtatools to the location you have set up in CMAKE_INSTALL_PREFIX (maybe as root):
make install
Congratulations, you have successfully built gtatools.
Here is a random list of some problems you may run into while building gtatools, and hints on how to fix them:
error: #error "You must build your code with position independent code if Qt was built with -reduce-relocations. " "Compile your code with -fPIC or -fPIE.You should add the option -fPIC to CMAKE_CXX_FLAGS and configure, generate and run make again.
error: ´kF_UseSubSimplexConvexCastRaytest´ is not a member of ´btTriangleRaycastCallback´Then you are using an old version of Bullet. As stated above, you will need at least Bullet 2.82.