Tidy up non-standard project intialisation

Author: mpilgrem

doc/build_command.md

@@ -125,62 +125,158 @@ about how these dependencies get specified.
 In addition to specifying targets, you can also control what gets built, or
 retained, with the following flags:
 
-* `--haddock`, to build documentation.  This may cause a lot of packages to get
-  re-built, so that the documentation links work.
+### The `stack build --dependencies-only` flag
 
-* `--force-dirty`, to force rebuild of packages even when it doesn't seem
-  necessary based on file dirtiness.
+Set the flag to skip building the targets. The flag `--only-dependencies` has
+the same effect.
 
-* `--reconfigure`, to force reconfiguration even when it doesn't seem necessary
-  based on file dirtiness. This is sometimes useful with custom `Setup.hs`
-  files, in particular when they depend on external data files.
+### The `stack build --[no-]dry-run` flag
 
-* `--dry-run`, to build nothing and output information about the build plan.
+Default: Disabled
 
-* `--only-dependencies`, to skip building the targets.
+Set the flag to build nothing and output information about the build plan.
 
-* `--only-snapshot`, to only build snapshot dependencies, which are cached and
-  shared with other projects.
+### The `stack build --flag` option
 
-* `--keep-going`, to continue building packages even after some build step
-  fails. The packages which depend upon the failed build won't get built.
+`stack build --flag <package_name>:[-]<flag_name>` sets (or unsets) the
+specified Cabal flag for the specified package.
 
-* `--keep-tmp-files`, to keep intermediate files and build directories that
-  would otherwise be considered temporary and deleted. It may be useful to
-  inspect these, if a build fails. By default, they are not kept.
+This option can be specified multiple times to set (or unset) multiple Cabal
+flags.
 
