In previous tutorials you learned how to develop native packages and how to deal with their dependencies.

In the tutorial explaining what is package registering you already used a contribution space, more precisely the default official contribution space of PID.

In practice only part of packages you develop should be part of the official contribution space (those that are generic and/or reusable enough). Other contributions, for instance the contribution files for my-first-package, should be placed in a private contribution space.

One good practice is so to use different contribution spaces:

  • one for each specific development team you belong to, that contains all contributions that are only relevant to this group.
  • one by user (i.e. yourself), that contains all contributions that are only relevant to this user.

It is now time to define your own contribution space and use it to share contribution files generated by your projects.

Let’s suppose we continue to work on my-first-package starting from previous tutorial.

Step 1: Create a contribution space for your personnal work

Let’s imagine you want to develop some packages for your personnal work. You know that those packages will be only usefull for you and probably not really usable by anyone else. It is not recommanded to put them in PID official contribution space because they will just add some noise into it without any benefits for the others.

The best thing to do is to put them (at least in a first time) into a private contribution space. This way you will be able to deploy those packages in any workstation you use.

  • in your favorite git hosting service simply create an empty git repository. Let’s call it my_contributions and let’s suppose its addres is git@gite.lirmm.fr:own/my_contributions.git (change with its real address). That’s it you created a contribution space !

  • Now you need to configure your local workspace to be able to use this contribution space. We use the manage command of the workspace that is dedicated to the management of contribution spaces.

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

That’s it your configuration space is ready to use !

Just have a quick look into the folder <pid-workspace>/contributions. There is a file named contribution_spaces_list.cmake. This file contains the definition of all contribution spaces you are currently using in your local workspace. You should see 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)
  • Contribution space called pid is the official one, it should always be present in your workspace (i.e. its use is automatic).
  • The second line specifies the contribution space you just added.

Step 2: Define a default contribution space for a package

Now we want to register contribution files of my-first-package into my_contributions rather than in pid.

One important rule: when referencing a package, its contribution files are put into all contribution spaces that already contain those files. Indeed it is possible for a package to contribute to many contribution spaces. So for now, according to this rule, anytime you use the commands register (at workspace level) or referencing (at package level) any update of my-first-package’s contribution files will take place only in pid contribution space.

2.1 Define default contribution space for a package

One quick way to solve this issue is to define a default contribution space for a package. Edit the root CMakeLists.txt of my-first-package and replace existing description with this one:

cmake_minimum_required(VERSION 3.15.7)
set(WORKSPACE_DIR ${CMAKE_SOURCE_DIR}/../.. CACHE PATH "root of the packages workspace directory")
list(APPEND CMAKE_MODULE_PATH ${WORKSPACE_DIR}/cmake) # using generic scripts/modules of the workspace
include(Package_Definition NO_POLICY_SCOPE)

project(my-first-package)

PID_Package(AUTHOR 		    My Name
			      INSTITUTION	  LIRMM
            YEAR 		      2015
            ADDRESS		    git@gite.lirmm.fr:own/my-first-package.git
            LICENSE 	    CeCILL
            DESCRIPTION   TODO: input a short description of package toto utility here
						CONTRIBUTION_SPACE my_contributions  #this line has been added
            VERSION       0.2.0
		)

check_PID_Platform(CONFIGURATION posix) #adding this line to previous content
PID_Dependency(boost)

build_PID_Package()

Only thing that changes from previous description is the specification of a default contribution space, using the CONTRIBUTION_SPACE argument of PID_Package.

Now build the package:

cd <my-first-package>
pid build

The find file generated by my-first-package at install time should now also appear in <pid-workspace>/contributions/my_contributions/finds.

Let’s now do the same for the reference file:

cd <my-first-package>
pid referencing

The reference file generated by my-first-package has been copied into <pid-workspace>/contributions/my_contributions/references.

2.2 Update your online reposotiry of your private contribution space

Now to memorize these contributions into my_contributions online repository, you can simply commit and push content of your local folder <pid-workspace>/contributions/my_contributions, or use dedicated PID command:

cd <pid-workspace>
pid contributions cmd=publish space=my_contributions

Have a look to my_contributions online repository, you should see a commit telling that the contribution space has been updated.

2.3 Clean official contribution space

For now the pid contribution space also contain contributions files generated by my-first-package from package registering tutorial. According to the rule explained before, anytime you update those contribution files they will be updated in my-first-package and pid.

We want to restart from a clean situation by removing the contribution files from pid contribution space.

The simplest way to do so is to:

  • delete and recreate pid-contributions into your online git hosting service. This way you have no more traces of my-first-package.

  • reset local pid contribution space

cd <pid-workspace>
pid contributions cmd=rm space=pid

This last command will remove pid but this later is mandatory and default into a workspace so it will be automatically reinstalled.

Now you should see that contribution_spaces_list.cmake changed:

PID_Contribution_Space(NAME my_contributions UPDATE git@gite.lirmm.fr:own/my_contributions.git)
PID_Contribution_Space(NAME pid UPDATE https://gite.lirmm.fr/pid/pid-contributions.git PUBLISH git@gite.lirmm.fr:own/pid-contributions.git)
  • pid is now on the second line, simply because 1) it has been remove then added again and 2) anytime a contribution space is added in workspace its definition is appended at the end of the file.
  • PUBLISH and UPDATE remotes of pid have been reset to their initial value.

If you still want to be capable of proposing contributions to the official contribution space, you need to configure its publish remote again :

cd <pid-worskspace>
pid contributions cmd=churl space=pid publish=git@gite.lirmm.fr:own/pid-contributions.git

Now simply try to find any contribution file of my-first-package into pid contribution space (in finds and references subfolders of <pid-workspace>/contributions/pid). You should see none.

2.4 Registering again contribution files

Now to see the consequences simply redo the referencing of my-first-package:

cd <my-first-package>
pid referencing

Again have a look into finds and references subfolders of <pid-workspace>/contributions/pid. Still no trace of my-first-package contributions what is exactly what we expected.

Conclusion

You just learned the basics of contribution spaces, but there is much more to learn and it is important to well understand this concept since this is the base of contributions sharing process in PID. We advise to have a look at this more complete tutorial on contributions.