Skip to content

Commit b6b151c

Browse files
michaeltlombardimichaeltlombardi
authored
Merge pull request #939 from Gijsreyn/reference-doc-brew
Add reference documentation for DSC.PackageManagement/Brew
2 parents 53e246b + 13023c1 commit b6b151c

File tree

3 files changed

+372
-0
lines changed

3 files changed

+372
-0
lines changed

‎docs/reference/resources/DSC/PackageManagement/Brew/examples/install-a-package-with-brew.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
description: >
3+
Demonstrates how to install a package with the DSC.PackageManagement/Brew resource
4+
ms.date: 07/03/2025
5+
ms.topic: reference
6+
title: Install a package with Brew
7+
---
8+
9+
# Install a package with Brew
10+
11+
This example demonstrates how to use the `DSC.PackageManagement/Brew` resource to install a package
12+
on MacOS systems using Brew.
13+
14+
## Test if package is installed
15+
16+
The following snippet shows how you can use the resource with the [dsc resource test][00] command
17+
to check whether the `node` package exists.
18+
19+
```bash
20+
dsc resource test --resource DSC.PackageManagement/Brew --input '{"packageName":"node"}'
21+
```
22+
23+
When the package is not installed, DSC returns the following result.
24+
25+
```yaml
26+
desiredState:
27+
packageName: node
28+
actualState:
29+
_exist: false
30+
packageName: node
31+
version: ""
32+
inDesiredState: false
33+
differingProperties:
34+
- _exist
35+
```
36+
37+
## Ensure a package is installed
38+
39+
To ensure the system is in the desired state, use the [dsc resource set][01]
40+
command.
41+
42+
```bash
43+
dsc resource set --resource DSC.PackageManagement/Brew --input '{"packageName":"node"}'
44+
```
45+
46+
When the resource installs the package, DSC returns the following result:
47+
48+
```yaml
49+
beforeState:
50+
packageName: "node"
51+
version: ""
52+
_exist: false
53+
afterState:
54+
_exist: true
55+
packageName: node
56+
version: "24.3.0"
57+
changedProperties:
58+
- _exist
59+
- version
60+
```
61+
62+
> [!NOTE]
63+
> Note that the version can differ depending on your system's package repositories
64+
> and available package versions.
65+
66+
You can test the instance again to confirm that the package exists:
67+
68+
```bash
69+
dsc resource test --resource DSC.PackageManagement/Brew --input '{"packageName":"node"}'
70+
```
71+
72+
```yaml
73+
desiredState:
74+
packageName: node
75+
actualState:
76+
_exist: true
77+
packageName: node
78+
version: "24.3.0"
79+
inDesiredState: true
80+
differingProperties: []
81+
```
82+
83+
<!-- Link reference definitions -->
84+
[00]: ../../../../../cli/resource/test.md
85+
[01]: ../../../../../cli/resource/set.md

