diff --git a/doc/configure/yaml/index.md b/doc/configure/yaml/index.md index 78aed557d2..45e96eb5a7 100644 --- a/doc/configure/yaml/index.md +++ b/doc/configure/yaml/index.md @@ -16,7 +16,7 @@ Stack's configuration options are each of one of two types: - :material-account:{ .lg .middle } __Project-specific__ - Configured at the project level + Configured only at the project level --- @@ -32,6 +32,8 @@ Stack's configuration options are each of one of two types: +Most of Stack's configuration options are non-project specific. + ## Project-level and global configuration files Stack's configuration files are each of one of two types: diff --git a/doc/configure/yaml/non-project.md b/doc/configure/yaml/non-project.md index 51ad15f308..157123ee0b 100644 --- a/doc/configure/yaml/non-project.md +++ b/doc/configure/yaml/non-project.md @@ -2,11 +2,18 @@ # Non-project-specific configuration -Non-project configuration options can be included in a project-level -configuration file (`stack.yaml`, by default) or in global configuration files -(`config.yaml`). However, non-project-specific options in the project-level -configuration file in the `global-project` directory are ignored by Stack. The -options below are listed in alphabetic order. +Non-project configuration options can be included in: + +* a [project-level configuration file](../yaml/index.md#project-level-and-global-configuration-files) + (`stack.yaml`, by default), like [project-specific](project.md) ones; or + +* [global configuration files](../yaml/index.md#project-level-and-global-configuration-files) + (`config.yaml`). + +However, non-project-specific options in the project-level configuration file in +the `global-project` directory are ignored by Stack. + +The options below are listed in alphabetic order. ## allow-different-user diff --git a/doc/configure/yaml/project.md b/doc/configure/yaml/project.md index aa391ab6ea..a92a44fec3 100644 --- a/doc/configure/yaml/project.md +++ b/doc/configure/yaml/project.md @@ -3,7 +3,8 @@ # Project-specific configuration Project-specific configuration options are valid only in a project-level -configuration file (`stack.yaml`, by default). +configuration file (`stack.yaml`, by default). Most of Stack's configuration +options are [non-project specific](non-project.md). Each of the Haskell packages to which a Stack project relates is either a **project package** that is part of the project and located locally or a package diff --git a/doc/tutorial/cabal_flags_and_ghc_options.md b/doc/tutorial/cabal_flags_and_ghc_options.md index 87eacde79d..5fb7fd00da 100644 --- a/doc/tutorial/cabal_flags_and_ghc_options.md +++ b/doc/tutorial/cabal_flags_and_ghc_options.md @@ -15,20 +15,27 @@ command: stack build --flag yackage:-upload ~~~ -This means: when compiling the `yackage` package, turn off the `upload` flag -(thus the `-` in `-upload`). Unlike other tools, Stack is explicit about which -package's flag you want to change. It does this for two reasons: +This means: when compiling the `yackage` package, turn off the `upload` Cabal +flag (thus the `-` in `-upload`). Unlike other tools, Stack is explicit about +which package's flag you want to change. It does this for two reasons: 1. There's no global meaning for Cabal flags, and therefore two packages can use the same flag name for completely different things. + 2. By following this approach, we can avoid unnecessarily recompiling snapshot - packages that happen to use a flag that we're using. + packages that happen to use a Cabal flag that we're using. -You can also change flag values on the command line for extra-dep and snapshot -packages. If you do this, that package will automatically be promoted to an -extra-dep, since the build plan is different than what the plan snapshot +You can also change Cabal flag values on the command line for extra-dep and +snapshot packages. If you do this, that package will automatically be promoted +to an extra-dep, since the build plan is different than what the plan snapshot definition would entail. +If you have Cabal flags that you will be setting regularly when building your +packages, you can add them to your Stack project-level configuration file +(`stack.yaml`). For more information, see the +[flags](../configure/yaml/project.md#flags) project-specific configuration +option documentation. + ## GHC options GHC options follow a similar logic as in managing Cabal flags, with a few @@ -90,10 +97,13 @@ While this specific corner case does catch people by surprise, the overall goal of reproducible builds is - in the Stack maintainers' views - worth the confusion. -Final point: if you have GHC options that you'll be regularly passing to your -packages, you can add them to your `stack.yaml` file. For more information, see -the [ghc-options](../configure/yaml/non-project.md#ghc-options) non-project -specific configuration option documentation. +If you have GHC options that you will be applying regularly when building your +packages, you can add them to your Stack project-level configuration file +(`stack.yaml`) or (if applicable) to a +[global Stack configuration file](../configure/yaml/index.md#project-level-and-global-configuration-files). +For more information, see the +[ghc-options](../configure/yaml/non-project.md#ghc-options) non-project specific +configuration option documentation. !!! note diff --git a/doc/tutorial/project_configuration.md b/doc/tutorial/project_configuration.md index 386799f4fb..066c6c1472 100644 --- a/doc/tutorial/project_configuration.md +++ b/doc/tutorial/project_configuration.md @@ -25,11 +25,13 @@ is the `stack.yaml` file. ## `stack.yaml` Stack requires a Stack project-level configuration file for every project. -`stack.yaml` is that file. The contents of the file define project-specific -options and non-project-specific options that apply to the project. +`stack.yaml` is that file. The contents of the file set project-specific and +non-project-specific options that apply to the project. (Non-project +specific options that affect the project may also be set in a +[global Stack configuration file](../configure/yaml/index.md#project-level-and-global-configuration-files).) -The contents of the file include comments beginning `#`. Ignoring those -comments, the contents will look something like this: +The contents of the `stack.yaml` file include comments beginning `#`. Ignoring +those comments, the contents will look something like this: ~~~yaml snapshot: