From d6539e843167be1b9fba1601fc29105e05f097e2 Mon Sep 17 00:00:00 2001 From: Roman Kuzmin Date: Tue, 13 Feb 2024 06:54:46 +0000 Subject: [PATCH] README --- README.md | 4 ++-- .../01-script-and-task/tea.build.ps1 | 6 ++--- .../02-add-new-tasks/tea.build.ps1 | 4 ++-- .../03-dot-and-docs/tea.build.ps1 | 8 +++---- .../06-parameters/tea.build.ps1 | 2 +- .../07-conditions/tea.build.ps1 | 2 +- .../08-bootstrap/tea.build.ps1 | 9 +++++--- .../09-Docker/tea.build.ps1 | 11 +++++---- Tasks/01-step-by-step-tutorial/README.md | 2 +- Tasks/Direct/README.md | 23 +++++++++++-------- Tasks/Direct/my.build.ps1 | 3 +-- 11 files changed, 41 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 928a663..74616ad 100644 --- a/README.md +++ b/README.md @@ -123,8 +123,8 @@ In order to get help for internal commands: : Why build scripts may have advantages over normal scripts. - [Script Tutorial](https://github.com/nightroman/Invoke-Build/wiki/Script-Tutorial) : Take a look in order to get familiar with build scripts. -- [01-step-by-step-tutorial](https://github.com/nightroman/Invoke-Build/tree/main/Tasks/01-step-by-step-tutorial) -: From "Hello world" to featured script. +- [Step by Step Tutorial](https://github.com/nightroman/Invoke-Build/tree/main/Tasks/01-step-by-step-tutorial) +: From "Hello world" to featured scripts. - [Invoke-Build.template](https://github.com/nightroman/Invoke-Build.template) : Create scripts by `dotnet new ib`. - [Project Wiki](https://github.com/nightroman/Invoke-Build/wiki) diff --git a/Tasks/01-step-by-step-tutorial/01-script-and-task/tea.build.ps1 b/Tasks/01-step-by-step-tutorial/01-script-and-task/tea.build.ps1 index ad82133..6ef027a 100644 --- a/Tasks/01-step-by-step-tutorial/01-script-and-task/tea.build.ps1 +++ b/Tasks/01-step-by-step-tutorial/01-script-and-task/tea.build.ps1 @@ -1,9 +1,9 @@ <# Initial steps: - - create a file named like `*.build.ps1`, `tea.build.ps1` - - add a task, `boil_water`, at least one is required + - create a file named like `*.build.ps1`: `tea.build.ps1` + - add a task, at least one is required: `boil_water` -Run the task boil_water: +Run the task `boil_water`: Invoke-Build Invoke-Build boil_water #> diff --git a/Tasks/01-step-by-step-tutorial/02-add-new-tasks/tea.build.ps1 b/Tasks/01-step-by-step-tutorial/02-add-new-tasks/tea.build.ps1 index 9ad5f41..6538d2c 100644 --- a/Tasks/01-step-by-step-tutorial/02-add-new-tasks/tea.build.ps1 +++ b/Tasks/01-step-by-step-tutorial/02-add-new-tasks/tea.build.ps1 @@ -8,8 +8,8 @@ Run any task or combinations: Invoke-Build add_sugar Invoke-Build boil_water, add_tea, add_sugar -Issue: - - the last command "make tea" is rather verbose for the task +Issue to solve: + - the last command "make tea" is rather verbose for the objective #> task boil_water { diff --git a/Tasks/01-step-by-step-tutorial/03-dot-and-docs/tea.build.ps1 b/Tasks/01-step-by-step-tutorial/03-dot-and-docs/tea.build.ps1 index 2e00e44..9299406 100644 --- a/Tasks/01-step-by-step-tutorial/03-dot-and-docs/tea.build.ps1 +++ b/Tasks/01-step-by-step-tutorial/03-dot-and-docs/tea.build.ps1 @@ -1,13 +1,13 @@ <# New features: - - the default task `.` is our "make tea" - - special comments `# Synopsis:` + - the default task `.` is our objective "make tea" + - special task comments `# Synopsis:` -Run the default task: +Run the default task, "make tea": Invoke-Build Invoke-Build . -Show the task list: +Show the task list with comments: Invoke-Build ? #> diff --git a/Tasks/01-step-by-step-tutorial/06-parameters/tea.build.ps1 b/Tasks/01-step-by-step-tutorial/06-parameters/tea.build.ps1 index f1d054e..a9910eb 100644 --- a/Tasks/01-step-by-step-tutorial/06-parameters/tea.build.ps1 +++ b/Tasks/01-step-by-step-tutorial/06-parameters/tea.build.ps1 @@ -3,7 +3,7 @@ New features: - new script parameters with reasonable defaults - tasks `add_tea` and `add_sugar` use parameters -Make default tea: +Make default tea, one tea bag, no sugar: Invoke-Build Make stronger tea with one sugar: diff --git a/Tasks/01-step-by-step-tutorial/07-conditions/tea.build.ps1 b/Tasks/01-step-by-step-tutorial/07-conditions/tea.build.ps1 index 9903736..2b22e7f 100644 --- a/Tasks/01-step-by-step-tutorial/07-conditions/tea.build.ps1 +++ b/Tasks/01-step-by-step-tutorial/07-conditions/tea.build.ps1 @@ -3,7 +3,7 @@ Resolved: - `add_sugar` is invoked for nothing when there is no sugar New features: - - `add_sugar` has a condition, the task is skipped when there is no sugar + - `add_sugar` task condition, it runs with one or more sugar #> param( diff --git a/Tasks/01-step-by-step-tutorial/08-bootstrap/tea.build.ps1 b/Tasks/01-step-by-step-tutorial/08-bootstrap/tea.build.ps1 index 8bd93a9..32deb55 100644 --- a/Tasks/01-step-by-step-tutorial/08-bootstrap/tea.build.ps1 +++ b/Tasks/01-step-by-step-tutorial/08-bootstrap/tea.build.ps1 @@ -1,6 +1,6 @@ <# New features: - - parameter `$Tasks` and bootstrap block allow running the script directly + - parameter `$Tasks` and bootstrap block to run the script directly - InvokeBuild is installed automatically when needed Run the build script directly: @@ -11,8 +11,11 @@ But it is still Invoke-Build: #> param( - [string[]]$Tasks, - [int]$TeaBags = 1, + [Parameter(Position=0)] + [string[]]$Tasks + , + [int]$TeaBags = 1 + , [int]$SugarLumps ) diff --git a/Tasks/01-step-by-step-tutorial/09-Docker/tea.build.ps1 b/Tasks/01-step-by-step-tutorial/09-Docker/tea.build.ps1 index 31e9de5..3437c43 100644 --- a/Tasks/01-step-by-step-tutorial/09-Docker/tea.build.ps1 +++ b/Tasks/01-step-by-step-tutorial/09-Docker/tea.build.ps1 @@ -1,12 +1,12 @@ <# New features: - - new file `implicit.Dockerfile`, does not install InvokeBuild - - new file `explicit.Dockerfile`, gets and imports InvokeBuild - - new parameter `Docker`, to choose 'implicit', 'explicit' + - new file `implicit.Dockerfile` does not install InvokeBuild + - new file `explicit.Dockerfile` gets and imports InvokeBuild + - new parameter `Docker` to choose 'implicit', 'explicit' - new task `docker` to build the image - - and standard documentation comments + - PowerShell script help comments -Build and run the Docker image: +Build the Docker image, then run it: Invoke-Build docker Invoke-Build docker -Docker explicit @@ -34,6 +34,7 @@ See -WhatIf info and script help: Tells how to build the Docker image. Used by `docker`. Values: implicit (default), explicit #> param( + [Parameter(Position=0)] [string[]]$Tasks , [int]$TeaBags = 1 diff --git a/Tasks/01-step-by-step-tutorial/README.md b/Tasks/01-step-by-step-tutorial/README.md index e70c479..e55ca24 100644 --- a/Tasks/01-step-by-step-tutorial/README.md +++ b/Tasks/01-step-by-step-tutorial/README.md @@ -1,4 +1,4 @@ -# Step by step tutorial +# Step by Step Tutorial Composing build scripts is incremental process, from small to complex, gradually adding tasks and features. diff --git a/Tasks/Direct/README.md b/Tasks/Direct/README.md index 08c5e07..2301ec5 100644 --- a/Tasks/Direct/README.md +++ b/Tasks/Direct/README.md @@ -46,15 +46,20 @@ usual call by `Invoke-Build`. See the script [my.build.ps1](my.build.ps1) for a working example. -See also the sample [Paket](../Paket) where a directly invokable build script -is designed for automatic bootstrapping with `Invoke-Build` downloaded as well. +## Bootstrap InvokeBuild -## Note +Directly invokable scripts may automatically install `InvokeBuild` when needed. -Make the parameter `Tasks` positional (`[Parameter(Position=0)]`) and keep other parameters named. -This maintains similarity of parameters used by direct invocation and `Invoke-Build`. -Task names are often specified with the parameter name omitted (`Tasks` or `Task`). -Other parameters are usually named. +See examples: -Also, using the `Parameter` attribute automatically applies `CmdletBinding`. -As a result, misspelled or not supported parameters cause invocation errors. +- [08-bootstrap/tea.build.ps1](../01-step-by-step-tutorial/08-bootstrap/tea.build.ps1) - straightforward bootstrapping +- [Paket/Project.build.ps1](../Paket/Project.build.ps1) - some custom bootstrapping + +## Notes + +Consider making the parameter `Tasks` positional (`[Parameter(Position=0)]`) and keeping other parameters named. +This maintains similarity of parameters used by direct invocation and by `Invoke-Build`: +tasks are specified first, unnamed, then other parameters, all named. + +Also, `Parameter` implies `CmdletBinding`, so we may omit `CmdletBinding` if it was used. +`Parameter` or `CmdletBinding` is recommended for parameter checks on direct invocations. diff --git a/Tasks/Direct/my.build.ps1 b/Tasks/Direct/my.build.ps1 index 8889f6b..813995a 100644 --- a/Tasks/Direct/my.build.ps1 +++ b/Tasks/Direct/my.build.ps1 @@ -38,8 +38,7 @@ param( # call the build engine with this script and return if ($MyInvocation.ScriptName -notlike '*Invoke-Build.ps1') { - Invoke-Build $Tasks $MyInvocation.MyCommand.Path @PSBoundParameters - return + return Invoke-Build $Tasks $MyInvocation.MyCommand.Path @PSBoundParameters } # the usual build script