Skip to content

Commit 047611e

Browse files
mpilgremmpilgrem
committed
Merge branch 'stable'
2 parents bac975e + a638e81 commit 047611e

File tree

1 file changed

+128
-62
lines changed

1 file changed

+128
-62
lines changed

‎doc/yaml_configuration.md

Lines changed: 128 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -618,7 +618,7 @@ configure-options:
618618

619619
(Since 0.1.5)
620620

621-
Specify a variant binary distribution of GHC to use. Known values:
621+
Specify a variant binary distribution of GHC to use. Known values:
622622

623623
* `standard`: This is the default, uses the standard GHC binary distribution
624624
* `integersimple`: Use a GHC bindist that uses
@@ -636,110 +636,176 @@ This option is incompatible with `system-ghc: true`.
636636

637637
Specify a specialized architecture bindist to use. Normally this is
638638
determined automatically, but you can override the autodetected value here.
639-
Possible arguments include `standard`, `gmp4`, `tinfo6`, and `nopie`.
639+
Possible arguments include `standard`, `gmp4`, `nopie`, `tinfo6`,
640+
`tinfo6-nopie`, `ncurses6`, and `integersimple`.
640641

641-
### setup-info-locations
642+
### setup-info
642643

643-
(Since 2.3)
644+
(Since 0.1.5)
644645

645-
Possible usages of this config are:
646-
1. Using `stack` offline or behind a firewall
647-
2. Extending the tools known to `stack` such as cutting-edge versions of `ghc` or builds for custom linux distributions.
646+
The `setup-info` dictionary specifies download locations for tools to be
647+
installed during set-up, such as GHC or, on Windows, 7z and MSYS2. The
648+
dictionary maps `('Tool', 'Platform', 'Version')` to the location where it can
649+
be obtained. For example, mapping `(GHC, 64-bit Windows, 9.2.3)` to the URL
650+
hosting the archive file for GHC's installation.
648651

649-
The `setup-info` dictionary specifies locations for installation of Haskell-related tooling - it maps `(Tool, Platform, Version)` to the location where it can be obtained, such as `(GHC, Windows64, 8.6.5)` to the url hosting the `*.tar.xz` for GHC's installation.
652+
Possible usages of this configuration option are:
650653

