PSDepend

0.3.8

en-US/about_PSDepend_Definitions.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 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, 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