# User guide (advanced)
Some of Stack's features will not be needed regularly or by all users. This part
of the guide provides information about those features. Some of the features are
complex and separate pages are dedicated to them.
## The `stack --hpack-numeric-version` flag
Stack will report the numeric version of its built-in Hpack library to standard
output (e.g. `0.35.0`) and quit.
## The `stack --numeric-version` flag
Stack will report its numeric version to standard output (e.g. `2.9.1`) and
quit.
## The `stack --[no-]rsl-in-log` flag
[:octicons-tag-24: 2.9.1](https://github.com/commercialhaskell/stack/releases/tag/v2.9.1)
Default: Disabled
Enables/disables the logging of the raw snapshot layer (rsl) in debug output.
Information about the raw snapshot layer can be lengthy. If you do not need it,
it is best omitted from the debug output.
## The `stack --silent` flag
Equivalent to the `stack --verbosity silent` option.
## The `stack --stack-root` option
`stack --stack-root ` specifies the path to the
Stack root directory. The path must be an absolute one. The option will override
the contents of any `STACK_ROOT` environment variable.
## The `stack --[no-]time-in-logs` flag
Default: Enabled
Enables/disables the inclusion of time stamps against logging entries when the
verbosity level is 'debug'.
## The `stack -v, --verbose` flags
Equivalent to the `stack --verbosity debug` option.
## The `stack --verbosity` option
Default: info
`stack --verbosity ` will set the level for logging. Possible levels
are `silent`, `error`, `warn`, `info` and `debug`, in order of increasing
amounts of information provided by logging.
## The `stack --version` flag
Stack will report its version to standard output and quit. For versions that are
release candidates, the report will list the dependencies that Stack has been
compiled with.
## The `stack --work-dir` option
Default: `.stack-work`
`stack --work-dir ` specifies the path to
Stack's work directory for the project. The path must be a relative one,
relative to the project's root directory. The option will override the contents
of any `STACK_WORK` environment variable.
## The `stack build` command
The `stack build` command is introduced in the first part of Stack's
[user's guide](GUIDE.md#the-stack-build-command). For further information about
the command, see the [build command](build_command.md) documentation.
## The `stack config` commands
The `stack config` commands provide assistance with accessing or modifying
Stack's configuration. See `stack config` for the available commands.
## The `stack config env` command
`stack config env` outputs a script that sets or unsets environment variables
for a Stack environment. Flags modify the script that is output:
* `--[no-]locals` (enabled by default) include/exclude local package information
* `--[no-]ghc-package-path` (enabled by default) set `GHC_PACKAGE_PATH`
environment variable or not
* `--[no-]stack-exe` (enabled by default) set `STACK_EXE` environment variable
or not
* `--[no-]locale-utf8` (disabled by default) set the `GHC_CHARENC`
environment variable to `UTF-8` or not
* `--[no-]keep-ghc-rts` (disabled by default) keep/discard any `GHCRTS`
environment variable
## The `stack config set` commands
The `stack config set` commands allow the values of keys in YAML configuration
files to be set. See `stack config set` for the available keys.
## The `stack config set install-ghc` command
`stack config set install-ghc true` or `false` sets the `install-ghc` key in a
YAML configuration file, accordingly. By default, the project-level
configuration file (`stack.yaml`) is altered. The `--global` flag specifies the
user-specific global configuration file (`config.yaml`).
## The `stack config set resolver` command
`stack config set resolver ` sets the `resolver` key in the
project-level configuration file (`stack.yaml`).
A snapshot of `lts` or `nightly` will be translated into the most recent
available. A snapshot of `lts-19` will be translated into the most recent
available in the `lts-19` sequence.
Known bug:
* The command does not respect the presence of a `snapshot` key.
## The `stack config set system-ghc` command
`stack config set system-ghc true` or `false` sets the `system-ghc` key in a
YAML configuration file, accordingly. By default, the project-level
configuration file (`stack.yaml`) is altered. The `--global` flag specifies the
user-specific global configuration file (`config.yaml`).
## The `stack dot` command
If you'd like to get some insight into the dependency tree of your packages, you
can use the `stack dot` command and Graphviz. More information is available in
the [Dependency visualization](dependency_visualization.md) documentation.
## The `stack ide` commands
The `stack ide` commands provide information that may be of use in an
integrated development environment (IDE). See `stack ide` for the available
commands.
## The `stack ide packages` command
`stack ide packages` lists all available local packages that are loadable. By
default, its output is sent to the standard error channel. This can be changed
to the standard output channel with the `--stdout` flag.
By default, the output is the package name (without its version). This can be
changed to the full path to the package's Cabal file with the `--cabal-files`
flag.
## The `stack ide targets` command
`stack ide targets` lists all available Stack targets. By default, its output is
sent to the standard error channel. This can be changed to the standard output
channel with the `--stdout` flag.
For example, for the Stack project itself, command:
~~~text
cd stack
stack ide targets
~~~
and the output from the second command is:
~~~text
stack:lib
stack:exe:stack
stack:exe:stack-integration-test
stack:test:stack-test
~~~
## The `stack list` command
`stack list [PACKAGE]...` list the version of the specified package(s) in a
snapshot, or without an argument list all the snapshot's package versions. If no
resolver is specified the latest package version from Hackage is given.
## The `stack ls` commands
The `stack ls` commands list different types of information. See `stack ls` for
the available commands.
## The `stack ls dependencies` command
`stack ls dependencies` lists all of the packages and versions used for a
project.
## The `stack ls snapshots` command
`stack ls snapshots` will list all the local snapshots by default. You can also
view the remote snapshots using `stack ls snapshots remote`. It also supports
options for viewing only lts (`-l`) and nightly (`-n`) snapshots.
## The `stack ls stack-colors` command
The British English spelling is also accepted (`stack ls stack-colours`).
`stack ls stack-colors` will list all of Stack's output styles. A number of
different formats for the output are available, see
`stack ls stack-colors --help`.
The default is a full report, with the equivalent SGR instructions and an
example of the applied style. The latter can be disabled with flags `--no-sgr`
and `--no-example`.
The flag `--basic` specifies a more basic report, in the format that is accepted
by Stack's command line option `--stack-colors` and the YAML configuration key
`stack-colors`.
## The `stack ls tools` command
`stack ls tools` will list Stack's installed tools. On Unix-like operating
systems, they will be one or more versions of GHC. On Windows, they will include
MSYS2. For example, on Windows the command:
~~~text
stack ls tools
~~~
yields output like:
~~~text
ghc-9.4.1
ghc-9.2.4
ghc-9.0.2
msys2-20210604
~~~
The `--filter ` option will filter the output by a tool name (e.g.
'ghc', 'ghc-git' or 'msys2'). The tool name is case sensitive. For example the
command:
~~~text
stack ls tools --filter ghc
~~~
yields output like:
~~~text
ghc-9.4.1
ghc-9.2.4
ghc-9.0.2
~~~
## The `stack sdist` command
Hackage only accepts packages for uploading in a standard form, a compressed
archive ('tarball') in the format produced by Cabal's `sdist` action.
`stack sdist` generates a file for your package, in the format accepted by
Hackage for uploads. The command will report the location of the generated file.
### The `stack sdist --ignore-check` flag
Pass the flag to disable checks of the package for common mistakes. By default,
the command will check the package for common mistakes.
### The `stack sdist --pvp-bounds` option
The `--pvp-bounds ` option determines whether and, if so, how
PVP version bounds should be added to the Cabal file of the package. The
available modes for basic use are: `none`, `lower`, `upper`, and `both`. The
available modes for use with Cabal file revisions are `lower-revision`,
`upper-revision` and `both-revision`.
For futher information, see the
[YAML configuration](yaml_configuration.md#pvp-bounds) documentation.
### The `stack sdist --tar-dir` option
The `--tar-dir ` option determines whether the package
archive should be copied to the specified directory.
### The `stack sdist --[no-]test-tarball` flag
Default: Disabled
Set the flag to cause Stack to test the resulting package archive, by attempting
to build it.
## The `stack templates` command
`stack templates` provides information about how to find templates available for
`stack new`.
Stack provides multiple templates to start a new project from. You can specify
one of these templates following your project name in the `stack new` command:
~~~text
stack new my-rio-project rio
Downloading template "rio" to create project "my-rio-project" in my-rio-project/ ...
Looking for .cabal or package.yaml files to use to init the project.
Using cabal packages:
- my-rio-project/
Selecting the best among 18 snapshots...
* Matches ...
Selected resolver: ...
Initialising configuration using resolver: ...
Total number of user packages considered: 1
Writing configuration to file: my-rio-project/stack.yaml
All done.
\templates\rio.hsfiles: 10.10 KiB downloaded...
~~~
The default templates repository is
https://github.com/commercialhaskell/stack-templates. You can download templates
from a different GitHub user by prefixing the username and a slash. Command:
~~~text
stack new my-yesod-project yesodweb/simple
~~~
Then template file `simple.hsfiles` would be downloaded from GitHub repository
`yesodweb/stack-templates`.
You can even download templates from a service other that GitHub, such as
[GitLab](https://gitlab.com) or [Bitbucket](https://bitbucket.com). For example,
command:
~~~text
stack new my-project gitlab:user29/foo
~~~
Template file `foo.hsfiles` would be downloaded from GitLab, user account
`user29`, repository `stack-templates`.
If you need more flexibility, you can specify the full URL of the template.
Command:
~~~text
stack new my-project https://my-site.com/content/template9.hsfiles
~~~
(The `.hsfiles` extension is optional; it will be added if it's not specified.)
Alternatively you can use a local template by specifying the path. Command:
~~~text
stack new project /template.hsfiles
~~~
As a starting point for creating your own templates, you can use the
["simple" template](https://github.com/commercialhaskell/stack-templates/blob/master/simple.hsfiles).
The
[stack-templates repository](https://github.com/commercialhaskell/stack-templates#readme)
provides an introduction into creating templates.
## The `stack update` command
`stack update` will download the most recent set of packages from your package
indices (e.g. Hackage). Generally, Stack runs this for you automatically when
necessary, but it can be useful to do this manually sometimes.
## The `stack upgrade` command
`stack upgrade` will build a new version of Stack from source.
* `--git` is a convenient way to get the most recent version from the `master`
branch, for those testing and living on the bleeding edge.
## The `stack unpack` command
`stack unpack` does what you'd expect: downloads a tarball and unpacks it. It
accepts an optional `--to` argument to specify the destination directory.
## The `stack upload` command
Hackage accepts packages for uploading in a standard form, a compressed archive
('tarball') in the format produced by Cabal's `sdist` action.
`stack upload` generates a file for your package, in the format accepted by
Hackage for uploads, and uploads the package to Hackage. For example, if the
current working directory is the root directory of your project:
~~~text
stack upload .
~~~
### The `HACKAGE_USERNAME` and `HACKAGE_PASSWORD` environment variables
[:octicons-tag-24: 2.3.1](https://github.com/commercialhaskell/stack/releases/tag/v2.3.1)
`stack upload` will request a Hackage username and password to authenticate.
This can be avoided by setting the `HACKAGE_USERNAME` and `HACKAGE_PASSWORD`
environment variables. For
example:
=== "Unix-like"
~~~text
export $HACKAGE_USERNAME=""
export $HACKAGE_PASSWORD=""
stack upload .
~~~
=== "Windows (with PowerShell)"
~~~text
$Env:HACKAGE_USERNAME=''
$Env:HACKAGE_PASSWORD=''
stack upload .
~~~
### The `HACKAGE_KEY` environment variable
[:octicons-tag-24: 2.7.5](https://github.com/commercialhaskell/stack/releases/tag/v2.7.5)
Hackage allows its members to register an API authentification token and to
authenticate using the token.
A Hackage API authentification token can be used with `stack upload` instead of
username and password, by setting the `HACKAGE_KEY` environment variable. For
example:
=== "Unix-like"
~~~text
HACKAGE_KEY=
stack upload .
~~~
=== "Windows (with PowerShell)"
~~~text
$Env:HACKAGE_KEY=
stack upload .
~~~
### The `stack upload --candidate` flag
Pass the flag to upload a
[package candidate](http://hackage.haskell.org/upload#candidates).
### The `stack upload --ignore-check` flag
Pass the flag to disable checks of the package for common mistakes. By default,
the command will check the package for common mistakes.
### The `stack upload --pvp-bounds` option
The `--pvp-bounds ` option determines whether and, if so, how
PVP version bounds should be added to the Cabal file of the package. The
available modes for basic use are: `none`, `lower`, `upper`, and `both`. The
available modes for use with Cabal file revisions are `lower-revision`,
`upper-revision` and `both-revision`.
For futher information, see the
[YAML configuration](yaml_configuration.md#pvp-bounds) documentation.
### The `stack upload --tar-dir` option
The `--tar-dir ` option determines whether the package
archive should be copied to the specified directory.
### The `stack upload --[no-]test-tarball` flag
Default: Disabled
Set the flag to cause Stack to test the resulting package archive, by attempting
to build it.
## Docker integration
Stack is able to build your code inside a Docker image, which means even more
reproducibility to your builds, since you and the rest of your team will always
have the same system libraries.
For further information, see the [Docker integration](docker_integration.md)
documentation.
## Nix integration
Stack provides an integration with [Nix](http://nixos.org/nix), providing you
with the same two benefits as the first Docker integration discussed above:
* more reproducible builds, since fixed versions of any system libraries and
commands required to build the project are automatically built using Nix and
managed locally per-project. These system packages never conflict with any
existing versions of these libraries on your system. That they are managed
locally to the project means that you don't need to alter your system in any
way to build any odd project pulled from the Internet.
* implicit sharing of system packages between projects, so you don't have more
copies on-disk than you need to.
When using the Nix integration, Stack downloads and builds Haskell dependencies
as usual, but resorts on Nix to provide non-Haskell dependencies that exist in
the Nixpkgs.
Both Docker and Nix are methods to *isolate* builds and thereby make them more
reproducible. They just differ in the means of achieving this isolation. Nix
provides slightly weaker isolation guarantees than Docker, but is more
lightweight and more portable (Linux and macOS mainly, but also Windows). For
more on Nix, its command-line interface and its package description language,
read the [Nix manual](http://nixos.org/nix/manual). But keep in mind that the
point of Stack's support is to obviate the need to write any Nix code in the
common case or even to learn how to use the Nix tools (they're called under the
hood).
For more information, see the [Nix-integration](nix_integration.md)
documentation.
## Continuous integration (CI)
### GitHub Actions
The Stack repository uses GitHub Actions for its own CI. For further
information, see the guide to
[contributing](CONTRIBUTING.md#continuous-integration-ci).
### Azure
For further information, see the [Azure CI](azure_ci.md) documentation.
### Travis
For further information, see the [Travis CI](travis_ci.md) documentation.
## Editor integration
### The `intero` project
For editor integration, Stack has a related project called
[intero](https://github.com/commercialhaskell/intero). It is particularly well
supported by Emacs, but some other editors have integration for it as well.
### Shell auto-completion
Love tab-completion of commands? You're not alone. If you're on bash, just run
the following command (or add it to `.bashrc`):
~~~text
eval "$(stack --bash-completion-script stack)"
~~~
For more information and other shells, see the
[Shell auto-completion wiki page](https://docs.haskellstack.org/en/stable/shell_autocompletion)
## Debugging
To profile a component of the current project, simply pass the `--profile`
flag to `stack`. The `--profile` flag turns on the `--enable-library-profiling`
and `--enable-executable-profiling` Cabal options _and_ passes the `+RTS -p`
runtime options to any testsuites and benchmarks.
For example the following command will build the `my-tests` testsuite with
profiling options and create a `my-tests.prof` file in the current directory
as a result of the test run.
~~~text
stack test --profile my-tests
~~~
The `my-tests.prof` file now contains time and allocation info for the test run.
To create a profiling report for an executable, e.g. `my-exe`, you can command:
~~~text
stack exec --profile -- my-exe +RTS -p
~~~
For more fine-grained control of compilation options there are the
`--library-profiling` and `--executable-profiling` flags which will turn on the
`--enable-library-profiling` and `--enable-executable-profiling` Cabal
options respectively. Custom GHC options can be passed in with
`--ghc-options "more options here"`.
To enable compilation with profiling options by default you can add the
following snippet to your `stack.yaml` or `~/.stack/config.yaml`:
~~~yaml
build:
library-profiling: true
executable-profiling: true
~~~
### Further reading
For more commands and uses, see the
[official GHC chapter on profiling](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html),
the [Haskell wiki](https://wiki.haskell.org/How_to_profile_a_Haskell_program),
and the
[chapter on profiling in Real World Haskell](http://book.realworldhaskell.org/read/profiling-and-optimization.html).
### Tracing
To generate a backtrace in case of exceptions during a test or benchmarks run,
use the `--trace` flag. Like `--profile` this compiles with profiling options,
but adds the `+RTS -xc` runtime option.
### Debugging symbols
Building with debugging symbols in the
[DWARF information](https://ghc.haskell.org/trac/ghc/wiki/DWARF) is supported by
Stack. This can be done by passing the flag `--ghc-options="-g"` and also to
override the default behaviour of stripping executables of debugging symbols by
passing either one of the following flags: `--no-strip`,
`--no-library-stripping` or `--no-executable-stripping`.
In Windows, GDB can be installed to debug an executable with
`stack exec -- pacman -S gdb`. Windows' Visual Studio compiler's debugging
format PDB is not supported at the moment. This might be possible by
[separating](https://stackoverflow.com/questions/866721/how-to-generate-gcc-debug-symbol-outside-the-build-target)
debugging symbols and
[converting](https://github.com/rainers/cv2pdb) their format. Or as an option
when
[using the LLVM backend](http://blog.llvm.org/2017/08/llvm-on-windows-now-supports-pdb-debug.html).