-* `--skip`, to skip building components of a local package. It allows
-  you to skip test suites and benchmark without specifying other components
-  (e.g. `stack test --skip long-test-suite` will run the tests without the
-  `long-test-suite` test suite). Be aware that skipping executables won't work
-  the first time the package is built due to
-  [an issue in cabal](https://github.com/commercialhaskell/stack/issues/3229).
-  This option can be specified multiple times to skip multiple components.
+The same Cabal flag name can be set (or unset) for multiple packages (at the
+command line only) with:
 
-## Flags
+~~~text
+stack build --flag *:[-]<flag)name>
+~~~
+
+!!! note
+
+    Currently you needs to list all of your modules that interpret flags in the
+    `other-modules` section of a Cabal file. Cabal (the tool) has a different
+    behavior currently and doesn't require that the modules be listed. This may
+    change in a future release.
+
+### The `stack build --[no-]force-dirty` flag
+
+Default: Disabled
+
+Set the flag to force rebuild of packages even when it doesn't seem necessary
+based on file dirtiness.
+
+### The `stack build --[no-]haddock` flag
+
+Default: Disabled
+
+Set the flag to build Haddock documentation. This may cause a lot of packages to
+get re-built, so that the documentation links work.
+
+### The `stack build --[no-]keep-going` flag
+
+Default (`stack build`): Disabled
+
+Default (`stack test` or `stack bench`): Enabled
+
+Set the flag to continue building packages even after some build step fails.
+The packages which depend upon the failed build won't get built.
+
+### The `stack build --[no-]keep-tmp-files` flag
+
+Default: Disabled
+
+Set the flag to keep intermediate files and build directories that would
+otherwise be considered temporary and deleted. It may be useful to inspect
+these, if a build fails. By default, they are not kept.
+
+### The `stack build --only-dependencies` flag
+
+Set the flag to skip building the targets. The flag `--dependencies-only` has
+the same effect.
+
+### The `stack build --[no-]reconfigure` flag
+
+Default: Disabled
+
+Set the flag to force reconfiguration even when it doesn't seem necessary based
+on file dirtiness. This is sometimes useful with custom `Setup.hs` files, in
+particular when they depend on external data files.
+
+### The `stack build --skip` option
+
+`stack build --skip <component>` skips building the specified components of a
+local package. It allows you to skip test suites and benchmark without
+specifying other components (e.g. `stack test --skip long-test-suite` will run
+the tests without the `long-test-suite` test suite). Be aware that skipping
+executables won't work the first time the package is built due to an issue in
+[Cabal](https://github.com/commercialhaskell/stack/issues/3229).
+
+This option can be specified multiple times to skip multiple components.
+
+### The `stack build --only-snapshot` flag
+
+Set the flag to build only snapshot dependencies, which are cached and shared
+with other projects.
+
+## Other flags and options
 
 There are a number of other flags accepted by `stack build`. Instead of listing
 all of them, please use `stack build --help`. Some particularly convenient ones
 worth mentioning here since they compose well with the rest of the build system
 as described:
 
-* `--file-watch` will rebuild your project every time a file changes, by default
-  it will take into account all files belonging to the targets you specify,
-  alternatively one could specify `--watch-all` which will make Stack watch
-  any local files (from project packages or from local dependencies)
-* `--exec "cmd [args]"` will run a command after a successful build
+### The `stack build --exec` option
+
+`stack build --exec "<command> [<arguments>]"` will run a command after a
+successful build.
+
+### The `stack build --file-watch` flag
+
+Set the flag to rebuild your project every time a file changes. By default it
+will take into account all files belonging to the targets you specify. See also
+the `--watch-all` flag.
+
+### The `stack build --[no-]interleaved-output` flag
+
+[:octicons-tag-24: 2.1.1](https://github.com/commercialhaskell/stack/releases/tag/v2.1.1)
+
+Default: Enabled
+
+Set the flag to have the output of all packages being built scroll by in a
+streaming fashion. The output from each package built will be prefixed by the
+package name, e.g. `mtl> Building ...`. This will include the output from
+dependencies being built, not just targets.
+
+Unset the flag to disable this behaviour. When disabled:
 
-To come back to the composable approach described above, consider this final
-example (which uses the [wai repository](https://github.com/yesodweb/wai/)). The
+* When building a single target package (e.g., `stack build` in a project
+  with only one package, or `stack build <package_name>` in a multi-package
+  project), the build output from GHC will be hidden for building all
+  dependencies, and will be displayed for the one target package.
+* By default, when building multiple target packages, the output from these
+  will end up in a log file instead of on the console unless it contains
+  errors or warnings, to avoid problems of interleaved output and decrease
+  console noise. If you would like to see this content instead, you can use
+  the `dump-logs` option.
+
+### The `stack build --watch-all` flag
+
+Set the flag to rebuild your project every time any local file changes (from
+project packages or from local dependencies). See also the `--file-watch` flag.
+
+## Composition
+
+To come back to the composable approach described above, consider this example
+(which uses the `wai` [repository](https://github.com/yesodweb/wai/)). The
 command:
 
 ~~~text
 stack build --file-watch --test --copy-bins --haddock wai-extra :warp warp:doctest --exec 'echo Yay, it worked!'
 ~~~
 
-This command will start Stack up in file watch mode, waiting for files in your
-project to change. When first starting, and each time a file changes, it will do
-all of the following.
+will start Stack up in file watch mode, waiting for files in your project to
+change. When first starting, and each time a file changes, it will do all of the
+following.
 
 * Build the wai-extra package and its test suites
 * Build the `warp` executable
@@ -191,25 +287,3 @@ all of the following.
 * If all of that succeeds:
     * Copy generated executables to the local bin path
     * Run the command `echo Yay, it worked!`
-
-## Build output
-
-Starting with Stack 2.1, output of all packages being built scrolls by in a
-streaming fashion. The output from each package built will be prefixed by the
-package name, e.g. `mtl> Building ...`. This will include the output from
-dependencies being built, not just targets.
-
-To disable this behaviour, you can pass `--no-interleaved-output`, or add
-`interleaved-output: false` to your `stack.yaml` file.  When disabled:
-
-  * When building a single target package (e.g., `stack build` in a project
-    with only one package, or `stack build package-name` in a multi-package
-    project), the build output from GHC will be hidden for building all
-    dependencies, and will be displayed for the one target package.
-
-  * By default, when building multiple target packages, the output from these
-    will end up in a log file instead of on the console unless it contains
-    errors or warnings, to avoid problems of interleaved output and decrease
-    console noise. If you would like to see this content instead, you can use
-    the `--dump-logs` command line option, or add `dump-logs: all` to your
-    YAML configuration file (`stack.yaml` or `config.yaml`).

doc/nonstandard_project_init.md

@@ -2,132 +2,34 @@
 
 # Non-standard project initialization
 
-## Introduction
-The purpose of this page is to collect information about issues that arise when
-users either have an existing Cabal project or another nonstandard setup such
-as a private Hackage database.
+You may need to configure Stack to work with an existing project that has one or
+more Cabal files but no Stack project-level configuration file (`stack.yaml`).
 
-## Using a Cabal file
+## The `stack init` command
 
-New users may be confused by the fact that you must add dependencies to the
-package's Cabal file, even in the case when you have already listed the package
-in the `stack.yaml` file. In most cases, dependencies for your package that are
-in the Stackage snapshot need *only* be added to the Cabal file. Stack makes
-heavy use of Cabal under the hood. In general, your Stack packages should also
-end up being valid packages for Cabal (the tool).
+The `stack init` command:
 
-### Issues Referenced
-  - <https://github.com/commercialhaskell/stack/issues/105>
+* finds all of the Cabal files in your current directory and subdirectories
+  (unless you use `--ignore-subdirs`) and determines the packages and versions
+  they require
+* Finds the best combination of snapshot and package flags that allows
+  everything to compile with minimum external dependencies
+* Tries to look for the best matching snapshot from latest Haskell LTS, latest
+  Stackage Nightly, and other Haskell LTS, in that order
 
-## Passing Flags to Cabal
+If `stack init` finds a match, it will generate a `stack.yaml` file.
 
-Any build command, `bench`, `install`, `haddock`, `test`, etc. takes a `--flag`
-option which passes flags to cabal. Another way to do this is using the flags
-field in a `stack.yaml`, with the option to specify flags on a per package
-basis.
+You can specify the directory, or directories to include in the search for
+Cabal files.
 
-As an example, in a `stack.yaml` for multi-package project with packages `foo`,
-`bar`, `baz`:
+### The `stack init --force` flag
 
-~~~yaml
-flags:
-  foo:
-    release: true
-  bar:
-    default: true
-  baz:
-    manual: true
-~~~
+Set the flag to force the over-writing of any existing `stack.yaml` file.
 
-It is also possible to pass the same flag to multiple packages, i.e.
-`stack build --flag *:necessary`
+### The `stack init --ignore-subdirs` flag
 
-Currently one needs to list all of your modules that interpret flags in the
-`other-modules` section of a cabal file. Cabal (the tool) has a different
-behavior currently and doesn't require that the modules be listed. This may
-change in a future release.
+Set the flag to not search for Cabal files in subdirectories.
 
+### The `stack init --omit-packages` flag
 
-### Issues Referenced
-  - <https://github.com/commercialhaskell/stack/issues/191>
-  - <https://github.com/commercialhaskell/stack/issues/417>
-  - <https://github.com/commercialhaskell/stack/issues/335>
-  - <https://github.com/commercialhaskell/stack/issues/301>
-  - <https://github.com/commercialhaskell/stack/issues/365>
-  - <https://github.com/commercialhaskell/stack/issues/105>
-
-## Selecting a Resolver
-
-`stack init` or `stack new` will try to default to the current Haskell LTS
-present on `https://www.stackage.org/snapshots` if no snapshot has been
-previously used locally, and to the latest LTS snapshot locally used for a
-build otherwise. Using an incorrect resolver can cause a build to fail if the
-version of GHC it requires is not present.
-
-In order to override the resolver entry at project initialization one can pass
-`--prefer-lts` or `--prefer-nightly`. These options will choose the latest LTS
-or nightly versions locally used.  Alternatively the `--resolver` option can be
-used with the name of any snapshots on Stackage, or with `lts` or `nightly` to
-select the latest versions, disregarding previously used ones. This is not the
-default so as to avoid unnecessary recompilation time.
-
-:TODO: Document `--solver`
-
-### Issues Referenced
-  - <https://github.com/commercialhaskell/stack/issues/468>
-  - <https://github.com/commercialhaskell/stack/issues/464>
-
-## Using git Repositories
-
-Stack has support for packages that reside in remote git locations. Please see
-the [YAML configuration
-documentation](yaml_configuration.md#git-and-mercurial-repos) for more
-information.
-
-### Issues Referenced
-  - <https://github.com/commercialhaskell/stack/issues/254>
-  - <https://github.com/commercialhaskell/stack/issues/199>
-
-## Private Hackage
-Working with a private Hackage is currently supported in certain situations.
-There exist special entries in `stack.yaml` that may help you. In a
-`stack.yaml` file, it is possible to add lines for packages in your database
-referencing the sdist locations via an `http` entry, or to use a `Hackage`
-entry.
-
-The recommended stack workflow is to use git submodules instead of a private
-Hackage. Either by using git submodules and listing the directories in the
-packages section of `stack.yaml`, or by adding the private dependencies as git
-URIs with a commit SHA to the `stack.yaml`. This has the large benefit of
-eliminating the need to manage a Hackage database and pointless version bumps.
-
-For further information see [YAML configuration](yaml_configuration.md)
-
-### Issues Referenced
-  - <https://github.com/commercialhaskell/stack/issues/445>
-  - <https://github.com/commercialhaskell/stack/issues/565>
-
-## Custom Snapshots
-See [Custom Snapshots](custom_snapshot.md).
-
-### Issues Referenced
-  - <https://github.com/commercialhaskell/stack/issues/111>
-  - <https://github.com/commercialhaskell/stack/issues/253>
-  - <https://github.com/commercialhaskell/stack/issues/137>
-
-## Intra-package Targets
-
-Stack supports intra-package targets, similar to `cabal build COMPONENTS` for
-situations when you don't want to build every target inside your package.
-
-For example, command:
-
-~~~text
-stack build stack:lib:stack
-stack test stack:test:stack-integration-test
-~~~
-
-Note: this does require prefixing the component name with the package name.
-
-### Issues referenced
-  - <https://github.com/commercialhaskell/stack/issues/201>
+Set the flag to exclude any conflicting or incompatible user packages.

doc/yaml_configuration.md

@@ -225,7 +225,7 @@ Default: `{}`
 
 Command line equivalent (takes precedence): `stack build --flag` option
 
-Flags can be set for each package separately, e.g.
+Flags can be set for each package separately. For example:
 
 ~~~yaml
 flags: