From 4b198806be037f96b3a85f31075880e7686d5d7f Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Tue, 26 Nov 2024 17:48:26 +0000 Subject: [PATCH 1/2] Re #6660 Fix typographical errors --- CONTRIBUTING.md | 4 ++-- doc/maintainers/releases.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6d7f44c127..866b1a0910 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -336,7 +336,7 @@ entry and [documentation](https://github.com/commercialhaskell/stack/tree/master/doc/) updates with your pull request. -## Backwards Compatability +## Backwards Compatibility The Stack package provides a library and an executable (`stack`) that depends on the library. The library is intended for use only by the executable. @@ -481,7 +481,7 @@ That said, the following may help: * Stack's imports are listed alphabetically, including `Stack.Prelude`, where applicable. The module names are left aligned, with space left for `qualified` where it is absent. -* Stack's code is sufficiently stable that explict import lists can sensibly be +* Stack's code is sufficiently stable that explicit import lists can sensibly be used. The exception is the import of `Stack.Prelude`. Not all modules have comprehensive explicit import lists. * Short explicit import lists follow the module name. Longer lists start on the diff --git a/doc/maintainers/releases.md b/doc/maintainers/releases.md index 5ce0e8d91c..adde6ac392 100644 --- a/doc/maintainers/releases.md +++ b/doc/maintainers/releases.md @@ -67,7 +67,7 @@ Examples: 4. Check the copyright dates, and update if needed. -5. Check the backwards compatability section of `CONTRIBUTING.md` is up to +5. Check the backwards compatibility section of `CONTRIBUTING.md` is up to date. 6. Ensure CI matrices in docs (travis-complex, appveyor, azure) have current From d2c3eb9544a75af96ddc4b43b0e1f4c876bb4d3b Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Tue, 26 Nov 2024 18:17:36 +0000 Subject: [PATCH 2/2] Document Stack's use of RTS options --- doc/commands/build_command.md | 10 ++++++++++ doc/commands/index.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+) diff --git a/doc/commands/build_command.md b/doc/commands/build_command.md index f472f84b62..7b2be2e51e 100644 --- a/doc/commands/build_command.md +++ b/doc/commands/build_command.md @@ -623,6 +623,11 @@ command line arguments. For example, to pass `'a single quoted string'`: The content of single quotes is taken literally. Within single quotes, `''` escapes a single quote. +!!! note "Runtime system (RTS) options" + + RTS options must be quoted to prevent the RTS extracting them as its own + when the Stack executable is run. + ### `--exec` option `stack build --exec ' []'` will run the specified command @@ -700,6 +705,11 @@ command line arguments. For example, to pass `'a single quoted string'`: The content of single quotes is taken literally. Within single quotes, `''` escapes a single quote. +!!! note "Runtime system (RTS) options" + + RTS options must be quoted to prevent the RTS extracting them as its own + when the Stack executable is run. + ## Flags affecting GHC's behaviour ### `--[no-]executable-profiling` flag diff --git a/doc/commands/index.md b/doc/commands/index.md index 9979587a37..817dcf9b15 100644 --- a/doc/commands/index.md +++ b/doc/commands/index.md @@ -10,6 +10,36 @@ of the guide and the part on [configuration](../configure/index.md) provide information about some of those features, organised as a reference guide. Some of the features are complex and separate pages are dedicated to them. +## stack command + +Stack is usually used with one of its commands (see further below). However: + +* `stack`, `stack --help` (or `-h`) lists Stack's commands, and flags and + options common to those commands; + +* `stack --help` (or `-h`) — provides help on the particular Stack + command, including flags and options specific to the command; and + +* `stack --version` identifies the version and Git hash of the Stack executable. + +!!! info "Runtime system (RTS) options" + + The Stack executable is built by GHC with the `-rtsopts=some` option. This + means that the RTS extracts command-line arguments bracketed between `+RTS` + and `-RTS` as its own when Stack is run. Only the following RTS + options are available: + + * `-?` (e.g. `stack +RTS -?`) causes the RTS to output information about + RTS options; and + + * `--info` (e.g. `stack +RTS --info`) causes the RTS to output information + about the RTS. + + To avoid the RTS extracting such command-line arguments as its own when + using Stack commands such as [`exec`](exec_command.md), + [`test`](test_command.md) or [`bench`](bench_command.md), see the + documentation for those commands. + ## Stack commands (thematic) ### Setting up