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:
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 intoHALCYON_BASE
.LANG
is set toC.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
or1
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
or1
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 byhalcyon paths
.When installing an app, Halcyon creates a symlink pointing
~/.cabal/config
to theconfig
file located in the Cabal directory.
HALCYON_LOG_TIMESTAMP
Default value: 0
Type: 0
or1
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
or1
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
or1
Command-line option: --app-reconfigure
Forces Halcyon to run cabal configure
before building the app.
HALCYON_APP_NO_STRIP
Default value: 0
Type: 0
or1
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
or1
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
or1
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
or1
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
or1
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
or1
Command-line option: --app-reinstall
Forces Halcyon to prepare the install directory again.
HALCYON_APP_NO_REMOVE_DOC
Default value: 0
Type: 0
or1
Command-line option: --app-no-remove-doc
Disables removing documentation when preparing the install directory.
HALCYON_KEEP_DEPENDENCIES
Default value: 0
Type: 0
or1
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
or1
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
or1
Command-line option: --no-archive
Prevents creating any archives in HALCYON_CACHE
.
HALCYON_NO_CLEAN_CACHE
Default value: 0
Type: 0
or1
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
or1
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.
Note: Currently, the following S3 regions can’t be used:
- China (Beijing)
- EU (Frankfurt)
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
or1
Command-line option: --no-private-storage
Prevents accessing HALCYON_S3_BUCKET
.
HALCYON_NO_UPLOAD
Default value: 0
Type: 0
or1
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
or1
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
or1
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
or1
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
or1
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
or1
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
or1
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
or1
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
or1
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 #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
or1
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
or1
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
or1
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
or1
Command-line option: none
Prevents Halcyon from updating itself.