Halcyon reference

Halcyon is a system for installing Haskell apps and development tools, including GHC and Cabal.

This reference is a complete list of available Halcyon commands and options.

Commands

halcyon install

Arguments: app? option*

Builds and installs the app, restoring or building all dependencies on-the-fly.

The app can be specified as:

  • label
  • directory path
  • git URL

Labels can be in name or name-version format, referencing a Cabal package name and version number.

git URLs default to the master branch. Other branches can be specified with a #branch suffix.

halcyon build

Arguments: app? option*

Builds the app, restoring or building all dependencies on-the-fly.

The app can be specified as for halcyon install.

halcyon label

Arguments: app? option*

Outputs the app name and version number in name-version format, as declared in the Cabal package description.

The app can be specified as for halcyon install.

Intended to quickly determine the newest version of the app.

halcyon executable

Arguments: app? option*

Outputs the app executable name, as declared in the Cabal package description.

The app can be specified as for halcyon install.

halcyon constraints

Arguments: app? option*

Outputs the app version constraints.

The app can be specified as for halcyon install.

Intended to be used with the HALCYON_IGNORE_ALL_CONSTRAINTS option, to quickly determine the newest versions of all required Cabal packages.

Note: Recommended over cabal freeze because of Cabal issue #1908.

halcyon paths

Arguments: none

Outputs a shell script which sets up the needed environment variables:

  1. HALCYON_BASE is set to /app, unless already set.

  2. CABAL_CONFIG, PATH, CPATH, LIBRARY_PATH, LD_LIBRARY_PATH, PKG_CONFIG_PATH are set to point into HALCYON_BASE.

  3. LANG is set to C.UTF-8, unless already set.

The script is intended to be sourced in a .bash_profile.

Note: Using a UTF-8 locale works around Cabal issue #1883.

General options

HALCYON_BASE

Default value: /app
Type: directory
Command-line option: --base=...

Directory in which Halcyon builds or restores the GHC, Cabal, and sandbox directories.

Default value of HALCYON_PREFIX.

HALCYON_PREFIX

Default value: HALCYON_BASE
Type: directory
Command-line option: --prefix=...

Directory in which Halcyon installs apps.

If the install directory consists of bin/hello, and HALCYON_PREFIX is set to /app, then the app will be installed as /app/bin/hello.

HALCYON_ROOT

Default value: /
Type: directory
Command-line option: --root=...

Root directory for the directory in which Halcyon installs apps.

Intended to support constructing deployment systems.

If the install directory consists of bin/hello, HALCYON_PREFIX is set to /app, and HALCYON_ROOT is set to /tmp/hello, then the app will be configured to be installed as /app/bin/hello, and will actually be installed as /tmp/hello/app/bin/hello.

HALCYON_NO_APP

Default value: 0
Type: 0 or 1
Command-line option: --no-app

When no app is specified, prevents Halcyon from looking for an app in the current directory, and instead forces Halcyon to install GHC and Cabal only.

HALCYON_LOG_TIMESTAMP

Default value: 0
Type: 0 or 1
Command-line option: --log-timestamp

Prefixes each logged message with the number of seconds since beginning execution.

Build-time options

HALCYON_CONSTRAINTS

Default value: none
Type: string, file, or directory, optional
Command-line option: --constraints=...
Magic file: .halcyon/constraints

Version constraints to be declared by the app, overriding any constraints declared in a cabal.config file.

Each constraint must be in name-version format, referencing a Cabal package name and version number. The constraints must be separated by whitespace.

When a directory is specified, it must contain a constraints file named name-version.constraints, referencing the app name and version number.

The source code of each example app includes a constraints file.

HALCYON_EXTRA_SOURCE_HASH_IGNORE

Default value: none
Type: string or file, optional
Command-line option: --extra-source-hash-ignore=...
Magic file: .halcyon/extra-source-hash-ignore

Additional files or directories to be ignored when calculating the source hash.

By default, Halcyon ignores:

  • .git
  • .gitmodules
  • .ghc
  • .cabal
  • .cabal-sandbox
  • cabal.sandbox.config

The files or directories must be separated by whitespace, and can be specified as names or find -name patterns.

HALCYON_EXTRA_CONFIGURE_FLAGS

Default value: none
Type: string or file, optional
Command-line option: --extra-configure-flags=...
Magic file: .halcyon/extra-configure-flags

Additional flags for cabal configure.

The flags must be separated by whitespace.

Note: Any --prefix=... flags will be ignored.

See the Try Haste source code for an example of using extra configure flags.

HALCYON_PRE_BUILD_HOOK

