Skip to content

Commit a4a66f2

Browse files
mpilgremmpilgrem
committed
Re commercialhaskell#5467 Improve documentation of build targets
1 parent bc3625a commit a4a66f2

File tree

1 file changed

+127
-83
lines changed

1 file changed

+127
-83
lines changed

‎doc/build_command.md

Lines changed: 127 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -72,95 +72,139 @@ project-level configuration file (`stack.yaml`, by default).
7272
## Target syntax
7373

7474
`stack build` takes a list of one or more optional *targets* to be built. The
75-
supported syntaxes for targets are:
76-
77-
* *package*, e.g. `stack build foobar`, is the most commonly used target. It
78-
will try to find the package in the following locations: project packages,
79-
extra-deps, the snapshot, and the package index (e.g. Hackage). If it's
80-
found in the package index, then the latest version of that package from the
81-
index is implicitly added as an extra-dep.
82-
83-
If the package is a project package, the library and executable components
84-
are selected to be built. If the `--test` and `--bench` flags are set, then
85-
all of the test suite and benchmark components, respectively, are selected
86-
to be built.
87-
88-
If *package* is a GHC boot package (packages that come with GHC and are
89-
included in GHC's global package database), the behaviour can be complex.
90-
If the boot package has not been 'replaced', then `stack build` will,
91-
effectively, do nothing. However, if the boot package has been 'replaced'
92-
then `stack build` will specify the latest version of that package in the
93-
package index, which may differ from the version provided by the version of
94-
GHC specified by the snapshot. A boot package will be treated as 'replaced'
95-
if the package is included directly in the Stackage snapshot or it depends
96-
on a package included directly in the snapshot. Stackage snapshots do not
97-
include directly most boot packages but some snapshots may include directly
98-
some boot packages. In particular, some snapshots include directly `Win32`
99-
(which is a boot package on Windows) while others do not. For example, if
100-
`Cabal` (a boot package) is not a project package or an extra-dep, then
101-
`stack build Cabal` with Stackage snapshot LTS Haskell 20.25 will:
102-
103-
* on Windows, try to build the latest version of `Cabal` in the package
104-
index (because that snapshot includes `Win32` directly, and `Cabal`
105-
depends on `Win32` and so is treated as 'replaced'); and
106-
* on non-Windows, effectively, do nothing (because `Cabal` is not
107-
'replaced').
108-
109-
* *package identifier*, e.g. `stack build foobar-1.2.3`, is usually used to
110-
include specific package versions from the package index.
111-
112-
If the package name conflicts with that of a project package, then Stack
113-
fails with an error.
114-
115-
Otherwise, this is the same as using `stack build foobar` (that is, ignoring
116-
the specified version), unless the specified version exists in the package
117-
index. If it exists, then the latest revision of that version from the
118-
package index is used.
119-
120-
* *component*. Instead of referring to an entire package and letting Stack
121-
decide which components to build, you select individual components from
122-
inside a package. This can be done for more fine-grained control over which
123-
test suites to run, or to have a faster compilation cycle. There are
124-
multiple ways to refer to a specific component (provided for convenience):
125-
126-
* `<package-name>:lib` or `<package-name>:<comp-type>:<comp-name>` (where
127-
the component type, `<comp-type>`, is one of `exe`, `test`, or `bench`)
128-
is the most explicit. The library component type (`lib`) does not have
129-
an associated component name, `<comp-name>`.
130-
131-
!!! note
132-
133-
When any `exe` component is specified, all of the package's
134-
executable components will be built. This is due to limitations in
135-
all currently released versions of Cabal. See
136-
[issue#1046](https://github.com/commercialhaskell/stack/issues/1406)
137-
138-
* `<package-name>:<comp-name>` allows you to leave out the component type,
139-
as that will often be unique for a given component name. For
140-
example, `stack build mypackage:mytestsuite`.
141-
142-
* `:<comp-name>` is a useful shortcut, saying "find the component
143-
`<comp-name>` in all of the project packages". This will result in an
144-
error if more than one package has a component with the specified name.
145-
To continue the above example, `stack build :mytestsuite`.
146-
147-
* *directory*, e.g. `stack build foo/bar`, will find all project packages that
148-
exist in the given directory hierarchy and then follow the same procedure as
149-
passing in package names as mentioned above. There's an important caveat
150-
here: if your directory name is parsed as one of the above target types, it
151-
will be treated as that. Explicitly starting your target with `./` can be a
152-
good way to avoid that, e.g. `stack build ./foo`.
153-
154-
!!! note
155-
156-
`stack build .` will target project packages in the current working
157-
directory or its subdirectories.
75+
supported syntaxes for targets are as follows:
76+
77+
### No targets specified
78+
79+
Example: `stack build`
15880

15981
`stack build` with no targets specified will build all project packages.
16082

83+
### Target: *package*
84+
85+
Example: `stack build foobar`
86+
87+
Stack will try to find the package in the following locations:
88+
89+
* project packages,
90+
* extra-deps,
91+
* the snapshot, and
92+
* the package index (e.g. Hackage).
93+
94+
If the package is found in the package index, then the latest version of that
95+
package from the index is implicitly added as an extra-dep.
96+
97+
If the package is a project package, the library and executable components are
98+
selected to be built. If the `--test` and `--bench` flags are set, then all of
99+
the test suite and benchmark components, respectively, are selected to be built.
100+
101+
If *package* is a GHC boot package (packages that come with GHC and are included
102+
in GHC's global package database), the behaviour can be complex:
103+
104+
* If the boot package has not been 'replaced', then `stack build` will,
105+
effectively, do nothing.
106+
107+
* If the boot package has been 'replaced' then `stack build` will specify the
108+
latest version of that package in the package index, which may differ from the
109+
version provided by the version of GHC specified by the snapshot.
110+
111+
A boot package will be treated as 'replaced' if the package is included directly
112+
in the Stackage snapshot or it depends on a package included directly in the
113+
snapshot.
114+
115+
!!! note
116+
117+
Stackage snapshots do not include directly most boot packages but some
118+
snapshots may include directly some boot packages. In particular, some
119+
snapshots include directly `Win32` (which is a boot package on Windows)
120+
while others do not.
121+
122+
For example, if `Cabal` (a boot package) is not a project package or an
123+
extra-dep, then `stack build Cabal` with Stackage snapshot LTS Haskell 20.25
124+
will:
125+
126+
* on Windows, try to build the latest version of `Cabal` in the package
127+
index (because that snapshot includes `Win32` directly, and `Cabal`
128+
depends on `Win32` and so is treated as 'replaced'); and
129+
* on non-Windows, effectively, do nothing (because `Cabal` is not
130+
'replaced').
131+
132+
### Target: *package identifier*
133+
134+
Example: `stack build foobar-1.2.3`
135+
136+
If the package name is that of a project package, then Stack fails with an
137+
error.
138+
139+
If the package version is in the package index (e.g. Hackage) then Stack will
140+
use the latest revision of that version from the package index.
141+
142+
If the package is an extra-dep or in the snapshot, Stack will behave as if only
143+
the package name had been specified as the target (that is, ignoring the
144+
specified version).
145+
146+
Otherwise, Stack will fail with an error, reporting that the package name is
147+
unknown.
148+
149+
### Target: project package *component*
150+
151+
Examples:
152+
* `stack build my-package:lib`
153+
* `stack build my-package:exe:my-executable`
154+
* `stack build my-package:test:my-test-suite`
155+
* `stack build my-package:bench:my-benchmark`
156+
* `stack build my-package:my-executable`
157+
* `stack build my-package:my-test-suite`
158+
* `stack build my-package:my-benchmark`
159+
* `stack build :my-executable`
160+
* `stack build :my-test-suite`
161+
* `stack build :my-benchmark`
162+
163+
You can select individual components from inside a project package to be built.
164+
This can be done for more fine-grained control over which test suites to run, or
165+
to have a faster compilation cycle.
166+
167+
There are multiple ways to refer to a specific component:
168+
169+
* `<package-name>:lib` or `<package-name>:<comp-type>:<comp-name>` (where the
170+
component type, `<comp-type>`, is one of `exe`, `test`, or `bench`) is the
171+
most explicit. The library component type (`lib`) does not have an
172+
associated component name, `<comp-name>`.
173+
174+
* `<package-name>:<comp-name>` allows you to leave out the component type, as
175+
that will often be unique for a given component name. For example,
176+
`stack build mypackage:my-test-suite`.
177+
178+
* `:<comp-name>` is a useful shortcut, saying "find the component`<comp-name>`
179+
in all of the project packages". This will result in an error if more than
180+
one package has a component with the specified name. For example,
181+
`stack build :my-test-suite`.
182+
161183
For further information about available targets, see the
162184
[`stack ide targets` command](ide_command.md).
163185

186+
### Target: *local directory*
187+
188+
Examples:
189+
* `stack build foo/bar`
190+
* `stack build ./foo`
191+
* `stack build .`
192+
193+
Stack will find all project packages that exist in the given directory hierarchy
194+
and then follow the same procedure as passing in package names as mentioned
195+
above.
196+
197+
!!! note
198+
199+
If the directory name is parsed as one of the above target types, it will
200+
be treated as that. Explicitly starting the target with `./` can avoid that.
201+
For example, `stack build ./foo`.
202+
203+
!!! note
204+
205+
`stack build .` will target project packages in the current working
206+
directory or its subdirectories.
207+
164208
## Controlling what gets built
165209

166210
Stack will automatically build the necessary dependencies. See the introductory

0 commit comments

Comments
 (0)