From e8ad2d457c0b1f4b46901ba376fe2081d0c82844 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 15:44:44 +0000 Subject: [PATCH 01/15] feat: add arm platform support --- README.md | 2 +- extensions.bzl | 61 ++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 48 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index f9d7b13..87285f2 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ use_repo(doxygen_extension, "doxygen") ``` By default, version `1.12.0` of Doxygen is used. -You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_ and _linux_. +You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_, _mac-arm_, _linux_ and _linux-arm_. ```bzl # MODULE.bazel file diff --git a/extensions.bzl b/extensions.bzl index 3622fd7..4e8e775 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -3,6 +3,37 @@ load("@bazel_tools//tools/build_defs/repo:cache.bzl", "get_default_canonical_id") load("@bazel_tools//tools/build_defs/repo:utils.bzl", "get_auth") +def _get_current_platform(ctx): + """ + Get the current platform. + + It uses the context to get the current platform and architecture and returns the platform name. + The string returned is one of the following: + + - windows + - mac + - mac-arm + - linux + - linux-arm + + Args: + ctx: a [repository context](https://bazel.build/rules/lib/builtins/repository_ctx) object + or a [module context](https://bazel.build/rules/lib/builtins/module_ctx) object + containing the repository's attributes + """ + + if ctx.os.name.startswith("windows"): + return "windows" + if ctx.os.name.startswith("mac") and (ctx.os.arch == "amd64" or ctx.os.arch == "i686"): + return "mac" + if ctx.os.name.startswith("mac") and ctx.os.arch == "arm64": + return "mac-arm" + if ctx.os.name == "linux" and (ctx.os.arch == "amd64" or ctx.os.arch == "i686"): + return "linux" + if ctx.os.name == "linux" and ctx.os.arch == "arm64": + return "linux-arm" + fail("Unsupported platform: %s (%s)" % (ctx.os.name, ctx.os.arch)) + def _doxygen_repository(ctx): """ Repository rule for doxygen. @@ -17,8 +48,8 @@ def _doxygen_repository(ctx): if len(ctx.attr.versions) != len(ctx.attr.sha256s) or len(ctx.attr.versions) != len(ctx.attr.platforms): fail("The number of versions, sha256s and platforms must be the same") for platform in ctx.attr.platforms: - if platform not in ("windows", "mac", "linux"): - fail("Unsupported platform: '%s'. Available options are (windows, mac, linux)" % platform) + if platform not in ("windows", "mac", "mac-arm", "linux", "linux-arm"): + fail("Unsupported platform: '%s'. Available options are (windows, mac, mac-arm, linux, linux-arm)" % platform) ctx.file("WORKSPACE", "workspace(name = %s)\n" % repr(ctx.name)) ctx.file("doxygen.bzl", ctx.read(ctx.attr.doxygen_bzl)) @@ -30,11 +61,11 @@ def _doxygen_repository(ctx): # No download will be performed # This happens only if the platform matches the current platform if doxygen_version == "0.0.0": - if platform == "windows" and ctx.os.name.startswith("windows"): + if platform == "windows" and _get_current_platform(ctx) == platform: ctx.file("windows/doxygen.exe", ctx.read(ctx.which("doxygen")), legacy_utf8 = False) - elif platform == "mac" and ctx.os.name.startswith("mac"): + elif platform in ("mac", "mac-arm") and _get_current_platform(ctx) == platform: ctx.file("mac/doxygen", ctx.read(ctx.which("doxygen")), legacy_utf8 = False) - elif platform == "linux" and ctx.os.name == "linux": + elif platform in ("linux", "linux-arm") and _get_current_platform(ctx) == platform: ctx.file("linux/doxygen", ctx.read(ctx.which("doxygen")), legacy_utf8 = False) continue @@ -42,7 +73,7 @@ def _doxygen_repository(ctx): doxygen_version_dash = doxygen_version.replace(".", "_") download_output = "doxygen-dir" - if platform == "windows" and ctx.os.name.startswith("windows"): + if platform == "windows" and _get_current_platform(ctx) == platform: # For windows, download the zip file and extract the executable and dll url = url % (doxygen_version_dash, doxygen_version, "windows.x64.bin.zip") ctx.download_and_extract( @@ -58,7 +89,7 @@ def _doxygen_repository(ctx): ctx.file("windows/doxygen.exe", ctx.read("doxygen-dir/doxygen.exe"), legacy_utf8 = False) ctx.file("windows/libclang.dll", ctx.read("doxygen-dir/libclang.dll"), legacy_utf8 = False) - elif platform == "mac" and ctx.os.name.startswith("mac"): + elif platform in ("mac", "mac-arm") and _get_current_platform(ctx) == platform: # For mac, download the dmg file, mount it and copy the executable url = url % (doxygen_version_dash, doxygen_version, "dmg") download_output = "doxygen.dmg" @@ -79,7 +110,7 @@ def _doxygen_repository(ctx): # Unmount the dmg file ctx.execute(["hdiutil", "detach", "doxygen-mount"]) - elif platform == "linux" and ctx.os.name == "linux": + elif platform in ("linux", "linux-arm") and _get_current_platform(ctx) == platform: # For linux, download the tar.gz file and extract the executable url = url % (doxygen_version_dash, doxygen_version, "linux.bin.tar.gz") ctx.download_and_extract( @@ -103,7 +134,7 @@ doxygen_repository = repository_rule( doc = """ 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. +It can be provided with a configuration for each of the three platforms (windows, mac, mac-arm, linux, linux-arm) 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. @@ -150,7 +181,7 @@ doxygen_repository( allow_empty = False, ), "platforms": attr.string_list( - doc = "List of platforms to download the doxygen binary for. Available options are (windows, mac, linux). Must be the same length as `version` and `sha256s`.", + doc = "List of platforms to download the doxygen binary for. Available options are (windows, mac, mac-arm, linux, linux-arm). Must be the same length as `version` and `sha256s`.", mandatory = True, allow_empty = False, ), @@ -188,14 +219,16 @@ def _doxygen_extension_impl(ctx): default_configurations = { "windows": struct(version = "1.12.0", sha256 = "07f1c92cbbb32816689c725539c0951f92c6371d3d7f66dfa3192cbe88dd3138"), "mac": struct(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001"), + "mac-arm": struct(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001"), "linux": struct(version = "1.12.0", sha256 = "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647"), + "linux-arm": struct(version = "1.12.0", sha256 = "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647"), } # Otherwise, add all the configurations (version and sha256) for each platform for attr in mod.tags.version: - platform = attr.platform if attr.platform != "" else "windows" if ctx.os.name.startswith("windows") else "mac" if ctx.os.name.startswith("mac") else "linux" + platform = attr.platform if attr.platform != "" else _get_current_platform(ctx) if platform not in default_configurations: - fail("Unsupported platform: '%s'. Available options are (windows, mac, linux)" % platform) + fail("Unsupported platform: '%s'. Available options are (windows, mac, mac-arm, linux, linux-arm)" % platform) if platform in platforms: fail("Doxygen version/sha256 for platform '%s' was already specified: (version = '%s', sha256 = '%s')" % (platform, versions[platforms.index(platform)], sha256s[platforms.index(platform)])) platforms.append(platform) @@ -219,7 +252,7 @@ def _doxygen_extension_impl(ctx): _doxygen_version = tag_class(attrs = { "version": attr.string(doc = "The version of doxygen to use. If set to `0.0.0`, the doxygen executable will be assumed to be available from the PATH", mandatory = True), "sha256": attr.string(doc = "The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used."), - "platform": attr.string(doc = "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."), + "platform": attr.string(doc = "The target platform for the doxygen binary. Available options are (windows, mac, mac-arm, linux, linux-arm). If not specified, it will select the platform it is currently running on."), }) doxygen_extension = module_extension( @@ -233,7 +266,7 @@ The resulting repository will have the following targets: - `@doxygen//:Doxyfile.template`, default Doxyfile template used to generate the Doxyfile. By default, version `1.12.0` of Doxygen is used. -You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_ and _linux_. +You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_, _mac-arm_, _linux_ and _linux-arm_. ```bzl # MODULE.bazel file From 21ed8c48d0a5b7f7938fb159dcb4b066574d7d7d Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 17:43:34 +0000 Subject: [PATCH 02/15] ref: rename version -> configuration, support executable --- .github/workflows/ci.yml | 69 ++++++++++++++++++++++++---- examples/BUILD.bazel | 1 + examples/MODULE.bazel | 11 +++-- extensions.bzl | 97 +++++++++++++++++++++++++--------------- 4 files changed, 129 insertions(+), 49 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a28cb65..975c3ef 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,6 +24,9 @@ jobs: with: files: "examples/bazel-bin/${{ matrix.subdir }}/html/index.html" fail: true + - name: Check doxygen version in produced index.html + run: grep 'Doxygen 1.12.0' examples/bazel-bin/${{ matrix.subdir }}/html/index.html + shell: bash tests-system-installation: strategy: @@ -36,11 +39,13 @@ jobs: - uses: actions/checkout@v4 - name: Install doxygen uses: ssciwr/doxygen-install@v1 + with: + version: "1.9.7" - name: Enable use of system doxygen by decommenting the module extension line uses: richardrigutins/replace-in-files@v2 with: - search-text: '# doxygen_extension.version(version = "0.0.0")' - replacement-text: doxygen_extension.version(version = "0.0.0") + search-text: '# doxygen_extension.configuration(version = "0.0.0")' + replacement-text: doxygen_extension.configuration(version = "0.0.0") files: examples/MODULE.bazel - name: Build ${{ matrix.subdir }} run: bazel build //${{ matrix.subdir }}:doxygen @@ -50,6 +55,9 @@ jobs: with: files: "examples/bazel-bin/${{ matrix.subdir }}/html/index.html" fail: true + - name: Check doxygen version in produced index.html + run: grep 'Doxygen 1.9.7' examples/bazel-bin/${{ matrix.subdir }}/html/index.html + shell: bash tests-multiple-installations: strategy: @@ -64,20 +72,62 @@ jobs: - 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") + search-text: '# doxygen_extension.configuration(version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows")' + replacement-text: doxygen_extension.configuration(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") + search-text: '# doxygen_extension.configuration(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", platform = "mac")' + replacement-text: doxygen_extension.configuration(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") + search-text: '# doxygen_extension.configuration(version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux")' + replacement-text: doxygen_extension.configuration(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 + - name: Check doxygen version in produced index.html (windows) + if: matrix.os == 'windows-latest' + run: grep 'Doxygen 1.11.0' examples/bazel-bin/${{ matrix.subdir }}/html/index.html + shell: bash + - name: Check doxygen version in produced index.html (mac) + if: matrix.os == 'macos-latest' + run: grep 'Doxygen 1.12.0' examples/bazel-bin/${{ matrix.subdir }}/html/index.html + shell: bash + - name: Check doxygen version in produced index.html (linux) + if: matrix.os == 'ubuntu-latest' + run: grep 'Doxygen 1.10.0' examples/bazel-bin/${{ matrix.subdir }}/html/index.html + shell: bash + + tests-local-executable: + strategy: + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + subdir: [base] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - name: Install doxygen + uses: ssciwr/doxygen-install@v1 + with: + version: "1.9.7" + - name: Move binary to examples folder + run: mv $(which doxygen) examples/doxygen + shell: bash + - name: Enable use of local doxygen by decommenting the module extension line + uses: richardrigutins/replace-in-files@v2 + with: + search-text: '# doxygen_extension.configuration(executable = "@@//:doxygen")' + replacement-text: doxygen_extension.configuration(executable = "@@//:doxygen") files: examples/MODULE.bazel - name: Build ${{ matrix.subdir }} run: bazel build //${{ matrix.subdir }}:doxygen @@ -87,3 +137,6 @@ jobs: with: files: "examples/bazel-bin/${{ matrix.subdir }}/html/index.html" fail: true + - name: Check doxygen version in produced index.html + run: grep 'Doxygen 1.9.7' examples/bazel-bin/${{ matrix.subdir }}/html/index.html + shell: bash diff --git a/examples/BUILD.bazel b/examples/BUILD.bazel index e69de29..3b912b5 100644 --- a/examples/BUILD.bazel +++ b/examples/BUILD.bazel @@ -0,0 +1 @@ +# exports_files(["doxygen"]) diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel index 33c4ad4..2a7545b 100644 --- a/examples/MODULE.bazel +++ b/examples/MODULE.bazel @@ -9,11 +9,14 @@ local_path_override( doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension") # doxygen_extension with a system installation of doxygen -# doxygen_extension.version(version = "0.0.0") +# doxygen_extension.configuration(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") +# doxygen_extension.configuration(version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux") +# doxygen_extension.configuration(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", platform = "mac") +# doxygen_extension.configuration(version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows") + +# doxygen_extension with a provided doxygen binary +# doxygen_extension.configuration(executable = "@@//:doxygen") use_repo(doxygen_extension, "doxygen") diff --git a/extensions.bzl b/extensions.bzl index 4e8e775..872a64b 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -45,8 +45,8 @@ def _doxygen_repository(ctx): """ # Copy the necessary files to the repository by reading them from the current repository - if len(ctx.attr.versions) != len(ctx.attr.sha256s) or len(ctx.attr.versions) != len(ctx.attr.platforms): - fail("The number of versions, sha256s and platforms must be the same") + if len(ctx.attr.versions) != len(ctx.attr.sha256s) or len(ctx.attr.versions) != len(ctx.attr.platforms) or len(ctx.attr.versions) != len(ctx.attr.executables): + fail("The number of versions, sha256s, platforms and executables must be the same") for platform in ctx.attr.platforms: if platform not in ("windows", "mac", "mac-arm", "linux", "linux-arm"): fail("Unsupported platform: '%s'. Available options are (windows, mac, mac-arm, linux, linux-arm)" % platform) @@ -56,24 +56,33 @@ def _doxygen_repository(ctx): ctx.file("BUILD.bazel", ctx.read(ctx.attr.build)) ctx.file("Doxyfile.template", ctx.read(ctx.attr.doxyfile_template)) - for doxygen_version, sha256, platform in zip(ctx.attr.versions, ctx.attr.sha256s, ctx.attr.platforms): + for doxygen_version, sha256, platform, executable in zip(ctx.attr.versions, ctx.attr.sha256s, ctx.attr.platforms, ctx.attr.executables): + if platform == "windows" and _get_current_platform(ctx) == platform: + executable_destination = "windows/doxygen.exe" + elif platform in ("mac", "mac-arm") and _get_current_platform(ctx) == platform: + executable_destination = "mac/doxygen" + elif platform in ("linux", "linux-arm") and _get_current_platform(ctx) == platform: + executable_destination = "linux/doxygen" + else: + continue # Skip the platform if it does not match the current platform. No operation will be performed + # If the version is set to 0.0.0 use the installed version of doxygen from the PATH # No download will be performed # This happens only if the platform matches the current platform if doxygen_version == "0.0.0": - if platform == "windows" and _get_current_platform(ctx) == platform: - ctx.file("windows/doxygen.exe", ctx.read(ctx.which("doxygen")), legacy_utf8 = False) - elif platform in ("mac", "mac-arm") and _get_current_platform(ctx) == platform: - ctx.file("mac/doxygen", ctx.read(ctx.which("doxygen")), legacy_utf8 = False) - elif platform in ("linux", "linux-arm") and _get_current_platform(ctx) == platform: - ctx.file("linux/doxygen", ctx.read(ctx.which("doxygen")), legacy_utf8 = False) + ctx.file(executable_destination, ctx.read(ctx.which("doxygen")), legacy_utf8 = False) + continue + + # If an executable is provided, use it instead of downloading the doxygen binary + if executable != "": + ctx.file(executable_destination, ctx.read(executable), legacy_utf8 = False) continue url = "https://github.com/doxygen/doxygen/releases/download/Release_%s/doxygen-%s.%s" doxygen_version_dash = doxygen_version.replace(".", "_") download_output = "doxygen-dir" - if platform == "windows" and _get_current_platform(ctx) == platform: + if platform == "windows": # For windows, download the zip file and extract the executable and dll url = url % (doxygen_version_dash, doxygen_version, "windows.x64.bin.zip") ctx.download_and_extract( @@ -86,10 +95,10 @@ def _doxygen_repository(ctx): ) # Copy the doxygen executable (and dll) to the repository - ctx.file("windows/doxygen.exe", ctx.read("doxygen-dir/doxygen.exe"), legacy_utf8 = False) + ctx.file(executable_destination, ctx.read("doxygen-dir/doxygen.exe"), legacy_utf8 = False) ctx.file("windows/libclang.dll", ctx.read("doxygen-dir/libclang.dll"), legacy_utf8 = False) - elif platform in ("mac", "mac-arm") and _get_current_platform(ctx) == platform: + elif platform in ("mac", "mac-arm"): # For mac, download the dmg file, mount it and copy the executable url = url % (doxygen_version_dash, doxygen_version, "dmg") download_output = "doxygen.dmg" @@ -105,12 +114,12 @@ def _doxygen_repository(ctx): ctx.execute(["hdiutil", "attach", "-nobrowse", "-readonly", "-mountpoint", "doxygen-mount", download_output]) # Copy the doxygen executable to the repository - ctx.file("mac/doxygen", ctx.read("doxygen-mount/Doxygen.app/Contents/Resources/doxygen"), legacy_utf8 = False) + ctx.file(executable_destination, ctx.read("doxygen-mount/Doxygen.app/Contents/Resources/doxygen"), legacy_utf8 = False) # Unmount the dmg file ctx.execute(["hdiutil", "detach", "doxygen-mount"]) - elif platform in ("linux", "linux-arm") and _get_current_platform(ctx) == platform: + elif platform in ("linux", "linux-arm"): # For linux, download the tar.gz file and extract the executable url = url % (doxygen_version_dash, doxygen_version, "linux.bin.tar.gz") ctx.download_and_extract( @@ -124,7 +133,7 @@ def _doxygen_repository(ctx): ) # Copy the doxygen executable to the repository - ctx.file("linux/doxygen", ctx.read("doxygen-dir/bin/doxygen"), legacy_utf8 = False) + ctx.file(executable_destination, ctx.read("doxygen-dir/bin/doxygen"), legacy_utf8 = False) # Delete temporary files ctx.delete(download_output) @@ -171,20 +180,25 @@ doxygen_repository( """, attrs = { "versions": attr.string_list( - doc = "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`.", + doc = "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`, `platforms` and `executables`.", mandatory = True, allow_empty = False, ), "sha256s": attr.string_list( - doc = "List of sha256 hashes of the doxygen archive. Must be the same length as `versions and `platforms`.", + doc = "List of sha256 hashes of the doxygen archive. Must be the same length as `versions, `platforms` and `executables`.", mandatory = True, allow_empty = False, ), "platforms": attr.string_list( - doc = "List of platforms to download the doxygen binary for. Available options are (windows, mac, mac-arm, linux, linux-arm). Must be the same length as `version` and `sha256s`.", + doc = "List of platforms to download the doxygen binary for. Available options are (windows, mac, mac-arm, linux, linux-arm). Must be the same length as `version`, `sha256s` and `executables`.", mandatory = True, allow_empty = False, ), + "executables": attr.string_list( + doc = "List of doxygen executables to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. Must be the same length as `version`, `sha256s` and `platforms`.", + allow_empty = False, + mandatory = True, + ), "doxygen_bzl": attr.label( doc = "The starlark file containing the doxygen macro", allow_single_file = True, @@ -215,25 +229,31 @@ def _doxygen_extension_impl(ctx): platforms = [] versions = [] sha256s = [] + executables = [] default_configurations = { - "windows": struct(version = "1.12.0", sha256 = "07f1c92cbbb32816689c725539c0951f92c6371d3d7f66dfa3192cbe88dd3138"), - "mac": struct(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001"), - "mac-arm": struct(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001"), - "linux": struct(version = "1.12.0", sha256 = "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647"), - "linux-arm": struct(version = "1.12.0", sha256 = "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647"), + "windows": struct(version = "1.12.0", sha256 = "07f1c92cbbb32816689c725539c0951f92c6371d3d7f66dfa3192cbe88dd3138", executable = ""), + "mac": struct(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", executable = ""), + "mac-arm": struct(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", executable = ""), + "linux": struct(version = "1.12.0", sha256 = "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647", executable = ""), + "linux-arm": struct(version = "1.12.0", sha256 = "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647", executable = ""), } # Otherwise, add all the configurations (version and sha256) for each platform - for attr in mod.tags.version: + for attr in mod.tags.configuration: platform = attr.platform if attr.platform != "" else _get_current_platform(ctx) + if attr.version != "" and attr.executable != "": + fail("`Version` and `executable` are mutually exclusive") + if attr.version == "" and attr.executable == "": + fail("Exactly one between `version` and `executable` must be specified") if platform not in default_configurations: fail("Unsupported platform: '%s'. Available options are (windows, mac, mac-arm, linux, linux-arm)" % platform) if platform in platforms: - fail("Doxygen version/sha256 for platform '%s' was already specified: (version = '%s', sha256 = '%s')" % (platform, versions[platforms.index(platform)], sha256s[platforms.index(platform)])) + fail("Doxygen configuration for platform '%s' was already specified: (version = '%s', sha256 = '%s', executable = %s)" % (platform, versions[platforms.index(platform)], sha256s[platforms.index(platform)], executables[platforms.index(platform)])) platforms.append(platform) - versions.append(attr.version if attr.version != "" else fail("Version must be specified")) + versions.append(attr.version) sha256s.append(attr.sha256 if attr.sha256 != "" else "0" * 64) + executables.append(str(ctx.path(Label(attr.executable)))) # If no version is specified for a platform, use the default for platform in default_configurations: @@ -241,25 +261,28 @@ def _doxygen_extension_impl(ctx): platforms.append(platform) versions.append(default_configurations[platform].version) sha256s.append(default_configurations[platform].sha256) + executables.append(default_configurations[platform].executable) doxygen_repository( name = "doxygen", versions = versions, sha256s = sha256s, platforms = platforms, + executables = executables, ) -_doxygen_version = tag_class(attrs = { - "version": attr.string(doc = "The version of doxygen to use. If set to `0.0.0`, the doxygen executable will be assumed to be available from the PATH", mandatory = True), +_doxygen_configuration = tag_class(attrs = { + "version": attr.string(doc = "The version of doxygen to use. If set to `0.0.0`, the doxygen executable will be assumed to be available from the PATH. Mutually exclusive with `executable`."), "sha256": attr.string(doc = "The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used."), "platform": attr.string(doc = "The target platform for the doxygen binary. Available options are (windows, mac, mac-arm, linux, linux-arm). If not specified, it will select the platform it is currently running on."), + "executable": attr.string(doc = "The doxygen executable to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`."), }) doxygen_extension = module_extension( implementation = _doxygen_extension_impl, - tag_classes = {"version": _doxygen_version}, + tag_classes = {"configuration": _doxygen_configuration}, doc = """ -Module extension for declaring the doxygen version to use. +Module extension for declaring the doxygen configurations to use. The resulting repository will have the following targets: - `@doxygen//:doxygen.bzl`, containing the doxygen macro used to generate the documentation. @@ -276,7 +299,7 @@ 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, default version on all other platforms -doxygen_extension.version( +doxygen_extension.configuration( version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", @@ -316,7 +339,7 @@ doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_ex # 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( +doxygen_extension.configuration( version = "1.10.0", sha256 = "2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b", ) @@ -331,17 +354,17 @@ bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True) doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension") -doxygen_extension.version( +doxygen_extension.configuration( version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", ) -doxygen_extension.version( +doxygen_extension.configuration( version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", platform = "mac", ) -doxygen_extension.version( +doxygen_extension.configuration( version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows", @@ -358,13 +381,13 @@ 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( +doxygen_extension.configuration( version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", ) # Use the local doxygen installation on mac -doxygen_extension.version( +doxygen_extension.configuration( version = "0.0.0", platform = "mac", ) From 688ee633f6fcfe782f25d29a9459fb361f98d18a Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 17:43:45 +0000 Subject: [PATCH 03/15] ci: update ci with tests --- .github/workflows/ci.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 975c3ef..5bddfe5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -129,6 +129,12 @@ jobs: search-text: '# doxygen_extension.configuration(executable = "@@//:doxygen")' replacement-text: doxygen_extension.configuration(executable = "@@//:doxygen") files: examples/MODULE.bazel + - name: Export doxygen binary + uses: richardrigutins/replace-in-files@v2 + with: + search-text: '# exports_files(["doxygen"])' + replacement-text: exports_files(["doxygen"]) + files: examples/BUILD.bazel - name: Build ${{ matrix.subdir }} run: bazel build //${{ matrix.subdir }}:doxygen working-directory: examples From 4ea8b2b92017636de844c9092eb243907651f3ba Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 19:50:27 +0000 Subject: [PATCH 04/15] docs: update documentation --- CHANGELOG.md | 7 ++++++- README.md | 26 ++++++++++++++++++++++---- extensions.bzl | 11 +++++++++++ 3 files changed, 39 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 23a8c6b..ace7659 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -69,7 +69,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 hermetic build for `mac` platform (thanks to @kaycebasques) - Support for platform-specific configurations in the extension rule ### Changed @@ -80,6 +80,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [NEXT.VERSION] +### Added + +- Platform `mac-silicon` to support the Apple silicon macs +- Allow executable configuration in the `doxygen` extension rule + [1.0.0]: https://github.com/TendTo/rules_doxygen/tree/1.0.0 [1.1.0]: https://github.com/TendTo/rules_doxygen/compare/1.0.0...1.1.0 [1.1.1]: https://github.com/TendTo/rules_doxygen/compare/1.1.0...1.1.1 diff --git a/README.md b/README.md index 87285f2..88cec6b 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ 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, default version on all other platforms -doxygen_extension.version( +doxygen_extension.configuration( version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", @@ -71,6 +71,8 @@ The build will fail with an error message containing the correct SHA256. Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.windows.x64.bin.zip failed: class com.google.devtools.build.lib.bazel.repository.downloader.UnrecoverableHttpException Checksum was 2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b but wanted 0000000000000000000000000000000000000000000000000000000000000000 ``` +#### System-wide doxygen installation + 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. @@ -82,6 +84,17 @@ No download will be performed and bazel will use the installed version of doxyge > 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. +#### Using a local doxygen executable + +You can also provide a label to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. +No download will be performed, and the file indicated by the label will be used as the doxygen executable. + +> [!Note] +> `version` and `executable` are mutually exclusive. +> You must provide exactly one of them. + +#### Example + Different strategies can be combined in the same file, one for each platform, as shown below: ```bzl @@ -92,17 +105,22 @@ 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( +doxygen_extension.configuration( version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", ) # Use the local doxygen installation on mac -doxygen_extension.version( +doxygen_extension.configuration( version = "0.0.0", platform = "mac", ) -# Since no configuration has been provided, windows will fallback to the default version +# Use the doxygen provided executable on mac-arm +doxygen_extension.configuration( + executable = "@@//path/to/doxygen:doxygen", + platform = "mac-arm", +) +# Since no configuration has been provided, all other platforms will fallback to the default version use_repo(doxygen_extension, "doxygen") ``` diff --git a/extensions.bzl b/extensions.bzl index 872a64b..f0c3bc9 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -316,6 +316,8 @@ The build will fail with an error message containing the correct SHA256. Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.windows.x64.bin.zip failed: class com.google.devtools.build.lib.bazel.repository.downloader.UnrecoverableHttpException Checksum was 2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b but wanted 0000000000000000000000000000000000000000000000000000000000000000 ``` +#### System-wide doxygen installation + 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. @@ -327,6 +329,15 @@ No download will be performed and bazel will use the installed version of doxyge > 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. +#### Using a local doxygen executable + +You can also provide a label to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. +No download will be performed, and the file indicated by the label will be used as the doxygen executable. + +> [!Note] +> `version` and `executable` are mutually exclusive. +> You must provide exactly one of them. + ### Examples ```starlark From 367f6d44fba7d9a0e54a7a8f8cc6b4c8a56598f2 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 19:58:28 +0000 Subject: [PATCH 05/15] fix: correct arch and missing extension --- extensions.bzl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/extensions.bzl b/extensions.bzl index f0c3bc9..6b49424 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -26,11 +26,11 @@ def _get_current_platform(ctx): return "windows" if ctx.os.name.startswith("mac") and (ctx.os.arch == "amd64" or ctx.os.arch == "i686"): return "mac" - if ctx.os.name.startswith("mac") and ctx.os.arch == "arm64": + if ctx.os.name.startswith("mac") and ctx.os.arch == "aarch64": return "mac-arm" if ctx.os.name == "linux" and (ctx.os.arch == "amd64" or ctx.os.arch == "i686"): return "linux" - if ctx.os.name == "linux" and ctx.os.arch == "arm64": + if ctx.os.name == "linux" and ctx.os.arch == "aarch64": return "linux-arm" fail("Unsupported platform: %s (%s)" % (ctx.os.name, ctx.os.arch)) @@ -253,7 +253,7 @@ def _doxygen_extension_impl(ctx): platforms.append(platform) versions.append(attr.version) sha256s.append(attr.sha256 if attr.sha256 != "" else "0" * 64) - executables.append(str(ctx.path(Label(attr.executable)))) + executables.append(str(ctx.path(Label(attr.executable))) if attr.executable != "" else "") # If no version is specified for a platform, use the default for platform in default_configurations: From 5f400df4111c54caa8413544ad0b8c4d60c0a596 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 19:59:36 +0000 Subject: [PATCH 06/15] fix: use cp instead of mv --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5bddfe5..d21934d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -121,7 +121,7 @@ jobs: with: version: "1.9.7" - name: Move binary to examples folder - run: mv $(which doxygen) examples/doxygen + run: cp $(which doxygen) examples/doxygen shell: bash - name: Enable use of local doxygen by decommenting the module extension line uses: richardrigutins/replace-in-files@v2 From d4d0548aeb3a74715affaab8d9c025a591aba1eb Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 20:12:02 +0000 Subject: [PATCH 07/15] ci: use different steps for windows and other platforms --- .github/workflows/ci.yml | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d21934d..3b873f7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -119,22 +119,45 @@ jobs: - name: Install doxygen uses: ssciwr/doxygen-install@v1 with: - version: "1.9.7" - - name: Move binary to examples folder + version: "1.10.0" + + - name: Copy binary to examples folder (windows) + if: matrix.os == 'windows-latest' + run: cp $(Get-Command doxygen).Source examples/doxygen.exe + - name: Copy binary to examples folder (mac, linux) + if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' run: cp $(which doxygen) examples/doxygen - shell: bash - - name: Enable use of local doxygen by decommenting the module extension line + + - name: Enable use of local doxygen by decommenting the module extension line (windows) uses: richardrigutins/replace-in-files@v2 + if: matrix.os == 'windows-latest' + with: + search-text: '# doxygen_extension.configuration(executable = "@@//:doxygen")' + replacement-text: doxygen_extension.configuration(executable = "@@//:doxygen.exe") + files: examples/MODULE.bazel + - name: Export doxygen binary (windows) + uses: richardrigutins/replace-in-files@v2 + if: matrix.os == 'windows-latest' + with: + search-text: '# exports_files(["doxygen"])' + replacement-text: exports_files(["doxygen.exe"]) + files: examples/BUILD.bazel + + - name: Enable use of local doxygen by decommenting the module extension line (mac, linux) + uses: richardrigutins/replace-in-files@v2 + if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' with: search-text: '# doxygen_extension.configuration(executable = "@@//:doxygen")' replacement-text: doxygen_extension.configuration(executable = "@@//:doxygen") files: examples/MODULE.bazel - - name: Export doxygen binary + - name: Export doxygen binary (mac, linux) uses: richardrigutins/replace-in-files@v2 + if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' with: search-text: '# exports_files(["doxygen"])' replacement-text: exports_files(["doxygen"]) files: examples/BUILD.bazel + - name: Build ${{ matrix.subdir }} run: bazel build //${{ matrix.subdir }}:doxygen working-directory: examples @@ -144,5 +167,5 @@ jobs: files: "examples/bazel-bin/${{ matrix.subdir }}/html/index.html" fail: true - name: Check doxygen version in produced index.html - run: grep 'Doxygen 1.9.7' examples/bazel-bin/${{ matrix.subdir }}/html/index.html + run: grep 'Doxygen 1.10.0' examples/bazel-bin/${{ matrix.subdir }}/html/index.html shell: bash From 9636222e8f2cdc6ffa23c38f6b42bb7fd3ac9e26 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 20:25:55 +0000 Subject: [PATCH 08/15] bump: version 2.0.0 --- .github/workflows/ci.yml | 2 +- CHANGELOG.md | 11 +++++- MODULE.bazel | 2 +- README.md | 6 +-- docs/extensions_doc.md | 84 +++++++++++++++++++++++++++------------- extensions.bzl | 29 +++++++++++--- 6 files changed, 94 insertions(+), 40 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3b873f7..989b387 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -112,7 +112,7 @@ jobs: strategy: matrix: os: [ubuntu-latest, windows-latest, macos-latest] - subdir: [base] + subdir: [base, kwargs, doxyfile, latex, nested, custom, awesome] runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v4 diff --git a/CHANGELOG.md b/CHANGELOG.md index ace7659..c73b377 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -78,13 +78,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Refactor of internal repository and extension rules - Updated documentation -## [NEXT.VERSION] +## [2.0.0] ### Added - Platform `mac-silicon` to support the Apple silicon macs - Allow executable configuration in the `doxygen` extension rule +### Changed + +- Module extension tag renamed from `version` to `configuration` **BREAKING CHANGE** + +## [NEXT.VERSION] + [1.0.0]: https://github.com/TendTo/rules_doxygen/tree/1.0.0 [1.1.0]: https://github.com/TendTo/rules_doxygen/compare/1.0.0...1.1.0 [1.1.1]: https://github.com/TendTo/rules_doxygen/compare/1.1.0...1.1.1 @@ -92,4 +98,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 [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 [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 +[2.0.0]: https://github.com/TendTo/rules_doxygen/compare/1.3.0...2.0.0 +[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/2.0.0...HEAD diff --git a/MODULE.bazel b/MODULE.bazel index a49350f..51749af 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -1,5 +1,5 @@ """rules_doxygen module""" -module(name = "rules_doxygen", version = "1.3.0", compatibility_level = 1) +module(name = "rules_doxygen", version = "2.0.0", compatibility_level = 2) bazel_dep(name = "platforms", version = "0.0.10") bazel_dep(name = "stardoc", version = "0.7.1", dev_dependency = True) diff --git a/README.md b/README.md index 88cec6b..832231e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Doxygen rules for Bazel -[![Bazel Central Repository](https://img.shields.io/badge/BCR-1.3.0-%230C713A?logo=bazel)](https://registry.bazel.build/modules/rules_doxygen) +[![Bazel Central Repository](https://img.shields.io/badge/BCR-2.0.0-%230C713A?logo=bazel)](https://registry.bazel.build/modules/rules_doxygen) [![CI](https://github.com/TendTo/rules_doxygen/actions/workflows/ci.yml/badge.svg)](https://github.com/TendTo/rules_doxygen/actions/workflows/ci.yml) This repository contains a [Starlark](https://github.com/bazelbuild/starlark) implementation of [Doxygen](https://www.doxygen.nl/) rules in [Bazel](https://bazel.build/). @@ -12,7 +12,7 @@ Add the following to your _MODULE.bazel_: ```bzl # MODULE.bazel file -bazel_dep(name = "rules_doxygen", version = "1.3.0", dev_dependency = True) +bazel_dep(name = "rules_doxygen", version = "2.0.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: @@ -20,7 +20,7 @@ If you don't want to depend on the [Bazel package registry](https://bazel.build/ ```bzl # MODULE.bazel file -bazel_dep(name = "rules_doxygen", version = "1.3.0", dev_dependency = True) +bazel_dep(name = "rules_doxygen", version = "2.0.0", dev_dependency = True) archive_override( module_name = "rules_doxygen", urls = "https://github.com/TendTo/rules_doxygen/archive/refs/heads/main.tar.gz", diff --git a/docs/extensions_doc.md b/docs/extensions_doc.md index f4077b9..463a821 100755 --- a/docs/extensions_doc.md +++ b/docs/extensions_doc.md @@ -9,13 +9,13 @@ Repository rule for downloading the correct version of doxygen using module exte 
 load("@rules_doxygen//:extensions.bzl", "doxygen_repository")
 
