Dot-sourcing common build script for multiple subprojects and parameters

[jperterm]

Hi,

first of all: Invoke-Build is a really simple to use and straight-forward tool for a lot of build tasks, thanks a lot!

Now, I have a (maybe) special use-case in which I want to re-use a common build script in a repository with a lot of subprojects. Those subprojects are of similar type, but with different configurations. I manage these configurations with JSON files.

To illustrate by example:

Project structure:

- common
  - common.build.ps1
- subproject1
  - subproject.build.ps1
- subproject2
- ...
- subprojectn

Sample content of common.build.ps1:

param (
    [string]$TestCase
)

task Debug {
    Write-Output "You're debugging test-case '$TestCase'"
}

And here the content of subproject1.build.ps1:

. '../common/common.build.ps1'

As you can see, I am dot-sourcing the common.build.ps1 into the subproject build file. This allows me to make improvements to the common build script, without making copies again and again, and also managing different versions.

To come to the point/problem:

Dot-sourcing the common script into the subproject works well with tasks. I can do Invoke-Build Debug and Invoke-Build ? and I get no different behaviour as when having a full copy of the build script in each subproject.

But when I want to pass parameters like Invoke-Build Debug -TestCase test1, then I get

Invoke-Build.ps1: A parameter cannot be found that matches parameter name 'TestCase'.

This behaviour somehow makes sense when I compare with "normal" powershell scripts (not called via Invoke-Build). Every script has its own parameters and indeed the subproject build files have no parameters at all.

Do you (or anyone) know what could be a best-practise for my use-case? I still want to be able to call Invoke-Build in the subproject.

[nightroman]

@jperterm Thank you. It's an interesting use case and the issue. Let me play/think a little bit.

[nightroman]

One possible approach
(note amended project structure and use of *.tasks.ps1 instead of *build.ps1 for subprojects)

Project structure:

- common.build.ps1
- subproject1
  - subproject1.tasks.ps1
- subproject2
  - subproject2.tasks.ps1
- ...

Sample content of common.build.ps1:

param (
    [string]$TestCase
)

# code before
#...

. $TestCase\$TestCase.tasks.ps1

# code after
#...

And here the content of subproject1.tasks.ps1, just own tasks, do not call common.build.ps1, + count on some # code before invoked for this script + count on common parameters:

task t1 {...}
...

Having done this, calling Invoke-Build Debug -TestCase test1 should work in the root folder and any subfolder.

[nightroman]

FWIW, I have created the demo: SubCases

[jperterm]

Thank you for your immediate feedback! I'll try that out and give feedback here soon.

[jperterm]

I checked your proposal, but it does not really fit for my use-case. I guess I somehow set you on the wrong track with my parameter example ($TestCase), or maybe I simply do not understand it right.

I understand that Invoke-Build will find the common.build.ps1 in the parent dir. And with the help of the parameter, the subproject's build script can be dot-sourced, and add tasks, etc. I will try to explain my view:

In your documentation you mention this:

$BuildRoot

It is the full path of the build script directory, by default. Build scripts may alter it on loading in special cases. For example:

• It is not suitable to keep a build script in a directory where it builds.
• A build script is designed to work for several or variable directories.

The last sentence "A build script is designed to work for several or variable directories." matches my use-case best.

Plus I want to be able to have the common.build.ps1 in multiple major versions. This can be neccessary, when breaking changes occur in the build pipeline (which I want to avoid as long as possible). Then I must be able to upgrade a subproject A to common.2.build.ps1 before subproject B which must still be build with common.1.build.ps1.

- common
  - common.1.build.ps1
  - common.2.build.ps1
...

Finally, as mentioned I landed in your docs about the $BuildRoot variable. I come nearest to what I want, when I call the subproject's build file directly (e.g. ./subproject1.build.ps1) with such contents:

Invoke-Build @args -File '..\common\common.1.build.ps1' -BuildRoot $PSScriptRoot

So what I loose in the end is, that I cannot type ib or Invoke-Build in the console (which I am used to and also liking a lot) like in my other projects.

Nonetheless, thank you for your help!

UPDATE: The example for the subproject1.build.ps1 I give above is meant to be a full sample. It shall not contain any other tasks or script logic.

[nightroman]

Yes, I see that your use case is more involved than my SubCases, especially with the requirement of supporting several versions of the main build script (interesting technique, by the way).

If you do not mind using dynamic parameters in subproject scripts (with a common helper, to avoid same boilerplate), this might be the way to explore.

UPDATE: I've tried dynamic parameters. So far even with a helper it looks not so good, too much cryptic code noise.