This page explains how to install PID. To be short, to use PID on your workstation you need to install a PID workspace somewhere on your filesystem. All commands will be explained in the context of a workstation with any Debian like Linux system (e.g. Ubuntu). We recommand using terminator terminal, or terminals with same splitting properties to facilitate the usage of PID in console mode. We also consider the usage of a gitlab server to manage repositories on server side but same process can be achieved with any tool supporting same functionnalities, for instance GitHub (https://github.com/).

Step 1 : installing dependencies on your workstation

There are few required dependencies for using PID:

  • {mandatory} CMake version 3.15.7 or more. Depending on your system this can be more or less fastidious. On debian like platforms you can do:
sudo apt-get install cmake
cmake --version #to check that version is at least 3.15.7

Otherwise, for instance if version is < 3.15.7, you can install cmake by hand. Go to CMake project download page and follows the instructions. Once unpacked you should simply have to register the binaries of CMake in the PATH of the system. Basically you should do something like that to register the project:

export PATH=/home/<name>/soft/cmake-3.15.7-Linux-x86_64/bin:$PATH

Don’t forget to put this command at the end of your .bashrc file so that you won’t have to do the same at each boot !

  • {mandatory} git, compatible with version 2.17.0 or more. On any debian like OS:
sudo apt install git
git --version #to check that version is at least 2.17.0
  • {mandatory but install step is optional depending if system packages provide it by default} git-lfs, compatible with version 1.0.1 and up.

Depending on your git version LFS may be already installed, otherwise you can install it by hand. Please visit git LFS project and install last version of git LFS using your preferred method.

On debian like system one of the simplest way for installing git LFS is to do:

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt install git-lfs
git lfs install
  • {mandatory} c/c++ build toolchain, should be natively available on linux and MACOSX.
sudo apt install build-essential

If you want to install a more recent version you can do, on debian like OS:

sudo apt install gcc-8

NB: you can use a newer version of gcc or even another compiler (e.g. clang is a good alternative).

  • Optional dependencies (recommended):
    • doxygen, compatible with version 1.7.6 or more.
    • lcov, compatible with version 1.12 or more.
    • cppcheck, compatible with version 1.72 or more.
    • clang-format, compatible with version 3.8 or more.
    • jekyll, compatible with version 3.0.1 and up. Mandatory if you intend to build frameworks static sites.

The all in one command on debian like systems:

sudo apt install doxygen lcov cppcheck clang-format jekyll

Step 2 : installing pid-workspace

Basically the pid-workspace official project is an online repository. It contains all CMake APIs and commands that are required to start working with PID. The install of PID basically consists in cloning this project on your workstation.

  • Choose a folder where to install pid workspace (we call it <path>):
cd <path>
  • Clone pid-workspace repository
git clone https://gite.lirmm.fr/pid/pid-workspace.git
  • Finally configure the project:
cd pid-worskspace
./pid configure

The following message should appear:

----------------------------------------------------- WARNING --------------------------------------------------
Consider sourcing the share/pid.sh script inside your workspace and use the pid command for better shell support

For the current session only run
    source /home/robin/soft/PID-test/pid-workspace/share/pid.sh

Then add the above line to your shell setup script
    echo "source /home/robin/soft/PID-test/pid-workspace/share/pid.sh" >> /home/robin/.bashrc
----------------------------------------------------------------------------------------------------------------

If it is the first time you deploy a workspace into your local station or if you never performed the script sourcing, simply follow the instructions given. This way the pid tool can be called as any program.

Otherwise, if you already installed a workspace, you can simply do:

cd pid-worskspace
pid configure

The standard output prints general information about the workspace. Something like:

...
[PID] INFO: using default profile, based on host native development environment.
[PID] INFO : ASM language available with gcc toolchain.
[PID] INFO : C language available with gcc toolchain (version 9.3.0).
[PID] INFO : C++ language available with gcc toolchain (version 9.3.0).
[PID] INFO : Python language available (version 2.7). To use python modules installed in workspace please set the PYTHONPATH to =/home/robin/soft/PID/pid-workspace/install/x86_64_linux_stdc++11/__python2.7__
[PID] INFO : CUDA language available (version 11.0). Building for architecture 6.1.
[PID] INFO : Fortran language available with GNU toolchain (version 5.5.0).

[PID] INFO : Target platform in use is x86_64_linux_stdc++11:
 + processor family = x86 (optimizations: SSE, SSE2, SSE3, SSSE3, SSE4_1, POPCNT, SSE4_2, FP16, FMA3, AVX, AVX2, AVX_512F, AVX512_SKX)
 + binary architecture= 64
 + operating system=linux (ubuntu 16.04, apt packaging)
 + C++ ABI= stdc++11

The output particularly prints information about detected features of your host system:

  • The target platform (in this example x86_64_linux_stdc++11). This is the platform for which the code will be built. A workspace may support the build for different platforms and can also deal with cross-compilation, but this is an advanced technique. For now only remember that there is a target platform that is, by default, automatically configured according to your workstation settings (processor, operating system and compiler), that is called the host platform.
  • The profile in use (in this example the default profile). A profile defines a set of user requirements on the host platform. Profiles may be used to define ways to cross-compile for different platform, use alternative compilers, etc. Usage of profiles is an advanced technique, for now remember that there is a default profile that is configured according to your workstation default settings.
  • available optional languages like CUDA, Fortran or Python. Remember that assembler (ASM), C and C++ are always available, otherwise configuration process would have crashed.

PID is now installed on your system and ready to be used ! You can repeat this step to install many instances of the workspace if you want to work on isolated projects.

You can now start learning how to use PID

Contributing to the pid-workspace project (advanced users only)

If you want to provide some modifications to the pid-workspace project (https://gite.lirmm.fr/pid/pid-workspace) and you are not part of the official developpers team, you need to either:

  • fork the official repository. You will be the owner of that new workspace project called a private workspace and be so allowed to invite people and determine their access rights. To fork a workspace, simply go to the official pid workspace or any other mirror repository in the git hosting service you are using (for instance github mirror) and use its fork functionality. As a result you have now a private workspace with same name (pid-workspace), but under your own account (or a group/company account you have rights to write in) where you can push some modifications and propose merge requests to the official workspace. To work locally simply clone the private workspace:
git clone git@gite.lirmm.fr:own/pid-workspace.git
cd pid-worskspace
pid configure

Where own is supposed to be a namespace where you can fork the project in the current git hosting service.

You will still be capable of getting upgrades of the APIs while your private workspace gives you the possibility to push and propose merge request for APIs modification.

  • join a private workspace. If you want your collaborators to test the modifications you made to the API (this is most of time usefull before proposing a merge request to the official workspace), let them:

    1. directly clone your private workspace in their workstation, or clone a fork of your private workspace (if you need them to be able to publish some patches whithout being a developper of the private workspace).
    2. configure their local repository
git clone git@gite.lirmm.fr:own/pid-workspace.git
cd pid-worskspace
pid configure -DPID_OFFICIAL_REMOTE_ADDRESS=git@gite.lirmm.fr:own/pid-workspace.git

The configuration differs a bit there with the line:

pid configure -DPID_OFFICIAL_REMOTE_ADDRESS=git@gite.lirmm.fr:own/pid-workspace.git

The CMake variable PID_OFFICIAL_REMOTE_ADDRESS is used to configure the workspace to make it update from another repository than default official one. Consequently users of a private workspace can get the latest modifications of PID APIs that are currenlty developped and not latest modifications of the official workspace. This is important to keep the development on APIs isolated from any modification of the official workspace, and so avoid potential conflicts during development of modifications. The merge of modifications coming from official workspace and those developped in a private workspace must be made by developper team of the private workspace before they provide a merge request.