Merge pull request #6 from TendTo/feat/macos-support

Add hermetic macos support

.bcr/presubmit.yml

@@ -1,7 +1,7 @@
 bcr_test_module:
   module_path: "examples"
   matrix:
-    platform: ["fedora40", "ubuntu2204", "windows"]
+    platform: ["fedora40", "ubuntu2204", "windows", "macos"]
     bazel: [7.x]
   tasks:
     run_tests:

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
   tests:
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-latest] # No macOS for now
+        os: [ubuntu-latest, windows-latest, macos-latest]
         subdir: [base, kwargs, doxyfile, latex, nested, custom, awesome]
     runs-on: ${{ matrix.os }}
 
@@ -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

BUILD.bazel

@@ -1,8 +1,3 @@
 """rules_doxygen BUILD file"""
 
-exports_files([
-    "Doxyfile.template",
-    "doxygen.BUILD.bazel",
-    "doxygen.bzl",
-    "extensions.bzl",
-])
+exports_files(["extensions.bzl"])

CHANGELOG.md

@@ -65,6 +65,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Default doxygen version is now `1.12.0`
 
+## [1.3.0]
+
+### Added
+
+- Support hermetic build for `macos` platform (thanks to @kaycebasques)
+- Support for platform-specific configurations in the extension rule
+
+### Changed
+
+- Update dependencies (stardoc 0.6.2 -> 0.7.1, platforms 0.0.5 -> 0.0.10)
+- Refactor of internal repository and extension rules
+- Updated documentation
+
 ## [NEXT.VERSION]
 
 [1.0.0]: https://github.com/TendTo/rules_doxygen/tree/1.0.0
@@ -73,4 +86,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [1.1.2]: https://github.com/TendTo/rules_doxygen/compare/1.1.1...1.1.2
 [1.1.3]: https://github.com/TendTo/rules_doxygen/compare/1.1.2...1.1.3
 [1.2.0]: https://github.com/TendTo/rules_doxygen/compare/1.1.3...1.2.0
