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 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 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..e9f72ef9784 100644 --- a/src/app/Fake.netcore/Cli.fs +++ b/src/app/Fake.netcore/Cli.fs @@ -6,64 +6,65 @@ open System 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.Runtime.Environment.fakeVersionStr} """ 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 """ 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