Download and Install

Prerequisites

Operating systems

Linux (Ubuntu, Scientific Linux, CentOS, Debian, ...) and MacOS X operating systems are supported. No support for Windows yet.

Basic software

You will need :

• git to download the sources
• CMake 3.13 or newer to configure the build
• a compiler supporting C++17
• if linked with ROOT, a ROOT version at least version 6.20

Getting the sources

TkN is available to download and build from source from our GitLab repository.

Let's suppose you plan to install TkN in the following directory:

cd /path/to/mysofts/TkN

The first time you download the source code, you need to clone the repository by typing the following command:

git clone https://gitlab.in2p3.fr/tkn/tkn-lib tkn-sources

This will create a directory called tkn-sources containing the source code. By default, the version of TkN in this directory corresponds to the latest commit on the prod branch.

To list the available TkN versions, use:

cd tkn-sources
git tag --sort=-version:refname

To use a specific release without creating a local branch, replace vX.Y with the desired tag:

git switch --detach vX.Y

Build and install

cmake configuration

In the folder TkN (see above section), create the build and install directories:

cmake -S tkn-sources -B tkn-build -DCMAKE_INSTALL_PREFIX=tkn-install

That should end with messages similar to:

-- TkN version: 2.6
-- TkN compiled with C++17
-- TkN compiled in Release mode
-- Install prefix: /path/to/mysofts/TkN/tkn-install
-- Looking for ROOT
-- ROOT found in /path/to/root/install
-- ROOT version: 6.36.04
-- Looking for SQLite
-- Configuring tksqlite3
-- Loading libraries
-- Configuring tkbase
-- Configuring tkdb
-- Configuring tkphysics
-- Configuring tkroot
-- Building user executables
-- Configuring tkn-print
-- Configuring tkn-db-update
-- Configuring tkn-root
-- TkN configuration complete
-- Configuring done (0.7s)
-- Generating done (0.0s)
-- Build files have been written to: /path/to/mysofts/TkN/tkn-build

Advanced options

The following user options can be given at the CMake configuration step (with default values):

option(USE_ROOT       "compile TkN using ROOT (if installed)"   ON)
option(DB_DOWNLOAD    "Download the SQL database at install"    OFF)
option(BUILD_EXAMPLES "Build example macros"                    OFF)
option(TKN_COLOR_OUTPUT "Use colors for important TkN CMake messages" ON)

For example, to build TkN without ROOT and install the SQLite database at the installation step, use:

cmake -S tkn-sources -B tkn-build -DCMAKE_INSTALL_PREFIX=tkn-install -DUSE_ROOT=OFF -DDB_DOWNLOAD=ON

Compile and install

cmake --build tkn-build --target install -jN

Replace N with the number of parallel build jobs to use.

Setting up the environment

After installing, source the environment script for your shell. It sets the paths used to find the TkN executables, libraries, database and CMake package:

# Bash or Zsh
source /path/to/mysofts/TkN/tkn-install/bin/thistkn.sh
 
# Csh or Tcsh
source /path/to/mysofts/TkN/tkn-install/bin/thistkn.csh

For Bash and Zsh, thistkn.sh also registers the TkN command completions installed under share/bash-completion/completions and share/zsh/site-functions. This works with a user installation prefix and does not require administrator privileges.

After doing this you should be able to do e.g.:

tkn-config --version
2.6

Downloading the database

The tkn-db-update executable allows you to download or update the SQLite database:

tkn-db-update --download
[ INFO     ] TkN_ensdf_YYMMDD_xundl_YYMMDD_v2.6.db installed in tkn-install/databases/

This step is not needed if the database has been downloaded during the installation process. The database is updated every month, following the ENSDF updates.

Interactive session

If TkN has been compiled with ROOT, you should be able to do:

tkn-root 
 _____    _   _   |  Documentation: https://tkn.in2p3.fr/
(_   _)  | \ | |  |  Source: https://gitlab.in2p3.fr/tkn/tkn-lib
  | |_  _|  \| |  |
  | | |/ /     |  |  Version 2.6
  | |   <| |\  |  |
  |_|_|\_\_| \_|  |  Database: TkN_ensdf_YYMMDD_xundl_YYMMDD_v2.6.db

If the database has not been downloaded during installation using the option -DDB_DOWNLOAD=ON or later using tkn-db-update, you will obtain the following message:

tkn-root 
[ ERROR    ] database::open(/Users/dudouet/Softs/TkN/test/tkn-install/databases/TkN.db,OPEN)
             can't open database: 'unable to open database file'
[ INFO     ] use tkn-db-update to download the database

In this case, as indicated, you need to use the tkn-db-update program to download the database.

Notes

• If ROOT is not detected, set ROOTSYS (and update PATH, LD_LIBRARY_PATH) before running CMake.
• Re-run the CMake configure step after changing options (e.g. USE_ROOT, DB_DOWNLOAD).