Tutorial
These pages explains the basic steps to start working with PID. Before reading them, you need a PID workspace installed on your workstation.
If you already know PID you may still need some answers, you can find some in the FAQ.
In all these tutorials, the name <pid-worskspace>
denotes the path to the place where PID workspace is installed on your workstation and <platform>
is the current target platform of the PID workspace (typical platform name: x86_64_linux_stdc++11
). Platforms are used to manage the compatibility between packages binaries generated by a build process, each target platform representing an isolated execution environment. More details on platforms and their role here.
Introduction to PID
To be aware of basic PID functionalities, please follow tutorials in this order:
About contribution spaces
Contribution spaces are kind of marketplaces used to memorize and shared contributions of users.
Wrapping external projects into PID
External project wrappers are used to port existing non PID projects into PID. They can be used either to deploy external projects from their sources, and/or for specifying requirements on target platform configuration.
Grouping packages and wrappers into frameworks
Frameworks are deployment unit used to group and organize a set of packages around a common domain. The best example of a framework utility is the site you are currently reading, that has been generated from a framework.
Setting host configuration using environments
Environments are deployment units used to define the development tools (compiler toolchains, crosscompilation related information, new third party tools, etc.) to use when building packages in a workspace.
About specific contributions : licenses and formats
Licenses
define the meta-data of licenses that apply to packages in a workspace.
formats
define the way clang-format will format files of packages.
Guideline for porting existing code in PID
If you want to port existing code into PID, the main question that first arise is : which mechanism should I use ? Indeed there are different options. We provide here a general guideline to help people porting third party code.
- If you get some mostly “unstructured” and/or raw source code, with no clean build management resources (like a CMakeLists.txt file for instance) then it is always preferrable to create a native PID package and start doing things cleanly. As a quick guideline on how to do that please follow this tutorial.
- If you developped a project and now want to manage it with PID then the best solution is to create a native PID package, see this tutorial.
- if the code you want to use is a commonly used system dependency (e.g.
libjpeg
,libpng
,x11
libraries, etc.) or completely bound to your hardware or kernel configuration (e.g.cuda
) it is most of time preferable to define it as a platform configuration. Use of platform configuration should be limited as far as possible but this is the only reasonnable way of doing for many dependencies. - If you use a cleanly defined open source and freely usable third party project:
- if this project is complex (lot of source files, complex configuration process, etc.) and/or still evolving (at least with new release published from time to time) then it is preferrable to create an external package wrapper. This is what we decided to do for
eigen
,boost
andopencv
projects for instance. To do this see how to define wrappers - if this project is small and no more evolve then transform it into a native PID package. This is the best solution if you want to bring some modifications to it in the future. We applied this strategy on many no more evolving project as
reflexxes
(Type 2),fast research interface library
and some others. To get some guidelines please follow same tutorial as for porting unstructured source code.
- if this project is complex (lot of source files, complex configuration process, etc.) and/or still evolving (at least with new release published from time to time) then it is preferrable to create an external package wrapper. This is what we decided to do for
- If you use a binary only code (libraries, executables) then it is preferable to define an external wrapper. This is typically the case for software comming from private companies like specific drivers for hardware they produce or software you have bought. Please read the wiki explaining how to port existing binary code as an external PID package.
Using PID from an external project
PID provides means for another non PID project to access the content of a workspace and use its packages.