The Asclepias Developer Guide

Use the command ghcup list to orient yourself with the following information.

The first column of the table provided by ghcup list is the least obvious. If a given row has an "✗", then it means that the corresponding version of the application hasn’t been downloaded by ghcup. If it has a "✔", then it means that it has been downloaded by ghcup, and if it has a "✔✔" then it means that it both has been downloaded by ghcup and is the currently active version.

The "active version" of a given application according to ghcup is the version that gets run when using a shell command such as ghc without supplying a version number (as in e.g. ghc-9.2.1). To change the currently active version for a particular application, use the ghcup set command. See ghcup set --help for details.

In more detail, ghcup stores various application versions in the $HOME/.ghcup/bin directory which is assumed to be on your shell’s path. Then for example, the ghc file located in that directory is a symbolic link to the active version of GHC according to ghcup (a similar pattern is used for other applications managed by ghcup). So suppose that the active version of GHC was GHC 8.10.7, then running the command ghc in your shell would run GHC 8.10.7 because the ${HOME}/.ghup/bin/ghc file would a symbolic link pointing to GHC 8.10.7.

As you find your way around the asclepias project, you may notice that in the sub-project Cabal package description files (i.e. the files with filenames ending in .cabal), that the cabal-version is specified as an older version of Cabal (such as version 2.2) than can be downloaded through ghcup. According to Package Field: cabal-version in the Cabal documentation Cabal is mostly backwards compatible so there shouldn’t be any issue with using a newer version.

As you find your way around the asclepias project, you may notice that in the sub-project Cabal package description files (i.e. the files with filenames ending in .cabal) that the default-language is specified as Haskell2010, which refers to the Haskell 2010 language report, and is the current definition of the Haskell language (also see Haskell 2010 inn Wikipedia and The Haskell 2010 report in The Haskell Wiki). GHC versions 8.0.2 and later implement the Haskell 2010 language report.

Although the Haskell language definition itself has stayed stable since the Haskell 2010 language report, the GHC compiler supports the adoption of new language features through the use of language extensions, which are opt-in non-standard language features. An effect of the specifying the Haskell 2010 language is that the language extensions listed in the Haskell 2010 Language Extensions in the GHC documentation are enabled by GHC.

Additional language extensions can be specified by various mechanisms in the sub-project Cabal package description files and/or in the source code files themselves as described in the Extensions blog post by Veronika Romashkina.

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.

Since the asclepias repository has a multiple project layout (i.e. hasklepias-core, hasklepias-main, etc.), it may not be obvious how to set up HLS. For example, should you run one server that serves all of the files across the various projects, or should you run one server per project?

To resolve this issue, the asclepias repository provides a file hie.yaml in the repository root that specifies the HLS configuration for all of the projects in the repository (see the hie-bios documentation for details). As a result of this setup, you can run a single HLS server that will work correctly for all of the projects in the repository. If you are asked by your editor to specify what directory to start HLS in then you can use the repository root directory.

Some editors may automatically detect the hie-bios configuration setup in the repository and just "do the right thing." If you open a Haskell file in your editor and the LSP client seems to be working properly then you are probably good-to-go.

If HLS ever stops working, you may need to clear the cache:

Suppose the export list looks like the example shown below. Loosely speaking this means the following.

The full export specification is rather involved so we will not try to cover everything in full detail, but rather try to cover the most common cases. See Export Lists in the Haskell 2010 Language Report for complete documentation.

When a given module is imported in GHCi (i.e. added to the current scope) it can be in one of two forms: the usual import form and a so-called *-form. The regular form places the module exports in scope, whereas the *-form places all top-level bindings in the module in scope.

Use the command :show imports to list the modules that are currently in scope, and the command :show bindings to list any binding that were declared directly in the REPL.

In the following example, we first start a new GHCi session and define the object fib. The subsequent :show bindings command then reports that the only binding made at the prompt was for lib. Next we use :module command to add several modules into the scope (see the Controlling what is in scope with the ':module' command in GHCi section for a description of :module). Then a subsequent :show imports command provides the output shown below. This can be read as meaning that the exports from the ExampleEvents and ExampleFeatures1 modules are in scope, whereas the entirety of the ExampleCohort1 and the Main modules are in scope (i.e. they are *-form imports).

When modules are loaded at GHCi startup (e.g. after invoking cabal repl) or through the :load command then a secondary effect of the load is that an automatic import is added to the scope for the most recently loaded target module. The effect of this import is that (i) the data and definitions of the module are made available to the top-level scope in GHCi, and (ii) all other bindings are removed from the top-level scope.

Note that the above effects also occur for the :add and :reload commands. See The effect of :load on what is in scope in the GHC documentation for more details.

You can use the usual Haskell import syntax to add a module’s exports (or possibly a subset of them) to the scope. In the following example we sequentially add the exports from ExampleFeatures1 and ExampleFeatures1 to the scope, but note that the effect is cumulative (i.e. each module is successively added to the scope). See Controlling what is in scope with import in the GHC documentation for full details.

An alternative to using an import command to modify the scope is to use the :module command. In the following example we see three forms of the :module command: one with a + that adds module declarations to the current scope, one with a - that removes module declarations from the current scope, and one without either a + or a - which replaces the current scope with a new scope. Furthermore, each module that is imported by the :module command can be either a regular import or a *-form input by either omitting or including an * before each module name. See Controlling what is in scope with the :module command in the GHC documentation for full details.