Compiling asclepias packages

A Cabal package is defined by the following (see Package Description in the Cabal documentation for full detail).

You can locate the various Cabal packages in the repository by using a command such as one of the ones shown below. For this particular project there is also a file hie.yaml (and which is described further in the [A note on using HLS in multi-project repositories] section) that should (unless it gets out-of-sync) accurately describe the package layout.

The Cabal package description file (i.e. the .cabal file) contains information about the package such as the package name, version, structure, and dependencies. Documentation for this file’s format can be found in Package descriptions in the Cabal documentation.

The description file contains a number of top-level fields called Package Properties and which contain information such as cabal-version, name, version, etc. In addition to these fields there may be an arbitrary number of sections from a fixed number of types that are called Component Types. The section type keywords include library, executable, and test-suite among others. Typically each section is named (with one important exception mentioned below) and contains a number of section-specific field/value pairs describing the given component. The fields within a section may optionally be indented, but each field within the section must have the same indentation.

Currently, there can only be one publicly exposed library in a package, and its name is the same as package name set by global name field. The name argument to the library section must be omitted (c.f. Library in the Cabal documentation).

Some fields expect lists for their specified values. For a given field, the thesevalues rather confusingly take exactly one of three forms: space separated (no commas allowed between elements), comma separated (a comma is required between elements), or optional comma separated (the elements may all either be comma seperated or all not comma separated). All optional comma separated fields must follow the same comma or non-comma style (the non-comma style is recommended). The Field Syntax Reference in the Cabal documentation lists the grammar for some of the fields.

Consider the following abridged version of the hasklepias-main.cabal file. In this example we see the top-level fields (i.e. the package properties) cabal-version, name, and version, and following these fields we see a total of three sections. The first section has a "library" component type, and because its name is omitted (i.e. there is no text to the right of the library keyword) this is taken to be the sole publicly exposed library for the package, and is given the same name as is specified by the name field (i.e. hasklepias-main). The second section has a "test-suite" component type, and is given the name examples. The third section has an "executable" component type, and is given the name exampleApp.

The visibility of a given module in a package is controlled by the other-modules, exposed-modules and main-is fields. Note that every package module must be listed in one of these fields. The meanings of these fields are described below.

The meanings of some of the other section-specific fields shown in the example are listed below.

As previously mentioned, the asclepias repository is organized using a multiple project setup. Some of the subdirectories of the repository such as hasklepias-core, hasklepias-main, etc. contain a Cabal package. The simplest thing to do to get started is to build (i.e. compile) all of the Cabal projects in the repository using the following command.

By default, Cabal doesn’t compile the test suite or benchmarking modules when using cabal build. In the following sections we will see ways to compile these components if desired.

Alternatively, you can build the packages one-at-a-time using a command of the following form. This is useful when you are working on a particular package and don’t want to compile everything at once in order to save time.

By default Cabal doesn’t compile the test suite or benchmarking modules for a given package so if you want to compile the tests along with the package itself then you can use e.g. the --enable-tests and/or --enable-profiling options.

In addition to specifying a package name to compile, the cabal build command allows you to specify finer-grained units of compilation called package components, where the package components correspond to the sections in the Cabal package description file. For example, in the example Cabal package description file example section the package name was hasklepias-main, and the package components were called hasklepias-main (a library), examples (a test-suite), and exampleApp an executable (recall that the hasklepias-main library was implicitly named after the package name).

Typically package components are identified using the form package:component (the available syntax is actually more flexible than the form shown here). So for example, you could use the command hasklepias-main:examples to compile the examples component from the hasklepias-main package.

Additionally you can use one of the forms package:ctype or all:ctype to compile all components of the specified type (i.e. the ctype) for a given package or across all packages, respectively. So for example, you could use the command hasklepias-main:executables to compile any components with an executable component type from the hasklepias-main package (of which there happens to be one component, i.e. the exampleApp component), or the command all:executables to compile any components with an executable component type from any package the asclepias repository.

There are other ways of specifying a component by specifying either a module name or the filepath of a module that belongs to the target component, however we do not cover those approaches here.