Skip to content

Frequently asked questions

Stack and Cabal

What is the relationship between Stack and Cabal?

'Cabal' can refer to Cabal (the library) or to Cabal (the tool).

Cabal (the library) is used by Stack to build your Haskell code.

A Haskell package is described by a Cabal file, which file is part of the package. The file is named <package_name>.cabal.

Stack requires a project-level configuration file (stack.yaml, by default).

For further information about the difference between a Cabal file and a project-level configuration file, see the stack.yaml vs a Cabal file documentation.

The stack init command initializes a project-level configuration file from package description files.

Stack uses Cabal (the library) via an executable. For build-type: Simple (the most common case), Stack builds that executable using the version of Cabal which came with GHC. Stack caches such executables, in the Stack root under directory setup-exe-cache.

In rare or complex cases, a different version of Cabal to the one that came with GHC may be needed. build-type: Custom and a setup-custom stanza in the Cabal file, and a Setup.hs file in the package directory, can be specified. Stack's project-level configuration file can then specify the version of Cabal that Stack will use to build the executable (named setup) from Setup.hs. Stack will use Cabal via setup.

Cabal (the tool) is a tool provided by the cabal-install Haskell package. It aims to simplify the process of managing Haskell software by automating the fetching, configuration, compilation and installation of Haskell libraries and programs. These are goals that Stack shares. Stack can be used independently of Cabal (the tool) but users can also use both, if they wish.

How do I use Stack with sandboxes?

A 'sandbox' is a development environment that is isolated from other parts of the system. The concept of sandboxing is built in to Stack. All builds are automatically isolated into separate package databases.

Can I run cabal commands inside stack exec?

Yes. Some cabal commands are inconsistent with the GHC_PACKAGE_PATH environment variable in the Stack environment. Command, for example:

stack exec --no-ghc-package-path -- cabal build
Will Stack interfere with the GHC I already have installed?

No.

I already have GHC installed. Can I still use Stack?

Yes. In its default configuration, Stack will simply ignore any system GHC installation and use a sandboxed GHC that it has installed itself. You can find these sandboxed GHC installations in the ghc-* directories in the stack path --programs directory.

If you would like Stack to use your system GHC installation, use the --system-ghc flag or run stack config set system-ghc --global true to make Stack check your PATH for a suitable GHC by default.

Stack can only use a system GHC installation if its version is compatible with the configuration of the current project, particularly the snapshot specified by the snapshot or resolver key.

GHC installation doesn't work for all operating systems, so in some cases you will need to use system-ghc and install GHC yourself.

When I command stack ghci what version of GHC is used?

The version of GHC is specified by the snapshot in the relevant Stack project-level configuration file. This may be the file in the global-project directory in the Stack root.

For further information, see the configuration documentation.

How does Stack determine what GHC to use?

In its default configuration, Stack determines from the current project which GHC version, architecture etc it needs. It then looks in the ghc-<version> subdirectory of the stack path --programs directory for a compatible GHC, requesting to install one via stack setup if none is found.

If you are using the --system-ghc flag or have configured system-ghc: true either in the project stack.yaml or the global config.yaml, Stack will use the first GHC that it finds on your PATH, falling back on its sandboxed installations only if the found GHC doesn't comply with the various requirements (version, architecture) that your project needs.

See issue #420 for a detailed discussion of Stack's behavior when system-ghc is enabled.

How can I test that different GHC versions can build my project?

You can create multiple project-level configuration files for your project, one for each build plan. For example, you might set up your project directory like so:

myproject/
  stack-ghc-9.6.6.yaml
  stack-ghc-9.8.2.yaml
  stack.yaml --> symlink to stack-ghc-9.6.6.yaml
  myproject.cabal
  src/
    ...

When you run stack build, you can set the STACK_YAML environment variable to indicate which build plan to use. Command:

STACK_YAML=stack-ghc-9.8.2.yaml
stack build

$Env:STACK_YAML='stack-ghc-9.8.2.yaml'
stack build

set STACK_YAML=stack-ghc-9.8.2.yaml
stack build
Where is Stack installed?

Command:

stack uninstall

for information about where Stack is installed.

Can I change Stack's default temporary directory?

