Contribution spaces are specific entities. They are not considered as deployment units as they cannot be automatically deployed in a workspace. Indeed they contain contribution files that are themselves used to deploy and more generally manage various aspects of deployment units. They can be seen as extensions of the workspace use tod to reference contribuions of users.
Structure of a contribution space
When used in a local workspace each contribution space is a folder hierarchy located in the
contributions folder. Its content is standardized and follows this pattern:
findssubfolder contains cmake find modules for native and external packages. These cmake scripts follow the CMake standard way of finding dependencies. Each PID package in use (either native or external) has a corresponding find file registered in at least one contribution space of the workspace.
referencessubfolder contains cmake modules containing meta-information about available packages, wrappers, frameworks and environments. They are used to locate git repositories of packages/wrappers/frameworks/environments and, if available, binary archives repositories for native and external packages.
licensessubfolder contains cmake modules containing available licenses description.
formatssubfolder contains clang-format code style description.
Have a look at
pid official contribution space you will find all thoses folders.
- files inside
formatsare direct contributions, meaning that they are not generated by packages or wrappers but directly written by users inside contribution spaces.
- files in
findsare generated by packages and wrappers.
- files in
referencesare generated by packages, wrappers, frameworks and environments.
Any of these folders is optional in a contribution space, so for instance a contribution space can only provide find and reference files and so only
references folders will be used.
Note: most of time, due to their nature
formats should be provided in the official PID contribution space as they are probably very generic. For instance any license file defining a very common license should be provided in official PID contribution space.
Repository of a contribution space
Each contribution space is, as most of elements in PID, a git repository.
- Getting contributions of a user or team is nothing more than cloning the repository of its/their contribution space into
contributionsfolder of the local workspace. To get updates anytime this team or user provides new/updated contributions it simply consists in updating the local repository with remote one (i.e.
- Adding contributions to a contribution space is nothing more than putting contributions files (find files, license files, etc.) into adequate subfolders and then commit the changes before pushing to its repository remote. This way other people using this contribution space can get updates.
Create a contribution space
To create a new contribution space you just have to create an empty repository in your favorite git hosting service. Then to use it in your local workspace:
a_csis the name of the contribution space you created.
firstname.lastname@example.org:own/a_cs_repo.gitis the address of the contribution space’s repository.
Dealing with contribution space’s remotes
Contribution spaces repository has:
- an update address: this is the
fetchaddress of the remote repository where to get updates of the contribution space content. If your contribution space is public this address is the http address of your online repository so that anyone can clone/pull its content without being registered in the git hosting solution you are using. Otherwise you should prefer using the ssh address so that only registered people can use it (without having to enter a password anytime an update is made).
- a publish address: this is the
pushaddress of the remote repository used to update online repository content. This should be a ssh address so that contributors do not have to enter a password any time they propose an update.
Both adress are by default the same but is is sometimes necessary to differentiate them. Indeed you can use a contribution space where you cannot publish content. This is for instance the case for the
pid contribution space. To propose contributions to a contribution space you are not allowed to push in:
- fork the repository of the contribution space in the git hosting service your are using. For instance fork the
- set the publish address to this fork into your local workspace. For instance :
own is the namespace where your forked
You can now publish your contributions to the official pid contribution space by doing:
And you need to:
- create a merge request between your fork of
pid-contributionsand official repository.
- wait the merge request to be accepted for your contributions to be part of official PID contribution space.
Same process can be used for any contribution space.
Global management of contribution spaces
In a local workspace, many contribution spaces can be used. There is at least the official contribution space (called
pid) that is installed by default.
Management of contribution spaces in use is made using a global file:
<pid-workspace>/contributions/contribution_spaces_list.cmake. This file list all contribution spaces currenlty in use and its content looks something like:
Each call to
PID_Contribution_Space define the use of a specific contribution space.
NAME is its nickname,
UPDATE is the update address from where contribution space content is updated and optional
PUBLISH address is the adress of the remote where to publish new/updated content. If no
PUBLISH address is specified then publish address is the same as
All contribution spaces in this file are ordered from highest (first line) to lowest priority (last line) priority. Priority is used to resolve potential conflicts if same contributions can be found in many contribution space: whenever a specific contribution must be used it is resolved in priority order. So for instance, for a package
pack, if reference and files of
pack are both in
my_contributions contribution spaces, those of
pid will be used. If we swap the two lines in
<pid-workspace>/contributions/contribution_spaces_list.cmake then those of
my_contributions will be used.
There are two ways to manage contribution spaces used at local workspace level:
my_contributionsconsists in writting the second line of the file and then:
my_contributionsconsists in removing the second line of the file and then:
- swapping priority for both contribution space consists in swapping the two lines of the file and then:
Direct edition of the file is particularly useful to manage priorities between contribution spaces when you use many.
contributions command of the workspace
my_contributions: It simply adds the second line of the file then reconfigure the workspace.
my_contributions: It simply removes the second line of the file then reconfigure the workspace.
There are plenty of commands to manage contribution space. You can have a complete list in workspace commands description:
Some of them cannot be performed by just editting the content of
deletehelps you manage contributions inside contribution spaces. This pratically consists in automating filesystem modification and git operations (commit).
statusgives the git status of a given contribution space, in order to know want can be published.
publishis used to publish modifications in a contribution space using ist
Contributing to a contribution space
Contributing to a contribution space simply consists in creating/updating contribution files it contains.
- find files are put in contribution spaces anytime the native or external package is installed or referenced.
- reference files are put in contribution spaces anytime the package is referenced:
- other contribution files (licenses and formats) are directly written within contribution spaces.
Then to publish contributions of the contribution space:
Contributions of deployment units
The most frequent operation is to add or update deployment unit’s references, it is often more convenient to directly reference a delpoyment unit contribution and publish it in one time:
Adding or updating contributions of a deployment unit follows this rule:
- contribution files are always published in all contribution spaces already containing those files. In other words, anytime its contribution files are updated for any reason (e.g. new version released, repository migration, update of meta information), update takes place in all contribution space containing find and/or reference files for this deployment unit.
If no contribution file of a deployment unit exists then:
- if a contribution space is defined in deployment unit description then contributions are put into this one.
- otherwise the contribution space with highest priority is used.
Other contributions are directly written within contribution spaces. Please follow the different tutorials to know how to create such contributions: