pkgs/by-name/az/azure-cli/README.md

   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
  22 There 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
  31 To manually add a missing extension, first query its metadata from the extension index.
  32 Use the following command, use the current version of azure-cli in nixpkgs as `cli-version`
  33 and 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
  39 The 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
  56 Based on this, you can add an attribute to `extensions-manual.nix`:
  57
  58 ```nix
  59   azure-devops = mkAzExtension rec {
  60     pname = "azure-devops";
  61     version = "1.0.0";
  62     url = "https://github.com/Azure/azure-devops-cli-extension/releases/download/20240206.1/azure_devops-${version}-py2.py3-none-any.whl";
  63     sha256 = "658a2854d8c80f874f9382d421fa45abf6a38d00334737dda006f8dec64cf70a";
  64     description = "Tools for managing Azure DevOps";
  65     propagatedBuildInputs = with python3Packages; [
  66       distro
  67     ];
  68     meta.maintainers = with lib.maintainers; [ katexochen ];
  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
  80 You 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
  83 nix build --impure --expr 'with (import ./. {}); azure-cli.withExtensions [ azure-cli.extensions.azure-devops ]'
  84 ```
  85
  86 Check if the desired functionality was added.
  87
  88 You can check if the extensions was recognized by running:
  89
  90 ```sh
  91 ./result/bin/az extension list
  92 ```
  93
  94 The 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
 111 If 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
 113 this example:
 114
 115 ```nix
 116 blockchain = throw "The 'blockchain' extension for azure-cli was deprecated upstream"; # Added 2024-04-26
 117 ```