Default value: none
Type: file, optional
Command-line option: --pre-build-hook=...
Magic file: .halcyon/pre-build-hook
Script arguments: tag source_dir build_dir

Script to be executed when building the app, before cabal build.

HALCYON_POST_BUILD_HOOK

Default value: none
Type: file, optional
Command-line option: --post-build-hook=...
Magic file: .halcyon/post-build-hook
Script arguments: tag source_dir build_dir

Script to be executed when building the app, after cabal build.

HALCYON_APP_REBUILD

Default value: 0
Type: 0 or 1
Command-line option: --app-rebuild

Forces Halcyon to build the app from scratch, which includes reinstalling all HALCYON_EXTRA_APPS and HALCYON_EXTRA_OS_PACKAGES.

HALCYON_APP_RECONFIGURE

Default value: 0
Type: 0 or 1
Command-line option: --app-reconfigure

Forces Halcyon to run cabal configure before building the app.

HALCYON_APP_NO_STRIP

Default value: 0
Type: 0 or 1
Command-line option: --app-no-strip

Disables stripping the contents of the build directory after running the post-build hook.

HALCYON_IGNORE_ALL_CONSTRAINTS

Default value: 0
Type: 0 or 1
Command-line option: --ignore-all-constraints

Forces Halcyon to ignore any version constraints declared with HALCYON_CONSTRAINTS or in a cabal.config file, and use the newest versions of all required Cabal packages.

Intended to support upgrading dependencies.

Note: Ignoring only certain constraints isn’t supported. See Cabal issue #2265 for details.

HALCYON_NO_BUILD

Default value: 0
Type: 0 or 1
Command-line option: --no-build

Prevents building the app and any dependencies.

Intended to use on resource-constrained machines, capable of installing and running the app, but not building it.

HALCYON_NO_BUILD_DEPENDENCIES

Default value: 0
Type: 0 or 1
Command-line option: --no-build-dependencies

Prevents building any dependencies.

Intended to use on resource-constrained machines, capable of building the app, but not the dependencies.

HALCYON_DEPENDENCIES_ONLY

Default value: 0
Type: 0 or 1
Command-line option: --dependencies-only

Prevents building and installing the app.

Intended to support constructing deployment systems.

Install-time options

HALCYON_EXTRA_APPS

Default value: none
Type: string or file, optional
Command-line option: --extra-apps=...
Magic file: .halcyon/extra-apps

Additional Haskell apps to be installed in the install directory as run-time dependencies.

The apps must be separated by whitespace, and can be specified as for halcyon install.

HALCYON_EXTRA_APPS_CONSTRAINTS

Default value: none
Type: string, file, or directory, optional
Command-line option: --extra-apps-constraints=...
Magic file: .halcyon/extra-apps-constraints

Version constraints to be declared by apps specified with HALCYON_EXTRA_APPS.

Each constraint must be in name-version format, referencing a Cabal package name and version number. The constraints must be separated by whitespace.

When a directory is specified, it must contain constraints files named name-version.constraints, referencing the name and version number of each extra app.

HALCYON_EXTRA_DATA_FILES

Default value: none
Type: string or file, optional
Command-line option: --extra-data-files=...
Magic file: .halcyon/extra-data-files

Additional data files to be copied to the install directory as run-time dependencies.

The files must be separated by whitespace, and can be specified as paths or GNU bash globs, relative to the build directory.

At run-time, the files will be available in the Cabal data files directory.

Note: Works around Cabal issue #713 and #784.

See the How I Start source code for an example of using extra data files.

HALCYON_EXTRA_OS_PACKAGES

Default value: none
Type: string or file, optional
Command-line option: --extra-os-packages=...
Magic file: .halcyon/extra-os-packages

Additional OS packages to be installed in the install directory as run-time dependencies.

Each package must be in name or pattern:name format, where pattern is a GNU bash regular expression to match the target platform. The packages must be separated by whitespace.

Platform identifiers are obtained with the detect_platform function.

See the Haskell Language source code for an example of using extra OS packages.

HALCYON_PRE_INSTALL_HOOK

Default value: none
Type: file, optional
Command-line option: --pre-install-hook=...
Magic file: .halcyon/pre-install-hook
Script arguments: tag source_dir install_dir data_dir

Script to execute when installing the app, before the install directory is archived.

See the Try Idris source code for an example of using a pre-install hook.

HALCYON_POST_INSTALL_HOOK

Default value: none
Type: file, optional
Command-line option: --post-install-hook=...
Magic file: .halcyon/post-install-hook
Script arguments: tag source_dir install_dir data_dir

Script to execute when installing the app, after the contents of the install directory are copied to HALCYON_ROOT.

