TPCCLIB
Installing tpcclib

Programs that are currently included in TPCCLIB are listed in http://www.turkupetcentre.net/petanalysis/tpcclib/doc/.

Installing the programs (binaries) for use

Download the binary installation package for your platform, using the links on the download page. Open the ZIP or GZ package, open bin folder in it, and extract the applications that you need (or all of them) to a folder in your computer. You may need to tell your operating system to search the target path for applications.

See more detailed instructions for Windows, Linux, and macOS.

Installing from the source code package

The process is tested in Windows 10, macOS, and Ubuntu and Fedora Linux.

Install command line tools for compilation

Installing of the C compiler is out of the scope of this documentation. You will need root (administrator) access to the computer. Some instructions on setting up the development environment are given for Linux and Windows.

In macOS you have to install Xcode from the App Store; you must register yourself as Apple Developer (registration is free). The Xcode package is several gigabytes in size and will take awhile to install; then you need to launch Xcode and sign in; after that you can exit Xcode, because building will be done in bash window (Terminal).

CMake

If CMake is not previously installed, then in Windows and macOS download the binary package from http://www.cmake.org and install it as usual. In Linux, download and install CMake using package manager:

sudo apt-get install cmake

You can use 32-bit version of CMake to build configurations for 64-bit software on 64-bit platforms.

In macOS you need to add CMake binary folder /Applications/CMake.app/Contents/bin to you $PATH environment variable, for example in file ${HOME}/.bash_profile: Move into your home directory and edit or create file .bash_profile

cd
nano .bash_profile

and edit or write the macOS PATH setting line to contain the CMake path, for example:

export PATH="/Applications/CMake.app/Contents/bin:$PATH"

Then save the file in nano by clicking 'control'+'o' and confirm the name of the file by hitting return. Exit nano with 'control'+'x'. Relaunch the macOS Terminal, and verify that contents of $PATH are correct, and that cmake can be found:

cmake --version

Download TPCCLIB source code

Clone the source codes from Git repository, or download the source code package and extract the files on your computer.

Clone from Git repository

Create folder tpcclib for source codes and building, and clone the sources of a specific TPCCLIB release:

cd
mkdir tpcclib
cd tpcclib
git clone --depth 1 --branch v0.7.2 https://gitlab.utu.fi/vesoik/tpcclib.git

Change the version number in the --branch option to the latest release. If you want to build the most recent source code versions (not recommended for production use), then leave out the option --branch v0.7.2. If you are a programmer and plan to edit the source codes and commit the changes, you should leave out both options.

Compilation

The Git commit above wrote the source codes into folder ~/tpcclib/tpcclib/. Create the build path(s), not under the source path, and not under network folders, or shared folders in virtual machine, because that would lead to "Clock skew detected" warnings and incomplete or failed compilation.

If you are building executables for the current operating system only, then the recommended directory structure is this:

tpcclib
├───tpcclib
└───build

If you will build executables for Linux and Windows and/or both 32- and 64-bit systems, then create separate build folder for each system:

tpcclib
├───tpcclib
├───linux
├───win64
└───win32

Move into the build directory, and then run cmake command, specifying the source path (in this example ../tpcclib), and optionally (-G) the make system generator (run cmake --help to see available options). See below for examples.

Then run make (in Linux, macOS, and Git for Windows bash shell with GCC):

make install

Running command make install creates the program executables (binaries) in your build directory under folder bin but does not copy them to a directory where they would be seen by your operating system. You can either change the CMake settings to specify another installation folder (see below), or or use the binaries from that folder, if you add the folder into PATH. For example in macOS you could again edit the file ${HOME}/.bash_profile:

cd
nano .bash_profile

to contain line:

export PATH="$HOME/tpcclib/build/bin:/Applications/CMake.app/Contents/bin:$PATH"

You can also create the source and binary packages for distribution to other computers.

Setting installation path

Installation directory is set to the current working directory in CMakeLists.txt. You can change the path by changing the line