‎docs/reference/resources/DSC/PackageManagement/Brew/examples/remove-a-package.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
description: >
3+
Demonstrates how to remove a package with the DSC.PackageManagement/Brew resource
4+
ms.date: 07/03/2025
5+
ms.topic: reference
6+
title: Remove a package with Brew
7+
---
8+
9+
# Remove a package with Brew
10+
11+
This example demonstrates how to use the `DSC.PackageManagement/Brew` resource to remove a package
12+
on MacOS systems using Brew.
13+
14+
## Test if package is installed
15+
16+
The following snippet shows how you can use the resource with the [dsc resource test][00] command
17+
to check whether the `node` package doesn't exists.
18+
19+
```bash
20+
dsc resource test --resource DSC.PackageManagement/Brew --input '{"packageName":"node","_exist":false}'
21+
```
22+
23+
When the package is installed, DSC returns the following result.
24+
25+
```yaml
26+
desiredState:
27+
packageName: node
28+
_exist: false
29+
actualState:
30+
_exist: true
31+
packageName: node
32+
version: "24.3.0"
33+
inDesiredState: false
34+
differingProperties:
35+
- _exist
36+
```
37+
38+
## Ensure a package is removed
39+
40+
To ensure the system is in the desired state, use the [dsc resource set][01]
41+
command.
42+
43+
```bash
44+
dsc resource set --resource DSC.PackageManagement/Brew --input '{"packageName":"node","_exist":false}'
45+
```
46+
47+
When the resource removes the package, DSC returns the following result:
48+
49+
```yaml
50+
beforeState:
51+
packageName: "node"
52+
version: "24.3.0"
53+
_exist: true
54+
afterState:
55+
_exist: false
56+
packageName: node
57+
version: ""
58+
changedProperties:
59+
- _exist
60+
- version
61+
```
62+
63+
You can test the instance again to confirm that the package has been removed:
64+
65+
```bash
66+
dsc resource test --resource DSC.PackageManagement/Brew --input '{"packageName":"node","_exist":false}'
67+
```
68+
69+
```yaml
70+
desiredState:
71+
packageName: node
72+
_exist: false
73+
actualState:
74+
_exist: false
75+
packageName: node
76+
version: ""
77+
inDesiredState: true
78+
differingProperties: []
79+
```
80+
81+
<!-- Link reference definitions -->
82+
[00]: ../../../../../cli/resource/test.md
83+
[01]: ../../../../../cli/resource/set.md

