Skip to content

Commit

Permalink
Re #4343 Remove ambiguity over use of target argument
Browse files Browse the repository at this point in the history
  • Loading branch information
@mpilgrem
mpilgrem committed Aug 7, 2024
1 parent b2cc34b commit c7f59ce
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 72 deletions.
51 changes: 28 additions & 23 deletions doc/commands/dot_command.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,29 +20,34 @@ to represent the relationships between your packages and their dependencies.

By default:

* external dependencies are excluded from the output. Pass the flag
`--external` to include external dependencies;
* the `base` package and its dependencies are included in the output. Pass the
flag `--no-include-base` to exclude `base` and its dependencies;
* there is no limit to the depth of the resolution of dependencies. Pass the
`--depth <depth>` option to limit the depth;
* all relevant packages are included in the output. Pass the
`--prune <packages>` option to exclude the specified packages, where
`<packages>` is a list of package names separated by commas;
* all packages in the project are included in the output. However, the target
for the command can be specified as an argument. It uses the same format
as the [`stack build` command](build_command.md);
* test components of the packages in the project are excluded from the output.
Pass the flag `--test` to include test components; and
* benchmark components of the packages in the project are excluded from the
output. Pass the flag `--bench` to include benchmark components.git p

Pass the option `--flag <package_name>:<flag_name>` or
`--flag <package_name>:-<flag_name>` to set or unset a Cabal flag. This
option can be specified multiple times.

Pass the flag `--global-hints` to use a hint file for global packages. If a hint
file is used, GHC does not need to be installed.
* external dependencies are excluded from the output. Pass the flag
`--external` to include external dependencies;
* the `base` package and its dependencies are included in the output. Pass the
flag `--no-include-base` to exclude `base` and its dependencies;
* there is no limit to the depth of the resolution of dependencies. Pass the
`--depth <depth>` option to limit the depth;
* all relevant packages are included in the output. Pass the
`--prune <packages>` option to exclude the specified packages (including
project packages), where `<packages>` is a list of package names separated
by commas;
* for all relevant project packages, relevant dependencies are included in the
output. However, each project package for which dependencies are included
can be specified as a target argument. The argument uses the same format as
the [`stack build` command](build_command.md) but components of project
packages are ignored. Non-project packages are also ignored;
* Cabal flags are as specified by the package description files and the
project-level configuration file (`stack.yaml`, by default). Pass the
option `--flag <package_name>:<flag_name>` or
`--flag <package_name>:-<flag_name>` to set or unset a Cabal flag. This
option can be specified multiple times;
* test components of project packages are excluded from the output. Pass the
flag `--test` to include test components;
* benchmark components of project packages are excluded from the output. Pass
the flag `--bench` to include benchmark components; and
* global packages for the specified version of GHC are those specified by the
global package database of an installed GHC. Pass the flag `--global-hints`
to use a hint file for global packages. If a hint file is used, GHC does not
need to be installed.

## Examples

Expand Down
97 changes: 48 additions & 49 deletions doc/commands/ls_command.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,20 +40,56 @@ stack ls dependencies [--separator SEP] [--[no-]license] [--filter ITEM]
[--test] [--bench] [--global-hints]
~~~

`stack ls dependencies` lists all of the packages and versions used for a
project. All project packages are considered by default, but one or more targets
can be specified as an argument. For further information, see the
[target syntax](build_command.md#target-syntax) documentation.
`stack ls dependencies` lists package versions used for a project.

!!! note

If the first target is one of `cabal`, `json`, `text` and `tree`, then a
subcommand must be specified.

!!! info
By default:

If a specified target is not a project package, then it will not contribute
packages to the command's output.
* with the `text` or `tree` subcommand (see below), the package name is
followed by its version. Pass the `--license` flag to follow the package
name with its licence. (Consistent with the Cabal package description format
specification, only the American English spelling (license) is accepted.)
* With the `text` or `tree` subcommand, the separator between the package name
and what follows is a space character. Pass the `--separator` option to
specify a different separator;
* with the `text` command, all relevant package names are included. Pass the
`--filter` option to specify an item to be filtered out from the results, if
present. An item can be `$locals` (for all project packages) or a package
name. It can be specified multiple times;

!!! note

The special value `$locals` will need to be enclosed with single quotes
to distinguish it from a shell variable.

* external dependencies are excluded from the output. Pass the flag
`--external` to include external dependencies;
* the `base` package and its dependencies are included in the output. Pass the
flag `--no-include-base` to exclude `base` and its dependencies;
* there is no limit to the depth of the resolution of dependencies. Pass the
`--depth <depth>` option to limit the depth;
* all relevant packages are included in the output. Pass the
`--prune <packages>` option to exclude the specified packages (including
project packages), where `<packages>` is a list of package names separated
by commas;
* for all relevant project packages, relevant dependencies are included in the
output. However, each project package for which dependencies are included
can be specified as a target argument. The argument uses the same format as
the [`stack build` command](build_command.md) but components of project
packages are ignored. Non-project packages are also ignored;

!!! note

If the first target is one of `cabal`, `json`, `text` and `tree`, then a
subcommand must be specified.

* test components of project packages are excluded from the output. Pass the
flag `--test` to include test components;
* benchmark components of project packages are excluded from the output. Pass
the flag `--bench` to include benchmark components; and
* global packages for the specified version of GHC are those specified by the
global package database of an installed GHC. Pass the flag `--global-hints`
to use a hint file for global packages. If a hint file is used, GHC does not
need to be installed.

Subcommands specify the format of the output, as follows:

Expand Down Expand Up @@ -144,43 +180,6 @@ Subcommands specify the format of the output, as follows:
│ │ │ ├─┬ ghc-prim 0.8.0
~~~
The `--separator` option, with the `text` or `tree` subcommand, specifies the
separator between the package name and its version. The default is a space
character.
Set the `--license` flag, after the `text` or `tree` subcommand, to replace each
package's version with its licence. (Consistent with the Cabal package
description format specification, only the American English spelling (license)
is accepted.)
The `--filter` option, with the `text` subcommand, specifies an item to be
filtered out from the results, if present. An item can be `$locals` (for all
project packages) or a package name. It can be specified multiple times.
!!! note
The special value `$locals` will need to be enclosed with single quotes to
distinguish it from a shell variable.
Set the `--no-external` flag to exclude external dependencies.
Set the `--no-include-base` flag to exclude dependencies on the `base` package.
The `--depth` option limits the depth of dependency resolution.
The `--prune <packages>` option prunes the specified packages and their
dependencies from the tree of packages used to generate the output, where
`<packages>` is a comma separated list of package names.
The `--flag` option allows Cabal flags to be specified.
Pass the `--test` flag to consider the dependencies of test suite components.
Pass the `--bench` flag to consider the dependencies of benchmark components.
Pass the `--global-hints` flag to use a hints file for global packages. The
command then does not require an installed GHC.
## The `stack ls globals` command
~~~text
Expand Down

0 comments on commit c7f59ce

Please sign in to comment.