HALCYON_APP_REINSTALL

Default value: 0
Type: 0 or 1
Command-line option: --app-reinstall

Forces Halcyon to prepare the install directory again.

HALCYON_APP_NO_REMOVE_DOC

Default value: 0
Type: 0 or 1
Command-line option: --app-no-remove-doc

Disables removing documentation when preparing the install directory.

HALCYON_KEEP_DEPENDENCIES

Default value: 0
Type: 0 or 1
Command-line option: --keep-dependencies

Forces Halcyon to keep all dependencies, restoring them even when an install directory archive is available.

Intended to support installing apps which require GHC and Cabal at run-time.

See the Try Haste source code for an example of using GHC and Cabal at run-time.

Cache options

HALCYON_CACHE

Default value: /var/tmp/halcyon-cache
Type: directory
Command-line option: --cache=...

Directory in which Halcyon caches recently used archives and constraints files.

HALCYON_PURGE_CACHE

Default value: 0
Type: 0 or 1
Command-line option: --purge-cache

Forces Halcyon to delete the entire contents of HALCYON_CACHE after beginning execution.

HALCYON_NO_ARCHIVE

Default value: 0
Type: 0 or 1
Command-line option: --no-archive

Prevents creating any archives in HALCYON_CACHE.

HALCYON_NO_CLEAN_CACHE

Default value: 0
Type: 0 or 1
Command-line option: --no-clean-cache

Prevents deleting any out-of-date archives from HALCYON_CACHE.

Public storage options

HALCYON_PUBLIC_STORAGE_URL

Default value: https://halcyon.global.ssl.fastly.net
Type: S3 URL
Command-line option: --public-storage-url=...

URL of the Amazon S3 bucket from which Halcyon downloads public archives and constraints files.

HALCYON_NO_PUBLIC_STORAGE

Default value: 0
Type: 0 or 1
Command-line option: --no-public-storage

Prevents downloading archives and constraints files from public storage.

Private storage options

HALCYON_AWS_ACCESS_KEY_ID

Default value: none
Type: 20-character string, optional
Command-line option: --aws-access-key-id=...

Amazon Web Services access key ID, used to authenticate S3 requests.

HALCYON_AWS_SECRET_ACCESS_KEY

Default value: none
Type: 40-character string, optional
Command-line option: --aws-secret-access-key=...

Amazon Web Services secret access key, used to authenticate S3 requests.

HALCYON_S3_BUCKET

Default value: none
Type: S3 name, optional
Command-line option: --s3-bucket=...

Name of the Amazon S3 bucket in which Halcyon stores private archives and constraints files.

Note: Using buckets located in S3 regions other than US Standard requires the right HALCYON_S3_ENDPOINT.

HALCYON_S3_ENDPOINT

Default value: s3.amazonaws.com
Type: S3 address, optional
Command-line option: --s3-endpoint=...

Address of the region-specific S3 endpoint in which HALCYON_S3_BUCKET is located.

Region Endpoint
us-east-1 s3.amazonaws.com, default
us-west-1 s3-us-west-1.amazonaws.com
us-west-2 s3-us-west-2.amazonaws.com
eu-west-1 s3-eu-west-1.amazonaws.com
ap-southeast-1 s3-ap-southeast-1.amazonaws.com
ap-southeast-2 s3-ap-southeast-2.amazonaws.com
ap-northeast-1 s3-ap-northeast-1.amazonaws.com
sa-east-1 s3-sa-east-1.amazonaws.com

Note: Currently, only regions supporting AWS Signature Version 2 are supported, which excludes eu-central-1. See bashmenot issue #9 for details.

HALCYON_S3_ACL

Default value: private
Type: S3 ACL
Command-line option: --s3-acl=...

Name of the S3 ACL to be assigned to all files uploaded to HALCYON_S3_BUCKET.

Commonly used values are private and public-read.

HALCYON_NO_PRIVATE_STORAGE

Default value: 0
Type: 0 or 1
Command-line option: --no-private-storage

Prevents accessing HALCYON_S3_BUCKET.

HALCYON_NO_UPLOAD

Default value: 0
Type: 0 or 1
Command-line option: --no-upload

Prevents uploading cached archives and constraints files to HALCYON_S3_BUCKET.

HALCYON_NO_CLEAN_PRIVATE_STORAGE

Default value: 0
Type: 0 or 1
Command-line option: --no-clean-private-storage

Prevents deleting out-of-date archives and constraints files from HALCYON_S3_BUCKET.

GHC options

HALCYON_GHC_VERSION

Default value: 7.8.4
Type: version
Command-line option: --ghc-version=...

Default version of GHC to be installed or restored in the GHC directory.

