fake --help should document -t and -s parameters

[agross]

Description

While fake build supports -t <Target> and -s to run a target without dependencies, both arguments are not reported when you run fake --help or just fake.

Repro steps

Run fake (I'm using the global tool).

Known workarounds

Read the docs.

Related information

• Operating system: macOS, Windows
• Branch: global tool install
• .NET Runtime, CoreCLR or Mono Version: .NET Core
• Indications of severity: hard to understand as a beginner
• Version of FAKE (4.X, 5.X): 5

[matthid]

This is currently by design. The "targets" command line is entirely provided by a NuGet package and can be replaced.

To "see" the targets command line use fake build --help:

Usage:
  fake-run --list
  fake-run --version
  fake-run --help | -h
  fake-run [target_opts] [target <target>] [--] [<targetargs>...]

Target Module Options [target_opts]:
    -t, --target <target>
                          Run the given target (ignored if positional argument 'target' is given)
    -e, --environment-variable <keyval> [*]
                          Set an environment variable. Use 'key=val'. Consider using regular arguments, see https://fake.build/core-targets.html
    -s, --single-target    Run only the specified target.
    -p, --parallel <num>  Run parallel with the given number of tasks.

In fact the regular fake --help includes the following text at the end:

  Hint: Run 'fake run <script.fsx> --help' to get help from your script.

We could change the hint to fake build --help as long as the scriptname equals build.fsx

[agross]

I understand the technical details behind the current behavior. But it was non-discoverable to us today as beginners. I'd say a module should be able to extend the default --help screen and do that by default.

[matthid]

Well technically we could make the hint more visible or something like that. The problem with other approaches is point in time. when you execute fake --help should we download and load packages just to give you help? I don't think users would accept that.

[agross]

should we download and load packages just to give you help

Hm, no. But from a novice's point of view: We had the fake build script and a resolution already in place. Fake could attempt to load it and if it appears to be cached extend the help output by what the target module provides.

[matthid]

While I agree in theory I just don't see how it could work technically, sorry

[matthid]

The only thing that comes to mind is to 'special case' the targets module in some way and modify the output accordingly

[agross]

Another option would be to assume that targets are being used and hard-code its help into the fake executable.

[matthid]

Yes indeed.
My longer reply would be that the design of FAKE 5 allows to use a different "Target" module implementation with a different CLI. This is something I probably like to experiment with in the future. Therefore I'm not particularly eager to hard-code something "special" in for the current target module. On the other hand I see possible confusion.
So hard-coding additional help text for the default target module is probably fine? We can remove it again once we have another one and we can be careful with the wording?

[agross]

So hard-coding additional help text for the default target module is probably fine

If you want to optimize FAKE for being discoverable by beginners, then yes.

[matthid]

What about this:

$ dotnet run --project src/app/Fake.netcore/ -- --help

General:

  Fake command line is devided into runtime and script arguments.
  Runtime arguments control compilation and processing of the script,
  while script arguments are specific for the script or provided by
  a NuGet package.
  In most use cases you use the "Fake.Core.Target"-Module and therefore
  inherit the correspondig command line interface. While these arguments
  are not strictly part of the runtime we still show both below to
  make it easier for newcomers.

 -- RUNTIME ARGUMENTS SECTION --


Usage:
  fake.exe [fake_opts] run [run_opts] [<script.fsx>] [--] [<scriptargs>...]
  fake.exe [fake_opts] build [build_opts] [--] [<scriptargs>...]
  fake.exe --version
  fake.exe --help | -h

Fake Options [fake_opts]:
  -v, --verbose [*]     Verbose (can be used multiple times)
                        Is ignored if -s is used.
                        * -v: Log verbose but only for FAKE
                        * -vv: Log verbose for Paket as well
  -s, --silent          Be silent, use this option if you need to pipe your output into another tool or need some additional processing.

Fake Run Options [run_opts]:
  -d, --debug           Debug the script.
  -n, --nocache         Disable fake cache for this run.
  -p, --partial-restore
                        Only restore the required group instead of a full restore,
                        can be set globally by setting the environment variable FAKE_PARTIAL_RESTORE to true.
  --fsiargs <fsiargs> [*]  Arguments passed to the f# interactive.

Fake Build Options [build_opts]:
  -d, --debug           Debug the script.
  -n, --nocache         Disable fake cache for this run.
  -p, --partial-restore
                        Only restore the required group instead of a full restore,
                        can be set globally by setting the environment variable FAKE_PARTIAL_RESTORE to true.
  --fsiargs <fsiargs> [*]  Arguments passed to the f# interactive.
  -f, --script <script.fsx>
                        The script to execute (defaults to `build.fsx`).


 -- SCRIPT ARGUMENTS SECTION --

THIS SECTION ONLY APPLIES IF YOU USE THE
'Fake.Core.Target' PACKAGE!
You can use the following arguments in place of `<scriptargs>`:

Usage:
  fake-run --list
  fake-run --version
  fake-run --help | -h
  fake-run [target_opts] [target <target>] [--] [<targetargs>...]

Target Module Options [target_opts]:
    -t, --target <target>
                          Run the given target (ignored if positional
argument 'target' is given)
    -e, --environment-variable <keyval> [*]
                          Set an environment variable. Use 'key=val'.
Consider using regular arguments, see https://fake.build/core-targets.html
    -s, --single-target    Run only the specified target.
    -p, --parallel <num>  Run parallel with the given number of tasks.

Example:

To use verbose mode (from [fake_opts]) and print all
targets use "fake -v build -- --list". Because "--list"
doesn't conflict with any of the [build_opts], you can use
"fake -v build --list"

[agross]

👍