651-
By default, it's obtained from [stack-setup-2.yaml](https://github.com/commercialhaskell/stackage-content/raw/master/stack/stack-setup-2.yaml).
654+
1. Using Stack offline or behind a firewall.
655+
2. Extending the tools known to Stack, such as cutting-edge versions of GHC or
656+
builds for custom Linux distributions (for use with the
657+
[ghc-variant](#ghc-variant) option).
658+
659+
By default, Stack obtains the dictionary from
660+
[stack-setup-2.yaml](https://github.com/commercialhaskell/stackage-content/raw/master/stack/stack-setup-2.yaml).
652661

653662
The `setup-info` dictionary is constructed in the following order:
654-
1. `setup-info` yaml configuration - inline config
655-
2. `--setup-info-yaml` command line arguments - urls or paths, multiple locations may be specified.
656-
3. `setup-info-locations` yaml configuration - urls or paths
657663

658-
The first location which specifies the location of a tool `(Tool, Platform, Version)` takes precedence, so one can extend the default tools with a fallback to the default `setup-info` location:
664+
1. `setup-info` in the YAML configuration - inline configuration
665+
2. `--setup-info-yaml` command line arguments - URLs or paths. Multiple
666+
locations may be specified.
667+
3. `setup-info-locations` in the YAML configuration - URLs or paths. See further
668+
below.
669+
670+
The format of this field is the same as in the default
671+
[stack-setup-2.yaml](https://github.com/commercialhaskell/stackage-content/raw/master/stack/stack-setup-2.yaml).
672+
For example, GHC 9.2.3 of custom variant `myvariant` (see further below) on
673+
64-bit Windows:
659674

660675
```yaml
676+
setup-info:
677+
ghc:
678+
windows64-custom-myvariant:
679+
9.2.3:
680+
url: "https://example.com/ghc-9.2.3-x86_64-unknown-mingw32-myvariant.tar.xz"
681+
```
682+
683+
'Platforms' are pairs of an operating system and a machine architecture (for
684+
example, 32-bit i386 or 64-bit x86-64) (represented by the
685+
`Cabal.Distribution.Systems.Platform` type). Stack currently (version 2.7.5)
686+
supports the following pairs in the format of the `setup-info` field:
687+
688+
|Operating system|I386 arch|X86_64 arch|Other machine architectures |
689+
|----------------|---------|-----------|------------------------------------------------------------|
690+
|Linux |linux32 |linux64 |AArch64: linux-aarch64, Arm: linux-armv7, Sparc: linux-sparc|
691+
|OSX |macosx |macosx | |
692+
|Windows |windows32|windows64 | |
693+
|FreeBSD |freebsd32|freebsd64 |AArch64: freebsd-aarch64 |
694+
|OpenBSD |openbsd32|openbsd64 | |
695+
696+
For GHC, the distinguishing 'Version' in the field format includes a 'tag' for
697+
any (optional) GHC variant (see [ghc-variant](#ghc-variant)) and a further 'tag'
698+
for any (optional) specialised GHC build (see [ghc-build](#ghc-build)).
699+
700+
The optional variant 'tag' is either `-integersimple` or
701+
`-custom-<custom_variant_name>`.
702+
703+
For example, for GHC 9.0.2 of specialised GHC build `tinfo6` on x86_64 Linux:
704+
~~~yaml
705+
setup-info:
706+
ghc:
707+
linux64-tinfo6:
708+
9.0.2:
709+
url: "http://downloads.haskell.org/~ghc/9.0.2/ghc-9.0.2a-x86_64-fedora27-linux.tar.xz"
710+
content-length: 237286244
711+
sha1: affc2aaa3e6a1c446698a884f56a0a13e57f00b4
712+
sha256: b2670e9f278e10355b0475c2cc3b8842490f1bca3c70c306f104aa60caff37b0
713+
~~~
714+
715+
On Windows, the required 7z executable and DLL tools are represented in the
716+
format of the `setup-info` field simply by `sevenzexe-info` and
717+
`sevenzdll-info`.
718+
719+
This configuration **adds** the specified setup information metadata to the
720+
default. Specifying this configuration **does not** prevent the default
721+
[stack-setup-2.yaml](https://github.com/commercialhaskell/stackage-content/raw/master/stack/stack-setup-2.yaml)
722+
from being consulted as a fallback. If, however, you need to **replace** the
723+
default `setup-info` dictionary, use the following:
724+
725+
~~~yaml
726+
setup-info-locations: []
727+
~~~
728+
729+
### setup-info-locations
730+
731+
(Since 2.3)
732+
733+
By way of introduction, see the [`setup-info`](#setup-info) option. This option
734+
specifies the location(s) of `setup-info` dictionaries.
735+
736+
The first location which provides a dictionary that specifies the location of a
737+
tool - `('Tool', 'Platform', 'Version')` - takes precedence. For example, you
738+
can extend the default tools, with a fallback to the default `setup-info`
739+
location, as follows:
740+
741+
~~~yaml
661742
setup-info-locations:
662743
- C:/stack-offline/my-stack-setup.yaml
663744
- relative/inside/my/project/setup-info.yaml
664745
- \\smbShare\stack\my-stack-setup.yaml
665746
- http://stack-mirror.com/stack-setup.yaml
747+
# Fallback to the default location
666748
- https://github.com/commercialhaskell/stackage-content/raw/master/stack/stack-setup-2.yaml
667-
```
749+
~~~
668750

669-
The default `setup-info` location is included only if no locations in the `setup-info-locations` config or the `--setup-info-yaml` command line argument were specified.
751+
Stack only refers to the default `setup-info` location if no locations are
752+
specified in the `setup-info-locations` configuration or on the command line
753+
using the `--setup-info-yaml` option.
670754

671-
Thus the following will cause `stack setup` not to consult github for the `setup-info`:
672-
```yaml
755+
For example, both of the following will cause `stack setup` not to consult the
756+
default `setup-info` location:
757+
758+
~~~yaml
673759
setup-info-locations:
674760
- C:/stack-offline/my-stack-setup.yaml
675-
```
761+
~~~
676762

677-
```yaml
763+
and
764+
765+
~~~yaml
678766
setup-info-locations: []
679-
```
767+
~~~
680768

681-
Relative paths are resolved relative to the `stack.yaml` file - either in the local project or the global `stack.yaml` in the stack directory.
769+
Relative paths are resolved relative to the `stack.yaml` file (either the one in
770+
the local project or the global `stack.yaml`).
682771

683-
Relative paths may also be used inside paths to tool installs - such as for ghc or 7z, which allows vendoring the tools inside a monorepo.
684-
For example:
772+
Relative paths may also be used for the installation paths to tools (such as GHC
773+
or 7z). This allows vendoring the tools inside a monorepo (a single respository
774+
storing many projects). For example:
685775

686776
Directory structure:
687-
```
777+
778+
~~~
688779
- src/
689780
- installs/
690781
- my-stack-setup.yaml
691782
- 7z.exe
692783
- 7z.dll
693-
- ghc-8.2.2.tar.xz
784+
- ghc-9.2.3.tar.xz
694785
- stack.yaml
695-
```
786+
~~~
696787

697788
In the project's `stack.yaml`:
698-
```yaml
789+
790+
~~~yaml
699791
setup-info-locations:
700792
- installs/my-stack-setup.yaml
701-
```
793+
~~~
702794

703795
In `installs/my-stack-setup.yaml`:
704-
```yaml
796+
797+
~~~yaml
705798
sevenzexe-info:
706-
url: "installs/7z.exe"
799+
url: "installs/7z.exe"
707800

708801
sevenzdll-info:
709-
url: "installs/7z.dll"
802+
url: "installs/7z.dll"
710803

711804
ghc:
712-
windows64:
713-
8.2.2:
714-
url: "installs/ghc-8.2.2.tar.xz"
715-
```
716-
717-
### setup-info
718-
719-
(Since 0.1.5)
720-
721-
Allows augmenting from where tools like GHC and MSYS2 (on Windows) are
722-
downloaded. Most useful for specifying locations of custom GHC binary
723-
distributions (for use with the [ghc-variant](#ghc-variant) option).
724-
725-
The format of this field is the same as in the default [stack-setup-2.yaml](https://github.com/commercialhaskell/stackage-content/raw/master/stack/stack-setup-2.yaml):
726-
727-
```yaml
728-
setup-info:
729-
ghc:
730-
windows32-custom-foo:
731-
7.10.2:
732-
url: "https://example.com/ghc-7.10.2-i386-unknown-mingw32-foo.tar.xz"
733-
```
734-
735-
This configuration **adds** the specified setup info metadata to the default;
736-
Specifying this config **does not** prevent the default `stack-setup-2.yaml` from being consulted as a fallback.
737-
738-
If you need to **replace** the default setup-info, add the following:
739-
740-
```yaml
741-
setup-info-locations: []
742-
```
805+
windows64:
806+
9.2.3:
807+
url: "installs/ghc-9.2.3.tar.xz"
808+
~~~
743809

744810
### pvp-bounds
745811

0 commit comments

Comments
 (0)