‎docs/reference/resources/DSC/PackageManagement/Brew/index.md

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
description: DSC.PackageManagement/Brew resource reference documentation
3+
ms.date: 07/03/2025
4+
ms.topic: reference
5+
title: DSC.PackageManagement/Brew
6+
---
7+
8+
# DSC.PackageManagement/Brew
9+
10+
## Synopsis
11+
12+
Manage packages using Homebrew on macOS systems.
13+
14+
> [!IMPORTANT]
15+
> The `DSC.PackageManagement/Brew` resource is a proof-of-concept example
16+
> for use with DSC. Don't use it in production.
17+
18+
## Metadata
19+
20+
```yaml
21+
Version : 0.1.0
22+
Kind : resource
23+
Tags : [macOS, brew, PackageManagement]
24+
Author : Microsoft
25+
```
26+
27+
## Instance definition syntax
28+
29+
```yaml
30+
resources:
31+
- name: <instance name>
32+
type: DSC.PackageManagement/Brew
33+
properties:
34+
# Required properties
35+
packageName: string
36+
# Instance properties
37+
_exist: boolean
38+
version: string
39+
```
40+
41+
## Description
42+
43+
The `DSC.PackageManagement/Brew` resource enables you to idempotently manage packages using Homebrew on
44+
macOS systems. The resource can:
45+
46+
- Install packages
47+
- Uninstall packages
48+
- Check if a package is installed
49+
- Verify the version of an installed package
50+
51+
## Requirements
52+
53+
- A macOS system with Homebrew installed
54+
- Administrative privileges may be required for certain package operations
55+
56+
## Capabilities
57+
58+
The resource has the following capabilities:
59+
60+
- `get` - You can use the resource to retrieve the actual state of an instance.
61+
- `set` - You can use the resource to enforce the desired state for an instance.
62+
- `export` - You can use the resource to export the current state of the system.
63+
64+
This resource uses the synthetic test functionality of DSC to determine whether an instance is in
65+
the desired state. For more information about resource capabilities, see
66+
[DSC resource capabilities][00].
67+
68+
## Examples
69+
70+
1. [Install a package with Brew][04] - Shows how to install a package using
71+
`DSC.PackageManagement/Brew` resource.
72+
2. [Remove a package][05] - Shows how to uninstall a package.
73+
74+
## Properties
75+
76+
The following list describes the properties for the resource.
77+
78+
- **Required properties:** <a id="required-properties"></a> The following properties are always
79+
required when defining an instance of the resource. An instance that doesn't define each of these
80+
properties is invalid. For more information, see the "Required resource properties" section in
81+
[DSC resource properties][01]
82+
83+
- [packageName](#packagename) - The name of the package to query or install.
84+
85+
- **Key properties:** <a id="key-properties"></a> The following properties uniquely identify an
86+
instance. If two instances of a resource have the same values for their key properties, the
87+
instances are conflicting. For more information about key properties, see the "Key resource
88+
properties" section in [DSC resource properties][02].
89+
90+
- [packageName](#packagename) (required) - The name of the package to query or install.
91+
92+
- **Instance properties:** <a id="instance-properties"></a> The following properties are optional.
93+
They define the desired state for an instance of the resource.
94+
95+
- [_exist](#_exist) - Defines whether the package should exist.
96+
- [version](#version) - The version of the package to install.
97+
98+
### packageName
99+
100+
<details><summary>Expand for <code>packageName</code> property metadata</summary>
101+
102+
```yaml
103+
Type : string
104+
IsRequired : true
105+
IsKey : true
106+
IsReadOnly : false
107+
IsWriteOnly : false
108+
```
109+
110+
</details>
111+
112+
Defines the name of the package to query or install. This property is required and serves as the key for uniquely
113+
identifying the package in the Homebrew package repository.
114+
115+
### _exist
116+
117+
<details><summary>Expand for <code>_exist</code> property metadata</summary>
118+
119+
```yaml
120+
Type : boolean
121+
IsRequired : false
122+
IsKey : false
123+
IsReadOnly : false
124+
IsWriteOnly : false
125+
DefaultValue : true
126+
```
127+
128+
</details>
129+
130+
The `_exist` canonical resource property determines whether a package should exist. When the
131+
value for `_exist` is `true`, the resource installs the package if it doesn't exist. When
132+
the value for `_exist` is `false`, the resource removes or uninstalls the package if it does exist.
133+
The default value for this property when not specified for an instance is `true`.
134+
135+
### version
136+
137+
<details><summary>Expand for <code>version</code> property metadata</summary>
138+
139+
```yaml
140+
Type : string
141+
IsRequired : false
142+
IsKey : false
143+
IsReadOnly : false
144+
IsWriteOnly : false
145+
```
146+
147+
</details>
148+
149+
Defines the version of the package to install. If not specified, the latest available version will be installed.
150+
151+
## Instance validating schema
152+
153+
The following snippet contains the JSON Schema that validates an instance of the resource. The
154+
validating schema only includes schema keywords that affect how the instance is validated. All
155+
non validating keywords are omitted.
156+
157+
```json
158+
{
159+
"type": "object",
160+
"required": ["packageName"],
161+
"additionalProperties": false,
162+
"properties": {
163+
"packageName": {
164+
"type": "string"
165+
},
166+
"version": {
167+
"type": "string"
168+
},
169+
"_exist": {
170+
"type": "boolean"
171+
}
172+
}
173+
}
174+
```
175+
176+
## Exit codes
177+
178+
The resource returns the following exit codes from operations:
179+
180+
- [0](#exit-code-0) - Success
181+
- [1](#exit-code-1) - Invalid parameter
182+
183+
### Exit code 0
184+
185+
Indicates the resource operation completed without errors.
186+
187+
### Exit code 1
188+
189+
Indicates the resource operation failed due to an invalid parameter. When the resource returns this
190+
exit code, it also emits an error message with details about the invalid parameter.
191+
192+
## See also
193+
194+
- [DSC.PackageManagement/Apt resource][03]
195+
- [For more information about Homebrew][06]
196+
197+
<!-- Link definitions -->
198+
[00]: ../../../../../concepts/resources/capabilities.md
199+
[01]: ../../../../../concepts/resources/properties.md#required-resource-properties
200+
[02]: ../../../../../concepts/resources/properties.md#key-resource-properties
201+
[03]: ../APT/index.md
202+
[04]: ./examples/install-a-package-with-brew.md
203+
[05]: ./examples/remove-a-package.md
204+
[06]: https://brew.sh/

0 commit comments

Comments
 (0)