Stack downloads and extracts files to $STACK_ROOT/programs on most platforms, which defaults to ~/.stack/programs. On Windows $LOCALAPPDATA\Programs\stack is used. If there is not enough free space in this directory, Stack may fail. For instance, stack setup with a GHC installation requires roughly 1GB free. If this is an issue, you can set local-programs-path in your ~/.stack/config.yaml to a directory on a file system with more free space.

If you use Stack with Nix integration, be aware that Nix uses a TMPDIR variable, and if it is not set Nix sets it to some subdirectory of /run, which on most Linuxes is a Ramdir. Nix will run the builds in TMPDIR, therefore if you don't have enough RAM you will get errors about disk space. If this happens to you, please manually set TMPDIR before launching Stack to some directory on the disk.

On Windows, stack setup tells me to add certain paths to the PATH instead of doing it?

In PowerShell, it is easy to automate even that step. Command:

$Env:Path = ( stack setup | %{ $_ -replace '[^ ]+ ', ''} ), $Env:Path -join ";"
Does Stack install the system/C libraries that some Cabal packages depend on?

No. This is currently out of the scope of Stack's target set of features. Instead of attempting to automate the installation of 3rd party dependencies, we have the following approaches for handling system dependencies:

  • Nix and docker help make your build and execution environment deterministic and predictable. This way, you can install system dependencies into a container, and share this container with all developers.

  • If you have installed some libraries into a non-standard location, use the extra-lib-dirs option or the extra-include-dirs option to specify it.

In the future, Stack might give operating system-specific suggestions for how to install system libraries.

How can I make Stack aware of my custom SSL certificates?

Use the SYSTEM_CERTIFICATE_PATH environment variable to point at the directory where you keep your SSL certificates.

In principle, you can use the following command to add a certificate to your system certificate keychain:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <certificate>

Some users have reported issues with this approach, see issue #907 for more information.

How does Stack support the Hpack specification?

The Hpack package description format is an alternative to that used in a Cabal file.

If a package directory contains an package description file in the Hpack format (package.yaml), Stack will use that file to create the corresponding Cabal file.

stack init will use Hpack format package description files, if they are present.

The with-hpack non-project specific configuration option or the --with-hpack global flag can be used to specify an Hpack executable to use instead of Stack's built-in Hpack functionality.

How do I update my package index?

Command:

stack update

However, generally, it's not necessary with Stack: if the package index is missing, or if a snapshot refers to package version that isn't available, Stack will automatically update the package index and then try again.

If you run into a situation where Stack doesn't automatically update the package index, please report it as a bug.

Is it dangerous to update the package index automatically? Can that corrupt build plans?

No. Stack is explicit about which packages it's going to build. There are three sources of information to tell Stack which packages to install: the selected snapshot, the extra-deps configuration value, and your project packages. The only way to get Stack to change its build plan is to modify one of those three. Updating the index will have no effect on Stack's behavior.

How do I use a custom package index?

See the package-index non-project specific configuration option documentation.

How do I use a package version on Hackage not in a snapshot?

Add the package version to the extra-deps project-specific configuration option in the project-level configuration file.

How do I use a package version not on Hackage?

Add the location of the package version to the extra-deps project-specific configuration option in the project-level configuration file.

For further information, see the package location documentation.

How do I use a modified version of a package?

Typically, a modified version of a package is used as a project package. Add the location of the package to the packages project-specific configuration option in the project-level configuration file.

One way to get the source code for the unmodified package version is to use the stack unpack.

I'd like to use my installed packages in a different directory. How do I tell Stack where to find my packages?

Set the STACK_YAML environment variable to point to the stack.yaml configuration file for your project. Then you can run stack exec, stack ghc, etc., from any directory and still use your packages.

Why does stack build fail with GHC 9.8.1 and 9.8.2 only?

If the Cabal file of the relevant package makes use of a c-sources field, the failure may be due to Cabal-3.10.2.0 enforcing that the field can specify only *.c files. Earlier and later versions of Cabal (the library) tolerate other files.

When the Cabal build type is not Custom, Stack builds with the Cabal boot package of the specified version of GHC. The boot package of GHC 9.8.1 and 9.8.2 is Cabal-3.10.2.0.

