Skip to content

Compiling The Code

Jump to bottom
Brett Anthony edited this page Jul 3, 2019 · 3 revisions

NOTE: if you'd rather not deal with the hassle of compiling code (we get it) grab a binary for your system from our releases page.

Table Of Contents

  1. Compiling For Windows
  2. Compiling For Linux

Compiling For Windows

Prerequisites

  • git-scm
  • cmake (minimum version 3.14)
  • C++ Compiler Supporting C++11 (we will assume you're using Visual Studio)
  • (optional) C Compiler (most C++ compilers double as C compilers) for running tests
  • (optional) git lfs for running tests

First clone the repository using some Windows git tool such as git-scm.

git clone https://github.com/xNWP/xTGA

After cloning the repository you will need 'cmake' to generate the project files, a minimum version of 3.14 is required but we recommend you always use the latest version. To keep the source tree clean you'll want to create a new folder inside the root directory, we recommend starting the folder name with build to exclude the folder from git.

Navigate to your build folder and generate the build files. The general form of this command assuming your build directory is a subdirectory of the root repository folder is:

cmake ..

If Visual Studio is installed this will typically build files for the latest version of Visual Studio found on the system by default. You may want to change the IDE the project is generated for as well as the target architecture (32/64 bit), some examples of different architectures with different versions of Visual Studio are below (notice that the default architecture is not always obvious, nor is the way to change it to the desired architecture).

For Visual Studio 2019 64-bit
  cmake -G "Visual Studio 16 2019" ..

For Visual Studio 2019 32-bit
  cmake -G "Visual Studio 16 2019" -A Win32 ..

For Visual Studio 2017 64-bit
  cmake -G "Visual Studio 15 2017 Win64" ..

For Visual Studio 2017 32-bit
  cmake -G "Visual Studio 15 2017" ..

After generating the project files, open the resulting TGA.sln file. At the top of Visual Studio you can now select the desired configuration.

Visual Studio Configurations

  • Debug will generate binaries with debug information and no optimizations, this is great for testing with but should not be selected for release software as it will not work on most end-user machines which lack debugging libraries.
  • MinSizeRel will generate binaries for distribution that optimize for minimal size.
  • Release will generate binaries for distribution that optimize for speed (this is the recommended).
  • RelWithDebInfo will generate binaries that optimize for speed but also contain debug symbols, this is great for profiling the library (or anything that uses the library) while still allowing you to debug the library.

After selecting your desired configuration you can decide which version/aspects of the library you'd like to build on the left in the Solution Explorer. Your list of projects may differ from the image below depending on the library version / my willingness to keep this wiki updated :-)

Visual Studio Targets

To build the library as a shared library build the xTGA project. To build the library as a static library build the xTGAs project (the 's' means static, pretty clever I know ツ). Or you can build the ALL_BUILD project which will build both versions of the library as well as all the test executables.

After compiling the library you may also want to build the RUN_TESTS project which will run a few tests to verify that the library hasn't gone horribly wrong at some point, this requires git lfs as the images are hosted using it. The output of the tests will be printed to the Output window of Visual Studio, all you're looking for is '100% tests passed'.

Alternatively you can build the project from the command line with cmake. From your build folder you can execute these commands:

Build all in the default configuration (Debug)
  cmake --build .
Build all in the Release configuration
  cmake --build . --config Release
Build just the shared library in Release configuration
  cmake --build . --target xTGA --config Release

You can also run the tests from here with the added benefit of the --verbose command which will print some helpful information about where and how a test failed (if one does).

ctest --verbose

That's it that's all! Your compiled binaries will be contained within their respective configuration folder, i.e. Release if you compiled with the Release configuration.

Compiling For Linux

Since there are many flavors of Linux out there we will be assuming that you are running a modern version of Ubuntu.

The first thing you'll need is git, if you plan on running the included tests you will need a version of git that git lfs, git >= 1.8.2.

sudo apt-get install git

(optional for tests)
sudo apt-get install git-lfs

If you do want to run the tests and installing git-lfs fails read this.

You will also need cmake, you will need at least version 3.14. However most PPA's unfortunately don't have this version, you can simply download the package from their website.

Also needed is a C++ Compiler Supporting C++11 (we use g++-9 which is included in the ubuntu-toolchain-r-test PPA)

sudo add-apt-repository ppa:ubuntu-toolchain-r-test && sudo apt-get install g++-9

(optional) you will need the some additional libraries for g++ to enable compiling for 32-bit systems.

sudo apt-get install g++-9-multilib

(optional) you will need a C compiler to compile the tests, we use gcc-9 (as well as its related 32-bit libraries).

sudo apt-get install gcc-9
sudo apt-get install gcc-9-multilib
sudo apt-get install linux-libc-dev:i386

(depends) you will need some sort of build system, we will be using make for this example but you can also use something like Ninja if you prefer it.

sudo apt-get install make

Now with that out of the way we are ready to generate some project files! For the sake of this guide we will be generating Unix Makefiles. First you will need to clone the repository somewhere.

git clone https://github.com/xNWP/xTGA

Navigate into the repository and create a folder for your build files, we recommend starting the folder name with build to exclude the folder from git. Navigate into the your build folder and run either of the two cmake commands below depending on your desired architecture.

For 64-bit binaries
  cmake ..
For 32-bit binaries
  cmake -DCMAKE_TOOLCHAIN_FILE=x86-toolchain.cmake ..

Once cmake finishes, you will have a Makefile. Typing make help will give you a list of all possible targets that can be built.

Ubuntu Make Targets

  • all will make the xTGA shared library, the xTGAs static library, and all tests (it will not run them however).
  • xTGA will compile the library as a shared library.
  • xTGAs will compile the library as a static library.
  • test will run the tests.
  • clean will clean the directory of build files, and the intermediate directories of object files.

We will simply run make for this example, which will perform the all target. During compilation you may notice a handful of warnings along the lines of...

warning: ‘xtga::structs::ImageDescriptor::<unnamed union>::<unnamed struct>::IMAGE_ORIGIN’ is too small to hold all values of ‘enum class xtga::flags::IMAGEORIGIN’

You can happily ignore this warning, it isn't entirely valid for the use case of the enum, and unfortunately there is no way to disable this warning with g++ or gcc.

After compiling we'll also run some tests, this is of course optional. You can simply run make test as discussed above, but we prefer ctest --verbose as it will enable you to see more precise information about where and why an error occurred (should one occur).

That's it that's all! Your compiled binaries will be contained in your build directory, libxTGA.so is the shared library while libxTGAs.a is the static library.

Clone this wiki locally