Basic concepts

A wrapper is the deployment unit used to import an external project into the PID environment: it is in the same time a CMake C/C++ project and a git repository. It basically contains:

  • git version control information.

  • CMake projects files used to :

    • download and build the source code of the external project.
    • install its resulting binaries in the workspace.
    • generate an installable relocatable archive that can be managed into a PID workspace.

The main idea is that a wrapper is self-explanatory. It does not means it contains all code and artefacts it uses but it contains all information needed to satisfy its dependencies. In other words considering a given wrapper, its installation process is done using this information and the information contained in its dependent packages.

An external package wrapper provides some functional code that can be reused (libraries, executables, header files, scripts, etc.) and depends on other packages either for its compilation (e.g. archive libraries, header files) or for its runtime use (dynamic libraries, executables, script-like files).

A wrapper has two main different forms :

  • a source form. In this form, the wrapper is a git repository that contains the external package’s description (in terms of PID managable content). It is something alive that is evolving any time new versions of the external project are to be managed into PID.
  • a binary form. In this form, the wrapper is a collection of software artifacts (headers, configuration files, executables, libraries, documentation, etc.) deployed in a given place of a file system. A binary external package can be embedded into an archive in order to be easily retrieved and deployed on a file system.

In all this web site, we use the term wrapper to say source form external package wrapper. If we speak about the binary form of the wrapper we use the term binary external package or more simply external package.

Component

One important concept when dealing with PID packages is the concept of component. A component is the generic term to denote a unitary software artifact that is contained in a package as well as in a wrapper. Components have a source form (its source files and all configuration elements used to build it) and a binary form (its public headers and/or the binary object resulting from the build process) when installed.

External component (i.e. component described within a wrapper) are a bit less descriptive than native components because PID simply has less information about them. An external component is defined as a collection of software artifacts (headers, binaries) generated by the wrapper they belong to.

Wrapper structure

A wrapper is implemented as folder hierarchies inside a worskpace. There are basically two types of folder hierarchies:

  • the one in the workspace wrappers folder, that is the source project of the wrapper.
  • those in the workspace install folder, that are the binary versions of the external package available for different platforms.

CMake project

A Wrapper is a CMake project structured according to the standard folder hierarchy defined below:

  • the root folder of the package has the name of the wrapper. This folder is basically a git repository which allows to manage concurrent work and version control on a wrapper’s content.
  • the .git folder contains version control related information, automatically managed by the git tool.
  • the root .gitignore file is used to exclude from version control some artefacts like temporary files.
  • the CMakeLists.txt file is used to describe how to deploy and build versions of the external project. It also contains meta-information on the wrappers (authors and institutions, repository address, license, etc.).
  • the build folder contains results from build process.
  • the src folder contains wrapper source files, that are mostly CMake files. Each subdirectory of src is either :
    • named with a version number of the form major.minor.patch and contains the CMakeLists.txt describing the external package content for this specific version. It also contains other cmake script files, notably those used to deploy (i.e. download, build, install) this version.
    • or the system folder that contains scripts used to check if target platform provides the external package as a system dependency.
  • the share folder contains user written documents and some specific files used by the build process. The share folder has following subdirectories:
    • the cmake folder contains cmake scripts (notably find scripts) that the wrappers uses to find external resources like libraries. This is the place used only for very specific resources for which no default cmake script is available.
    • the resources folder contains resources files used by libraries and applications/tests of the wrapper.
    • the ci folder contains scripts used during continuous integration process.
  • the license.txt file contains the license that applies to the whole source code produced in the wrapper. This file is generated by the build process. The licene applies only to the wrapper and not to the original project being wrapped.
  • the README.md file contains the text presenting the wrapper.
  • the .gitlab-ci.yml file ise used to control and configure the continuous integration process of the wrapper.

Git repository

Wrappers are git repositories, whose content is structured according to the previously defined pattern. git is used to version all text files used (mainly cmake scripts). Only source form of a wrapper is a git repository not its binary form.