3.8. Creating Snapshots and Releases

One of the main activities of prjm is the freezing of consistent project states into snapshots and releases. If all the packages in your project are checkd out as released versions, you may create a release, in any other case, you may only archive the state of development as a snapshot. This is done by the commands

  prjm -snapshot <snapshotname>
  prjm -release <releasename>

In any case prjm will start by checking if any of the packages of your project is modified. If so, it is useless to record the state, since it cannot be reconstructed. If all versions of the checked out packages are committed to the version control repository, prjm will proceed by assembling the symbolic tags that describe the version of all packages. These will be written as a snapshot definition or a release definition to the snaps directory. Here are two examples of definitions produced by prjm for its own project:

snapshot snap_prjm_Thu_Oct_30_01:13:33_MET_1997
  prjbase devel_prjbase_d2_2_1
  miscutils devel_miscutils_d3_5_1
  depgraph devel_depgraph_d1_2_0
  pkg_config devel_pkg=config_d3_0_6
  prjm devel_prjm_d3_1_0
  pkg_base devel_pkg=base_d1_9_0
  fileinfo devel_fileinfo_d0_0_0
  pkg_vc devel_pkg=vc_d7_1_2
  m3tkutils devel_m3tkutils_d0_0_0
end

release prjm_release_0_0
  prjbase release_prjbase_0_0_x
  miscutils release_miscutils_0_0_x
  depgraph release_depgraph_0_0_x
  pkg_config release_pkg=config_0_0_x
  prjm release_prjm_0_0_x
  pkg_base release_pkg=base_0_0_x
  fileinfo release_fileinfo_0_0_x
  pkg_vc release_pkg=vc_1_0_x
  m3tkutils release_m3tkutils_0_0_x
end

You will have noticed that these definitions are easily readable and parseable, and may be further processed by other tools. It is one of the main design goals of Elego ComPact to integrate easily into different kinds of development environments, and provide as much information as possible about every result produced by its tools.

The actual creation of a snapshot or a release may depend upon the execution of an external program specified by the values of the configuration variables external-project-snapshot-hook, external-project-release-hook, and external-commit-hook. See Section 3.11 for further details.

If you want a release and haven't got released all of your packages, you can even combine the actions commitrelease and remap=it>release by using

  prjm -newrelease <commit type> <release name>

This command will by default create release branches for all packages that are not checked out on a release branch, and use existing release branches for others.

If you additionally specify the -forcerelease option, prjm will create new release branches for all your packages. Be careful with this option; it is likely that what you wanted to do was creating new releases for some packages and using old release branches for others.

Unless -novr is specified, in every package root directory a PkgOvr file is created, which lists all the package imports with the corresponding versions. See the description of -saveimports above for further details. These files are created and then automatically added to version control and committed to the relevant branches. If these commits fail, no release configuration is saved. (At this point, prjm has already created an internal pre-release configuration, which will only be written to disk if you also specify -saveprereleases or -saveall.)

The current version of prjm auto-commits all newly created snapshots and releases, unless the -noversioncontrol option is specified. That is, the project directory is considered as a package, the new snapshot description is added, and the changes are committed.

If you have a release you can create a named stable release based on it, that is, a mapping from package names to stable branch tags based on the frozen release. As an example let us suppose that you have created a release name my_release_1_0. You would now proceed with the command

  prjm -stablerelease my_release_1_0

Prjm would now create a new release description named my_release_1_0_stable, which would contain all the packages and tags from the base release, except that all patch levels of the release tags would be replaced by stable. You can think of stable releases as equivalent to the head configuration: a stable release enables you to check out the latest versions of all packages of a project on stable branches.

Stable releases are a special case of something that in the literature is often referred to as unbound configurations. While every snapshot and release operation creates a completely bound configuration where every package version is uniquely identified, a stable release configuration always refers to the head of release branches, i.e. the actual revision of every package will change in time.

If you create a release, the project manager first checks if everything has been built successfully in your workspace. This is done via the builtok command specified in PkgBase.DefaultData for the corresponding package kind. If anything is found missing, the creation of the release is aborted. The check is not performed if the -force option is present.