From 1d6d90fe4811992b3f8ec31fcad472ee8e754419 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Mon, 21 Jul 2025 19:06:00 -0700 Subject: [PATCH 1/2] =?UTF-8?q?chore:=20=E2=9C=8F=EF=B8=8F=20New=20task=20?= =?UTF-8?q?dependencies?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added new task dependencies in `psakeFile.ps1` to improve build process. - Updated `CHANGELOG.md` to reflect changes in task dependencies. - Enhanced `README.md` with detailed descriptions of task dependencies and their default values. --- CHANGELOG.md | 9 ++- PowerShellBuild/build.properties.ps1 | 83 ++++++++----------- PowerShellBuild/psakeFile.ps1 | 82 +++++++++++++------ README.md | 116 ++++++++++++++------------- 4 files changed, 163 insertions(+), 127 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 02dead2..92685cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,12 +5,17 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). +## Unreleased + +- Add new dependencies variables to allow end user to modify which tasks are + run. + ## [0.7.2] 2025-05-21 ### Added -- The `$PSBPreference` variable now supports the following PlatyPS `New-MarkdownHelp` and `Update-MarkdownHelp` boolean - options: +- The `$PSBPreference` variable now supports the following PlatyPS + `New-MarkdownHelp` and `Update-MarkdownHelp` boolean options: - `$PSBPreference.Docs.AlphabeticParamsOrder` - `$PSBPreference.Docs.ExcludeDontShow` - `$PSBPreference.Docs.UseFullTypeName` diff --git a/PowerShellBuild/build.properties.ps1 b/PowerShellBuild/build.properties.ps1 index 4934bc2..d245ec3 100644 --- a/PowerShellBuild/build.properties.ps1 +++ b/PowerShellBuild/build.properties.ps1 @@ -7,63 +7,63 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul [ordered]@{ General = @{ # Root directory for the project - ProjectRoot = $env:BHProjectPath + ProjectRoot = $env:BHProjectPath # Root directory for the module - SrcRootDir = $env:BHPSModulePath + SrcRootDir = $env:BHPSModulePath # The name of the module. This should match the basename of the PSD1 file - ModuleName = $env:BHProjectName + ModuleName = $env:BHProjectName # Module version - ModuleVersion = $moduleVersion + ModuleVersion = $moduleVersion # Module manifest path ModuleManifestPath = $env:BHPSModuleManifest } - Build = @{ + Build = @{ # "Dependencies" moved to TaskDependencies section # Output directory when building a module - OutDir = $outDir + OutDir = $outDir # Module output directory # This will be computed in 'Initialize-PSBuild' so we can allow the user to # override the top-level 'OutDir' above and compute the full path to the module internally - ModuleOutDir = $null + ModuleOutDir = $null # Controls whether to "compile" module into single PSM1 or not - CompileModule = $false + CompileModule = $false # List of directories that if CompileModule is $true, will be concatenated into the PSM1 CompileDirectories = @('Enum', 'Classes', 'Private', 'Public') # List of directories that will always be copied "as is" to output directory - CopyDirectories = @() + CopyDirectories = @() # List of files (regular expressions) to exclude from output directory - Exclude = @() + Exclude = @() } - Test = @{ + Test = @{ # Enable/disable Pester tests - Enabled = $true + Enabled = $true # Directory containing Pester tests - RootDir = [IO.Path]::Combine($env:BHProjectPath, 'tests') + RootDir = [IO.Path]::Combine($env:BHProjectPath, 'tests') # Specifies an output file path to send to Invoke-Pester's -OutputFile parameter. # This is typically used to write out test results so that they can be sent to a CI system # This path is relative to the directory containing Pester tests - OutputFile = [IO.Path]::Combine($env:BHProjectPath, 'testResults.xml') + OutputFile = [IO.Path]::Combine($env:BHProjectPath, 'testResults.xml') # Specifies the test output format to use when the TestOutputFile property is given # a path. This parameter is passed through to Invoke-Pester's -OutputFormat parameter. - OutputFormat = 'NUnitXml' + OutputFormat = 'NUnitXml' - ScriptAnalysis = @{ + ScriptAnalysis = @{ # Enable/disable use of PSScriptAnalyzer to perform script analysis - Enabled = $true + Enabled = $true # When PSScriptAnalyzer is enabled, control which severity level will generate a build failure. # Valid values are Error, Warning, Information and None. "None" will report errors but will not @@ -73,26 +73,26 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul FailBuildOnSeverityLevel = 'Error' # Path to the PSScriptAnalyzer settings file. - SettingsPath = [IO.Path]::Combine($PSScriptRoot, 'ScriptAnalyzerSettings.psd1') + SettingsPath = [IO.Path]::Combine($PSScriptRoot, 'ScriptAnalyzerSettings.psd1') } # Import module from OutDir prior to running Pester tests. - ImportModule = $false + ImportModule = $false - CodeCoverage = @{ + CodeCoverage = @{ # Enable/disable Pester code coverage reporting. - Enabled = $false + Enabled = $false # Fail Pester code coverage test if below this threshold - Threshold = .75 + Threshold = .75 # CodeCoverageFiles specifies the files to perform code coverage analysis on. This property # acts as a direct input to the Pester -CodeCoverage parameter, so will support constructions # like the ones found here: https://pester.dev/docs/usage/code-coverage. - Files = @() + Files = @() # Path to write code coverage report to - OutputFile = [IO.Path]::Combine($env:BHProjectPath, 'codeCoverage.xml') + OutputFile = [IO.Path]::Combine($env:BHProjectPath, 'codeCoverage.xml') # The code coverage output format to use OutputFileFormat = 'JaCoCo' @@ -102,25 +102,25 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul SkipRemainingOnFailure = 'None' # Set verbosity of output. Options are None, Normal, Detailed and Diagnostic. Default: Detailed. - OutputVerbosity = 'Detailed' + OutputVerbosity = 'Detailed' } - Help = @{ + Help = @{ # Path to updatable help CAB - UpdatableHelpOutDir = [IO.Path]::Combine($outDir, 'UpdatableHelp') + UpdatableHelpOutDir = [IO.Path]::Combine($outDir, 'UpdatableHelp') # Default Locale used for help generation, defaults to en-US # Get-UICulture doesn't return a name on Linux so default to en-US - DefaultLocale = if (-not (Get-UICulture).Name) { 'en-US' } else { (Get-UICulture).Name } + DefaultLocale = if (-not (Get-UICulture).Name) { 'en-US' } else { (Get-UICulture).Name } # Convert project readme into the module about file ConvertReadMeToAboutHelp = $false } - Docs = @{ + Docs = @{ # Directory PlatyPS markdown documentation will be saved to - RootDir = [IO.Path]::Combine($env:BHProjectPath, 'docs') + RootDir = [IO.Path]::Combine($env:BHProjectPath, 'docs') # Whether to overwrite existing markdown files and use comment based help as the source of truth - Overwrite = $false + Overwrite = $false # Whether to order parameters alphabetically by name in PARAMETERS section. # Value passed to New-MarkdownHelp and Update-MarkdownHelp. @@ -128,35 +128,22 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul # Exclude the parameters marked with `DontShow` in the parameter attribute from the help content. # Value passed to New-MarkdownHelp and Update-MarkdownHelp. - ExcludeDontShow = $false + ExcludeDontShow = $false # Indicates that the target document will use a full type name instead of a short name for parameters. # Value passed to New-MarkdownHelp and Update-MarkdownHelp. - UseFullTypeName = $false + UseFullTypeName = $false } Publish = @{ # PowerShell repository name to publish modules to - PSRepository = 'PSGallery' + PSRepository = 'PSGallery' # API key to authenticate to PowerShell repository with - PSRepositoryApiKey = $env:PSGALLERY_API_KEY + PSRepositoryApiKey = $env:PSGALLERY_API_KEY # Credential to authenticate to PowerShell repository with PSRepositoryCredential = $null } - TaskDependencies = @{ - Clean = @('Init') - StageFiles = @('Clean') - Build = @('StageFiles', 'BuildHelp') - Analyze = @('Build') - Pester = @('Build') - Test = @('Pester', 'Analyze') - BuildHelp = @('GenerateMarkdown', 'GenerateMAML') - GenerateMarkdown = @('StageFiles') - GenerateMAML = @('GenerateMarkdown') - GenerateUpdatableHelp = @('BuildHelp') - Publish = @('Test') - } } # Enable/disable generation of a catalog (.cat) file for the module. diff --git a/PowerShellBuild/psakeFile.ps1 b/PowerShellBuild/psakeFile.ps1 index ea53c07..c1be2a6 100644 --- a/PowerShellBuild/psakeFile.ps1 +++ b/PowerShellBuild/psakeFile.ps1 @@ -11,19 +11,55 @@ FormatTaskName { Write-Host $taskName.ToUpper() -ForegroundColor Blue } +#region Task Dependencies +if ($null -eq $PSBCleanDependency) { + $PSBCleanDependency = @('Init') +} +if ($null -eq $PSBStageFilesDependency) { + $PSBStageFilesDependency = @('Clean') +} +if ($null -eq $PSBBuildDependency) { + $PSBBuildDependency = @('StageFiles', 'BuildHelp') +} +if ($null -eq $PSBAnalyzeDependency) { + $PSBAnalyzeDependency = @('Build') +} +if ($null -eq $PSBPesterDependency) { + $PSBPesterDependency = @('Build') +} +if ($null -eq $PSBTestDependency) { + $PSBTestDependency = @('Pester', 'Analyze') +} +if ($null -eq $PSBBuildHelpDependency) { + $PSBBuildHelpDependency = @('GenerateMarkdown', 'GenerateMAML') +} +if ($null -eq $PSBGenerateMarkdownDependency) { + $PSBGenerateMarkdownDependency = @('StageFiles') +} +if ($null -eq $PSBGenerateMAMLDependency) { + $PSBGenerateMAMLDependency = @('GenerateMarkdown') +} +if ($null -eq $PSBGenerateUpdatableHelpDependency) { + $PSBGenerateUpdatableHelpDependency = @('BuildHelp') +} +if ($null -eq $PSBPublishDependency) { + $PSBPublishDependency = @('Test') +} +#endregion Task Dependencies + # This psake file is meant to be referenced from another # Can't have two 'default' tasks # Task default -depends Test Task Init { Initialize-PSBuild -UseBuildHelpers -BuildEnvironment $PSBPreference -} -description 'Initialize build environment variables' +} -Description 'Initialize build environment variables' -Task Clean -depends $PSBPreference.TaskDependencies.Clean { +Task Clean -Depends $PSBCleanDependency { Clear-PSBuildOutputFolder -Path $PSBPreference.Build.ModuleOutDir -} -description 'Clears module output directory' +} -Description 'Clears module output directory' -Task StageFiles -depends $PSBPreference.TaskDependencies.StageFiles { +Task StageFiles -Depends $PSBStageFilesDependency { $buildParams = @{ Path = $PSBPreference.General.SrcRootDir ModuleName = $PSBPreference.General.ModuleName @@ -51,9 +87,9 @@ Task StageFiles -depends $PSBPreference.TaskDependencies.StageFiles { } Build-PSBuildModule @buildParams -} -description 'Builds module based on source directory' +} -Description 'Builds module based on source directory' -Task Build -depends $PSBPreference.TaskDependencies.Build -description 'Builds module and generate help documentation' +Task Build -Depends $PSBBuildDependency -Description 'Builds module and generate help documentation' $analyzePreReqs = { $result = $true @@ -67,14 +103,14 @@ $analyzePreReqs = { } $result } -Task Analyze -depends $PSBPreference.TaskDependencies.Analyze -precondition $analyzePreReqs { +Task Analyze -Depends $PSBAnalyzeDependency -PreCondition $analyzePreReqs { $analyzeParams = @{ Path = $PSBPreference.Build.ModuleOutDir SeverityThreshold = $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel SettingsPath = $PSBPreference.Test.ScriptAnalysis.SettingsPath } Test-PSBuildScriptAnalysis @analyzeParams -} -description 'Execute PSScriptAnalyzer tests' +} -Description 'Execute PSScriptAnalyzer tests' $pesterPreReqs = { $result = $true @@ -92,7 +128,7 @@ $pesterPreReqs = { } return $result } -Task Pester -depends $PSBPreference.TaskDependencies.Pester -precondition $pesterPreReqs { +Task Pester -Depends $PSBPesterDependency -PreCondition $pesterPreReqs { $pesterParams = @{ Path = $PSBPreference.Test.RootDir ModuleName = $PSBPreference.General.ModuleName @@ -109,12 +145,12 @@ Task Pester -depends $PSBPreference.TaskDependencies.Pester -precondition $peste OutputVerbosity = $PSBPreference.Test.OutputVerbosity } Test-PSBuildPester @pesterParams -} -description 'Execute Pester tests' +} -Description 'Execute Pester tests' -Task Test -depends $PSBPreference.TaskDependencies.Test { -} -description 'Execute Pester and ScriptAnalyzer tests' +Task Test -Depends $PSBTestDependency { +} -Description 'Execute Pester and ScriptAnalyzer tests' -Task BuildHelp -depends $PSBPreference.TaskDependencies.BuildHelp {} -description 'Builds help documentation' +Task BuildHelp -Depends $PSBBuildHelpDependency {} -Description 'Builds help documentation' $genMarkdownPreReqs = { $result = $true @@ -124,7 +160,7 @@ $genMarkdownPreReqs = { } $result } -Task GenerateMarkdown -depends $PSBPreference.TaskDependencies.GenerateMarkdown -precondition $genMarkdownPreReqs { +Task GenerateMarkdown -Depends $PSBGenerateMarkdownDependency -PreCondition $genMarkdownPreReqs { $buildMDParams = @{ ModulePath = $PSBPreference.Build.ModuleOutDir ModuleName = $PSBPreference.General.ModuleName @@ -136,7 +172,7 @@ Task GenerateMarkdown -depends $PSBPreference.TaskDependencies.GenerateMarkdown UseFullTypeName = $PSBPreference.Docs.UseFullTypeName } Build-PSBuildMarkdown @buildMDParams -} -description 'Generates PlatyPS markdown files from module help' +} -Description 'Generates PlatyPS markdown files from module help' $genHelpFilesPreReqs = { $result = $true @@ -146,9 +182,9 @@ $genHelpFilesPreReqs = { } $result } -Task GenerateMAML -depends $PSBPreference.TaskDependencies.GenerateMAML -precondition $genHelpFilesPreReqs { +Task GenerateMAML -Depends $PSBGenerateMAMLDependency -PreCondition $genHelpFilesPreReqs { Build-PSBuildMAMLHelp -Path $PSBPreference.Docs.RootDir -DestinationPath $PSBPreference.Build.ModuleOutDir -} -description 'Generates MAML-based help from PlatyPS markdown files' +} -Description 'Generates MAML-based help from PlatyPS markdown files' $genUpdatableHelpPreReqs = { $result = $true @@ -158,12 +194,12 @@ $genUpdatableHelpPreReqs = { } $result } -Task GenerateUpdatableHelp -depends $PSBPreference.TaskDependencies.GenerateUpdatableHelp -precondition $genUpdatableHelpPreReqs { +Task GenerateUpdatableHelp -Depends $PSBGenerateUpdatableHelpDependency -PreCondition $genUpdatableHelpPreReqs { Build-PSBuildUpdatableHelp -DocsPath $PSBPreference.Docs.RootDir -OutputPath $PSBPreference.Help.UpdatableHelpOutDir -} -description 'Create updatable help .cab file based on PlatyPS markdown help' +} -Description 'Create updatable help .cab file based on PlatyPS markdown help' -Task Publish -depends $PSBPreference.TaskDependencies.Publish { - Assert -conditionToCheck ($PSBPreference.Publish.PSRepositoryApiKey -or $PSBPreference.Publish.PSRepositoryCredential) -failureMessage "API key or credential not defined to authenticate with [$($PSBPreference.Publish.PSRepository)] with." +Task Publish -Depends $PSBPublishDependency { + Assert -ConditionToCheck ($PSBPreference.Publish.PSRepositoryApiKey -or $PSBPreference.Publish.PSRepositoryCredential) -FailureMessage "API key or credential not defined to authenticate with [$($PSBPreference.Publish.PSRepository)] with." $publishParams = @{ Path = $PSBPreference.Build.ModuleOutDir @@ -180,9 +216,9 @@ Task Publish -depends $PSBPreference.TaskDependencies.Publish { } Publish-PSBuildModule @publishParams -} -description 'Publish module to the defined PowerShell repository' +} -Description 'Publish module to the defined PowerShell repository' -Task ? -description 'Lists the available tasks' { +Task ? -Description 'Lists the available tasks' { 'Available tasks:' $psake.context.Peek().Tasks.Keys | Sort-Object } diff --git a/README.md b/README.md index b736273..510a66d 100644 --- a/README.md +++ b/README.md @@ -84,61 +84,69 @@ settings govern if certain tasks are executed or set default paths used to build and test the module. You can override these in either psake or Invoke-Build to match your environment. -| Setting | Default value | Description | -|-------------------------------------------------------------|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| -| $PSBPreference.General.ProjectRoot | `$env:BHProjectPath` | Root directory for the project | -| $PSBPreference.General.SrcRootDir | `$env:BHPSModulePath` | Root directory for the module | -| $PSBPreference.General.ModuleName | `$env:BHProjectName` | The name of the module. This should match the basename of the PSD1 file | -| $PSBPreference.General.ModuleVersion | `\` | The version of the module | -| $PSBPreference.General.ModuleManifestPath | `$env:BHPSModuleManifest` | Path to the module manifest (PSD1) | -| $PSBPreference.Build.OutDir | `$projectRoot/Output` | Output directory when building the module | -| $PSBPreference.Build.Dependencies | 'StageFiles, 'BuildHelp' | Default task dependencies for the `Build` task | -| $PSBPreference.Build.ModuleOutDir | `$outDir/$moduleName/$moduleVersion` | `For internal use only. Do not overwrite. Use '$PSBPreference.Build.OutDir' to set output directory` | -| $PSBPreference.Build.CompileModule | `$false` | Controls whether to "compile" module into single PSM1 or not | -| $PSBPreference.Build.CompileDirectories | `@('Enum', 'Classes', 'Private', 'Public')` | List of directories to "compile" into monolithic PSM1. Only valid when `$PSBPreference.Build.CompileModule` is `$true`. | -| $PSBPreference.Build.CopyDirectories | `@()` | List of directories to copy "as-is" to built module | -| $PSBPreference.Build.CompileHeader | `` | String that appears at the top of your compiled PSM1 file | -| $PSBPreference.Build.CompileFooter | `` | String that appears at the bottom of your compiled PSM1 file | -| $PSBPreference.Build.CompileScriptHeader | `` | String that appears in your compiled PSM1 file before each added script | -| $PSBPreference.Build.CompileScriptFooter | `` | String that appears in your compiled PSM1 file after each added script | -| $PSBPreference.Build.Exclude | `` | Array of files (regular expressions) to exclude when building module | -| $PSBPreference.Test.Enabled | `$true` | Enable/disable Pester tests | -| $PSBPreference.Test.RootDir | `$projectRoot/tests` | Directory containing Pester tests | -| $PSBPreference.Test.OutputFile | `$null` | Output file path Pester will save test results to | -| $PSBPreference.Test.OutputFormat | `NUnitXml` | Test output format to use when saving Pester test results | -| $PSBPreference.Test.ScriptAnalysis.Enabled | `$true` | Enable/disable use of PSScriptAnalyzer to perform script analysis | -| $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel | `Error` | PSScriptAnalyzer threshold to fail the build on | -| $PSBPreference.Test.ScriptAnalysis.SettingsPath | `./ScriptAnalyzerSettings.psd1` | Path to the PSScriptAnalyzer settings file | -| $PSBPreference.Test.CodeCoverage.Enabled | `$false` | Enable/disable Pester code coverage reporting | -| $PSBPreference.Test.CodeCoverage.Threshold | `.75` | Fail Pester code coverage test if below this threshold | -| $PSBPreference.Test.CodeCoverage.Files | `*.ps1, *.psm1` | Files to perform code coverage analysis on | -| $PSBPreference.Test.CodeCoverage.OutputFile | `coverage.xml` | Output file path (relative to Pester test directory) where Pester will save code coverage results to | -| $PSBPreference.Test.CodeCoverage.OutputFileFormat | `$null` | Test output format to use when saving Pester code coverage results | -| $PSBPreference.Test.ImportModule | `$false` | Import module from output directory prior to running Pester tests | -| $PSBPreference.Test.SkipRemainingOnFailure | `None` | Skip remaining tests after failure for selected scope. Options are None, Run, Container and Block. | -| $PSBPreference.Test.OutputVerbosity | `Detailed` | Set verbosity of output. Options are None, Normal, Detailed and Diagnostic. | -| $PSBPreference.Help.UpdatableHelpOutDir | `$OutDir/UpdatableHelp` | Output directory to store update module help (CAB) | -| $PSBPreference.Help.DefaultLocale | `(Get-UICulture).Name` | Default locale used for help generation | -| $PSBPreference.Help.ConvertReadMeToAboutHelp | `$false` | Convert project readme into the module about file | -| $PSBPreference.Docs.RootDir | `$projectRoot/docs` | Directory PlatyPS markdown documentation will be saved to | -| $PSBPreference.Docs.Overwrite | `$false` | Overwrite the markdown files in the docs folder using the comment based help as the source of truth. | +| Setting | Default value | Description | +|-------------------------------------------------------------|---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| $PSBPreference.General.ProjectRoot | `$env:BHProjectPath` | Root directory for the project | +| $PSBPreference.General.SrcRootDir | `$env:BHPSModulePath` | Root directory for the module | +| $PSBPreference.General.ModuleName | `$env:BHProjectName` | The name of the module. This should match the basename of the PSD1 file | +| $PSBPreference.General.ModuleVersion | `\` | The version of the module | +| $PSBPreference.General.ModuleManifestPath | `$env:BHPSModuleManifest` | Path to the module manifest (PSD1) | +| $PSBPreference.Build.OutDir | `$projectRoot/Output` | Output directory when building the module | +| $PSBPreference.Build.Dependencies | 'StageFiles, 'BuildHelp' | Default task dependencies for the `Build` task | +| $PSBPreference.Build.ModuleOutDir | `$outDir/$moduleName/$moduleVersion` | `For internal use only. Do not overwrite. Use '$PSBPreference.Build.OutDir' to set output directory` | +| $PSBPreference.Build.CompileModule | `$false` | Controls whether to "compile" module into single PSM1 or not | +| $PSBPreference.Build.CompileDirectories | `@('Enum', 'Classes', 'Private', 'Public')` | List of directories to "compile" into monolithic PSM1. Only valid when `$PSBPreference.Build.CompileModule` is `$true`. | +| $PSBPreference.Build.CopyDirectories | `@()` | List of directories to copy "as-is" to built module | +| $PSBPreference.Build.CompileHeader | `` | String that appears at the top of your compiled PSM1 file | +| $PSBPreference.Build.CompileFooter | `` | String that appears at the bottom of your compiled PSM1 file | +| $PSBPreference.Build.CompileScriptHeader | `` | String that appears in your compiled PSM1 file before each added script | +| $PSBPreference.Build.CompileScriptFooter | `` | String that appears in your compiled PSM1 file after each added script | +| $PSBPreference.Build.Exclude | `` | Array of files (regular expressions) to exclude when building module | +| $PSBPreference.Test.Enabled | `$true` | Enable/disable Pester tests | +| $PSBPreference.Test.RootDir | `$projectRoot/tests` | Directory containing Pester tests | +| $PSBPreference.Test.OutputFile | `$null` | Output file path Pester will save test results to | +| $PSBPreference.Test.OutputFormat | `NUnitXml` | Test output format to use when saving Pester test results | +| $PSBPreference.Test.ScriptAnalysis.Enabled | `$true` | Enable/disable use of PSScriptAnalyzer to perform script analysis | +| $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel | `Error` | PSScriptAnalyzer threshold to fail the build on | +| $PSBPreference.Test.ScriptAnalysis.SettingsPath | `./ScriptAnalyzerSettings.psd1` | Path to the PSScriptAnalyzer settings file | +| $PSBPreference.Test.CodeCoverage.Enabled | `$false` | Enable/disable Pester code coverage reporting | +| $PSBPreference.Test.CodeCoverage.Threshold | `.75` | Fail Pester code coverage test if below this threshold | +| $PSBPreference.Test.CodeCoverage.Files | `*.ps1, *.psm1` | Files to perform code coverage analysis on | +| $PSBPreference.Test.CodeCoverage.OutputFile | `coverage.xml` | Output file path (relative to Pester test directory) where Pester will save code coverage results to | +| $PSBPreference.Test.CodeCoverage.OutputFileFormat | `$null` | Test output format to use when saving Pester code coverage results | +| $PSBPreference.Test.ImportModule | `$false` | Import module from output directory prior to running Pester tests | +| $PSBPreference.Test.SkipRemainingOnFailure | `None` | Skip remaining tests after failure for selected scope. Options are None, Run, Container and Block. | +| $PSBPreference.Test.OutputVerbosity | `Detailed` | Set verbosity of output. Options are None, Normal, Detailed and Diagnostic. | +| $PSBPreference.Help.UpdatableHelpOutDir | `$OutDir/UpdatableHelp` | Output directory to store update module help (CAB) | +| $PSBPreference.Help.DefaultLocale | `(Get-UICulture).Name` | Default locale used for help generation | +| $PSBPreference.Help.ConvertReadMeToAboutHelp | `$false` | Convert project readme into the module about file | +| $PSBPreference.Docs.RootDir | `$projectRoot/docs` | Directory PlatyPS markdown documentation will be saved to | +| $PSBPreference.Docs.Overwrite | `$false` | Overwrite the markdown files in the docs folder using the comment based help as the source of truth. | | $PSBPreference.Docs.AlphabeticParamsOrder | `$false` | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. | -| $PSBPreference.Docs.ExcludeDontShow | `$false` | Exclude the parameters marked with `DontShow` in the parameter attribute from the help content. | -| $PSBPreference.Docs.UseFullTypeName | `$false` | Indicates that the target document will use a full type name instead of a short name for parameters. | -| $PSBPreference.Publish.PSRepository | `PSGallery` | PowerShell repository name to publish | -| $PSBPreference.Publish.PSRepositoryApiKey | `$env:PSGALLERY_API_KEY` | API key to authenticate to PowerShell repository with | -| $PSBPreference.Publish.PSRepositoryCredential | `$null` | Credential to authenticate to PowerShell repository with. Overrides `$psRepositoryApiKey` if defined | -| $PSBPreference.TaskDependencies.Clean | 'Init' | Tasks the 'Clean' task depends on. | -| $PSBPreference.TaskDependencies.StageFiles | 'Clean' | Tasks the 'StageFiles' task depends on. | -| $PSBPreference.TaskDependencies.Build | 'StageFiles', 'BuildHelp' | Tasks the 'Build' task depends on. | -| $PSBPreference.TaskDependencies.Analyze | 'Build' | Tasks the 'Analyze' task depends on. | -| $PSBPreference.TaskDependencies.Pester | 'Build' | Tasks the 'Pester' task depends on. | -| $PSBPreference.TaskDependencies.Test | 'Pester', 'Analyze' | Tasks the 'Test' task depends on. | -| $PSBPreference.TaskDependencies.BuildHelp | 'GenerateMarkdown', 'GenerateMAML' | Tasks the 'BuildHelp' task depends on. | -| $PSBPreference.TaskDependencies.GenerateMarkdown | 'StageFiles' | Tasks the 'GenerateMarkdown' task depends on. | -| $PSBPreference.TaskDependencies.GenerateMAML | 'GenerateMarkdown' | Tasks the 'GenerateMAML' task depends on. | -| $PSBPreference.TaskDependencies.GenerateUpdatableHelp | 'BuildHelp' | Tasks the 'GenerateUpdatableHelp' task depends on. | -| $PSBPreference.TaskDependencies.Publish | 'Test' | Tasks the 'Publish' task depends on. | +| $PSBPreference.Docs.ExcludeDontShow | `$false` | Exclude the parameters marked with `DontShow` in the parameter attribute from the help content. | +| $PSBPreference.Docs.UseFullTypeName | `$false` | Indicates that the target document will use a full type name instead of a short name for parameters. | +| $PSBPreference.Publish.PSRepository | `PSGallery` | PowerShell repository name to publish | +| $PSBPreference.Publish.PSRepositoryApiKey | `$env:PSGALLERY_API_KEY` | API key to authenticate to PowerShell repository with | +| $PSBPreference.Publish.PSRepositoryCredential | `$null` | Credential to authenticate to PowerShell repository with. Overrides `$psRepositoryApiKey` if defined | + +## Modifying Task Dependencies + +If you need to modify what dependencies are run you will need to set a variable +in your `psakeFile.ps1`. + +| Setting | Default value | Description | +|-------------------------------------|------------------------------------|----------------------------------------------------| +| $PSBCleanDependency | 'Init' | Tasks the 'Clean' task depends on. | +| $PSBStageFilesDependency | 'Clean' | Tasks the 'StageFiles' task depends on. | +| $PSBBuildDependency | 'StageFiles', 'BuildHelp' | Tasks the 'Build' task depends on. | +| $PSBAnalyzeDependency | 'Build' | Tasks the 'Analyze' task depends on. | +| $PSBPesterDependency | 'Build' | Tasks the 'Pester' task depends on. | +| $PSBTestDependency | 'Pester', 'Analyze' | Tasks the 'Test' task depends on. | +| $PSBBuildHelpDependency | 'GenerateMarkdown', 'GenerateMAML' | Tasks the 'BuildHelp' task depends on. | +| $PSBGenerateMarkdownDependency | 'StageFiles' | Tasks the 'GenerateMarkdown' task depends on. | +| $PSBGenerateMAMLDependency | 'GenerateMarkdown' | Tasks the 'GenerateMAML' task depends on. | +| $PSBGenerateUpdatableHelpDependency | 'BuildHelp' | Tasks the 'GenerateUpdatableHelp' task depends on. | +| $PSBPublishDependency | 'Test' | Tasks the 'Publish' task depends on. | ## Examples From e19a48eb8fb2ef57d052f6a01152317547f89653 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Tue, 22 Jul 2025 16:56:36 -0700 Subject: [PATCH 2/2] =?UTF-8?q?chore:=20=E2=9C=8F=EF=B8=8F=20Update=20task?= =?UTF-8?q?=20dependency=20modification=20instructions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Clarified instructions for modifying task dependencies in `psakeFile.ps1`. - Emphasized that variables should be set outside the `properties` block. --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 510a66d..8725468 100644 --- a/README.md +++ b/README.md @@ -131,8 +131,9 @@ match your environment. ## Modifying Task Dependencies -If you need to modify what dependencies are run you will need to set a variable -in your `psakeFile.ps1`. +To change which tasks depend on each other, set the variables below in your +`psakeFile.ps1`. Unlike `$PSBPreference` settings, these variables should be set +outside the `properties` block, before you reference any PowerShellBuild tasks. | Setting | Default value | Description | |-------------------------------------|------------------------------------|----------------------------------------------------|