tjh.dev
nixpkgs mirror (for testing)
github.com/NixOS/nixpkgs
nix
1# Azure CLI
2
3## Updating the CLI
4
5- Update `version` and `src.hash` in package.nix
6- Check out the changes made to the azure-cli [setup.py](https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/setup.py) since the last release
7- Try build the CLI, will likely fail with `ModuleNotFoundError`, for example
8 ```
9 ModuleNotFoundError: No module named 'azure.mgmt.storage.v2023_05_01'
10 ```
11 Sometimes it will also fail with other import errors.
12- Check the referenced module (`azure-mgmt-storage`) in the setup.py
13- Find the actual version required, for example
14 ```
15 'azure-mgmt-storage==21.2.0',
16 ```
17- Update version and hash of this dependency in python-packages.nix
18- Repeat until it builds
19
20## Extensions
21
22There are two sets of extensions:
23
24- `extensions-generated.nix` are extensions with no external requirements, which can be regenerated running:
25 > nix run .#azure-cli.passthru.generate-extensions
26
27- `extensions-manual.nix` are extensions with requirements, which need to be manually packaged and maintained.
28
29### Adding an extension to `extensions-manual.nix`
30
31To manually add a missing extension, first query its metadata from the extension index.
32Use the following command, use the current version of azure-cli in nixpkgs as `cli-version`
33and the name of the extension you want to package as `extension`:
34
35```sh
36./query-extension-index.sh --cli-version=2.61.0 --extension=azure-devops --download
37```
38
39The output should look something like this:
40
41```json
42{
43 "pname": "azure-devops",
44 "description": "Tools for managing Azure DevOps.",
45 "version": "1.0.1",
46 "url": "https://github.com/Azure/azure-devops-cli-extension/releases/download/20240514.1/azure_devops-1.0.1-py2.py3-none-any.whl",
47 "sha256": "f300d0288f017148514ebe6f5912aef10c7a6f29bdc0c916b922edf1d75bc7db",
48 "license": "MIT",
49 "requires": [
50 "distro (==1.3.0)",
51 "distro==1.3.0"
52 ]
53}
54```
55
56Based on this, you can add an attribute to `extensions-manual.nix`:
57
58```nix
59{
60 azure-devops = mkAzExtension {
61 pname = "azure-devops";
62 version = "1.0.0";
63 url = "https://github.com/Azure/azure-devops-cli-extension/releases/download/20240206.1/azure_devops-${version}-py2.py3-none-any.whl";
64 sha256 = "658a2854d8c80f874f9382d421fa45abf6a38d00334737dda006f8dec64cf70a";
65 description = "Tools for managing Azure DevOps";
66 propagatedBuildInputs = with python3Packages; [ distro ];
67 meta.maintainers = with lib.maintainers; [ katexochen ];
68 };
69}
70```
71
72* The attribute name should be the same as `pname`.
73* Replace the version in `url` with `${version}`.
74* The json output `requires` must be transformed into `propagetedBuildInputs`.
75* If `license` is `"MIT"`, it can be left out in the nix expression, as the builder defaults to that license.
76* Add yourself as maintainer in `meta.maintainers`.
77
78### Testing extensions
79
80You can build azure-cli with an extension on the command line by running the following command at the root of this repository:
81
82```sh
83nix build --impure --expr 'with (import ./. {}); azure-cli.withExtensions [ azure-cli.extensions.azure-devops ]'
84```
85
86Check if the desired functionality was added.
87
88You can check if the extensions was recognized by running:
89
90```sh
91./result/bin/az extension list
92```
93
94The output should show the extension like this:
95
96```sh
97[
98 {
99 "experimental": false,
100 "extensionType": "whl",
101 "name": "azure-devops",
102 "path": "/nix/store/azbgnpg5nh5rb8wfvp0r9bmcx83mqrj5-azure-cli-extensions/azure-devops",
103 "preview": false,
104 "version": "1.0.0"
105 }
106]
107```
108
109### Removing an extension
110
111If extensions are removed upstream, an alias is added to the end of `extensions-manual.nix`
112(see `# Removed extensions`). This alias should throw an error and be of similar structure as
113this example:
114
115```nix
116{
117 blockchain = throw "The 'blockchain' extension for azure-cli was deprecated upstream"; # Added 2024-04-26
118}
119```