-[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/1.2.0...HEAD
+[1.3.0]: https://github.com/TendTo/rules_doxygen/compare/1.2.0...1.3.0
+[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/1.3.0...HEAD

MODULE.bazel

@@ -1,5 +1,5 @@
 """rules_doxygen module"""
-module(name = "rules_doxygen", version = "1.2.0", compatibility_level = 1)
+module(name = "rules_doxygen", version = "1.3.0", compatibility_level = 1)
 
-bazel_dep(name = "platforms", version = "0.0.5")
-bazel_dep(name = "stardoc", version = "0.6.2", dev_dependency = True)
+bazel_dep(name = "platforms", version = "0.0.10")
+bazel_dep(name = "stardoc", version = "0.7.1", dev_dependency = True)

README.md

@@ -9,18 +9,22 @@ This repository contains a [Starlark](https://github.com/bazelbuild/starlark) im
 Add the following to your _MODULE.bazel_:
 
 ```bzl
-bazel_dep(name = "rules_doxygen", version = "1.2.0", dev_dependency = True)
+# MODULE.bazel file
+
+bazel_dep(name = "rules_doxygen", version = "1.3.0", dev_dependency = True)
 ```
 
 If you don't want to depend on the [Bazel package registry](https://bazel.build/external/bazelbuild/rules_pkg) or you want to use a not-yet-published version of this module, you can use an archive override by adding the following lines below the `bazel_dep` rule in your _MODULE.bazel_ file:
 
 ```bzl
-bazel_dep(name = "rules_doxygen", version = "1.2.0", dev_dependency = True)
+# MODULE.bazel file
+
+bazel_dep(name = "rules_doxygen", version = "1.3.0", dev_dependency = True)
 archive_override(
     module_name = "rules_doxygen",
     urls = "https://github.com/TendTo/rules_doxygen/archive/refs/heads/main.tar.gz",
     strip_prefix = "rules_doxygen-main",
-    # The SHA256 checksum of the archive file, based on the rules' version, for reproducibility
+    # The SHA256 checksum of the archive file, based on the rules' version
     # integrity = "sha256-0SCaZuAerluoDs6HXMb0Bj9FttZVieM4+Dpd9gnMM+o=", # Example
 )
 ```
@@ -30,19 +34,16 @@ archive_override(
 To select a doxygen version to use, use the `doxygen_extension` module extension below the `bazel_dep` rule in your MODULE.bazel file.
 
 ```bzl
-doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
-use_repo(doxygen_extension, "doxygen")
-```
+# MODULE.bazel file
 
-By default, version `1.12.0` of Doxygen is used. To select a different version, indicate it in the `version` module:
+bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
 
-```bzl
 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")
 ```
 
+By default, version `1.12.0` of Doxygen is used. To select a different version, indicate it in the `version` module:
+
 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.
 
@@ -52,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.
@@ -65,6 +99,7 @@ Only the sources are required, the rest of the parameters are optional.
 
 ```bzl
 # My BUILD.bazel file
+
 doxygen(
     name = "doxygen",   # Name of the rule, can be anything
     srcs = glob([       # List of sources to document.
@@ -73,12 +108,13 @@ doxygen(
     ]) + ["README.md"],
     project_brief = "Example project for doxygen",  # Brief description of the project
     project_name = "base",                          # Name of the project
-    configurations = [                              # Additional configurations to add to the Doxyfile
-        "GENERATE_HTML = YES",                      # They are the same as the Doxyfile options,
-        "GENERATE_LATEX = NO",                      # and will override the default values
+    configurations = [                              # Customizable configurations
+        "GENERATE_HTML = YES",                      # that override the default ones
+        "GENERATE_LATEX = NO",                      # from the Doxyfile
         "USE_MDFILE_AS_MAINPAGE = README.md",
     ]
-    tags = ["manual"]  # Tags to add to the target. This way the target won't run unless explicitly called
+    tags = ["manual"]  # Tags to add to the target.
+                       # This way the target won't run unless explicitly called
 )
 ```
 
@@ -100,6 +136,7 @@ For example, if the _BUILD.bazel_ file is in the root of the repository, and the
 
 ```bzl
 # BUILD.bazel file in the root of the repository
+
 doxygen(
     name = "doxygen",
     srcs = glob([
@@ -135,5 +172,4 @@ tar -czvf doxygen.tar.gz bazel-bin/<subpackage>/html
 
 ## TODO
 
-- [ ] Add support for macos other than the system-wide doxygen installation (I can't be bothered :D)
 - [ ] Add more easy-to-use common configuration for the Doxyfile

docs/BUILD.bazel

@@ -13,7 +13,7 @@ bzl_library(
 stardoc(
     name = "doxygen_doc",
     out = "doxygen_doc.md",
-    input = "@rules_doxygen//:doxygen.bzl",
+    input = "@rules_doxygen//doxygen:doxygen.bzl",
 )
 
 stardoc(

docs/doxygen_doc.md

@@ -7,6 +7,8 @@ Doxygen rule for Bazel.
 ## doxygen
 
 <pre>
+load("@doxygen//:doxygen.bzl", "doxygen")
+
 doxygen(<a href="#doxygen-name">name</a>, <a href="#doxygen-srcs">srcs</a>, <a href="#doxygen-project_name">project_name</a>, <a href="#doxygen-project_brief">project_brief</a>, <a href="#doxygen-project_number">project_number</a>, <a href="#doxygen-project_logo">project_logo</a>, <a href="#doxygen-project_icon">project_icon</a>,
         <a href="#doxygen-use_mdfile_as_mainpage">use_mdfile_as_mainpage</a>, <a href="#doxygen-extract_private">extract_private</a>, <a href="#doxygen-html_footer">html_footer</a>, <a href="#doxygen-html_header">html_header</a>, <a href="#doxygen-filter_patterns">filter_patterns</a>,
         <a href="#doxygen-use_mathjax">use_mathjax</a>, <a href="#doxygen-html_extra_stylesheet">html_extra_stylesheet</a>, <a href="#doxygen-html_extra_files">html_extra_files</a>, <a href="#doxygen-html_colorstyle">html_colorstyle</a>, <a href="#doxygen-aliases">aliases</a>, <a href="#doxygen-have_dot">have_dot</a>,