Skip to content

Latest commit

 

History

History
159 lines (113 loc) · 6.37 KB

dev_containers.md

File metadata and controls

159 lines (113 loc) · 6.37 KB
Raw

Dev Containers

A container refers to an isolated area of memory where application software and some drivers execute. A Development Container (or Dev Container for short) allows a container to be used as a full‑featured development environment.

Stack provides the following Dev Containers:

  • a default Dev Container, intended for use with Stack's default project‑level configuration file (stack.yaml); and
  • alternative Dev Containers, intended for use with Stack's experimental project‑level configurations (in anticipation of building Stack with more recent versions of GHC).

Stack's Dev Containers provide the following tools:

  1. The Haskell Toolchain (GHC, Stack, Cabal (the tool) and HLS)
  2. Git
  3. HLint
  4. yamllint
  5. ShellCheck
  6. hadolint

The tools in the Haskell Toolchain are installed at /usr/local/bin. HLS is provided in the default Dev Container only.

!!! info

The PATH is
`$HOME/.cabal/bin:$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`.
Consequently, executables installed with Cabal (the tool) (at
`$HOME/.cabal/bin` or `$HOME/.local/bin`) or Stack or Pip (at
`$HOME/.local/bin`) take precedence over the same executable installed at
`/usr/local/sbin`, `/usr/local/bin`, etc.

VS Code is used as IDE, with the following extensions pre‑installed:

Parent images

Stack's Dev Containers are derived from Docker images that are used to build the statically linked Linux/x86_64 and Linux/AArch64 binary distributions of Stack.

These Docker images are multi‑architecture (linux/amd64, linux/arm64/v8) GHC musl images. They are based on Alpine Linux (that is musl libc and BusyBox).

The images contain unofficial binary distributions of GHC (that is, ones not released by the GHC developers). That is because:

  1. the official GHC binary distributions for Alpine Linux/x86_64 have known bugs; and
  2. there are no official binary distributions for Alpine Linux/AArch64.

Stack's global configuration (/etc/stack/config.yaml) sets system-ghc: true and install-ghc: false. That ensures that only the GHC available in the Dev Containers is used.

Usage

You can run Dev Containers locally/remotely with VS Code, or create a GitHub Codespace for a branch in a repository to develop online.

=== "VS Code"

Follow the instructions at
[Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers).

=== "GitHub Codespaces"

For use with GitHub Codespaces, follow the instructions at
[Creating a codespace for a repository](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository).

Build Stack

Stack can be built with Stack (which is recommended) or with Cabal (the tool).

=== "Stack"

Command <nobr>`stack build`</nobr> to build the `stack` executable.

Append <nobr>`--flag=stack:static`</nobr> to build a *statically linked*
`stack` executable that can run on any Linux machine of the same
architecture.

Append <nobr>`--stack-yaml stack-ghc-$GHC_VERSION.yaml`</nobr> if you want
to use an experimental project‑level configuration with the appropriate Dev
Container.

=== "Cabal (the tool)"

!!! info

    Default Dev Container only.

Command <nobr>`cabal build`</nobr> to build the `stack` executable.

Append <nobr>`--flag=static`</nobr> to build a *statically linked* `stack`
executable that can run on any Linux machine of the same architecture.

Haskell Language Server (HLS)

The Haskell Language Server and the Haskell extension are only available in the default Dev Container. In order to use the Haskell extension, you must first configure the project for the tool used for building of your choice.

See the documentation at Contributing: Haskell Language Server for cradles (hie.yaml files) that should suffice to configure the HLS explicitly for ./Setup.hs and each of the buildable components in Stack's Cabal file.

Haskell extension

Choose Manually via PATH when asked the following question:

Manage HLS

Issues

If there is a problem with a Dev Container, please open an issue at its parent images' repository at https://github.com/benz0li/ghc-musl.