Assume arguments provided _after_ the .cake script (when provided) to be "remaining arguments"

This is closely related to #3279.

Background

The Cake runner supports a number of arguments, such --version to display the version of the runner, or --debug to launch the script in debug mode.

However, this make it impossible for these names to be used as arguments in Cake build scripts. For example, if one wanted to use the argument version as an input to the build script:

var version = Argument<string>("version");

And then run Cake:

dotnet cake --version=1.2.3

They would receive an error: Flags cannot be assigned a value

Workaround

The current workaround is to use the “remaining arguments” feature when using one of these “reserved” argument names:

dotnet cake -- --version=1.2.3

Proposal

This issue intends to make the necessary updates to - only when a .cake file is provided as an argument - to assume that any arguments after the .cake file to be considered as “remaining arguments” instead of Cake runner arguments.

In other words: Consider that all arguments before the .cake filename to be arguments targeted at the Cake runner, and all arguments after the .cake filename to be targeted at the build script:

dotnet cake (cake-args) filename.cake (build-args)

Command-line	Expected result
dotnet cake --version	Display Cake version (as it is today)
dotnet cake --version=1.2.3	Error: Flags cannot be assigned a value (unless #3279 is implemented)
dotnet cake build.cake --version=1.2.3	Run build script and set the version argument to 1.2.3
dotnet cake --version=1.2.3 build.cake	Error: Flags cannot be assigned a value (unless #3279 is implemented)

This should work for all Cake runner arguments.

---

Related:

• Improve error message for reserved argument names
• Allow users to use any of the Cake runner arguments as build script arguments

[FrankRay78]

Sounds good @augustoproiete, I hadn’t thought about using a warning to prepare for the future transition. Can you assign this issue to me again and I will implement it?

[augustoproiete]

Hey @FrankRay78 I like your idea of implementing a new BuildCommand that would allow us to ship this new behavior in a minor release of Cake as soon as it’s ready, document it, and give some time for people to try it it, and eventually we can replace the DefaultCommand with this new one, on a major release of Cake.

I also would suggest we update the DefaultCommand to analyze the arguments and detect any Cake-specific arguments passed after a .cake file (if any), and emit a warning to the user, so that they can adjust their build scripts.

e.g.

dotnet cake --tree frank.cake --target=pack
OK / No warning

dotnet cake frank.cake --tree --target=pack
Warning: Cake will soon require Cake arguments to be passed before the cake build script file.
e.g. instead of
> dotnet cake frank.cake --tree --target=pack
should be
> dotnet cake --tree frank.cake --target=pack