Step 5 : Saving current development state
You can continue working on your package, by adding source files, creating new libraries and applications, etc.
From time to time (at least each day), it is a good practice to save the current revision of your package. To do so, simply use git:
At this time the new commit should have been added to the
integration branch of your package’s local repository. Then when you want to save your work in a online server simply do:
You should always push to the
integration branch (or eventually another specific branch) but never to the master branch until you want to release a new version. We advise you to have a look at git tutorial here to better use git than the really raw (but simple) way of doing presented in this section.
Also, when working with manual git commands, you should always push
integration branch to the
Another option, to avoid mistakes in git usage, is to use PID dedicated command:
This command will also manage the update of your
integration branch from information coming from the
origin remote before pushing your own commits.
Step 6 : Releasing a package
From time to time, you will have to release your package when you think its state is stable enough. When released it is supposed to be usable by a third party that has access to it. In the end a release is not more than an interesting state of the project, corresponding to a specific git commit. As usually done in modern development process, a release of a package is bound to a specific version number.
6.1 Apply a software license to source files
Before releasing it is most of time a good thing to apply the chosen software license (see root
CMakeLists.txt file) to your source files so that the corresponding copyrights applies to all parts of your package without possible legal bypassing. To do so:
The operation may take a long time (depending on how many files rely in your package). To see the result open any source file and look at its header: it now contains license information.
Then remember to save the modifications:
6.2 Generate API documentation
As it is supposed to be accessed by other person, it is also a good thing to provide an API documentation for this package.
In the CMake configuration interface, set
ON, then type
Otherwise simply use the
pid script to do this all in one:
The build process will inform you from missing information in the API (e.g. missing parameters of a function and so on). It is a good pratice to try to resolve these errors by modifying or adding adequate doxygen comment directly into the header files of your library (only headers are taken into account for API documentation). You can find the resulting API in
<pid-workspace>/install/<platform>/my-first-package/0.1.0/share/doc/html. Simply open the
index.html file with a web crawler and see the result.
Once you think that the result is satisfying, remember to save the modifications:
6.3 Release the current version
After these cosmetic (but usefull, in the end) operations you can release the current package version. This operation simply consists in marking a specific state of your package’s repository. This is performed, among other operations, by tagging this specific state by using git tags. The main goal of a release is to be able to quickly find a functionnal version of your code. The best way to perform this operation adequately is to use PID dedicated commands:
The release process automatically performs following actions:
- tries a first build with all tests activated (if any), to check if code can be compiled and tests pass. If not successfull the release process stops here.
- merges the package’s
integrationbranch in the
masterbranch. If merge is conflicting then the release stops here and package is put in its original state.
- tags the last commit on
masterwith adequate version tag.
- build again the package on
masterbranch (with options limited to the strict minimum) to ensure that enerything is ok.
- updates (i.e. push to) the
officialremote repository of the package (
masterbranch and tags). This may launch the CI process of the package on server side.
- goes back to
integrationbranch and increments the version number in the root
CMakeLists.txt. The new version number simply increases the previous minor number by default, but this can be controlled by the
make releasecommand (using
- updates the
integrationbranch of local and
After that, you are still on integration branch but any further build will install a new version (e.g. 0.2.0).
Now you know how to release a package, let’s see why you need to register it.