From c4c8c5bc2a205b964581d3d564f5e8ef0c4208be Mon Sep 17 00:00:00 2001 From: GijsR Date: Thu, 3 Jul 2025 10:49:54 +0200 Subject: [PATCH 1/3] Add reference documentation for DSC.Packagemanagement/Brw --- .../examples/install-a-package-with-brew.md | 0 .../Brew/examples/remove-a-package.md | 0 .../DSC/PackageManagement/Brew/index.md | 208 ++++++++++++++++++ 3 files changed, 208 insertions(+) create mode 100644 docs/reference/resources/DSC/PackageManagement/Brew/examples/install-a-package-with-brew.md create mode 100644 docs/reference/resources/DSC/PackageManagement/Brew/examples/remove-a-package.md create mode 100644 docs/reference/resources/DSC/PackageManagement/Brew/index.md diff --git a/docs/reference/resources/DSC/PackageManagement/Brew/examples/install-a-package-with-brew.md b/docs/reference/resources/DSC/PackageManagement/Brew/examples/install-a-package-with-brew.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/resources/DSC/PackageManagement/Brew/examples/remove-a-package.md b/docs/reference/resources/DSC/PackageManagement/Brew/examples/remove-a-package.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/resources/DSC/PackageManagement/Brew/index.md b/docs/reference/resources/DSC/PackageManagement/Brew/index.md new file mode 100644 index 000000000..868364a28 --- /dev/null +++ b/docs/reference/resources/DSC/PackageManagement/Brew/index.md @@ -0,0 +1,208 @@ +--- +description: DSC.PackageManagement/Brew resource reference documentation +ms.date: 07/03/2025 +ms.topic: reference +title: DSC.PackageManagement/Brew +--- + +# DSC.PackageManagement/Brew + +## Synopsis + +Manage packages using Homebrew on macOS systems. + +> [!IMPORTANT] +> The `DSC.PackageManagement/Brew` resource is a proof-of-concept example +> for use with DSC. Don't use it in production. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [macOS, brew, PackageManagement] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: DSC.PackageManagement/Brew + properties: + # Required properties + packageName: string + # Instance properties + _exist: boolean + version: string +``` + +## Description + +The `DSC.PackageManagement/Brew` resource enables you to idempotently manage packages using Homebrew on +macOS systems. The resource can: + +- Install packages +- Uninstall packages +- Check if a package is installed +- Verify the version of an installed package + +> [!NOTE] +> This resource only works on macOS systems with Homebrew installed. + +## Requirements + +- A macOS system with Homebrew installed +- Administrative privileges may be required for certain package operations + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of an instance. +- `set` - You can use the resource to enforce the desired state for an instance. +- `export` - You can use the resource to export the current state of the system. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is in +the desired state. For more information about resource capabilities, see +[DSC resource capabilities][00]. + +## Examples + +1. [Install a package with Brew][04] - Shows how to install a package using + `DSC.PackageManagement/Brew` resource. +2. [Remove a package][05] - Shows how to uninstall a package. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. An instance that doesn't define each of these + properties is invalid. For more information, see the "Required resource properties" section in + [DSC resource properties][01] + + - [packageName](#packagename) - The name of the package to query or install. + +- **Key properties:** The following properties uniquely identify an + instance. If two instances of a resource have the same values for their key properties, the + instances are conflicting. For more information about key properties, see the "Key resource + properties" section in [DSC resource properties][02]. + + - [packageName](#packagename) (required) - The name of the package to query or install. + +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [_exist](#_exist) - Defines whether the package should exist. + - [version](#version) - The version of the package to install. + +### packageName + +
Expand for packageName property metadata + +```yaml +Type : string +IsRequired : true +IsKey : true +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the name of the package to query or install. This property is required and serves as the key for uniquely +identifying the package in the Homebrew package repository. + +### _exist + +
Expand for _exist property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +DefaultValue : true +``` + +
+ +The `_exist` canonical resource property determines whether a package should exist. When the +value for `_exist` is `true`, the resource installs the package if it doesn't exist. When +the value for `_exist` is `false`, the resource removes or uninstalls the package if it does exist. +The default value for this property when not specified for an instance is `true`. + +### version + +
Expand for version property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the version of the package to install. If not specified, the latest available version will be installed. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. The +validating schema only includes schema keywords that affect how the instance is validated. All +non validating keywords are omitted. + +```json +{ + "type": "object", + "required": ["packageName"], + "additionalProperties": false, + "properties": { + "packageName": { + "type": "string" + }, + "version": { + "type": "string" + }, + "_exist": { + "type": "boolean" + } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Invalid parameter + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed due to an invalid parameter. When the resource returns this +exit code, it also emits an error message with details about the invalid parameter. + +## See also + +- [DSC.PackageManagement/Apt resource][03] +- [For more information about Homebrew][07] + + +[00]: ../../../../../concepts/resources/capabilities.md +[01]: ../../../../../concepts/resources/properties.md#required-resource-properties +[02]: ../../../../../concepts/resources/properties.md#key-resource-properties +[03]: ../APT/index.md +[04]: ./examples/install-package-with-brew.md +[05]: ./examples/install-specific-version.md +[06]: ./examples/remove-package.md +[07]: https://brew.sh/ From e04e10b92332e27ec37c6d472e78bfadc6996b88 Mon Sep 17 00:00:00 2001 From: GijsR Date: Thu, 3 Jul 2025 11:31:48 +0200 Subject: [PATCH 2/3] Add two examples --- .../examples/install-a-package-with-brew.md | 85 +++++++++++++++++++ .../Brew/examples/remove-a-package.md | 83 ++++++++++++++++++ .../DSC/PackageManagement/Brew/index.md | 9 +- 3 files changed, 172 insertions(+), 5 deletions(-) diff --git a/docs/reference/resources/DSC/PackageManagement/Brew/examples/install-a-package-with-brew.md b/docs/reference/resources/DSC/PackageManagement/Brew/examples/install-a-package-with-brew.md index e69de29bb..731b60f14 100644 --- a/docs/reference/resources/DSC/PackageManagement/Brew/examples/install-a-package-with-brew.md +++ b/docs/reference/resources/DSC/PackageManagement/Brew/examples/install-a-package-with-brew.md @@ -0,0 +1,85 @@ +--- +description: > + Demonstrates how to install a package with the DSC.PackageManagement/Brew resource +ms.date: 07/03/2025 +ms.topic: reference +title: Install a package with Brew +--- + +# Install a package with Brew + +This example demonstrates how to use the `DSC.PackageManagement/Brew` resource to install a package +on MacOS systems using Brew. + +## Test if package is installed + +The following snippet shows how you can use the resource with the [dsc resource test][00] command +to check whether the `node` package exists. + +```bash +dsc resource test --resource DSC.PackageManagement/Brew --input '{"packageName":"node"}' +``` + +When the package is not installed, DSC returns the following result. + +```yaml +desiredState: + packageName: node +actualState: + _exist: false + packageName: node + version: "" +inDesiredState: false +differingProperties: + - _exist +``` + +## Ensure a package is installed + +To ensure the system is in the desired state, use the [dsc resource set][01] +command. + +```bash +dsc resource set --resource DSC.PackageManagement/Brew --input '{"packageName":"node"}' +``` + +When the resource installs the package, DSC returns the following result: + +```yaml +beforeState: + packageName: "node" + version: "" + _exist: false +afterState: + _exist: true + packageName: node + version: "24.3.0" +changedProperties: +- _exist +- version +``` + +> [!NOTE] +> Note that the version can differ depending on your system's package repositories +> and available package versions. + +You can test the instance again to confirm that the package exists: + +```bash +dsc resource test --resource DSC.PackageManagement/Brew --input '{"packageName":"node"}' +``` + +```yaml +desiredState: + packageName: node +actualState: + _exist: true + packageName: node + version: "24.3.0" +inDesiredState: true +differingProperties: [] +``` + + +[00]: ../../../../../cli/resource/test.md +[01]: ../../../../../cli/resource/set.md diff --git a/docs/reference/resources/DSC/PackageManagement/Brew/examples/remove-a-package.md b/docs/reference/resources/DSC/PackageManagement/Brew/examples/remove-a-package.md index e69de29bb..3f980723a 100644 --- a/docs/reference/resources/DSC/PackageManagement/Brew/examples/remove-a-package.md +++ b/docs/reference/resources/DSC/PackageManagement/Brew/examples/remove-a-package.md @@ -0,0 +1,83 @@ +--- +description: > + Demonstrates how to remove a package with the DSC.PackageManagement/Brew resource +ms.date: 07/03/2025 +ms.topic: reference +title: Remove a package with Brew +--- + +# Remove a package with Brew + +This example demonstrates how to use the `DSC.PackageManagement/Brew` resource to remove a package +on MacOS systems using Brew. + +## Test if package is installed + +The following snippet shows how you can use the resource with the [dsc resource test][00] command +to check whether the `node` package doesn't exists. + +```bash +dsc resource test --resource DSC.PackageManagement/Brew --input '{"packageName":"node","_exist":false}' +``` + +When the package is installed, DSC returns the following result. + +```yaml +desiredState: + packageName: node + _exist: false +actualState: + _exist: true + packageName: node + version: "24.3.0" +inDesiredState: false +differingProperties: + - _exist +``` + +## Ensure a package is removed + +To ensure the system is in the desired state, use the [dsc resource set][01] +command. + +```bash +dsc resource set --resource DSC.PackageManagement/Brew --input '{"packageName":"node","_exist":false}' +``` + +When the resource removes the package, DSC returns the following result: + +```yaml +beforeState: + packageName: "node" + version: "24.3.0" + _exist: true +afterState: + _exist: false + packageName: node + version: "" +changedProperties: +- _exist +- version +``` + +You can test the instance again to confirm that the package has been removed: + +```bash +dsc resource test --resource DSC.PackageManagement/Brew --input '{"packageName":"node","_exist":false}' +``` + +```yaml +desiredState: + packageName: node + _exist: false +actualState: + _exist: false + packageName: node + version: "" +inDesiredState: true +differingProperties: [] +``` + + +[00]: ../../../../../cli/resource/test.md +[01]: ../../../../../cli/resource/set.md diff --git a/docs/reference/resources/DSC/PackageManagement/Brew/index.md b/docs/reference/resources/DSC/PackageManagement/Brew/index.md index 868364a28..c21ebe54b 100644 --- a/docs/reference/resources/DSC/PackageManagement/Brew/index.md +++ b/docs/reference/resources/DSC/PackageManagement/Brew/index.md @@ -195,14 +195,13 @@ exit code, it also emits an error message with details about the invalid paramet ## See also - [DSC.PackageManagement/Apt resource][03] -- [For more information about Homebrew][07] +- [For more information about Homebrew][06] [00]: ../../../../../concepts/resources/capabilities.md [01]: ../../../../../concepts/resources/properties.md#required-resource-properties [02]: ../../../../../concepts/resources/properties.md#key-resource-properties [03]: ../APT/index.md -[04]: ./examples/install-package-with-brew.md -[05]: ./examples/install-specific-version.md -[06]: ./examples/remove-package.md -[07]: https://brew.sh/ +[04]: ./examples/install-a-package-with-brew.md +[05]: ./examples/remove-a-package.md +[06]: https://brew.sh/ From 13023c12e5b9d763b35839a2ac294c88495286d0 Mon Sep 17 00:00:00 2001 From: GijsR Date: Thu, 3 Jul 2025 15:59:27 +0200 Subject: [PATCH 3/3] Remove comment --- docs/reference/resources/DSC/PackageManagement/Brew/index.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/reference/resources/DSC/PackageManagement/Brew/index.md b/docs/reference/resources/DSC/PackageManagement/Brew/index.md index c21ebe54b..60f08c4a8 100644 --- a/docs/reference/resources/DSC/PackageManagement/Brew/index.md +++ b/docs/reference/resources/DSC/PackageManagement/Brew/index.md @@ -48,9 +48,6 @@ macOS systems. The resource can: - Check if a package is installed - Verify the version of an installed package -> [!NOTE] -> This resource only works on macOS systems with Homebrew installed. - ## Requirements - A macOS system with Homebrew installed