en-US/about_PSDepend.help.txt
|
TOPIC
about_PSDepend SHORT DESCRIPTION PSDepend is a module to simplify dependency handling DETAILED DESCRIPTION PSDepend is a module to simplify dependency handling Think of this like a simplified (Ruby) Bundler, or (Python) pip requirements files Terminology and concepts ======================== There are three primary concepts: *.depend.psd1 files: PSD1 files that tell PSDepend what you want to install. You can also use requirements.psd1 Dependency Type: These define how to actually install something. Each type is associated with a script. The default type is PSGalleryModule. This is extensible. Dependency Script: These are scripts associated to a particular dependency type. They tell PSDepend how to install a dependency type. All should accept a 'Dependency' parameter. For example, the PSGalleryModule script uses PowerShellGet to find and install any dependencies specified in a depend.psd1 or requirements.psd1 file. Prerequisites ============ Each dependency type may have certain prerequisites: * PSGalleryModule: Requires the PowerShellGet module (WMF 5 or a separate install) * PSGalleryNuget: This requires nuget.exe in your path*. We handle this for you: When you import PSDepend, we... Look for nuget.exe in your path. If we don't find it... Look in the path specified in PSDepend\PSDepend.Config's NugetPath. Default is PSDepend\nuget.exe If we don't find it there, we download to that path If we do find it there, we add the parent container to $ENV:Path * Git: Requires git in your path, or in the file path specified in PSDepend\PSDepend.Config's GitPath * Npm: Requires npm in your path Example use (*.PSDepend.ps1) ============================ I want to install dependencies from C:\projectx\projectx.depend.psd1 C:\projectx\projectx.depend.psd1 looks like this: @{ psdeploy = @{ Version = '0.1.8' Target = 'C:\ProjectX' DependencyType = 'PSGalleryModule' } buildhelpers = @{ Target = 'CurrentUser' } pester = 'latest' psake = '4.6.0' } # Install dependencies cd C:\projectx Invoke-PSDepend # Alternatively Invoke-PSDepend -Path C:\projectx See about_PSDepend_Definitions for more information Learning about Dependency Scripts ================================ PSDepend Dependency scripts each treat Dependency details (e.g. Name, Source, Version) differently. In some cases, they may have their own Parameters. For example, a PSGalleryModule has a Repository Parameter. It is up to authors of Dependency scripts to expose help for this information. A few tools can assist in finding more information: # List available PSDepend Types, and their DependencyScripts Get-PSDependType # Show comment-based help for the PSGalleryModule DependencyType: Get-PSDependType -DependencyType PSGalleryModule -ShowHelp By convention, the comment-based help DESCRIPTION field should indicate how Dependency details are handled. For example, here's PSGalleryModule: Relevant Dependency metadata: Name: The name for this module Version: Used to identify existing installs meeting this criteria, and as RequiredVersion for installation. Defaults to 'latest' Target: Used as 'Scope' for Install-Module. If this is a path, we use Save-Module with this path. On reruns, PSDepend checks existing modules first and skips reinstalling when the requested version is already present. Defaults to 'AllUsers' Lastly, DependencyType specific parameters should be included as parameters for Dependency scripts. For example, we can see the Repository parameter for PSGalleryModule: -Repository <String> PSRepository to download from. Defaults to PSGallery Required? false Position? 2 Default value PSGallery Locking dependencies ==================== Like npm's package-lock.json, PSDepend can pin every dependency, and the dependencies they pull in, to exact versions: Update-PSDependLock -Path .\requirements.psd1 # writes requirements.lock.json Invoke-PSDepend -Path .\requirements.psd1 # installs the locked versions Update-PSDependLock asks each DependencyType that supports Resolve for the highest version satisfying Version and walks direct dependencies recursively. Gallery, NuGet and Chocolatey types use NuGet ranges; Npm uses npm semver ranges and pins only the declared package. npm's package-lock.json governs its subtree. One version is locked per DependencyType::Name. Resolution is greedy: child constraints are intersected, but PSDepend does not backtrack to an older parent. Narrow the parent range when an older version is required. Invoke-PSDepend and Get-Dependency apply a neighboring lock automatically. Locked transitive packages install first and are materialized once per root installation context. A changed Dependency, Version, resolution Source, or DependencyScript parameter makes the lock stale; -IgnoreLock opts out. With -Test, locked roots and transitive packages are tested. Commit and review locks like code. PSDepend validates structure and exact versions before use, but lock format version 1 has no package content hashes. A DependencyScript opts in by accepting Resolve in PSDependAction and emits one PSDepend.ResolvedDependency (Name, exact Version, direct Dependencies) after querying its source without installing anything. Extending PSDepend ================== PSDepend is somewhat extensible. To add a new dependency type: Update PSDependMap.psd1 in the PSDepend root. The dependency type name is the root node. The script node defines what script to run for these dependency types The description is... not really used. But feel free to write one! For example, I might add support for PackageManagement, and include a long and shorthand way to name these: Package: Script: Package.ps1 Description: Install packages via PackageManagement module PackageManagement: Script: Package.ps1 Description: Install packages via PackageManagement module Create the associated script in PSDepend\PSDependScripts For example, I would create \\Path\To\PSDepend\PSDependScripts\Package.ps1 Include a 'Dependency' parameter. See \\Path\To\PSDepend\PSDependScripts\PSGalleryModule.ps1 for an example Here's how I implement this: param( [PSTypeName('PSDepend.Dependency')] [PSObject[]]$Dependency ... Include a 'PSDependAction' parameter. Use ValidateSet to specify whether your type supports Test, Install, Import, or other actions. Include details on how you use Dependency properties in the comment-based help DESCRIPTION field. See \\Path\To\PSDepend\PSDependScripts\PSGalleryModule.ps1 DESCRIPTION field for an example Include parameters and comment based help for any parameters you read from the Dependency Parameter property. See \\Path\To\PSDepend\PSDependScripts\PSGalleryModule.ps1 parameters and help for an example Update *.depend.ps1 schema as needed. Get-Dependency converts PSD1 files into a number of 'Dependency' objects. If you need other data included, you can extend the schema and reference the 'Raw' property on the dependency objects: this contains the raw data from the psd1 SEE ALSO about_PSDepend_Definitions https://github.com/PowerShellOrg/PSDepend |