What causes dependency on multiple versions of the same package?

When building a package, during its configuration, Stack may warn:

This package indirectly depends on multiple versions of the same package.
This is very likely to cause a compile failure.

and the build subsequently fails.

Often the cause is that: (1) the package depends, directly or indirectly, on a GHC wired-in package (for example, the ghc package); and (2) a direct or indirect dependency of that wired-in package is also specified as an extra-dep but the versions differ.

Why does stack test trigger a rebuild of other components?

If the set of dependencies of a project package to be built are not a subset of the set of dependencies when it was last built, then that will trigger a rebuild of components that were previously built.

The command:

stack build

will build the library and executable components of project packages and the build will take into account the dependencies of those components.

If you then command:

stack test

or, equivalently:

stack build --test

the test suite components of project packages are added to the build targets.

That can add dependencies to a project package, if its test suite components have dependencies that are not dependencies of its library and executable components.

What is true of test suite components applies equally to benchmark components.

If that behaviour is undesirable, a way to avoid it is to change the description of each project package so that adding its test suite (or benchmark) components does not add dependencies to the package. That is, to specify, in the package description, the dependencies as common to all the components that you are switching between from one build to another.

For example, if you are using package.yaml, add the dependencies to its top-level dependencies key.

Alternatively, build all components of project packages without running tests or benchmarks once built. Command:

stack build --test --no-run-tests --bench --no-run-benchmarks
How do I use a custom preprocessor?

See the customer-prepocessor-extensions project-specific configuration option documentation.

How do I get extra tools used during building?

Stack will automatically install tools used during building required by your packages or their dependencies, in particular Alex and Happy.

Note

This works when using LTS or nightly snapshots, not with GHC or custom snapshots. You can manually install tools used during building by running, e.g., stack build alex happy.

My tests are failing. What should I do?

Like all other targets, stack test runs test suites in parallel by default. This can cause problems with test suites that depend on global resources such as a database or binding to a fixed port number. A quick hack is to force stack to run all test suites in sequence, using stack test --jobs=1. For test suites to run in parallel developers should ensure that their test suites do not depend on global resources (e.g. by asking the operating system for a random port to bind to) and where unavoidable, add a lock in order to serialize access to shared resources.

How do I use Stack with Docker?

See the Docker integration documentation.

How do I build a statically-linked executable on Linux?

The way that Stack itself builds statically-linked Stack executables for Linux is as follows:

  • In the Cabal file, the following ld-options are set: -static and -pthread.

  • The Stack command is run in a Docker container based on Alpine Linux. The relevant Docker image repository is set out in Stack's stack.yaml file. See also Olivier Benz's GHC musl project.

  • Stack's configuration includes:

    extra-include-dirs:
- /usr/include
extra-lib-dirs:
- /lib
- /usr/lib

  • The build command is stack build --docker --system-ghc --no-install-ghc (on x86_64) or stack build --docker --docker-stack-exe=image --system-ghc --no-install-ghc (on AArch64; the host Stack and the image Stack must have the same version number).

Why doesn't Stack rebuild my project when I specify --ghc-options on the command line?

Because GHC options often only affect optimization levels and warning behavior, Stack doesn't recompile when it detects an option change by default. This behavior can be changed though by setting the rebuild-ghc-options option to true.

To force recompilation manually, use the --force-dirty flag. If this still doesn't lead to a rebuild, add the -fforce-recomp flag to your --ghc-options.

Why doesn't Stack apply my --ghc-options to my dependencies?

By default, Stack applies command line GHC options only to project packages. For an explanation of this choice see this discussion on issue #827.

If you still want to set specific GHC options for a dependency, use the ghc-options option in your YAML configuration file.

To change the set of packages that command line GHC options apply to, use the apply-ghc-options option.

How does Stack handle parallel builds?

See issue #644 for more details.

Where does the output from --ghc-options=-ddump-splices (and other -ddump* options) go?

These are written to *.dump-* files inside the package's .stack-work directory. Specifically, they will be available at PKG-DIR/$(stack path --dist-dir)/build/SOURCE-PATH, where SOURCE-PATH is the path to the source file, relative to the location of the Cabal file. When building named components such as test-suites, SOURCE-PATH will also include COMPONENT/COMPONENT-tmp, where COMPONENT is the name of the component.