Used when the app doesn’t declare a base package constraint, or when installing GHC and Cabal only.

Supported versions include:

HALCYON_GHC_PRE_BUILD_HOOK

Default value: none
Type: file, optional
Command-line option: --ghc-pre-build-hook=...
Magic file: .halcyon/ghc-pre-build-hook
Script arguments: tag source_dir ghc_dir

Script to execute when building the GHC directory, before GHC is installed.

HALCYON_GHC_POST_BUILD_HOOK

Default value: none
Type: file, optional
Command-line option: --ghc-post-build-hook=...
Magic file: .halcyon/ghc-post-build-hook
Script arguments: tag source_dir ghc_dir

Script to execute when building the GHC directory, after GHC is installed.

HALCYON_GHC_REBUILD

Default value: 0
Type: 0 or 1
Command-line option: --ghc-rebuild

Forces Halcyon to rebuild the GHC directory from scratch by installing GHC again.

HALCYON_GHC_NO_REMOVE_DOC

Default value: 0
Type: 0 or 1
Command-line option: --ghc-no-remove-doc

Disables removing documentation from the GHC directory after running the GHC post-build hook.

HALCYON_GHC_NO_STRIP

Default value: 0
Type: 0 or 1
Command-line option: --ghc-no-strip

Disables stripping the contents of the GHC directory after running the GHC post-build hook.

Cabal options

HALCYON_CABAL_VERSION

Default value: 1.20.0.3
Type: version
Command-line option: --cabal-version=...
Magic file: .halcyon/cabal-version

Version of cabal-install to be bootstrapped or restored in the Cabal directory.

Supported versions include:

Note: cabal-install 1.22.0.1 is missing from the Cabal releases page. See Cabal issue #2492 for details.

HALCYON_CABAL_REMOTE_REPO

Default value: hackage:http://hackage.haskell.org/packages/archive
Type: string or file
Command-line option: --cabal-remote-repo=...
Magic file: .halcyon/cabal-remote-repo

Name and URL of the Cabal repository to be referenced in the Halcyon cabal.config file.

The value must be in Cabal remote-repo format.

Note: Cabal doesn’t support HTTPS URLs. See Cabal issue #936 for details.

HALCYON_CABAL_PRE_BUILD_HOOK

Default value: none
Type: file, optional
Command-line option: --cabal-pre-build-hook=...
Magic file: .halcyon/cabal-pre-build-hook
Script arguments: tag source_dir cabal_dir

Script to execute when building the Cabal directory, before cabal-install is bootstrapped.

HALCYON_CABAL_POST_BUILD_HOOK

Default value: none
Type: file, optional
Command-line option: --cabal-post-build-hook=...
Magic file: .halcyon/cabal-post-build-hook
Script arguments: tag source_dir cabal_dir

Script to execute when building the Cabal directory, after cabal-install is bootstrapped.

HALCYON_CABAL_PRE_UPDATE_HOOK

Default value: none
Type: file, optional
Command-line option: --cabal-pre-update-hook=...
Magic file: .halcyon/cabal-pre-update-hook
Script arguments: none

Script to execute when updating the Cabal directory, before cabal update.

HALCYON_CABAL_POST_UPDATE_HOOK

Default value: none
Type: file, optional
Command-line option: --cabal-post-update-hook=...
Magic file: .halcyon/cabal-post-update-hook
Script arguments: none

Script to execute when updating the Cabal directory, after cabal update.

HALCYON_CABAL_REBUILD

Default value: 0
Type: 0 or 1
Command-line option: --cabal-rebuild

Forces Halcyon to rebuild the Cabal directory from scratch by bootstrapping cabal-install again.

HALCYON_CABAL_UPDATE

Default value: 0
Type: 0 or 1
Command-line option: --cabal-update

Forces Halcyon to update the Cabal directory by running cabal update again.

HALCYON_CABAL_NO_STRIP

Default value: 0
Type: 0 or 1
Command-line option: --cabal-no-strip

Disables stripping the contents of the Cabal directory after running the Cabal post-build hook.

HALCYON_CABAL_NO_UPDATE

Default value: 0
Type: 0 or 1
Command-line option: --cabal-no-update

Prevents updating the Cabal directory by running cabal update.

Sandbox options

HALCYON_SANDBOX_EXTRA_CONFIGURE_FLAGS

Default value: none
Type: string or file, optional
Command-line option: --sandbox-extra-configure-flags=...
Magic file: .halcyon/sandbox-extra-configure-flags

Additional flags for cabal install --dependencies-only.

The flags must be separated by whitespace.

Note: Any --prefix=... flags will be ignored.