-doxygen_repository(name, build, doxyfile_template, doxygen_bzl, platforms, repo_mapping, sha256s,
-                   versions)
+doxygen_repository(name, build, doxyfile_template, doxygen_bzl, executables, platforms,
+                   repo_mapping, sha256s, versions)
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. +It can be provided with a configuration for each of the three platforms (windows, mac, mac-arm, linux, linux-arm) 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. @@ -29,7 +29,7 @@ You can further customize the repository by specifying the `doxygen_bzl`, `build ### Example ```starlark -# Download the os specific version 1.12.0 of doxygen supporting all platforms +# Download the os specific version 1.12.0 of doxygen supporting all the indicated platforms doxygen_repository( name = "doxygen", versions = ["1.12.0", "1.12.0", "1.12.0"], @@ -39,14 +39,16 @@ doxygen_repository( "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647", ] platforms = ["windows", "mac", "linux"], + executables = ["", "", ""], ) -# Use the system installed version of doxygen on linux and download version 1.11.0 for windows. No support for mac +# Use the system installed version of doxygen on linux and download version 1.11.0 for windows. Use the provided executable on mac-arm doxygen_repository( name = "doxygen", - version = ["0.0.0", "1.11.0"], - sha256s = ["", "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f"], - platforms = ["linux", "windows"], + version = ["0.0.0", "1.11.0", ""], + sha256s = ["", "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", ""], + platforms = ["linux", "windows", "mac-arm"], + executables = ["", "", "/path/to/doxygen"], ) ``` @@ -59,10 +61,11 @@ doxygen_repository( | build | The BUILD file of the repository | Label | optional | `"@rules_doxygen//doxygen:BUILD.bazel"` | | doxyfile_template | The Doxyfile template to use | Label | optional | `"@rules_doxygen//doxygen:Doxyfile.template"` | | doxygen_bzl | The starlark file containing the doxygen macro | Label | optional | `"@rules_doxygen//doxygen:doxygen.bzl"` | -| 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 | | +| executables | List of doxygen executables to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. Must be the same length as `version`, `sha256s` and `platforms`. | List of strings | required | | +| platforms | List of platforms to download the doxygen binary for. Available options are (windows, mac, mac-arm, linux, linux-arm). Must be the same length as `version`, `sha256s` and `executables`. | List of strings | required | | | 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.

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`).

This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> String | optional | | -| sha256s | List of sha256 hashes of the doxygen archive. Must be the same length as `versions and `platforms`. | List of strings | required | | -| 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 | | +| sha256s | List of sha256 hashes of the doxygen archive. Must be the same length as `versions, `platforms` and `executables`. | List of strings | required | | +| 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`, `platforms` and `executables`. | List of strings | required | | @@ -71,17 +74,17 @@ doxygen_repository( 
 doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
-doxygen_extension.version(platform, sha256, version)
+doxygen_extension.configuration(executable, platform, sha256, version)
-Module extension for declaring the doxygen version to use. +Module extension for declaring the doxygen configurations to use. The resulting repository will have the following targets: - `@doxygen//:doxygen.bzl`, containing the doxygen macro used to generate the documentation. - `@doxygen//:Doxyfile.template`, default Doxyfile template used to generate the Doxyfile. By default, version `1.12.0` of Doxygen is used. -You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_ and _linux_. +You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_, _mac-arm_, _linux_ and _linux-arm_. ```bzl # MODULE.bazel file @@ -91,7 +94,7 @@ 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, default version on all other platforms -doxygen_extension.version( +doxygen_extension.configuration( version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", @@ -108,6 +111,8 @@ The build will fail with an error message containing the correct SHA256. Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.windows.x64.bin.zip failed: class com.google.devtools.build.lib.bazel.repository.downloader.UnrecoverableHttpException Checksum was 2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b but wanted 0000000000000000000000000000000000000000000000000000000000000000 ``` +#### System-wide doxygen installation + 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. @@ -119,6 +124,15 @@ No download will be performed and bazel will use the installed version of doxyge > 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. +#### Using a local doxygen executable + +You can also provide a label to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. +No download will be performed, and the file indicated by the label will be used as the doxygen executable. + +> [!Note] +> `version` and `executable` are mutually exclusive. +> You must provide exactly one of them. + ### Examples ```starlark @@ -131,7 +145,7 @@ doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_ex # 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( +doxygen_extension.configuration( version = "1.10.0", sha256 = "2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b", ) @@ -146,17 +160,27 @@ bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True) doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension") -doxygen_extension.version( +doxygen_extension.configuration( version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", ) -doxygen_extension.version( +doxygen_extension.configuration( + version = "1.10.0", + sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", + platform = "linux-arm", +) +doxygen_extension.configuration( version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", platform = "mac", ) -doxygen_extension.version( +doxygen_extension.configuration( + version = "1.12.0", + sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", + platform = "mac-arm", +) +doxygen_extension.configuration( version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows", @@ -173,17 +197,22 @@ 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( +doxygen_extension.configuration( version = "1.10.0", sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", ) # Use the local doxygen installation on mac -doxygen_extension.version( +doxygen_extension.configuration( version = "0.0.0", platform = "mac", ) -# Since no configuration has been provided, windows will fallback to the default version +# Use the doxygen provided executable on mac-arm +doxygen_extension.configuration( + executable = "@@//path/to/doxygen:doxygen", + platform = "mac-arm", +) +# Since no configuration has been provided, all other platforms will fallback to the default version use_repo(doxygen_extension, "doxygen") ``` @@ -191,16 +220,17 @@ use_repo(doxygen_extension, "doxygen") **TAG CLASSES** - + -### version +### configuration **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| 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 | `""` | -| sha256 | The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used. | String | optional | `""` | -| 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 | | +| executable | The doxygen executable to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. | String | optional | `""` | +| platform | The target platform for the doxygen binary. Available options are (windows, mac, mac-arm, linux, linux-arm). If not specified, it will select the platform it is currently running on. | String | optional | `""` | +| sha256 | The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used. | String | optional | `""` | +| 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. Mutually exclusive with `executable`. | String | optional | `""` | diff --git a/extensions.bzl b/extensions.bzl index 6b49424..b7efe9e 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -157,7 +157,7 @@ You can further customize the repository by specifying the `doxygen_bzl`, `build ### Example ```starlark -# Download the os specific version 1.12.0 of doxygen supporting all platforms +# Download the os specific version 1.12.0 of doxygen supporting all the indicated platforms doxygen_repository( name = "doxygen", versions = ["1.12.0", "1.12.0", "1.12.0"], @@ -167,14 +167,16 @@ doxygen_repository( "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647", ] platforms = ["windows", "mac", "linux"], + executables = ["", "", ""], ) -# Use the system installed version of doxygen on linux and download version 1.11.0 for windows. No support for mac +# Use the system installed version of doxygen on linux and download version 1.11.0 for windows. Use the provided executable on mac-arm doxygen_repository( name = "doxygen", - version = ["0.0.0", "1.11.0"], - sha256s = ["", "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f"], - platforms = ["linux", "windows"], + version = ["0.0.0", "1.11.0", ""], + sha256s = ["", "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", ""], + platforms = ["linux", "windows", "mac-arm"], + executables = ["", "", "/path/to/doxygen"], ) ``` """, @@ -370,11 +372,21 @@ doxygen_extension.configuration( sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", platform = "linux", ) +doxygen_extension.configuration( + version = "1.10.0", + sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747", + platform = "linux-arm", +) doxygen_extension.configuration( version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", platform = "mac", ) +doxygen_extension.configuration( + version = "1.12.0", + sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", + platform = "mac-arm", +) doxygen_extension.configuration( version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", @@ -402,7 +414,12 @@ doxygen_extension.configuration( version = "0.0.0", platform = "mac", ) -# Since no configuration has been provided, windows will fallback to the default version +# Use the doxygen provided executable on mac-arm +doxygen_extension.configuration( + executable = "@@//path/to/doxygen:doxygen", + platform = "mac-arm", +) +# Since no configuration has been provided, all other platforms will fallback to the default version use_repo(doxygen_extension, "doxygen") ``` From b8758dd1f8d54b6024e05c181b0a6f35d57e91e6 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Sun, 24 Nov 2024 20:27:10 +0000 Subject: [PATCH 09/15] ci: speed up action by removing some examples --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 989b387..7c66806 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,7 +63,7 @@ jobs: strategy: matrix: os: [ubuntu-latest, windows-latest, macos-latest] - subdir: [base, kwargs, doxyfile, latex, nested, custom, awesome] + subdir: [base] runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v4 @@ -112,7 +112,7 @@ jobs: strategy: matrix: os: [ubuntu-latest, windows-latest, macos-latest] - subdir: [base, kwargs, doxyfile, latex, nested, custom, awesome] + subdir: [base] runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v4 From ea2a19cbc28f93b15f0af724d258ceaf205c1f54 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca <65033249+TendTo@users.noreply.github.com> Date: Tue, 26 Nov 2024 22:52:35 +0000 Subject: [PATCH 10/15] fix: review from @kaycebasques Co-authored-by: Kayce Basques --- CHANGELOG.md | 2 +- extensions.bzl | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c73b377..1559faf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -69,7 +69,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Support hermetic build for `mac` platform (thanks to @kaycebasques) +- Support hermetic build for `mac` platform (thanks to @kaycebasques, @wyverald, @tpudlik, @rickeylev) - Support for platform-specific configurations in the extension rule ### Changed diff --git a/extensions.bzl b/extensions.bzl index b7efe9e..1a4d6c2 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -255,7 +255,7 @@ def _doxygen_extension_impl(ctx): platforms.append(platform) versions.append(attr.version) sha256s.append(attr.sha256 if attr.sha256 != "" else "0" * 64) - executables.append(str(ctx.path(Label(attr.executable))) if attr.executable != "" else "") + executables.append(str(ctx.path(attr.executable)) if attr.executable != "" else "") # If no version is specified for a platform, use the default for platform in default_configurations: @@ -277,7 +277,7 @@ _doxygen_configuration = tag_class(attrs = { "version": attr.string(doc = "The version of doxygen to use. If set to `0.0.0`, the doxygen executable will be assumed to be available from the PATH. Mutually exclusive with `executable`."), "sha256": attr.string(doc = "The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used."), "platform": attr.string(doc = "The target platform for the doxygen binary. Available options are (windows, mac, mac-arm, linux, linux-arm). If not specified, it will select the platform it is currently running on."), - "executable": attr.string(doc = "The doxygen executable to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`."), + "executable": attr.label(doc = "The doxygen executable to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`."), }) doxygen_extension = module_extension( From 36b46d2081cbf037ae43ac0287ad25d27199834e Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Tue, 26 Nov 2024 23:57:38 +0000 Subject: [PATCH 11/15] fix: correctly check None for labels --- .github/workflows/ci.yml | 8 ++++---- README.md | 2 +- docs/extensions_doc.md | 4 ++-- examples/MODULE.bazel | 2 +- extensions.bzl | 11 ++++++----- 5 files changed, 14 insertions(+), 13 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7c66806..350a9f4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -132,8 +132,8 @@ jobs: uses: richardrigutins/replace-in-files@v2 if: matrix.os == 'windows-latest' with: - search-text: '# doxygen_extension.configuration(executable = "@@//:doxygen")' - replacement-text: doxygen_extension.configuration(executable = "@@//:doxygen.exe") + search-text: '# doxygen_extension.configuration(executable = "@//:doxygen")' + replacement-text: doxygen_extension.configuration(executable = "@//:doxygen.exe") files: examples/MODULE.bazel - name: Export doxygen binary (windows) uses: richardrigutins/replace-in-files@v2 @@ -147,8 +147,8 @@ jobs: uses: richardrigutins/replace-in-files@v2 if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' with: - search-text: '# doxygen_extension.configuration(executable = "@@//:doxygen")' - replacement-text: doxygen_extension.configuration(executable = "@@//:doxygen") + search-text: '# doxygen_extension.configuration(executable = "@//:doxygen")' + replacement-text: doxygen_extension.configuration(executable = "@//:doxygen") files: examples/MODULE.bazel - name: Export doxygen binary (mac, linux) uses: richardrigutins/replace-in-files@v2 diff --git a/README.md b/README.md index 832231e..22f88aa 100644 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ doxygen_extension.configuration( ) # Use the doxygen provided executable on mac-arm doxygen_extension.configuration( - executable = "@@//path/to/doxygen:doxygen", + executable = "@my_module//path/to/doxygen:doxygen", platform = "mac-arm", ) # Since no configuration has been provided, all other platforms will fallback to the default version diff --git a/docs/extensions_doc.md b/docs/extensions_doc.md index 463a821..5b12838 100755 --- a/docs/extensions_doc.md +++ b/docs/extensions_doc.md @@ -61,7 +61,7 @@ doxygen_repository( | build | The BUILD file of the repository | Label | optional | `"@rules_doxygen//doxygen:BUILD.bazel"` | | doxyfile_template | The Doxyfile template to use | Label | optional | `"@rules_doxygen//doxygen:Doxyfile.template"` | | doxygen_bzl | The starlark file containing the doxygen macro | Label | optional | `"@rules_doxygen//doxygen:doxygen.bzl"` | -| executables | List of doxygen executables to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. Must be the same length as `version`, `sha256s` and `platforms`. | List of strings | required | | +| executables | List of paths to doxygen executables to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. Must be the same length as `version`, `sha256s` and `platforms`. | List of strings | required | | | platforms | List of platforms to download the doxygen binary for. Available options are (windows, mac, mac-arm, linux, linux-arm). Must be the same length as `version`, `sha256s` and `executables`. | List of strings | required | | | 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.

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`).

This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> String | optional | | | sha256s | List of sha256 hashes of the doxygen archive. Must be the same length as `versions, `platforms` and `executables`. | List of strings | required | | @@ -209,7 +209,7 @@ doxygen_extension.configuration( ) # Use the doxygen provided executable on mac-arm doxygen_extension.configuration( - executable = "@@//path/to/doxygen:doxygen", + executable = "@my_module//path/to/doxygen:doxygen", platform = "mac-arm", ) # Since no configuration has been provided, all other platforms will fallback to the default version diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel index 2a7545b..abe78bf 100644 --- a/examples/MODULE.bazel +++ b/examples/MODULE.bazel @@ -17,6 +17,6 @@ doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_ex # doxygen_extension.configuration(version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows") # doxygen_extension with a provided doxygen binary -# doxygen_extension.configuration(executable = "@@//:doxygen") +doxygen_extension.configuration(executable = "@//:doxygen") use_repo(doxygen_extension, "doxygen") diff --git a/extensions.bzl b/extensions.bzl index 1a4d6c2..e2eaa2d 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -197,7 +197,7 @@ doxygen_repository( allow_empty = False, ), "executables": attr.string_list( - doc = "List of doxygen executables to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. Must be the same length as `version`, `sha256s` and `platforms`.", + doc = "List of paths to doxygen executables to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. Must be the same length as `version`, `sha256s` and `platforms`.", allow_empty = False, mandatory = True, ), @@ -244,9 +244,10 @@ def _doxygen_extension_impl(ctx): # Otherwise, add all the configurations (version and sha256) for each platform for attr in mod.tags.configuration: platform = attr.platform if attr.platform != "" else _get_current_platform(ctx) - if attr.version != "" and attr.executable != "": + if attr.version != "" and attr.executable != None: + print(attr.version, attr.executable) fail("`Version` and `executable` are mutually exclusive") - if attr.version == "" and attr.executable == "": + if attr.version == "" and attr.executable != None: fail("Exactly one between `version` and `executable` must be specified") if platform not in default_configurations: fail("Unsupported platform: '%s'. Available options are (windows, mac, mac-arm, linux, linux-arm)" % platform) @@ -255,7 +256,7 @@ def _doxygen_extension_impl(ctx): platforms.append(platform) versions.append(attr.version) sha256s.append(attr.sha256 if attr.sha256 != "" else "0" * 64) - executables.append(str(ctx.path(attr.executable)) if attr.executable != "" else "") + executables.append(str(ctx.path(attr.executable)) if attr.executable != None else "") # If no version is specified for a platform, use the default for platform in default_configurations: @@ -416,7 +417,7 @@ doxygen_extension.configuration( ) # Use the doxygen provided executable on mac-arm doxygen_extension.configuration( - executable = "@@//path/to/doxygen:doxygen", + executable = "@my_module//path/to/doxygen:doxygen", platform = "mac-arm", ) # Since no configuration has been provided, all other platforms will fallback to the default version From 4fe30cc55d1eba4d98a99e0478149b8f2c0ba590 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Wed, 27 Nov 2024 00:10:48 +0000 Subject: [PATCH 12/15] fix: inverted condition --- examples/MODULE.bazel | 2 +- extensions.bzl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel index abe78bf..306ed06 100644 --- a/examples/MODULE.bazel +++ b/examples/MODULE.bazel @@ -17,6 +17,6 @@ doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_ex # doxygen_extension.configuration(version = "1.11.0", sha256 = "478fc9897d00ca181835d248a4d3e5c83c26a32d1c7571f4321ddb0f2e97459f", platform = "windows") # doxygen_extension with a provided doxygen binary -doxygen_extension.configuration(executable = "@//:doxygen") +# doxygen_extension.configuration(executable = "@//:doxygen") use_repo(doxygen_extension, "doxygen") diff --git a/extensions.bzl b/extensions.bzl index e2eaa2d..d137e3a 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -247,7 +247,7 @@ def _doxygen_extension_impl(ctx): if attr.version != "" and attr.executable != None: print(attr.version, attr.executable) fail("`Version` and `executable` are mutually exclusive") - if attr.version == "" and attr.executable != None: + if attr.version == "" and attr.executable == None: fail("Exactly one between `version` and `executable` must be specified") if platform not in default_configurations: fail("Unsupported platform: '%s'. Available options are (windows, mac, mac-arm, linux, linux-arm)" % platform) From 2c9e717a1e8a6d4b8fb175fb576e37b43ba64e99 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Wed, 27 Nov 2024 10:09:41 +0000 Subject: [PATCH 13/15] fix: transfer label to repository rule instead of path --- extensions.bzl | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/extensions.bzl b/extensions.bzl index d137e3a..bb1af03 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -75,7 +75,7 @@ def _doxygen_repository(ctx): # If an executable is provided, use it instead of downloading the doxygen binary if executable != "": - ctx.file(executable_destination, ctx.read(executable), legacy_utf8 = False) + ctx.file(executable_destination, ctx.read(Label(executable)), legacy_utf8 = False) continue url = "https://github.com/doxygen/doxygen/releases/download/Release_%s/doxygen-%s.%s" @@ -245,7 +245,6 @@ def _doxygen_extension_impl(ctx): for attr in mod.tags.configuration: platform = attr.platform if attr.platform != "" else _get_current_platform(ctx) if attr.version != "" and attr.executable != None: - print(attr.version, attr.executable) fail("`Version` and `executable` are mutually exclusive") if attr.version == "" and attr.executable == None: fail("Exactly one between `version` and `executable` must be specified") @@ -256,7 +255,7 @@ def _doxygen_extension_impl(ctx): platforms.append(platform) versions.append(attr.version) sha256s.append(attr.sha256 if attr.sha256 != "" else "0" * 64) - executables.append(str(ctx.path(attr.executable)) if attr.executable != None else "") + executables.append(str(attr.executable) if attr.executable != None else "") # If no version is specified for a platform, use the default for platform in default_configurations: From aacc1c856c350a89a0fa9c43b9318a248d5f1781 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Wed, 27 Nov 2024 17:17:18 +0000 Subject: [PATCH 14/15] fix: add missing x86_64 architecture --- extensions.bzl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions.bzl b/extensions.bzl index bb1af03..ff53551 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -24,11 +24,11 @@ def _get_current_platform(ctx): if ctx.os.name.startswith("windows"): return "windows" - if ctx.os.name.startswith("mac") and (ctx.os.arch == "amd64" or ctx.os.arch == "i686"): + if ctx.os.name.startswith("mac") and (ctx.os.arch == "amd64" or ctx.os.arch == "i686" or ctx.os.arch == "x86_64"): return "mac" if ctx.os.name.startswith("mac") and ctx.os.arch == "aarch64": return "mac-arm" - if ctx.os.name == "linux" and (ctx.os.arch == "amd64" or ctx.os.arch == "i686"): + if ctx.os.name == "linux" and (ctx.os.arch == "amd64" or ctx.os.arch == "i686" or ctx.os.arch == "x86_64"): return "linux" if ctx.os.name == "linux" and ctx.os.arch == "aarch64": return "linux-arm" From f45c72b9658ed310ed7ecdaf1af4bcd057eb69c3 Mon Sep 17 00:00:00 2001 From: Ernesto Casablanca Date: Wed, 27 Nov 2024 17:48:01 +0000 Subject: [PATCH 15/15] docs: update documentation --- CHANGELOG.md | 5 +++-- README.md | 31 +++++++++++++++---------------- docs/extensions_doc.md | 23 ++++++++++++----------- extensions.bzl | 21 +++++++++++---------- 4 files changed, 41 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1559faf..393b7dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -82,12 +82,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Platform `mac-silicon` to support the Apple silicon macs -- Allow executable configuration in the `doxygen` extension rule +- Platform `mac-silicon` to support the Apple silicon macs (thanks to @kaycebasques, @wyverald, @tpudlik, @rickeylev) +- Allow executable configuration in the `doxygen` extension rule (thanks to @kaycebasques, @wyverald, @tpudlik, @rickeylev) ### Changed - Module extension tag renamed from `version` to `configuration` **BREAKING CHANGE** +- Updated documentation ## [NEXT.VERSION] diff --git a/README.md b/README.md index 22f88aa..c7de3e3 100644 --- a/README.md +++ b/README.md @@ -15,24 +15,22 @@ Add the following to your _MODULE.bazel_: bazel_dep(name = "rules_doxygen", version = "2.0.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: +If you don't want to depend on the [Bazel package registry](https://bazel.build/external/bazelbuild/rules_pkg) or need a not-yet-published version of this module, you can use a `git_override` by adding the following lines below `bazel_dep` in your _MODULE.bazel_ file: ```bzl # MODULE.bazel file bazel_dep(name = "rules_doxygen", version = "2.0.0", dev_dependency = True) -archive_override( +git_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 - # integrity = "sha256-0SCaZuAerluoDs6HXMb0Bj9FttZVieM4+Dpd9gnMM+o=", # Example + commit = "aacc1c856c350a89a0fa9c43b9318a248d5f1781", # Commit hash you want to use + remote = "https://github.com/TendTo/rules_doxygen.git", ) ``` ### Doxygen version selection -To select a doxygen version to use, use the `doxygen_extension` module extension below the `bazel_dep` rule in your MODULE.bazel file. +To add the `@doxygen` repository to your module, use `doxygen_extension` under `bazel_dep` in your MODULE.bazel file. ```bzl # MODULE.bazel file @@ -43,7 +41,7 @@ doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_ex use_repo(doxygen_extension, "doxygen") ``` -By default, version `1.12.0` of Doxygen is used. +The extension will create a default configuration for all platforms with the version `1.12.0` of Doxygen. You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_, _mac-arm_, _linux_ and _linux-arm_. ```bzl @@ -63,7 +61,7 @@ doxygen_extension.configuration( use_repo(doxygen_extension, "doxygen") ``` -When you do so, you must also provide the SHA256 of the given doxygen installation. +When you do so, you must also provide the SHA256 of the given doxygen archive. If you don't know the SHA256 value, just leave it empty. The build will fail with an error message containing the correct SHA256. @@ -71,6 +69,11 @@ The build will fail with an error message containing the correct SHA256. Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.windows.x64.bin.zip failed: class com.google.devtools.build.lib.bazel.repository.downloader.UnrecoverableHttpException Checksum was 2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b but wanted 0000000000000000000000000000000000000000000000000000000000000000 ``` +> [!Tip] +> Not indicating the platform will make the configuration apply to the platform it is running on. +> The build will fail when the download 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. + #### System-wide doxygen installation If you set the version to `0.0.0`, the doxygen executable will be assumed to be available from the PATH. @@ -79,14 +82,9 @@ No download will be performed and bazel will use the installed version of doxyge > [!Warning] > Setting the version to `0.0.0` this will break the hermeticity of your build, as it will now depend on the environment. -> [!Tip] -> Not indicating the platform will make the configuration apply to the platform it is running on. -> 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. - #### Using a local doxygen executable -You can also provide a label to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. +You can also provide a label pointing to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. No download will be performed, and the file indicated by the label will be used as the doxygen executable. > [!Note] @@ -120,7 +118,8 @@ doxygen_extension.configuration( executable = "@my_module//path/to/doxygen:doxygen", platform = "mac-arm", ) -# Since no configuration has been provided, all other platforms will fallback to the default version +# Since no configuration has been provided for them, +# all other platforms will fallback to the default version use_repo(doxygen_extension, "doxygen") ``` diff --git a/docs/extensions_doc.md b/docs/extensions_doc.md index 5b12838..79735ad 100755 --- a/docs/extensions_doc.md +++ b/docs/extensions_doc.md @@ -83,7 +83,7 @@ The resulting repository will have the following targets: - `@doxygen//:doxygen.bzl`, containing the doxygen macro used to generate the documentation. - `@doxygen//:Doxyfile.template`, default Doxyfile template used to generate the Doxyfile. -By default, version `1.12.0` of Doxygen is used. +The extension will create a default configuration for all platforms with the version `1.12.0` of Doxygen. You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_, _mac-arm_, _linux_ and _linux-arm_. ```bzl @@ -103,7 +103,7 @@ doxygen_extension.configuration( use_repo(doxygen_extension, "doxygen") ``` -When you do so, you must also provide the SHA256 of the given doxygen installation. +When you do so, you must also provide the SHA256 of the given doxygen archive. If you don't know the SHA256 value, just leave it empty. The build will fail with an error message containing the correct SHA256. @@ -111,6 +111,11 @@ The build will fail with an error message containing the correct SHA256. Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.windows.x64.bin.zip failed: class com.google.devtools.build.lib.bazel.repository.downloader.UnrecoverableHttpException Checksum was 2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b but wanted 0000000000000000000000000000000000000000000000000000000000000000 ``` +> [!Tip] +> Not indicating the platform will make the configuration apply to the platform it is running on. +> The build will fail when the download 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. + #### System-wide doxygen installation If you set the version to `0.0.0`, the doxygen executable will be assumed to be available from the PATH. @@ -119,14 +124,9 @@ No download will be performed and bazel will use the installed version of doxyge > [!Warning] > Setting the version to `0.0.0` this will break the hermeticity of your build, as it will now depend on the environment. -> [!Tip] -> Not indicating the platform will make the configuration apply to the platform it is running on. -> 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. - #### Using a local doxygen executable -You can also provide a label to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. +You can also provide a label pointing to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. No download will be performed, and the file indicated by the label will be used as the doxygen executable. > [!Note] @@ -142,7 +142,7 @@ 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. +# Using the 1.10.0 version of Doxygen instead of the default one. # Note that che checksum is correct only if the platform is windows. # If the platform is different, the build will fail. doxygen_extension.configuration( @@ -212,7 +212,8 @@ doxygen_extension.configuration( executable = "@my_module//path/to/doxygen:doxygen", platform = "mac-arm", ) -# Since no configuration has been provided, all other platforms will fallback to the default version +# Since no configuration has been provided for them, +# all other platforms will fallback to the default version use_repo(doxygen_extension, "doxygen") ``` @@ -228,7 +229,7 @@ use_repo(doxygen_extension, "doxygen") | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| executable | The doxygen executable to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. | String | optional | `""` | +| executable | The doxygen executable to use. If set, no download will take place and the provided doxygen executable will be used. Mutually exclusive with `version`. | Label | optional | `None` | | platform | The target platform for the doxygen binary. Available options are (windows, mac, mac-arm, linux, linux-arm). If not specified, it will select the platform it is currently running on. | String | optional | `""` | | sha256 | The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used. | String | optional | `""` | | 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. Mutually exclusive with `executable`. | String | optional | `""` | diff --git a/extensions.bzl b/extensions.bzl index ff53551..7e60b5d 100644 --- a/extensions.bzl +++ b/extensions.bzl @@ -290,7 +290,7 @@ The resulting repository will have the following targets: - `@doxygen//:doxygen.bzl`, containing the doxygen macro used to generate the documentation. - `@doxygen//:Doxyfile.template`, default Doxyfile template used to generate the Doxyfile. -By default, version `1.12.0` of Doxygen is used. +The extension will create a default configuration for all platforms with the version `1.12.0` of Doxygen. You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_, _mac-arm_, _linux_ and _linux-arm_. ```bzl @@ -310,7 +310,7 @@ doxygen_extension.configuration( use_repo(doxygen_extension, "doxygen") ``` -When you do so, you must also provide the SHA256 of the given doxygen installation. +When you do so, you must also provide the SHA256 of the given doxygen archive. If you don't know the SHA256 value, just leave it empty. The build will fail with an error message containing the correct SHA256. @@ -318,6 +318,11 @@ The build will fail with an error message containing the correct SHA256. Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.windows.x64.bin.zip failed: class com.google.devtools.build.lib.bazel.repository.downloader.UnrecoverableHttpException Checksum was 2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b but wanted 0000000000000000000000000000000000000000000000000000000000000000 ``` +> [!Tip] +> Not indicating the platform will make the configuration apply to the platform it is running on. +> The build will fail when the download 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. + #### System-wide doxygen installation If you set the version to `0.0.0`, the doxygen executable will be assumed to be available from the PATH. @@ -326,14 +331,9 @@ No download will be performed and bazel will use the installed version of doxyge > [!Warning] > Setting the version to `0.0.0` this will break the hermeticity of your build, as it will now depend on the environment. -> [!Tip] -> Not indicating the platform will make the configuration apply to the platform it is running on. -> 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. - #### Using a local doxygen executable -You can also provide a label to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. +You can also provide a label pointing to the `doxygen` executable you want to use by using the `executable` parameter in the extension configuration. No download will be performed, and the file indicated by the label will be used as the doxygen executable. > [!Note] @@ -349,7 +349,7 @@ 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. +# Using the 1.10.0 version of Doxygen instead of the default one. # Note that che checksum is correct only if the platform is windows. # If the platform is different, the build will fail. doxygen_extension.configuration( @@ -419,7 +419,8 @@ doxygen_extension.configuration( executable = "@my_module//path/to/doxygen:doxygen", platform = "mac-arm", ) -# Since no configuration has been provided, all other platforms will fallback to the default version +# Since no configuration has been provided for them, +# all other platforms will fallback to the default version use_repo(doxygen_extension, "doxygen") ```