Halcyon reference

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

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 .

`halcyon paths`

Arguments: none

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

HALCYON_BASE is set to /app, unless already set.
CABAL_CONFIG, PATH, CPATH, LIBRARY_PATH, LD_LIBRARY_PATH, PKG_CONFIG_PATH are set to point into HALCYON_BASE.
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 .

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_NO_MODIFY_HOME`

Default value: 0

Type: 0 or 1

Command-line option: --no-modify-home

Prevents Halcyon from making changes to the home directory:

When running the setup script for the first time, Halcyon extends ~/.bash_profile to source the script output by halcyon paths.
When installing an app, Halcyon creates a symlink pointing ~/.cabal/config to the config file located in the Cabal directory.

`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 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 , relative to the build directory.

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

Note: Works around Cabal issue and .

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 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:

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 in which HALCYON_S3_BUCKET is located.

Note: Currently, the following S3 regions can’t be used:

China (Beijing)
EU (Frankfurt)

See bashmenot issue for details.

`HALCYON_S3_ACL`

Default value: private

Type: S3 ACL

Command-line option: --s3-acl=...

Name of the 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:

1.22.0.1

Note: cabal-install 1.22.0.1 is missing from the Cabal releases page. See Cabal issue 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 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

Note: Implements Cabal feature requests and .

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 and .

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 function.

Note: Implements Cabal feature request .

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:

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.

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

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

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

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

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

Default value:
Type:	S3 URL
Command-line option:	`--public-storage-url=...`

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

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

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

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

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`

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