Skip to content

Commit d42e32d

Browse files
mpilgremmpilgrem
committed
Fix misnamed file names
1 parent b278745 commit d42e32d

File tree

2 files changed

+157
-0
lines changed

2 files changed

+157
-0
lines changed

‎doc/tutorial/multi-package_projects.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
<div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
2+
3+
# 7. Multi-package projects
4+
5+
Until now, everything we've done with Stack has used a single-package project.
6+
However, Stack's power truly shines when you're working on multi-package
7+
projects. All the functionality you'd expect to work just does: dependencies
8+
between packages are detected and respected, dependencies of all packages are
9+
just as one cohesive whole, and if anything fails to build, the build commands
10+
exits appropriately.
11+
12+
Let's demonstrate this with the `wai-app-static` and `yackage` packages,
13+
starting in the root directory for all our Haskell projects. Command:
14+
15+
~~~text
16+
mkdir multi
17+
cd multi
18+
stack unpack wai-app-static yackage
19+
Unpacked wai-app-static (from Hackage) to .../multi/wai-app-static-3.1.7.4/
20+
Unpacked yackage (from Hackage) to .../multi/yackage-0.8.1/
21+
stack init
22+
Looking for .cabal or package.yaml files to use to init the project.
23+
Using cabal packages:
24+
- wai-app-static-3.1.7.4/
25+
- yackage-0.8.1/
26+
27+
Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@47:40: version operators used. To use version operators the package needs to specify at least 'cabal-version: >= 1.8'.
28+
Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@21:36: version operators used. To use version operators the package needs to specify at least 'cabal-version: >= 1.8'.
29+
Selecting the best among 18 snapshots...
30+
31+
* Matches ...
32+
33+
Selected resolver: ...
34+
Initialising configuration using resolver: ...
35+
Total number of user packages considered: 2
36+
Writing configuration to file: stack.yaml
37+
stack build --haddock --test
38+
# Goes off to build a whole bunch of packages
39+
~~~
40+
41+
If you look at the `stack.yaml` file, you'll see exactly what you'd expect:
42+
43+
~~~yaml
44+
resolver:
45+
url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/19/17.yaml
46+
packages:
47+
- wai-app-static-3.1.7.4
48+
- yackage-0.8.1
49+
~~~
50+
51+
Notice that multiple directories are listed in the `packages` key.
52+
53+
In addition to local directories, you can also refer to packages available in a
54+
Git repository or in a tarball over HTTP/HTTPS. This can be useful for using a
55+
modified version of a dependency that hasn't yet been released upstream.
56+
57+
!!! note
58+
59+
When adding upstream packages directly to your project it is important to
60+
distinguish _project packages_ located locally from the upstream
61+
_dependency packages_. Otherwise you may have trouble running `stack ghci`.
62+
See [stack.yaml documentation](../configure/yaml/project.md#packages) for
63+
more details.

‎doc/tutorial/stack_build_synonyms.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
<div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
2+
3+
# 5. `stack build` synonyms
4+
5+
Let's look at a subset of the `stack --help` output:
6+
7+
~~~text
8+
build Build the package(s) in this directory/configuration
9+
install Shortcut for 'build --copy-bins'
10+
test Shortcut for 'build --test'
11+
bench Shortcut for 'build --bench'
12+
haddock Shortcut for 'build --haddock'
13+
~~~
14+
15+
Four of these commands are just synonyms for the `build` command. They are
16+
provided for convenience for common cases (e.g., `stack test` instead of
17+
`stack build --test`) and so that commonly expected commands just work.
18+
19+
What's so special about these commands being synonyms? It allows us to make
20+
much more composable command lines. For example, we can have a command that
21+
builds executables, generates Haddock documentation (Haskell API-level docs),
22+
and builds and runs your test suites, with:
23+
24+
~~~text
25+
stack build --haddock --test
26+
~~~
27+
28+
You can even get more inventive as you learn about other flags. For example,
29+
take the following command:
30+
31+
~~~text
32+
stack build --pedantic --haddock --test --exec "echo Yay, it succeeded" --file-watch
33+
~~~
34+
35+
This command will:
36+
37+
* turn on all warnings and errors (the `--pedantic` flag)
38+
* build your library and executables
39+
* generate Haddocks (the `--haddock` flag)
40+
* build and run your test suite (the `--test` flag)
41+
* run the command `echo Yay, it succeeded` when that completes (the `--exec`
42+
option)
43+
* after building, watch for changes in the files used to build the project, and
44+
kick off a new build when done (the `--file-watch` flag)
45+
46+
## The `stack install` command and `copy-bins` option
47+
48+
It's worth calling out the behavior of the `install` command and `--copy-bins`
49+
option, since this has confused a number of users (especially when compared to
50+
behavior of other tools like Cabal (the tool)). The `install` command does
51+
precisely one thing in addition to the build command: it copies any generated
52+
executables to the local binary directory. You may recognize the default value
53+
for that path:
54+
55+
On Unix-like operating systems, command:
56+
57+
~~~text
58+
stack path --local-bin
59+
/home/<user_name>/.local/bin
60+
~~~
61+
62+
On Windows, command:
63+
64+
~~~text
65+
stack path --local-bin
66+
C:\Users\<user_name>\AppData\Roaming\local\bin
67+
~~~
68+
69+
That's why the download page recommends adding that directory to your PATH. This
70+
feature is convenient, because now you can simply run `executable-name` in your
71+
shell instead of having to run `stack exec executable-name` from inside your
72+
project directory.
73+
74+
Since it's such a point of confusion, let me list a number of things Stack does
75+
*not* do specially for the `install` command:
76+
77+
* Stack will always build any necessary dependencies for your code. The install
78+
command is not necessary to trigger this behavior. If you just want to build a
79+
project, run `stack build`.
80+
* Stack will *not* track which files it's copied to your local binary directory
81+
nor provide a way to automatically delete them. There are many great tools out
82+
there for managing installation of binaries, and Stack does not attempt to
83+
replace those.
84+
* Stack will not necessarily be creating a relocatable executable. If your
85+
executables hard-codes paths, copying the executable will not change those
86+
hard-coded paths.
87+
88+
* At the time of writing, there's no way to change those kinds of paths with
89+
Stack, but see
90+
[issue #848 about --prefix](https://github.com/commercialhaskell/stack/issues/848)
91+
for future plans.
92+
93+
That's really all there is to the `install` command: for the simplicity of what
94+
it does, it occupies a much larger mental space than is warranted.

0 commit comments

Comments
 (0)