Why is DYLD_LIBRARY_PATH ignored?

If you are on Mac OS X 10.11 ("El Capitan") or later, there is a GHC issue #11617 which prevents the DYLD_LIBRARY_PATH environment variable from being passed to GHC (see issue #1161) when System Integrity Protection (a.k.a. "rootless") is enabled. There are two known workarounds:

  1. Known to work in all cases: disable System Integrity Protection. WARNING: Disabling SIP will severely reduce the security of your system, so only do this if absolutely necessary!
  2. Experimental: modify GHC's shell script wrappers to use a shell outside the protected directories (see issue #1161).
How do I get verbose output from GHC when I build?

Set the --ghc-options option of stack build to -v.

How does Stack choose which snapshot to use when creating a project-level configuration file?

See the stack init command documentation.

How do I use Stack with Travis CI?

See the Travis CI documentation.

How do I use Stack with Azure CI?

See the Azure CI documentation.

How do fix error [S-9443] for 'linux64-ncurses6'?

Most Linux distributions have standardized on providing libtinfo.so.6, either directly or as a symbolic link to libncursesw.so.6. As such, there are no GHC binary distributions that link to libncursesw.so.6 after GHC 8.2.2.

This error can be prevented by creating a symbolic link to libncursesw.so.6 using name libtinfo.so.6. Command:

ln -s /usr/lib/libncursesw.so.6 /usr/lib/libtinfo.so.6

Root privileges may be required.

On macOS, how do I resolve linker errors when running stack setup or stack build?

This is likely to be caused by having both a LLVM installation and default Apple Clang compiler on the PATH. The symptom of this issue is a linker error "bad relocation (Invalid pointer diff)". The compiler picks up inconsistent versions of binaries and the mysterious error occurs.

The workaround is to remove LLVM binaries from the PATH.

On macOS, how do I suppress '-nopie' warnings with stack build? 
clang: warning: argument unused during compilation: '-nopie'
 [-Wunused-command-line-argument]

This warning is shown when compiler support of -no-pie is expected but unavailable. It's possible to bypass the warning for a specific version of GHC by modifying a global setting:

# ~/.stack/programs/x86_64-osx/ghc-8.2.2/lib/ghc-8.2.2/settings
-- ("C compiler supports -no-pie", "YES"),
++ ("C compiler supports -no-pie", "NO"),

Note that we're fixing ghc-8.2.2 in this case; repeat for other versions as necessary. You should apply this fix for the version of GHC that matches your snapshot.

Issue #4009 goes into further detail.

What is licensing restrictions on Windows?

Currently, on Windows, GHC produces binaries linked statically with GNU Multiple Precision Arithmetic Library (GMP), which is used by integer-gmp library to provide big integer implementation for Haskell. Contrary to the majority of Haskell code licensed under permissive BSD3 license, GMP library is licensed under LGPL, which means resulting binaries have to be provided with source code or object files. That may or may not be acceptable for your situation. Current workaround is to use GHC built with alternative big integer implementation called integer-simple, which is free from LGPL limitations as it's pure Haskell and does not use GMP. Unfortunately it has yet to be available out of the box with Stack. See issue #399 for the ongoing effort and information on workarounds.

I have a Windows username with a space in it and problems building

See the local-programs-path non-project specific configuration option documentation for advice.

How to get a working executable on Windows?

When executing a binary after building with stack build (e.g. for target "foo"), the command foo.exe might complain about missing runtime libraries (whereas stack exec foo works).

Windows is not able to find the necessary C++ libraries from the standard prompt because they're not in the PATH environment variable. stack exec works because it's modifying PATH to include extra things.

Those libraries are shipped with GHC (and, theoretically in some cases, MSYS2). The easiest way to find them is stack exec which. For example, command:

stack exec -- which libstdc++-6.dll
/c/Users/Michael/AppData/Local/Programs/stack/i386-windows/ghc-7.8.4/mingw/bin/libstdc++-6.dll

A quick workaround is adding this path to the PATH environment variable or copying the files somewhere Windows finds them (see https://msdn.microsoft.com/de-de/library/7d83bc18.aspx).

See issue #425.