feat: support platform-specific configurations

TendTo · Nov 15, 2024 · 5f4e296 · 5f4e296
1 parent 36dfc71
commit 5f4e296
Show file tree

Hide file tree

Showing 7 changed files with 378 additions and 136 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -50,3 +50,40 @@ jobs:
         with:
           files: "examples/bazel-bin/${{ matrix.subdir }}/html/index.html"
           fail: true
+
+  tests-multiple-installations:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        subdir: [base, kwargs, doxyfile, latex, nested, custom, awesome]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install doxygen
+        uses: ssciwr/doxygen-install@v1
+      - name: Enable use of windows doxygen by decommenting the module extension line
+        uses: richardrigutins/replace-in-files@v2
+        with:
+          search-text: '# doxygen_extension.version(version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows")'
+          replacement-text: doxygen_extension.version(version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows")
+          files: examples/MODULE.bazel
+      - name: Enable use of mac doxygen by decommenting the module extension line
+        uses: richardrigutins/replace-in-files@v2
+        with:
+          search-text: '# doxygen_extension.version(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", platform = "mac")'
+          replacement-text: doxygen_extension.version(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", platform = "mac")
+          files: examples/MODULE.bazel
+      - name: Enable use linux doxygen by decommenting the module extension line
+        uses: richardrigutins/replace-in-files@v2
+        with:
+          search-text: '# doxygen_extension.version(version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux")'
+          replacement-text: doxygen_extension.version(version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux")
+          files: examples/MODULE.bazel
+      - name: Build ${{ matrix.subdir }}
+        run: bazel build //${{ matrix.subdir }}:doxygen
+        working-directory: examples
+      - name: Check output
+        uses: andstor/file-existence-action@v3
+        with:
+          files: "examples/bazel-bin/${{ matrix.subdir }}/html/index.html"
+          fail: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -70,6 +70,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Support hermetic build for `macos` platform (thanks to @kaycebasques)
+- Support for platform-specific configurations in the extension rule
 
 ### Changed
 

diff --git a/README.md b/README.md
@@ -36,24 +36,14 @@ To select a doxygen version to use, use the `doxygen_extension` module extension
 ```bzl
 # MODULE.bazel file
 
+bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
+
 doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
 use_repo(doxygen_extension, "doxygen")
 ```
 
 By default, version `1.12.0` of Doxygen is used. To select a different version, indicate it in the `version` module:
 
-```bzl
-# MODULE.bazel file
-
-doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
-# Using the 1.10.0 version of Doxygen on Windows instead of the default 1.12.0
-doxygen_extension.version(
-    version = "1.10.0",
-    sha256 = "2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b",
-)
-use_repo(doxygen_extension, "doxygen")
-```
-
 If you don't know the SHA256 of the Doxygen binary, just leave it empty.
 The build will fail with an error message containing the correct SHA256.
 
@@ -63,7 +53,40 @@ Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_
 
 If you set the version to `0.0.0`, the doxygen executable will be assumed to be available from the PATH.
 No download will be performed and bazel will use the installed version of doxygen.
-Keep in mind that this will break the hermeticity of your build, as it will now depend on the environment.
+
+> [!Warning]  
+> Setting the version to `0.0.0` this will break the hermeticity of your build, as it will now depend on the environment.
+
+The module also supports multiple versions of doxygen for different platforms.
+Each will only be downloaded if the given platform matches the current platform.
+
+> [!Tip]  
+> Not indicating the platform will make the configuration apply to all platforms.
+> The build will fail when the downloaded file does not match the SHA256 checksum, i.e. when the platform changes.
+> Unless you are using a system-wide doxygen installation, you should always specify the platform.
+
+```bzl
+# MODULE.bazel file
+
+bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
+
+doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
+
+# Download doxygen version 1.10.0 on linux
+doxygen_extension.version(
+    version = "1.10.0",
+    sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747",
+    platform = "linux",
+)
+# Use the local doxygen installation on mac
+doxygen_extension.version(
+    version = "0.0.0",
+    platform = "mac",
+)
+# Since no configuration has been provided, windows will fallback to the default version
+
+use_repo(doxygen_extension, "doxygen")
+```
 
 > [!Note]
 > See [the documentation](docs/extensions_doc.md) for more information.
@@ -90,7 +113,7 @@ doxygen(
         "GENERATE_LATEX = NO",                      # from the Doxyfile
         "USE_MDFILE_AS_MAINPAGE = README.md",
     ]
-    tags = ["manual"]  # Tags to add to the target. 
+    tags = ["manual"]  # Tags to add to the target.
                        # This way the target won't run unless explicitly called
 )
 ```

diff --git a/docs/extensions_doc.md b/docs/extensions_doc.md
@@ -9,35 +9,44 @@ Repository rule for downloading the correct version of doxygen using module exte
 <pre>
 load("@rules_doxygen//:extensions.bzl", "doxygen_repository")
 
-doxygen_repository(<a href="#doxygen_repository-name">name</a>, <a href="#doxygen_repository-build">build</a>, <a href="#doxygen_repository-doxyfile_template">doxyfile_template</a>, <a href="#doxygen_repository-doxygen_bzl">doxygen_bzl</a>, <a href="#doxygen_repository-repo_mapping">repo_mapping</a>, <a href="#doxygen_repository-sha256">sha256</a>, <a href="#doxygen_repository-version">version</a>)
+doxygen_repository(<a href="#doxygen_repository-name">name</a>, <a href="#doxygen_repository-build">build</a>, <a href="#doxygen_repository-doxyfile_template">doxyfile_template</a>, <a href="#doxygen_repository-doxygen_bzl">doxygen_bzl</a>, <a href="#doxygen_repository-platforms">platforms</a>, <a href="#doxygen_repository-repo_mapping">repo_mapping</a>, <a href="#doxygen_repository-sha256s">sha256s</a>,
+                   <a href="#doxygen_repository-versions">versions</a>)
 </pre>
 
 Repository rule for doxygen.
 
+It can be provided with a configuration for each of the three platforms (windows, mac, linux) to download the correct version of doxygen only when the configuration matches the current platform.
 Depending on the version, the behavior will change:
 - If the version is set to `0.0.0`, the repository will use the installed version of doxygen, getting the binary from the PATH.
 - If a version is specified, the repository will download the correct version of doxygen and make it available to the requesting module.
 
-> [!Note]
-> The local installation version of the rules needs doxygen to be installed on your system and the binary (named doxygen) must available in the PATH.
+> [!Warning]
+> If version is set to `0.0.0`, the rules needs doxygen to be installed on your system and the binary (named doxygen) must available in the PATH.
 > Keep in mind that this will break the hermeticity of your build, as it will now depend on the environment.
 
 You can further customize the repository by specifying the `doxygen_bzl`, `build`, and `doxyfile_template` attributes, but the default values should be enough for most use cases.
 
 ### Example
 
 ```starlark
-# Download the os specific version 1.12.0 of doxygen
+# Download the os specific version 1.12.0 of doxygen supporting all platforms
 doxygen_repository(
     name = "doxygen",
-    version = "1.12.0",
-    sha256 = "07f1c92cbbb32816689c725539c0951f92c6371d3d7f66dfa3192cbe88dd3138",
+    versions = ["1.12.0", "1.12.0", "1.12.0"],
+    sha256s = [
+        "07f1c92cbbb32816689c725539c0951f92c6371d3d7f66dfa3192cbe88dd3138",
+        "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001",
+        "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647",
+    ]
+    platforms = ["windows", "mac", "linux"],
 )
 
-# Use the system installed version of doxygen
+# Use the system installed version of doxygen on linux and download version 1.11.0 for windows. No support for mac
 doxygen_repository(
     name = "doxygen",
-    version = "0.0.0",
+    version = ["0.0.0", "1.11.0"],
+    sha256s = ["", "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f"],
+    platforms = ["linux", "windows"],
 )
 ```
 
@@ -50,9 +59,10 @@ doxygen_repository(
 | <a id="doxygen_repository-build"></a>build |  The BUILD file of the repository   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `"@rules_doxygen//doxygen:BUILD.bazel"`  |
 | <a id="doxygen_repository-doxyfile_template"></a>doxyfile_template |  The Doxyfile template to use   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `"@rules_doxygen//doxygen:Doxyfile.template"`  |
 | <a id="doxygen_repository-doxygen_bzl"></a>doxygen_bzl |  The starlark file containing the doxygen macro   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `"@rules_doxygen//doxygen:doxygen.bzl"`  |
+| <a id="doxygen_repository-platforms"></a>platforms |  List of platforms to download the doxygen binary for. Available options are (windows, mac, linux). Must be the same length as `version` and `sha256s`.   | List of strings | required |  |
 | <a id="doxygen_repository-repo_mapping"></a>repo_mapping |  In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<br><br>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).<br><br>This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional |  |
-| <a id="doxygen_repository-sha256"></a>sha256 |  The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used.   | String | optional |  `"0000000000000000000000000000000000000000000000000000000000000000"`  |
-| <a id="doxygen_repository-version"></a>version |  The version of doxygen to use. If set to `0.0.0`, the doxygen executable will be assumed to be available from the PATH   | String | required |  |
+| <a id="doxygen_repository-sha256s"></a>sha256s |  List of sha256 hashes of the doxygen archive. Must be the same length as `versions and `platforms`.   | List of strings | required |  |
+| <a id="doxygen_repository-versions"></a>versions |  List of versions of doxygen to use. If set to `0.0.0`, the doxygen executable will be assumed to be available from the PATH. Must be the same length as `sha256s` and `platforms`.   | List of strings | required |  |
 
 
 <a id="doxygen_extension"></a>
@@ -61,7 +71,7 @@ doxygen_repository(
 
 <pre>
 doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
-doxygen_extension.version(<a href="#doxygen_extension.version-sha256">sha256</a>, <a href="#doxygen_extension.version-version">version</a>)
+doxygen_extension.version(<a href="#doxygen_extension.version-platform">platform</a>, <a href="#doxygen_extension.version-sha256">sha256</a>, <a href="#doxygen_extension.version-version">version</a>)
 </pre>
 
 Module extension for declaring the doxygen version to use.
@@ -81,9 +91,37 @@ Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_
 
 If you set the version to `0.0.0`, the doxygen executable will be assumed to be available from the PATH.
 No download will be performed and bazel will use the installed version of doxygen.
-Keep in mind that this will break the hermeticity of your build, as it will now depend on the environment.
 
-### Example
+> [!Warning]
+> Setting the version to `0.0.0` this will break the hermeticity of your build, as it will now depend on the environment.
+
+The module also supports multiple versions of doxygen for different platforms.
+Each will only be downloaded if the given platform matches the current platform.
+
+> [!Tip]
+> Not indicating the platform will make the configuration apply to all platforms.
+> The build will fail when the downloaded file does not match the SHA256 checksum, i.e. when the platform changes.
+> Unless you are using a system-wide doxygen installation, you should always specify the platform.
+
+### Examples
+
+```starlark
+# MODULE.bazel file
+
+bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
+
+doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
+
+# Using the 1.10.0 version of Doxygen instead of the default 1.12.0.
+# Note that che checksum is correct only if the platform is windows.
+# If the platform is different, the build will fail.
+doxygen_extension.version(
+    version = "1.10.0",
+    sha256 = "2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b",
+)
+
+use_repo(doxygen_extension, "doxygen")
+```
 
 ```starlark
 # MODULE.bazel file
@@ -92,8 +130,44 @@ bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
 
 doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
 
-# Using the 1.10.0 version of Doxygen on Windows instead of the default 1.12.0
-doxygen_extension.version(version = "1.10.0", sha256 = "2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b")
+doxygen_extension.version(
+    version = "1.10.0",
+    sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747",
+    platform = "linux",
+)
+doxygen_extension.version(
+    version = "1.12.0",
+    sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001",
+    platform = "mac",
+)
+doxygen_extension.version(
+    version = "1.11.0",
+    sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f",
+    platform = "windows",
+)
+
+use_repo(doxygen_extension, "doxygen")
+```
+
+```bzl
+# MODULE.bazel file
+
+bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
+
+doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
+
+# Download doxygen version 1.10.0 on linux
+doxygen_extension.version(
+    version = "1.10.0",
+    sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747",
+    platform = "linux",
+)
+# Use the local doxygen installation on mac
+doxygen_extension.version(
+    version = "0.0.0",
+    platform = "mac",
+)
+# Since no configuration has been provided, windows will fallback to the default version
 
 use_repo(doxygen_extension, "doxygen")
 ```
@@ -109,6 +183,7 @@ use_repo(doxygen_extension, "doxygen")
 
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="doxygen_extension.version-platform"></a>platform |  The target platform for the doxygen binary. Available options are (windows, mac, linux). If not specified, it will select the platform it is currently running on.   | String | optional |  `""`  |
 | <a id="doxygen_extension.version-sha256"></a>sha256 |  The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used.   | String | optional |  `""`  |
 | <a id="doxygen_extension.version-version"></a>version |  The version of doxygen to use. If set to `0.0.0`, the doxygen executable will be assumed to be available from the PATH   | String | required |  |
 

diff --git a/doxygen/BUILD.bazel b/doxygen/BUILD.bazel
@@ -9,9 +9,9 @@ filegroup(
     name = "executable",
     srcs = select(
         {
-            "@platforms//os:linux": ["doxygen"],
-            "@platforms//os:macos": ["doxygen"],
-            "@platforms//os:windows": ["doxygen.exe"],
+            "@platforms//os:linux": ["linux/doxygen"],
+            "@platforms//os:macos": ["mac/doxygen"],
+            "@platforms//os:windows": ["windows/doxygen.exe"],
         },
         "Unsupported platform",
     ),

diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel
@@ -7,6 +7,13 @@ local_path_override(
 )
 
 doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
-# Test doxygen_extension with a system installation of doxygen
+
+# doxygen_extension with a system installation of doxygen
 # doxygen_extension.version(version = "0.0.0")
+
+# Multiple versions of doxygen for different platforms
+# doxygen_extension.version(version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux")
+# doxygen_extension.version(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", platform = "mac")
+# doxygen_extension.version(version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows")
+
 use_repo(doxygen_extension, "doxygen")