|
1 | | -# build |
2 | | -Action that is used to build a PowerShell module |
| 1 | +# Build-PSModule |
| 2 | + |
| 3 | +This action "compiles" the module source code into a efficient PowerShell module that is ready to be published to the PowerShell Gallery. |
| 4 | + |
| 5 | +This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the [Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module. |
| 6 | + |
| 7 | +## Supported module types |
| 8 | + |
| 9 | +- Script module type |
| 10 | +- Manifest module type |
| 11 | + |
| 12 | +## Supported practices and principles |
| 13 | + |
| 14 | +- [PowerShellGallery Publishing Guidelines and Best Practices](https://learn.microsoft.com/powershell/gallery/concepts/publishing-guidelines) are followed as much as possible. |
| 15 | + |
| 16 | +## How it works |
| 17 | + |
| 18 | +During the build process the following steps are performed: |
| 19 | + |
| 20 | +1. Copies the source code of the module to an output folder. |
| 21 | +1. Builds the module manifest file based of info on the GitHub repository and source code. Read the [Module Manifest](#module-manifest) section for more information. |
| 22 | +1. Builds the root module (.psm1) file by combining source code and adding automation into the root module file. Read the [Root module](#root-module) section for more information. |
| 23 | +1. Builds the module documentation using platyPS and comment based help in the source code. Read the [Module documentation](#module-documentation) section for more information. |
| 24 | + |
| 25 | +## Usage |
| 26 | + |
| 27 | +| Name | Description | Required | Default | |
| 28 | +| --- | --- | --- | --- | |
| 29 | +| `Name` | Name of the module to process. | `false` | | |
| 30 | +| `Path` | Path to the folder where the modules are located. | `false` | `src` | |
| 31 | +| `ModulesOutputPath` | Path to the folder where the built modules are outputted. | `false` | `outputs/modules` | |
| 32 | +| `DocsOutputPath` | Path to the folder where the built docs are outputted. | `false` | `outputs/docs` | |
| 33 | + |
| 34 | +## Root module |
| 35 | + |
| 36 | +The root module file is the main file that is loaded when the module is imported. |
| 37 | +It is built from the source code files in the module folder in the following order: |
| 38 | + |
| 39 | +1. Adds module headers from `header.ps1`. |
| 40 | +1. Adds data loader automation that loads files from the `data` folder as variables in the module scope. The variables are available using the ´$script:<filename>´ syntax. |
| 41 | +1. Adds content from subfolders, in the order: |
| 42 | + - Init |
| 43 | + - Private |
| 44 | + - Public |
| 45 | + - *.ps1 on module root |
| 46 | +1. Adds the Export-ModuleMember function to the end of the file, to make sure that only the functions, cmdlets, variables and aliases that are defined in the module are exported. |
| 47 | + |
| 48 | +### The root module in the `src` folder |
| 49 | + |
| 50 | +The root module file that is included in the source files contains the same functionality but is not optimized for performance. |
| 51 | +The goal with this is to have a quick way to import and test the module without having to build it. |
| 52 | + |
| 53 | +## Module manifest |
| 54 | + |
| 55 | +The module manifest file is the file that describes the module and its content. It is used by PowerShell to load the module and its prerequisites. |
| 56 | +The file also contains important metadata that is used by the PowerShell Gallery. |
| 57 | + |
| 58 | +During the module manifest build process the following steps are performed: |
| 59 | + |
| 60 | +1. Get the manifest file from the source code. Content from this file overrides any value that would be calculated based on the source code. |
| 61 | +1. Find and set the `RootModule` based on filename and extension. |
| 62 | +1. Set a temporary `ModuleVersion`, as this is set during the release process by [Publish-PSModule](https://github.com/PSModule/Publish-PSModule). |
| 63 | +1. Set the `Author` and `CompanyName` based on GitHub Owner. |
| 64 | +1. Set the `Copyright` information based on a default text (`(c) 2024 >>OwnerName<<. All rights reserved.`) and adds either the `Author`, `CompanyName` or both (`Author | CompanyName`) when these are different. |
| 65 | +1. Set the `Description` based on the GitHub repository description. |
| 66 | +1. Set various properties in the manifest such as `PowerShellHostName`, `PowerShellHostVersion`, `DotNetFrameworkVersion`, `ClrVersion`, and `ProcessorArchitecture`. There is currently no automation for these properties. |
| 67 | +1. Get the list of files in the module source folder and set the `FileList` property in the manifest. |
| 68 | +1. Get the list of required assemblies (`*.dll` files) from the `assemblies` folder and set the `RequiredAssemblies` property in the manifest. |
| 69 | +1. Get the list of nested modules (`*.psm1` files) from the `modules` folder and set the `NestedModules` property in the manifest. |
| 70 | +1. Get the list of scripts to process (`*.ps1` files) from the `classes` and `scripts` folders and set the `ScriptsToProcess` property in the manifest. This ensures that the scripts are loaded to the caller session (parent of module session). |
| 71 | +1. Get the list of types to process by searching for `*.Types.ps1xml` files in the entire module source folder and set the `TypesToProcess` property in the manifest. |
| 72 | +1. Get the list of formats to process by searching for `*.Format.ps1xml` files in the entire module source folder and set the `FormatsToProcess` property in the manifest. |
| 73 | +1. Get the list of DSC resources to export by searching for `*.psm1` files in the `resources` folder and set the `DscResourcesToExport` property in the manifest. |
| 74 | +1. Get the list of functions, cmdlets, aliases, and variables to export and set the respective properties in the manifest. |
| 75 | +1. Get the list of modules by searching for all `*.psm1` files in the entire module source folder, excluding the root module and set the `ModuleList` property in the manifest. |
| 76 | +1. Gather information about required modules, PowerShell version, and compatible PS editions from the module source files and set the respective properties in the manifest. |
| 77 | +1. The following values are gathered from the GitHub repository: |
| 78 | + - `Tags` are generated from Repository topics in addition to compatability tags gathered from the source code. |
| 79 | + - `LicenseUri` is generated assuming there is a `LICENSE` file on the root of the repository. |
| 80 | + - `ProjectUri` is the URL to the GitHub repository |
| 81 | + - `IconUri` is generated assuming there is a `icon.png` file in the `icon` folder on the repository root. |
| 82 | +1. `ReleaseNotes` currently not automated, but could be the PR description or release description. |
| 83 | +1. `PreRelease` is not managed here, but is managed from [Publish-PSModule](https://github.com/PSModule/Publish-PSModule) |
| 84 | +1. `RequireLicenseAcceptance` is not automated and defaults to `false`, and |
| 85 | +1. `ExternalModuleDependencies` is currenlty not automated. |
| 86 | +1. `HelpInfoURI` is not automated. |
| 87 | +1. Create a new manifest file in the output folder with the gathered info above. This also generates a new `GUID` for the module. |
| 88 | +1. Format the manifest file using the `Set-ModuleManifest` function from the [Utilities](https://github.com/PSModule/Utilities) module. |
| 89 | + |
| 90 | +Linking the description to the module manifest file might show more how this works: |
| 91 | + |
| 92 | +```powershell |
| 93 | +@{ |
| 94 | + RootModule = 'Utilities.psm1' # Get files from root of folder wher name is same as the folder and file extension is .psm1, .ps1, .psd1, .dll, .cdxml, .xaml. Error if there are multiple files that meet the criteria. |
| 95 | + ModuleVersion = '0.0.1' # Set during release using Publish-PSModule. |
| 96 | + CompatiblePSEditions = @() # Get from source files, REQUIRES -PSEdition <PSEdition-Name>, null if not provided. |
| 97 | + GUID = '<GUID>' # Generated when finally saving the manifest using New-ModuleManifest. |
| 98 | + Author = 'PSModule' # Get from GitHub Owner, else use info from source manifest file. |
| 99 | + CompanyName = 'PSModule' # Get from GitHub Owner, else use info from source manifest file. |
| 100 | + Copyright = '(c) 2024 PSModule. All rights reserved.' # Generated from the current year and Author and Company values. |
| 101 | + Description = 'This is a module.' # Get from the repository description, else use info from source manifest file. |
| 102 | + PowerShellVersion = '' # Get from source files, REQUIRES -Version <N>[.<n>], null if not provided. |
| 103 | + PowerShellHostName = '' # Get from manifest file, null if not provided. |
| 104 | + PowerShellHostVersion = '' # Get from manifest file, null if not provided. |
| 105 | + DotNetFrameworkVersion = '' # Get from manifest file, null if not provided. |
| 106 | + ClrVersion = '' # Get from manifest file, null if not provided. |
| 107 | + ProcessorArchitecture = '' # Get from manifest file, null if not provided. |
| 108 | + RequiredModules = @() # Get from source files, REQUIRES -Modules <Module-Name> | <Hashtable> -> Need to be installed and loaded on build time. Will be installed in global session state during installtion. |
| 109 | + RequiredAssemblies = @() # Get from assemblies\*.dll. |
| 110 | + ScriptsToProcess = @() # Get from scripts\*.ps1 and classes\*.ps1 ordered by name. These are loaded to the caller session (parent of module session). |
| 111 | + TypesToProcess = @() # Get from *.Types.ps1xml anywhere in the source module folder. |
| 112 | + FormatsToProcess = @() # Get from *.Format.ps1xml anywhere in the source module folder. |
| 113 | + NestedModules = @() # Get from modules\*.psm1. |
| 114 | + FunctionsToExport = @() # Get from public\*.ps1. |
| 115 | + CmdletsToExport = @() # Get from manifest file, @() if not provided. |
| 116 | + VariablesToExport = @() # To be automated, currently adds '@()' to the manifest file. |
| 117 | + AliasesToExport = '*' # To be automated, currently adds '*' to the manifest file. |
| 118 | + DscResourcesToExport = @() # Get from resources\*.psm1. |
| 119 | + ModuleList = @() # Get from listing all .\*.psm1 files - Informational only. |
| 120 | + FileList = @() # Get from listing all .\* files - Informational only. |
| 121 | + PrivateData = @{ # <https://learn.microsoft.com/en-us/powershell/gallery/concepts/package-manifest-affecting-ui?view=powershellget-2.x> |
| 122 | + PSData = @{ |
| 123 | + Tags = @() # Get from repository topics + compatability tags collected from source files. |
| 124 | + LicenseUri = '' # Generate public link to .\LICENSE. |
| 125 | + ProjectUri = '' # Generate public link to GitHub Repository. |
| 126 | + IconUri = '' # Get from .\icon\icon.png. |
| 127 | + ReleaseNotes = '' # Update during release -> PR description or release description. |
| 128 | + Prerelease = '' # Update during release -> uses a normalized version of the branch name. |
| 129 | + RequireLicenseAcceptance = $false ## Get from manifest file, default is $false. |
| 130 | + ExternalModuleDependencies = @() # Get from source manifest file |
| 131 | + ExperimentalFeatures = @( # Get from source manifest file |
| 132 | + @{ |
| 133 | + Name = "SomeExperimentalFeature" |
| 134 | + Description = "This is an experimental feature." |
| 135 | + } |
| 136 | + ) |
| 137 | + } |
| 138 | + OtherKeys = @{} # Get from manifest file |
| 139 | + } |
| 140 | + HelpInfoURI = '' # Get from source manifest file |
| 141 | + DefaultCommandPrefix = '' # Get from source manifest file |
| 142 | +} |
| 143 | +``` |
| 144 | + |
| 145 | +### The module manifest in the `src` folder |
| 146 | + |
| 147 | +The module manifest file that is included in the source files contains the same functionality but is not optimized for performance and does not automatically gather all the information that is gathered during the build process. |
| 148 | +The goal with this is to have a quick way to import and test the module without having to build it. |
| 149 | + |
| 150 | +The source module manifest is also the only place where some of the values can be controlled. These values are typically difficult to calculate and are not automated. |
| 151 | + |
| 152 | +## Module documentation |
| 153 | + |
| 154 | +The module documentation is built using platyPS and comment based help in the source code. |
| 155 | +The documentation is currently not published anywhere, but should be published to GitHub Pages in a future release. |
| 156 | + |
| 157 | +## Sources |
| 158 | + |
| 159 | +Module manifest: |
| 160 | + |
| 161 | +- [about_Module_Manifests](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests) |
| 162 | +- [How to write a PowerShell module manifest](https://learn.microsoft.com/powershell/scripting/developer/module/how-to-write-a-powershell-module-manifest) |
| 163 | +- [New-ModuleManifest](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/new-modulemanifest) |
| 164 | +- [Update-ModuleManifest](https://learn.microsoft.com/powershell/module/powershellget/update-modulemanifest) |
| 165 | +- [Package metadata values that impact the PowerShell Gallery UI](https://learn.microsoft.com/powershell/gallery/concepts/package-manifest-affecting-ui#powershell-gallery-feature-elements-controlled-by-the-module-manifest) |
| 166 | +- [PowerShellGallery Publishing Guidelines and Best Practices](https://learn.microsoft.com/en-us/powershell/gallery/concepts/publishing-guidelines#tag-your-package-with-the-compatible-pseditions-and-platforms) |
| 167 | + |
| 168 | +Modules: |
| 169 | + |
| 170 | +- [PowerShell scripting performance considerations](https://learn.microsoft.com/powershell/scripting/dev-cross-plat/performance/script-authoring-considerations) |
| 171 | +- [PowerShell module authoring considerations](https://learn.microsoft.com/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations): |
| 172 | + |
| 173 | +Documentation: |
| 174 | + |
| 175 | +- [platyPS reference](https://learn.microsoft.com/powershell/module/platyps/?source=recommendations) |
| 176 | +- [PlatyPS overview](https://learn.microsoft.com/powershell/utility-modules/platyps/overview?view=ps-modules) |
| 177 | +- [about_Comment_Based_Help](https://go.microsoft.com/fwlink/?LinkID=123415) |
| 178 | +- [Supporting Updatable Help](https://learn.microsoft.com/powershell/scripting/developer/help/supporting-updatable-help) |
0 commit comments