Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
agross opened this issue Mar 18, 2019 · 11 comments

Comments

Projects
None yet
2 participants
@agross
Copy link

commented Mar 18, 2019

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 comment has been minimized.

Copy link
Collaborator

commented Mar 18, 2019

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

This comment has been minimized.

Copy link
Author

commented Mar 18, 2019

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

This comment has been minimized.

Copy link
Collaborator

commented Mar 18, 2019

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

This comment has been minimized.

Copy link
Author

commented Mar 18, 2019

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

This comment has been minimized.

Copy link
Collaborator

commented Mar 18, 2019

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

@matthid

This comment has been minimized.

Copy link
Collaborator

commented Mar 18, 2019

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

@agross

This comment has been minimized.

Copy link
Author

commented Mar 18, 2019

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

@matthid

This comment has been minimized.

Copy link
Collaborator

commented Mar 21, 2019

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

This comment has been minimized.

Copy link
Author

commented Mar 21, 2019

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

This comment has been minimized.

Copy link
Collaborator

commented Apr 4, 2019

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"

@matthid matthid closed this in f195d0b Apr 4, 2019

@agross

This comment has been minimized.

Copy link
Author

commented Apr 4, 2019

👍

@matthid matthid referenced this issue Apr 8, 2019

Merged

Release 5.13.0 #2279

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.