Designing the Package Specification

Design discussions pertaining to the CMaizeProject component (see Designing CMaize’s CMaizeProject Component) motivated the need for being able to represent a package’s specification. This page captures the design process of the CMaize’s PackageSpecification class.

What is a Package Specification?

When a project is installed, the result is a package. Generally speaking the same project can result in multiple packages. This is because projects evolve with time (e.g., new versions are released) and because most projects can be built in a number of different ways (i.e., with different versions of dependencies, with or without an optional feature, etc.). Package specifications are meant to uniquely identify a package.

Why Do We Need Package Specification?

At the end of the day, the packaged dependencies used to build a project can determine whether a build succeeds, the overall performance, and even the correctness. It is therefore critical that CMaize be able to capture sufficient package information so as to distinguish among different packages. The PackageSpecification class is charged with being able to represent the contents of a package.

Package Specification Considerations

package discernment

The primary purpose of the package specification is to contain enough information so that CMaize can discern among existing packages (particularly from the same project). This requires knowing:

  • Package’s name

  • Version

  • Configuration options (for packages built with CMake these are the CMake arguments used to configure the package).

  • Compilation arguments

source location

For packages CMaize is expected to obtain and/or build, we need to know where to find the package’s source code. For most dependencies this will be a URL, but for some projects (notably the one being built) the source files may reside locally on disk.

  • It is expected that there will be packages that users will not want CMaize to obtain/build. For such packages, the source location can simply be left blank.

Out of Scope

deciding if a package matches a specification

PackageSpecification objects are inputs to package managers. It is the package manager’s job to determine if a package matches a provided specification. See designing_cmaizes_packagemanager_component for more details.

Package Specification Design

../../../_images/package_specification.png

Fig. 6 Schematic illustration of the state of the PackageSpecification class.

Fig. 6 shows the PackageSpecification class’s state. The class itself is purely a data structure, meant to package all of the information together. While the source location attribute is not applicable to packages which have already been built, at present, we have opted to include it on all PackageSpecification objects. This is simply to avoid introducing a derived class to store one attribute. If management of the source location becomes more complicated it may make sense to factor it out out into a derived class.

Summary

package discernment

The PackageSpecification class contains state capable of recording how the package was configured.

source location

The PackageSpecification class stores the source location for packages CMaize is obtaining/building.