Skip to content

Build Scripts in Projects

Jump to bottom
Roman Kuzmin edited this page Oct 13, 2017 · 49 revisions

NOTE Consider to name build scripts like some-project-name.build.ps1, not .build.ps1. The latter is historically used in some mentioned projects and was fine for Windows. But PowerShell 6.0 is going to be cross-platform. On *nix systems .build.ps1 files are hidden from ls by default.

Invoke-Build, Helps (PowerShell scripts)

These scripts are for pure PowerShell script projects. The following tasks are automated:

  • Clean the project directory
  • Run tests and compare results with expected
  • Build the help file (PowerShell MAML format)
  • Convert markdown files to HTML for packages
  • Create packages

SplitPipeline, Mdbc (C#, PowerShell modules)

These scripts are examples of mixed build tools: Invoke-Build and MSBuild work together and call each other. See how the configuration parameter is passed in both directions.

The task Build calls MSBuild in order to build the C# project:

    exec { MSBuild Src\Mdbc.csproj /t:Build /p:Configuration=$Configuration }

The task PostBuild is called by MSBuild as the post-build event, it copies the just built module and its satellite files to one of the PowerShell module directories, so that it is ready to use/debug after the build. The post-build command line is:

PowerShell.exe -NoProfile Invoke-Build PostBuild $(ProjectDir)\..\.build.ps1 -Configuration $(ConfigurationName)

Or even simpler with ib.cmd which also bypasses execution policy restrictions:

ib PostBuild $(ProjectDir)\..\.build.ps1 -Configuration $(ConfigurationName)

Other tasks are typical: clean, test, build and test help, create packages. Both projects use Invoke-Build for testing, each test is represented by a task in a test build script.

Format PowerShell Code Module

zloeber/FormatPowershellCode/.build.ps1

It is one of the most evolved Invoke-Build scripts. It puts together a lot of typical project tasks with complex relations. Here is its impressive task graph.

PSReadLine

A bash inspired readline implementation for PowerShell.

lzybkr/PSReadLine/PSReadline.build.ps1

  • The script uses incremental tasks to avoid unnecessary build steps.
  • Splatting of Inputs and Outputs is used for better task readability.

OneBuild

lholman/OneBuild/OneBuild.build.ps1

OneBuild is a modular set of convention based .NET solution build scripts written in PowerShell, relying on Invoke-Build for task automation. See OneBuild for more details.

PowerShellTraps

PowerShellTraps/.build.ps1

This project is a collection of PowerShell issues described by markdown files, demo scripts, and test scripts. There is nothing to "build" here. The build script is for testing, generating the index, and other routine tasks.

FarNet family (C++, C#, PowerShell)

This project maintains the complex build system where Invoke-Build and MSBuild work together in the hierarchy of projects with Invoke-Build scripts, MSBuild scripts (C++ and C# projects), and Visual Studio solutions.

Parent project scripts dispatch common tasks like Build, Install, Clean to child scripts, some of them dispatch these tasks further to their children.

One of the scripts in this hierarchy is a build task library which is imported by other build scripts. Another point of interest is use of property. It gets parent script values in child scripts, parents do not have to specify them explicitly on task dispatching.

red-gate build scripts

Some red-gate projects use Invoke-Build scripts:

PowerShellEditorServices (common functionality across multiple editors)

PowerShell/PowerShellEditorServices/PowerShellEditorServices.build.ps1

vscode-powershell (PowerShell for Visual Studio Code)

PowerShell/vscode-powershell/vscode-powershell.build.ps1

Project Phosphor

PowerShell/Phosphor/Phosphor.build.ps1

  • It is cross-platform.
  • It uses dotnet and npm.

PSScriptAnalyzer

PowerShell/PSScriptAnalyzer/.build.ps1

PSScriptAnalyzer is a static code checker for Windows PowerShell modules and scripts.

Helpers

Appendix

Clone this wiki locally