en-US/about_PSDepend_Definitions.help.txt

TOPIC
    about_PSDepend_Definitions

SHORT DESCRIPTION
    PSDepend has several configuration definitions to work with

LONG DESCRIPTION
    PSDepend has several configuration definitions to work with:

        Dependency configurations: *.Depend.psd1 or requirements.psd1 script files
        PSDepend configuration: PSDepend.Config file with a few configurations for PSDepend
        Dependency type configurations: Map Dependency types to scripts that run them

    Please see about_PSDepend or other general PSDepend help for clarification on terminology

DETAILED DESCRIPTION

    Dependency Configurations: *.Depend.psd1 or requirements.psd1
    =========================================

        These are PowerShell data files that tell PSDepend what to install.

        We use the following attributes:

            DependencyFile: File that we read a dependency from
            DependencyName: Unique name within a dependency file - this is the key, the rest of the data is stored in this key's value.
            DependencyType: The dependency type. Defaults to PSGalleryModule
            Name: Name of the thing to install. Optional, use this if DependencyName has a collision
            Version: Version to install and check for. The dependency script author is responsible for testing whether this version already exists and installing it if not.
            Parameters: Optional parameters if the dependency type's script takes parameters. For example, the PSGalleryModule has an optional 'Repository' parameter.
            Source: Optional source. For example, a FileDownload source is a URL
            Target: Optional target. For example, a PSGalleryModule can target a path (uses Save-Module), or a scope like AllUsers (uses Install-Module)
            AddToPath: Optional flag to specify whether to add the installed dependency to the PATH (or PSModulePath, or comparable setting)
            Tags: Optional tags to categorize and filter dependencies
            DependsOn: Dependency that this Dependency depends upon. Uses DependencyName for reference.
            PreScripts: One or more paths to scripts to process before the dependency is processed
            PostScripts: One or more paths to scripts to process after the dependency is processed
            Raw: Raw data from the dependency in the psd1 file

            The Source and Target attributes allow the substitution of select variables:
                $PWD (or .) refer to the current path
                $DependencyFolder or $DependencyPath refer to the parent of the DependencyFile
                $ENV:ProgramData, USERPROFILE, APPDATA, and TEMP
                Variables need to be in single quotes or the $ needs to be escaped. We replace the raw strings with the values for you. This will not work: Target = "$PWD\dependencies". This will: Target = '$PWD\dependencies'

        A *.depend.ps1 file will have one or more dependency nodes like this:

            @{
                # This means 'install the latest copy of pester if I don't have it already, for all users, via PSGalleryModule'
                # We treat the value as a 'Version, if it's not a hashtable
                pester = 'latest'

                # Install a specific version of psake for all users via PSGalleryModule
                psake = '4.6.0'

                # Install the latest buildhelpers module from PSGalleryModule, for the CurrentUser only
                buildhelpers = @{
                    target = 'CurrentUser'
                }

                # This is a fleshed out dependency that doesn't rely on default values
                # Maybe I need multiple copies of PSDeploy, so I give the key a unique name...
                psdeploy_0_1_8 = @{

                    # This overrides the name that typically comes from the key
                    name = psdeploy

                    # We want a specific version
                    version = '0.1.8'

                    # We want to install to a specific path
                    target = 'C:\ProjectX'

                    # This is the default, but specified for clarity...
                    DependencyType = 'PSGalleryModule'

                    # Parameters specific to our PSGalleryModule dependency type
                    parameters = @{
                        # We want to install from an internal repository named MyPSGalleryRepository, that I've already registered
                        Repository = 'MyPSGalleryRepository'
                    }

                    # Tag it. Maybe only install in certain scenarios
                    tags = 'prod'

                    # Add to the PSModulePath
                    AddToPath = $True

                    # Make sure buildhelpers installs first
                    DependsOn = 'buildhelpers'

                    # Run this script after installing the module
                    PostScripts = "C:\Finalize-ProjectX.ps1"
                }
            }
            
        You can specify global defaults (and override them inside a Dependency):
            
            @{
                PSDependOptions = @{
                    Target = 'C:\MyProject' # I want all my modules installed here
                    Parameters = @{
                        Force = $True # I want to use -Force on each dependency
                    }
                }
                pester = 'latest'
                psake = 'latest'
                buildhelpers = 'latest'
                psdeploy = @{
                    Target = "C:\Exception" # Example overriding the global target
                }
            }
            
            Global defaults can be specified for the following attributes:
                Parameters
                Source
                Target
                AddToPath
                Tags
                DependsOn
                PreScripts
                PostScripts

    PSDepend configuration: PSDepend.Config
    =======================================

    This file includes a few configurations for PSDepend:
        
        NugetPath: Path to a nuget.exe, if it's not in your path. If it's not found in either spot, we download to this
        GitPath: Path to a git.exe, if it's not in your path. We do not resolve this dependency for you (yet).

    Dependency type map: PSDependMap.psd1
    =====================================

    This is a file that tells PSDepend what script to use for each DependencyType. By default, it sits in your PSDepend module folder.

    There are two scenarios you would generally work with this:

      - You want to extend PSDepend to add more DependencyTypes
      - You want to move the PSDependMap.psd1 to a central location that multiple systems could point to

    There are four attributes to each DependencyType in this file:

        DependencyType Name: The name of this DependencyType
        Script: The name of the script to process these DependencyTypes
                              This looks in the PSDepend module path, under PSDependScripts
                              You can theoretically specify an absolute path
        Description: Description for this DependencyType. Provided to a user when they run Get-PSDependType.
        Supports: Platforms this script supports: windows, core, macos, linux

    See about_PSDepend for more information