Skip to content

Commit 9388d36

Browse files
mpilgremmpilgrem
committed
Further revise FAQ
1 parent 2f2cecd commit 9388d36

File tree

1 file changed

+148
-151
lines changed

1 file changed

+148
-151
lines changed

‎doc/faq.md‎

Lines changed: 148 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -150,36 +150,102 @@
150150
stack build
151151
~~~
152152

153-
## Package-related
153+
## Setup-related
154154

155-
??? question "How do I use a package version on Hackage not in a snapshot?"
155+
??? question "Where is Stack installed?"
156156

157-
Add the package version to the [`extra-deps`](configure/yaml/project.md)
158-
project-specific configuration option in the
159-
[project-level configuration file](configure/yaml/yaml_configuration.md).
157+
Command:
160158

161-
??? question "How do I use a package version not on Hackage?"
159+
~~~text
160+
stack uninstall
161+
~~~
162162

163-
Add the location of the package version to the
164-
[`extra-deps`](configure/yaml/project.md) project-specific configuration
165-
option in the
166-
[project-level configuration file](configure/yaml/yaml_configuration.md).
163+
for information about where Stack is installed.
167164

168-
For further information, see the
169-
[package location](topics/package_location.md) documentation.
165+
??? question "Can I change Stack's default temporary directory?"
170166

171-
??? question "How do I use a modified upstream package?"
167+
Stack downloads and extracts files to `$STACK_ROOT/programs` on most platforms,
168+
which defaults to `~/.stack/programs`. On Windows `$LOCALAPPDATA\Programs\stack`
169+
is used. If there is not enough free space in this directory, Stack may fail.
170+
For instance, `stack setup` with a GHC installation requires roughly 1GB free.
171+
If this is an issue, you can set `local-programs-path` in your
172+
`~/.stack/config.yaml` to a directory on a file system with more free space.
172173

173-
Typically, you will want to get the source for the package and then add it
174-
to your `packages` list in the `stack.yaml` file. (See the previous
175-
question.) `stack unpack` is one approach for getting the source. Another
176-
would be to add the upstream package as a submodule to your project.
174+
If you use Stack with Nix integration, be aware that Nix uses a `TMPDIR`
175+
variable, and if it is not set Nix sets it to some subdirectory of `/run`, which
176+
on most Linuxes is a Ramdir. Nix will run the builds in `TMPDIR`, therefore if
177+
you don't have enough RAM you will get errors about disk space. If this happens
178+
to you, please _manually_ set `TMPDIR` before launching Stack to some directory
179+
on the disk.
177180

178-
??? question "I'd like to use my installed packages in a different directory. How do I tell Stack where to find my packages?"
181+
??? question "On Windows, `stack setup` tells me to add certain paths to the PATH instead of doing it?"
179182

