From 4632b7caff5432d2ed5056f352cc482608479aca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melvyn=20La=C3=AFly?= Date: Tue, 19 Apr 2022 21:42:40 +0200 Subject: [PATCH 1/5] Fix CLI docs links --- help/markdown/core-commandlineparsing.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/help/markdown/core-commandlineparsing.md b/help/markdown/core-commandlineparsing.md index 87cdb298651..b64a240f5c4 100644 --- a/help/markdown/core-commandlineparsing.md +++ b/help/markdown/core-commandlineparsing.md @@ -36,16 +36,18 @@ match DocoptResult.tryGetArgument "-m" results with | Some arg -> printfn "%s" arg ``` +*Note the following links are permalinks to old commits. They are intended only as examples. You are encouraged to look at the current version too, because it's likely to have been updated.* + A more sophisticated example can be found in the fake runner: https://github.com/fsharp/FAKE/blob/64d871f5065412fe7b233025e454ccf3b89e46d7/src/app/Fake.netcore/Program.fs#L204-L259 Or the target module: -- https://github.com/fsharp/FAKE/blob/rc_1/src/app/Fake.Core.Target/Target.fs#L9-L26 +- https://github.com/fsharp/FAKE/blob/64d871f5065412fe7b233025e454ccf3b89e46d7/src/app/Fake.Core.Target/Target.fs#L9-L26 - https://github.com/fsharp/FAKE/blob/64d871f5065412fe7b233025e454ccf3b89e46d7/src/app/Fake.Core.Target/Target.fs#L564-L619 You can also take a look at the test-suite: -- https://github.com/fsharp/FAKE/blob/rc_1/src/test/Fake.Core.CommandLine.UnitTests/Fake.Core.CommandLine.fs +- https://github.com/fsharp/FAKE/blob/64d871f5065412fe7b233025e454ccf3b89e46d7/src/test/Fake.Core.CommandLine.UnitTests/Fake.Core.CommandLine.fs ## Differences to the python reference Docopt implementation From a7425020adbab38fb1f487b8f19a141db9d2d204 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melvyn=20La=C3=AFly?= Date: Tue, 19 Apr 2022 21:43:45 +0200 Subject: [PATCH 2/5] Avoid NRE (annoying when doing step by step test debugging) --- src/app/Fake.Core.Environment/Environment.fs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/app/Fake.Core.Environment/Environment.fs b/src/app/Fake.Core.Environment/Environment.fs index c84e7c602dd..b342a1816b2 100644 --- a/src/app/Fake.Core.Environment/Environment.fs +++ b/src/app/Fake.Core.Environment/Environment.fs @@ -92,8 +92,10 @@ module Environment = /// Retrieves the environment variable with the given name or returns the default bool if no value was set let environVarAsBoolOrDefault varName defaultValue = - try - (environVar varName).ToUpper() = "TRUE" + try + match environVar varName with + | null -> defaultValue + | var -> var.ToUpper() = "TRUE" with | _ -> defaultValue From 9182250bfe2aed9ec46551ad36eaf7592dc1ce23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melvyn=20La=C3=AFly?= Date: Tue, 19 Apr 2022 21:45:15 +0200 Subject: [PATCH 3/5] Fix typos in tests --- src/test/Fake.Core.IntegrationTests/SimpleHelloWorldTests.fs | 2 +- src/test/Fake.Core.UnitTests/Fake.DotNet.Cli.fs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/test/Fake.Core.IntegrationTests/SimpleHelloWorldTests.fs b/src/test/Fake.Core.IntegrationTests/SimpleHelloWorldTests.fs index 7c8de9de855..ac2b14bc791 100644 --- a/src/test/Fake.Core.IntegrationTests/SimpleHelloWorldTests.fs +++ b/src/test/Fake.Core.IntegrationTests/SimpleHelloWorldTests.fs @@ -88,7 +88,7 @@ let tests = let stdOut = String.Join("\n", result.Messages) let stdErr = String.Join("\n", result.Errors) - stdOut.Trim() |> Expect.stringContains "Hello FAKE exected" "Hello FAKE" + stdOut.Trim() |> Expect.stringContains "Hello FAKE expected" "Hello FAKE" stdErr.Trim() |> Expect.equal "empty expected" "" testCase "simple failed to compile" <| fun _ -> diff --git a/src/test/Fake.Core.UnitTests/Fake.DotNet.Cli.fs b/src/test/Fake.Core.UnitTests/Fake.DotNet.Cli.fs index 32e28fadb91..ac0499e4180 100644 --- a/src/test/Fake.Core.UnitTests/Fake.DotNet.Cli.fs +++ b/src/test/Fake.Core.UnitTests/Fake.DotNet.Cli.fs @@ -7,7 +7,7 @@ open Expecto [] let tests = testList "Fake.DotNet.Cli.Tests" [ - testCase "Test that we can use Process-Helpers on Cli Paramters" <| fun _ -> + testCase "Test that we can use Process-Helpers on Cli Parameters" <| fun _ -> let cli = DotNet.Options.Create() |> Process.setEnvironmentVariable "Somevar" "someval" @@ -22,7 +22,7 @@ let tests = Expect.isEmpty cli "Empty push args." - testCase "Test that the dotnet nuget push arguments with all params setreturns correct string" <| fun _ -> + testCase "Test that the dotnet nuget push arguments with all params set returns correct string" <| fun _ -> let param = { DotNet.NuGetPushOptions.Create().PushParams with DisableBuffering = true From 83dfa1536f0d9e94345522124db243d878ed701b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melvyn=20La=C3=AFly?= Date: Tue, 19 Apr 2022 22:24:57 +0200 Subject: [PATCH 4/5] Try to clarify CLI --help --- src/app/Fake.Core.Target/Target.fs | 7 +- src/app/Fake.netcore/Cli.fs | 120 ++++++++++++++++------------- 2 files changed, 72 insertions(+), 55 deletions(-) diff --git a/src/app/Fake.Core.Target/Target.fs b/src/app/Fake.Core.Target/Target.fs index fbd25b4b986..67089a5871f 100644 --- a/src/app/Fake.Core.Target/Target.fs +++ b/src/app/Fake.Core.Target/Target.fs @@ -17,10 +17,11 @@ Usage: fake-run --help | -h fake-run [target_opts] [target ] [--] [...] -Target Module Options [target_opts]: - -t, --target Run the given target (ignored if positional argument 'target' is given) +Target Module options [target_opts]: + -t, --target Run the given target (ignored if a target is already provided with '[target ]') -e, --environment-variable [*] - Set an environment variable. Use 'key=val'. Consider using regular arguments, see https://fake.build/core-targets.html + 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 Run parallel with the given number of tasks. """ diff --git a/src/app/Fake.netcore/Cli.fs b/src/app/Fake.netcore/Cli.fs index 66d98c0372e..478fdbca88d 100644 --- a/src/app/Fake.netcore/Cli.fs +++ b/src/app/Fake.netcore/Cli.fs @@ -7,63 +7,64 @@ open Fake.Core.CommandLineParsing let fakeArgsHint = """ -General: - - The Fake command line is divided 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"-Package and therefore - inherit the corresponding 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 -- +FAKE 5 """ let fakeUsage = """ Usage: - fake.exe [fake_opts] run [run_opts] [] [--] [...] - fake.exe [fake_opts] build [build_opts] [--] [...] - 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. + fake [fake_opts] run [run_opts] [] [--] [...] + fake [fake_opts] build [build_opts] [--] [...] + fake --version + fake --help | -h + +Note `fake build` is basically equivalent to calling `fake run` with a script named `build.fsx`. + +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 [*] Arguments passed to the f# interactive. + 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 [*] Arguments passed to the F# interactive. -Fake Build Options [build_opts]: - -d, --debug Debug the script. - -n, --nocache Disable fake cache for this run. +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 [*] Arguments passed to the f# interactive. + 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 [*] Arguments passed to the F# interactive. -f, --script - The script to execute (defaults to `build.fsx`). + The script to execute (defaults to `build.fsx`). """ let fakeAdditionalHelp = """ - -- SCRIPT ARGUMENTS SECTION -- + ----- SCRIPT ARGUMENTS SECTION ----- + +Remaining arguments following the previously defined options are provided to the script. + +Each script might understand different arguments, +but since there are good chances you are using the 'Fake.Core.Target' package, +its command-line is documented below. + +THIS SECTION ONLY APPLIES IF YOU USE THE 'Fake.Core.Target' PACKAGE IN YOUR SCRIPT! -THIS SECTION ONLY APPLIES IF YOU USE THE 'Fake.Core.Target' PACKAGE! You can use the following arguments in place of ``: +(`fake-run` refers to the Fake command and arguments defined above) + Usage: fake-run --list fake-run --write-info @@ -71,20 +72,35 @@ Usage: fake-run --help | -h fake-run [target_opts] [target ] [--] [...] -Target Module Options [target_opts]: - -t, --target - Run the given target (ignored if positional -argument 'target' is given) +Target Module options [target_opts]: + -t, --target Run the given target (ignored if a target is already provided with '[target ]') -e, --environment-variable [*] - 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 Run parallel with the given number of tasks. + 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 Run parallel with the given number of tasks. + + ----- END OF SCRIPT ARGUMENTS SECTION ----- + +Warning: + +Ordering of arguments does MATTER. +`fake -v run script.fsx` executes `script.fsx` in verbose mode. +`fake run -v script.fsx` will try to execute a script named '-v' and fail. + +If a script argument/option conflicts with any of the options allowed before, +you need to separate script options with `--`. +The reverse is also true: to print all targets, you can use +`fake build --list` instead of `fake build -- --list` +because `--list` doesn't conflict with any of the [build_opts]. + +Basic examples: -Example: +Specify script file and execute default script action: + fake run mybuildscript.fsx -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" +Specify script file and run the Clean target: + fake run build.fsx --target Clean +or shorter version using the default build.fsx script: + fake build -t Clean """ From d8560cae4d765aff8576ba53e04761f422349753 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melvyn=20La=C3=AFly?= Date: Mon, 25 Apr 2022 20:37:46 +0200 Subject: [PATCH 5/5] Display dynamic version string in --help --- src/app/Fake.netcore/Cli.fs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/app/Fake.netcore/Cli.fs b/src/app/Fake.netcore/Cli.fs index 478fdbca88d..e9f72ef9784 100644 --- a/src/app/Fake.netcore/Cli.fs +++ b/src/app/Fake.netcore/Cli.fs @@ -6,8 +6,8 @@ open System open Fake.Core.CommandLineParsing let fakeArgsHint = - """ -FAKE 5 + $""" +{Fake.Runtime.Environment.fakeVersionStr} """