set(CMAKE_INSTALL_PREFIX ".")

, or you can remove the line: then cmake installs binaries to the default directory, which is /usr/local on UNIX/Linux and c:/Program Files on Windows. You can also set the installation directory from command-line when executing cmake, for example:

cmake -D CMAKE_INSTALL_PREFIX=/c/bin ../tpcclib

Notice that if you toggle compiler define options with -D, like above, the Makefile system does not recognize such a change. If you change definitions, then make clean.

Compiling for 32-bit Windows

In 64-bit Windows you may want to compile executables for 32-bit Windows, too. Specify the necessary compiler option '-m32' in the command-line for cmake. For example in Git bash:

cd ~/tpcclib/win32
cmake -G "MSYS Makefiles" -D CMAKE_C_FLAGS:STRING="-m32" ../tpcclib

Testing

After successful make install, you can test the library and applications. Please read the separate page on testing. Compiling and testing takes about 10 min on a modern laptop with SSD and quad-core i7 CPU.

Creating TPCCLIB documents

Create Doxygen documentation for the library, if necessary, by first moving to the source code directory, and then executing doxygen in each of the main source folders:

cd ~/tpcclib/tpcclib
doxygen
cd v1
doxygen
cd v2
doxygen

If usage information for the individual programs are required, then copy the script makedoc.sh from the source path into build directory, and run it:

cd ~/tpcclib/build
./makedoc.sh

After this the directory structure will be something like this, depending on the operating systems for which you have built the programs:

tpcclib
├───packages
├───tpcclib
├───tpcclib-doc
├───linux
│   ├───bin
├───win64
│   ├───bin
│   └───doc
└───win32
    └───bin

Distributable source and binary packages will be located in packages folder, library documentation in tpcclib-doc folder, usage information for binaries in win64/doc and compiled binaries in the bin folder(s).

Examples

GNU Linux, macOS, and Bash on Ubuntu on Windows

cd ~/tpcclib/build
cmake ../tpcclib
make -j 2 install
ctest --output-on-failure --parallel 2
cpack --config CPackConfig.cmake
cpack --config CPackSourceConfig.cmake

Options -j 2 and --parallel 2 in the example above speed up the process by using two processor cores or threads simultaneously.

Windows with Git bash on Windows

Using GCC from Equation Solution:

cd ~/tpcclib/build
cmake -G "MSYS Makefiles" ../tpcclib
make -j 2 install
ctest --output-on-failure --parallel 2
cpack --config CPackConfig.cmake
cpack --config CPackSourceConfig.cmake

Notice that make is used without option -j 2 in this example; parallel compiling may or may not work in Windows.

The previous commands create 32-bit binaries in a 32-bit platform and 64-bit binaries in a 64-bit platform. To make distributions for 32-bit Windows in a 64-bit platform:

cd ~/tpcclib/win32
cmake -G "MSYS Makefiles" -D CMAKE_C_FLAGS:STRING="-m32" ../tpcclib
make install

If CMake stops with error sh.exe was found in your PATH, you can comment out this check from file CMakeMinGWFindMake.cmake, which is located in the CMake directory, for instance in path C:\Program Files\CMake\share\cmake-3.15\Modules\. The error message gives the detailed path of the file to edit. Alternatively, you can rename the sh.exe in C:\Program Files\Git\usr\bin\ (or similar) to for instance sh-git.exe.

If you get problems with F-Secure or other virus scanners in Windows with gcc, it may help to include link option -s to remove all symbol table and relocation information from (temporary) executables. For example:

cmake -G "MSYS Makefiles" -D CMAKE_C_FLAGS:STRING="-m32 -s" ../tpcclib

More about CMake

The Makefile created by CMake is robust if you make source file changes, and it can manage complex module dependencies. Only if the project is altered you will have to re-run Cmake so that the new addition gets included. There are however cases where you should rebuild all the source. For example, if you toggle compiler define options (-D), then make clean before compilation.

If you run into problems you should consider removing the contents of the build directory and starting over.