180-
Set the `STACK_YAML` environment variable to point to the `stack.yaml`
181-
configuration file for your project. Then you can run `stack exec`, `stack ghc`,
182-
etc., from any directory and still use your packages.
183+
With PowerShell, it is easy to automate even that step. Command:
184+
185+
~~~ps
186+
$Env:Path = ( stack setup | %{ $_ -replace '[^ ]+ ', ''} ), $Env:Path -join ";"
187+
~~~
188+
189+
??? question "Does Stack install the system/C libraries that some Cabal packages depend on?"
190+
191+
No. This is currently out of the scope of Stack's target set of features.
192+
Instead of attempting to automate the installation of 3rd party dependencies, we
193+
have the following approaches for handling system dependencies:
194+
195+
* Nix and docker help make your build and execution environment deterministic
196+
and predictable. This way, you can install system dependencies into a
197+
container, and share this container with all developers.
198+
199+
* If you have installed some libraries into a non-standard location, use the
200+
[`extra-lib-dirs`](configure/yaml/non-project.md#extra-lib-dirs) option or the
201+
[`extra-include-dirs`](configure/yaml/non-project.md#extra-include-dirs)
202+
option to specify it.
203+
204+
In the future, Stack might give operating system-specific suggestions for how to
205+
install system libraries.
206+
207+
??? question "How can I make Stack aware of my custom SSL certificates?"
208+
209+
=== "Linux"
210+
211+
Use the `SYSTEM_CERTIFICATE_PATH` environment variable to point at the directory
212+
where you keep your SSL certificates.
213+
214+
215+
=== "macOS"
216+
217+
In principle, you can use the following command to add a certificate to your
218+
system certificate keychain:
219+
220+
~~~bash
221+
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <certificate>
222+
~~~
223+
224+
Some users have reported issues with this approach, see issue
225+
[#907](https://github.com/commercialhaskell/stack/issues/907) for more
226+
information.
227+
228+
## Package description format-related
229+
230+
??? question "How does Stack support the Hpack specification?"
231+
232+
The [Hpack](https://github.com/sol/hpack) package description format is an
233+
alternative to that used in a Cabal file.
234+
235+
If a package directory contains an package description file in the Hpack
236+
format (`package.yaml`), Stack will use that file to create the
237+
corresponding Cabal file.
238+
239+
[`stack init`](commands/init_command.md) will use Hpack format package
240+
description files, if they are present.
241+
242+
The [`with-hpack`](configure/yaml/non-project.md#with-hpack) non-project
243+
specific configuration option or the
244+
[`--with-hpack`](configure/global_flags.md#-with-hpack-option) global flag
245+
can be used to specify an Hpack executable to use instead of Stack's
246+
built-in Hpack functionality.
247+
248+
## Package index-related
183249

184250
??? question "How do I update my package index?"
185251

@@ -189,51 +255,63 @@
189255
stack update
190256
~~~
191257

192-
Users of Cabal (the tool) are used to running `cabal update` regularly.
193-
Generally, it's not necessary with Stack: if the package index is missing,
194-
or if a snapshot refers to package/version that isn't available, Stack will
195-
automatically update and then try again. If you run into a situation where
196-
Stack doesn't automatically do the update for you, please report it as a
197-
bug.
258+
However, generally, it's not necessary with Stack: if the package index is
259+
missing, or if a snapshot refers to package version that isn't available,
260+
Stack will automatically update the package index and then try again.
261+
262+
If you run into a situation where Stack doesn't automatically update the
263+
package index, please report it as a bug.
198264

199265
??? question "Is it dangerous to update the package index automatically? Can that corrupt build plans?"
200266

201-
No. Stack is very explicit about which packages it's going to build for you.
202-
There are three sources of information to tell it which packages to install:
203-
the selected snapshot, the `extra-deps` configuration value, and your local
204-
packages. The only way to get Stack to change its build plan is to modify one
205-
of those three. Updating the index will have no impact on Stack's behavior.
267+
No. Stack is explicit about which packages it's going to build. There are
268+
three sources of information to tell Stack which packages to install: the
269+
selected snapshot, the `extra-deps` configuration value, and your project
270+
packages. The only way to get Stack to change its build plan is to modify
271+
one of those three. Updating the index will have no effect on Stack's
272+
behavior.
206273

207274
??? question "How do I use a custom package index?"
208275

209276
You can configure this in your project-level configuration file (`stack.yaml`,
210277
by default). See [YAML configuration](configure/yaml/yaml_configuration.md).
211278

212-
??? question "How does Stack support the Hpack specification?"
279+
## Package-related
213280

214-
* If a package directory contains an [Hpack](https://github.com/sol/hpack)
215-
`package.yaml` file, then Stack will use it to generate a Cabal file when
216-
building the package.
217-
* You can run `stack init` to initialize a `stack.yaml` file regardless of
218-
whether your packages are declared with Cabal files or with Hpack
219-
`package.yaml` files.
220-
* You can use the `with-hpack` YAML configuration or command line option to
221-
specify an Hpack executable to use instead of Stack's in-built Hpack
222-
functionality.
281+
??? question "How do I use a package version on Hackage not in a snapshot?"
223282

224-
## `stack build`-related
283+
Add the package version to the [`extra-deps`](configure/yaml/project.md)
284+
project-specific configuration option in the
285+
[project-level configuration file](configure/yaml/yaml_configuration.md).
225286

226-
??? question "What is the meaning of the arguments given to `stack build`, `test`, etc?"
287+
??? question "How do I use a package version not on Hackage?"
227288

228-
Those are the targets of the build, and can have one of three formats:
289+
Add the location of the package version to the
290+
[`extra-deps`](configure/yaml/project.md) project-specific configuration
291+
option in the
292+
[project-level configuration file](configure/yaml/yaml_configuration.md).
293+
294+
For further information, see the
295+
[package location](topics/package_location.md) documentation.
229296

230-
* A package name (e.g., `my-package`) will mean that the `my-package` package
231-
must be built
232-
* A package identifier (e.g., `my-package-1.2.3`), which includes a specific
233-
version. This is useful for passing to `stack install` for getting a specific
234-
version from upstream
235-
* A directory (e.g., `./my-package`) for including a local directory's package,
236-
including any packages in subdirectories
297+
??? question "How do I use a modified version of a package?"
298+
299+
Typically, a modified version of a package is used as a project package.
300+
Add the location of the package to the
301+
[`packages`](configure/yaml/project.md#packages) project-specific
302+
configuration option in the
303+
[project-level configuration file](configure/yaml/yaml_configuration.md).
304+
305+
One way to get the source code for the unmodified package version is to use
306+
the [`stack unpack`](commands/unpack_command.md).
307+
308+
??? question "I'd like to use my installed packages in a different directory. How do I tell Stack where to find my packages?"
309+
310+
Set the `STACK_YAML` environment variable to point to the `stack.yaml`
311+
configuration file for your project. Then you can run `stack exec`, `stack ghc`,
312+
etc., from any directory and still use your packages.
313+
314+
## `stack build`-related
237315

238316
??? question "How do I use a custom preprocessor?"
239317

@@ -426,17 +504,14 @@
426504

427505
??? question "How do I get `verbose` output from GHC when I build?"
428506

429-
Add `ghc-options: -vN` to the Cabal file or pass it via
430-
`stack build --ghc-options="-v"`.
507+
Set the [`--ghc-options`](commands/build_command.md#-ghc-options-option)
508+
option of `stack build` to `-v`.
431509

432510
## Snapshot-related
433511

434-
??? question "How does Stack choose which snapshot to use when creating a new configuration file?"
512+
??? question "How does Stack choose which snapshot to use when creating a project-level configuration file?"
435513

436-
It checks the two most recent LTS Haskell major versions and the most recent
437-
Stackage Nightly for a snapshot that is compatible with all of the version
438-
bounds in your Cabal file, favoring the most recent LTS. For more information,
439-
see the snapshot auto-detection section in the architecture document.
514+
See the [`stack init`](commands/init_command.md) command documentation.
440515

441516
## CI-related
442517

@@ -448,110 +523,32 @@
448523

449524
See the [Azure CI](topics/azure_ci.md) documentation.
450525

451-
## Setup-related
526+
## Linux-related
452527

453-
??? question "Where is Stack installed?"
528+
??? question "How do fix error [S-9443] for 'linux64-ncurses6'?"
454529

455-
Command:
530+
Most Linux distributions have standardized on providing `libtinfo.so.6`,
531+
either directly or as a symbolic link to `libncursesw.so.6`. As such, there
532+
are no GHC binary distributions that link to `libncursesw.so.6` after
533+
GHC 8.2.2.
456534

457-
~~~text
458-
stack uninstall
459-
~~~
460-
461-
for information about where Stack is installed.
462-
463-
??? question "Can I change Stack's default temporary directory?"
464-
465-
Stack downloads and extracts files to `$STACK_ROOT/programs` on most platforms,
466-
which defaults to `~/.stack/programs`. On Windows `$LOCALAPPDATA\Programs\stack`
467-
is used. If there is not enough free space in this directory, Stack may fail.
468-
For instance, `stack setup` with a GHC installation requires roughly 1GB free.
469-
If this is an issue, you can set `local-programs-path` in your
470-
`~/.stack/config.yaml` to a directory on a file system with more free space.
471-
472-
If you use Stack with Nix integration, be aware that Nix uses a `TMPDIR`
473-
variable, and if it is not set Nix sets it to some subdirectory of `/run`, which
474-
on most Linuxes is a Ramdir. Nix will run the builds in `TMPDIR`, therefore if
475-
you don't have enough RAM you will get errors about disk space. If this happens
476-
to you, please _manually_ set `TMPDIR` before launching Stack to some directory
477-
on the disk.
478-
479-
??? question "On Windows, `stack setup` tells me to add certain paths to the PATH instead of doing it?"
480-
481-
With PowerShell, it is easy to automate even that step. Command:
482-
483-
~~~ps
484-
$Env:Path = ( stack setup | %{ $_ -replace '[^ ]+ ', ''} ), $Env:Path -join ";"
485-
~~~
486-
487-
??? question "Does Stack install the system/C libraries that some Cabal packages depend on?"
488-
489-
No. This is currently out of the scope of Stack's target set of features.
490-
Instead of attempting to automate the installation of 3rd party dependencies, we
491-
have the following approaches for handling system dependencies:
492-
493-
* Nix and docker help make your build and execution environment deterministic
494-
and predictable. This way, you can install system dependencies into a
495-
container, and share this container with all developers.
496-
497-
* If you have installed some libraries into a non-standard location, use the
498-
[`extra-lib-dirs`](configure/yaml/non-project.md#extra-lib-dirs) option or the
499-
[`extra-include-dirs`](configure/yaml/non-project.md#extra-include-dirs)
500-
option to specify it.
501-
502-
In the future, Stack might give operating system-specific suggestions for how to
503-
install system libraries.
504-
505-
??? question "How can I make Stack aware of my custom SSL certificates?"
506-
507-
=== "Linux"
508-
509-
Use the `SYSTEM_CERTIFICATE_PATH` environment variable to point at the directory
510-
where you keep your SSL certificates.
511-
512-
513-
=== "macOS"
514-
515-
In principle, you can use the following command to add a certificate to your
516-
system certificate keychain:
517-
518-
~~~bash
519-
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <certificate>
520-
~~~
521-
522-
Some users have reported issues with this approach, see issue
523-
[#907](https://github.com/commercialhaskell/stack/issues/907) for more
524-
information.
525-
526-
??? question "How do I install GHC in Stack when it fails with the error: Missing ghc bindist for 'linux64-ncurses6'?"
527-
528-
Example Error:
529-
530-
~~~text
531-
No setup information found for ghc-8.6.4 on your platform.
532-
This probably means a GHC bindist has not yet been added for OS key 'linux64-ncurses6'.
533-
Supported versions: ghc-7.10.3, ghc-8.0.1, ghc-8.0.2, ghc-8.2.1, ghc-8.2.2
534-
~~~
535-
536-
Most Linux distributions have standardized on providing libtinfo.so.6 (either
537-
directly or as a symlink to libncursesw.so.6). As such, there aren't GHC 8.6.*
538-
bindists that link to libncursesw.so.6 available.
539-
540-
So creating a symlink to libncursesw.so.6 as libtinfo.so.6 can prevent this
541-
error (root privileges might be required). Command:
535+
This error can be prevented by creating a symbolic link to
536+
`libncursesw.so.6` using name `libtinfo.so.6`. Command:
542537

543538
~~~bash
544539
ln -s /usr/lib/libncursesw.so.6 /usr/lib/libtinfo.so.6
545540
~~~
546541

542+
Root privileges may be required.
543+
547544
## macOS-related
548545

549546
??? question "On macOS, how do I resolve linker errors when running `stack setup` or `stack build`?"
550547

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

556553
The workaround is to remove LLVM binaries from the PATH.
557554

0 commit comments

Comments
 (0)