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:

  • the finds subfolder 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.
  • the references subfolder 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.
  • the licenses subfolder contains cmake modules containing available licenses description.
  • the formats subfolder contains clang-format code style description.

Have a look at pid official contribution space you will find all thoses folders.

  • files inside licenses and formats are direct contributions, meaning that they are not generated by packages or wrappers but directly written by users inside contribution spaces.
  • files in finds are generated by packages and wrappers.
  • files in references are 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 finds and references folders will be used.

Note: most of time, due to their nature licenses and 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 contributions folder 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. git pull).
  • 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:

cd <pid-worskspace>
pid contributions cmd=add space=a_cs update=git@gite.lirmm.fr:own/a_cs_repo.git

Where:

  • a_cs is the name of the contribution space you created.
  • git@gite.lirmm.fr:own/a_cs_repo.git is the address of the contribution space’s repository.

Dealing with contribution space’s remotes

Contribution spaces repository has:

  • an update address: this is the fetch address 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 push address 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 pid-contributions repository.
  • set the publish address to this fork into your local workspace. For instance :
cd <pid-worskspace>
pid contributions cmd=churl space=pid publish=git@gite.lirmm.fr:own/pid-contributions.git

Where own is the namespace where your forked pid-contributions.

You can now publish your contributions to the official pid contribution space by doing:

cd <pid-worskspace>
pid contributions cmd=publish space=pid

And you need to:

  • create a merge request between your fork of pid-contributions and 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:

PID_Contribution_Space(NAME pid UPDATE https://gite.lirmm.fr/pid/pid-contributions.git PUBLISH git@gite.lirmm.fr:own/pid-contributions.git)
PID_Contribution_Space(NAME my_contributions UPDATE git@gite.lirmm.fr:own/my_contributions.git)

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 UPDATE.

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 pid and 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:

directly edit <pid-workspace>/contributions/contribution_spaces_list.cmake

  • add my_contributions consists in writting the second line of the file and then:
cd <pid-worskspace>
pid configure #reconfigure the workspace
  • remove my_contributions consists in removing the second line of the file and then:
cd <pid-worskspace>
pid configure
  • swapping priority for both contribution space consists in swapping the two lines of the file and then:
cd <pid-worskspace>
pid configure

Direct edition of the file is particularly useful to manage priorities between contribution spaces when you use many.

use dedicated contributions command of the workspace

  • add my_contributions: It simply adds the second line of the file then reconfigure the workspace.
cd <pid-worskspace>
pid contributions cmd=add space=my_contributions update=git@gite.lirmm.fr:own/my_contributions.git
  • remove my_contributions: It simply removes the second line of the file then reconfigure the workspace.
cd <pid-worskspace>
pid contributions cmd=rm space=my_contributions

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 <pid-workspace>/contributions/contribution_spaces_list.cmake:

  • copy, move and delete helps you manage contributions inside contribution spaces. This pratically consists in automating filesystem modification and git operations (commit).

  • status gives the git status of a given contribution space, in order to know want can be published.
  • publish is used to publish modifications in a contribution space using ist PUBLISH remote.

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:
cd <my-first-package>
pid referencing
  • other contribution files (licenses and formats) are directly written within contribution spaces.

Then to publish contributions of the contribution space:

pid workspace contributions cmd=publish space=a_cs

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:

pid workspace register package=my-first-package

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

Other contributions are directly written within contribution spaces. Please follow the different tutorials to know how to create such contributions:

  • licenses
  • formats are defined the usual way in clang-format (see official documentation). They are simply put in the target contribution space’s formats folder. Have a look into <pid-workspace>/contributions/pid/formats to get many examples.