New (backwards compat) CLI for FAKE that includes FSI cmd args passing

[bentayloruk]

While working on #438, I realised that the feature would make the existing FAKE command line brittle. The existing code looks for argument strings regardless of their position or relation to switches. Adding support for passing arbitrary string args to FSI, could easily break this. Therefore, I have added the support I needed for #438 and created a new CLI for FAKE that I think will be much easier to understand and extend in the future. I hope you agree. If not, I would be happy to discuss and fix an concerns.

This PR makes FAKE.exe dependant on the UnionArgParser library. If figured this would be ok as FAKE includes other assemblies and this one is fairly small and focused. Using it to specify the FAKE CLI args is really clean.

type FakeArg = 
    | [<AltCommandLine("-ev")>] EnvVar of string * string
    | [<AltCommandLine("-ef")>] EnvFlag of string
    | [<AltCommandLine("-lf")>] LogFile of string
    | [<AltCommandLine("-pd")>] PrintDetails
    | [<AltCommandLine("-v")>] Version
    | [<Rest>] FsiArgs of string
    | [<Rest>] Boot of string
    interface IArgParserTemplate with
        member x.Usage = 
            match x with
            | EnvVar _ -> "Set environment variable <name> <value>. Supports multiple."
            | EnvFlag _ -> "Set environment variable flag <name> 'true'. Supports multiple."
            | LogFile _ -> "Build output log file path."
            | PrintDetails _ -> "Print details of FAKE's activity."
            | FsiArgs _ -> "Pass args after this switch to FSI when running the build script."
            | Version _ -> "Print FAKE version information."
            | Boot _ -> "TBC"

An example usage now looks like this:

fake.exe build.fsx clean --envvar key1 val1 --envar key2 val2

We also support the short switches:

fake.exe build.fsx -ev key1 val1 -ev key2 val2 -ef blah

fake --help now looks like this:

I don't think too much is outstanding, although I appreciate it is important that this is tested well, do we don't break old scripts. If the new CLI args don't parse, we fall back to exactly the same code as before the new CLI, so I hope this provides the safest experience.

TODO:

• Improve the switch documentation strings (I don't know much about Boot for example).
• There is some FSI arg crossover with Vasily's work on Pass optional script arguments into deployment script #453. I have merged this, but I think it could be cleaned up/generalised a little more.
• The --help arg defaults to a UnionArgParser parse error and we fall through to the old command line passing. This works for now.
• Done. I appreciate that previously the build script arg was first and did not require a switch. I could add support for this, but thought I would find out how important this is first.

Look forward to feedback!

[forki]

This looks pretty cool.
Making it backwards compatibile is very important. Thanks for taking care of this.

The build script arg in first position is actually used very frequently. Especially from a cmd prompt. Think of things like "fake clean" or "fake test".

[bentayloruk]

Thanks for the feedback. I'll update the PR with support for the positional, non-switch arguments (and fix up the target usage).

[bentayloruk]

@forki I've added back support for the positional arguments. You now have:

fake [<script>] [<target>] [switches]

I've updated the PR description with a new image and current switches. I've also added a few simple tests. I didn't create a new test project, but added them (and ref to fake.exe) in the FakeCore test lib. Hope this is OK.

It appears the build is failing, so I'll have a look at that.

[bentayloruk]

The build does not like the DU field names I've used on FsiArgs. Guessing this is some Mono F# build version/support issue...

[forki]

It's probably not supported in the F# version which is used by mono. I don't know if we can change that version.

[bentayloruk]

I'll remove the usage for now then.

[bentayloruk]

Building. I'm not planning on doing anything else on this for now. Think it is good to go, so will await the feedback!

[forki]

I'll release a prerelease version and check our build infrastructure against this.
Good work.

[bentayloruk]

Great, thanks! Glad to finally start putting something back into FAKE after all the use I have had from it.

[forki]

There is a bug. Please try "build.cmd clean" from the command line. I get:

[bentayloruk]

I see the problem. I handle fake.exe build.fsx clean or fake.exe clean or fake.exe build.fsx. I did not think about the usage fake.exe build.fsx target=clean as it is not explicit in the code and I assumed the positional usage rather than the kvp usage. Will fix now.

[forki]

thanks for fixing.

next cool step would be to improve https://github.com/fsharp/FAKE/blob/master/help/commandline.md - are you interested?

[bentayloruk]

Yes, I will do this. OSS without good docs is not good OSS!

[bentayloruk]

Wonder what the world would be like if PRs got rejected without good docs...

[bentayloruk]

BTW - did you see this nice Markdown extension for VS? http://visualstudiogallery.msdn.microsoft.com/0855e23e-4c4c-4c82-8b39-24ab5c5a7f79

[forki]

Wonder what the world would be like if PRs got rejected without good docs...

Then we would probably have no OSS at all.

[bentayloruk]

Maybe, maybe :)

[bentayloruk]

Do you think --EnvVar and --EnvFlag should be --EnvironmentVariable and --EnvironmentFlag? We have the short versions -ev and -ef, so maybe the long ones, should be long!

[forki]

sounds good