5. Packages

Packages are the unit of organization in Copland. All service and configuration points are grouped in packages.

5.1. Descriptor Syntax

Each package is described in a single file, named “package.yml”. (You can actually change what the descriptor file name ought to be—the default, though, is “package.yml”). It will typically contain all of the services defined in the same directory. In keeping with standard YAML syntax, this file should begin with a single line consisting solely of three dashes: ---.

The file may contain the following attributes:

id This is the name of the package. It must be a string, and it must be unique. If the registry encounters a package named identically to some other package it has already parsed, it will raise an exception.
require This is a list of other (non-core) packages that this package depends on. For example, to take advantage of any of the services in the “copland.lib” namespace, you would need to add “copland/lib” to the require list for the package that needs those services.
description This is an (optional) description of the current package. It is useful for documentation purposes, but is not used at all by Copland itself.
configuration-points This must contain a hash of values, each key of which names and references the definition of a configuration point (q.v.).
contributions This must contain a hash of values, each key of names a contribution to some configuration point. (See the chapter on contributions for more information.)
service-points This must contain a hash of values, each key of which names and references the definition of a service point (q.v.).

Of the attributes descibed above, only the id attribute is required, though it makes little sense to define a package that does not include at least one configuration point, contribution, or service point.

Also, if your package references any non-core packages (like “copland.lib” or “copland.remote”), you will need to add the requisite libraries to your package’s require clause.

5.2. Tips

Name your packages consistently. Here is a recommended naming convention:

  • Use dashes instead of underscores in your package names.
  • Make package names all lowercase.
  • Name your primary package after your application.
  • If your application uses more than one package (and large applications very well may), prefix each package name with the name of your application, followed by a dot. In other words, if your application was named “Astroscopus”, and you had a subpackage named “notewise”, you would name your primary package “astroscopus”, and the subpackage “astroscopus.notewise”. This gives your packages a hierarchical feel, though there is nothing saying they need to be laid out in a hierarchical directory structure.
  • If you are distributing a package that you created for others to use, name the package with your name or company (or website) as the primary package name, and your library as the secondary name. For instance, if your company was “Interrelated Autorotation, Inc.”, and you created a library called “papillomatosis”, you might name your package “interrelated-autorotation.papillomatosis”.

Try to group the service points and configuration points in your packages by common functionality. Don’t be afraid to create new packages where necessary to separate functional groups. Although having many packages may make your application’s start-up time a little slower (and it will only be a little), it is worth the benefits to maintainance it will add.