See the Haskell Language source code for an example of using extra configure flags.

HALCYON_SANDBOX_SOURCES

Default value: none
Type: string or file, optional
Command-line option: --sandbox-sources=...
Magic file: .halcyon/sandbox-sources

Additional Cabal packages to be copied to the sandbox directory as build-time dependencies and referenced with cabal sandbox add-source.

The packages must be separated by whitespace, and can be specified as:

  • directory paths
  • git URLs

git URLs default to the master branch. Other branches can be specified with a #branch suffix.

Note: Implements Cabal feature requests #1534 and #2189.

See the Try Haskell source code for an example of using sandbox sources.

HALCYON_SANDBOX_EXTRA_APPS

Default value: none
Type: string or file, optional
Command-line option: --sandbox-extra-apps=...
Magic file: .halcyon/sandbox-extra-apps

Additional Haskell apps to be installed in the sandbox directory as build-time dependencies.

The apps must be separated by whitespace, and can be specified as for halcyon install.

Intended to support installing Cabal build-tools, such as alex or happy.

Note: Works around Cabal issues #220 and #779.

See the Haskell Language source code for an example of using sandbox extra apps.

HALCYON_SANDBOX_EXTRA_APPS_CONSTRAINTS

Default value: none
Type: string, file, or directory, optional
Command-line option: --sandbox-extra-apps-constraints=...
Magic file: .halcyon/sandbox-extra-apps-constraints

Version constraints to be declared by apps specified with HALCYON_SANDBOX_EXTRA_APPS.

Each constraint must be in name-version format, referencing a Cabal package name and version number. The constraints must be separated by whitespace.

When a directory is specified, it must contain constraints files named name-version.constraints, referencing the name and version number of each extra app.

See the Haskell Language source code for an example of using sandbox extra apps constraints.

HALCYON_SANDBOX_EXTRA_OS_PACKAGES

Default value: none
Type: string or file, optional
Command-line option: --sandbox-extra-os-packages=...
Magic file: .halcyon/sandbox-extra-os-packages

Additional OS packages to be installed in the sandbox directory as build-time dependencies.

Each package must be in name or pattern:name format, where pattern is a GNU bash regular expression to match the target platform. The packages must be separated by whitespace.

Platform identifiers are obtained with the detect_platform function.

Note: Implements Cabal feature request #571.

See the Haskell Language source code for an example of using sandbox extra OS packages.

HALCYON_SANDBOX_PRE_BUILD_HOOK

Default value: none
Type: file, optional
Command-line option: --sandbox-pre-build-hook=...
Magic file: .halcyon/sandbox-pre-build-hook
Script arguments: tag source_dir constraints

Script to execute when building the sandbox directory, before cabal install --dependencies-only.

HALCYON_SANDBOX_POST_BUILD_HOOK

Default value: none
Type: file, optional
Command-line option: --sandbox-post-build-hook=...
Magic file: .halcyon/sandbox-post-build-hook
Script arguments: tag source_dir constraints

Script to execute when building the sandbox directory, after cabal install --dependencies-only.

See the Try Haskell source code for an example of using a sandbox post-build hook.

HALCYON_SANDBOX_REBUILD

Default value: 0
Type: 0 or 1
Command-line option: --sandbox-rebuild

Forces Halcyon to rebuild the sandbox directory and the app from scratch, which includes reinstalling all HALCYON_SANDBOX_EXTRA_APPS and HALCYON_SANDBOX_EXTRA_OS_PACKAGES.

HALCYON_SANDBOX_NO_REMOVE_DOC

Default value: 0
Type: 0 or 1
Command-line option: --sandbox-no-remove-doc

Disables removing documentation from the sandbox directory after running the GHC post-build hook.

HALCYON_SANDBOX_NO_STRIP

Default value: 0
Type: 0 or 1
Command-line option: --sandbox-no-strip

Disables stripping the contents of the sandbox directory after running the sandbox post-build hook.

Self-update options

HALCYON_DIR

Default value: variable
Type: read-only string
Command-line option: none

Directory in which Halcyon is installed.

Intended to support using Halcyon functions in hook scripts.

$ source "${HALCYON_DIR}/src.sh"

Automatically set by Halcyon at run-time. Setting this has an effect only before installing Halcyon by running the setup script.

HALCYON_URL

Default value: https://github.com/mietek/halcyon
Type: git URL
Command-line option: none

URL of the git repository from which Halcyon updates itself.

Defaults to the master branch. Other branches can be specified with a #branch suffix.

HALCYON_NO_SELF_UPDATE

Default value: 0
Type: 0 or 1
Command-line option: none

Prevents Halcyon from updating itself.