Fix rules_doxygen in submodules

.github/workflows/ci.yml

@@ -169,3 +169,24 @@ jobs:
       - name: Check doxygen version in produced index.html
         run: grep 'Doxygen 1.10.0' examples/bazel-bin/${{ matrix.subdir }}/html/index.html
         shell: bash
+
+  submodules:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        subdir: [root, submodule1, submodule2]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build submodules/${{ matrix.subdir }}
+        run: bazel build //:doxygen
+        working-directory: submodules/${{ matrix.subdir }}
+      - name: Check output
+        uses: andstor/file-existence-action@v3
+        with:
+          files: submodules/${{ matrix.subdir }}/bazel-bin/html/index.html
+          fail: true
+      - name: Check doxygen version in produced index.html
+        run: grep 'Doxygen 1.12.0' submodules/${{ matrix.subdir }}/bazel-bin/html/index.html
+        shell: bash

CHANGELOG.md

@@ -96,6 +96,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Most of the `doxygen` parameters are now available in the `doxygen` extension rule
 - Support for make substitutions in the `doxygen` extension rule
+- `repository` tag in the `doxygen` extension rule to avoid conflicts with other modules
 
 ### Fix
 

docs/doxygen_doc.md

@@ -122,8 +122,8 @@ doxygen(
 | <a id="doxygen-name"></a>name |  A name for the target.   |  none |
 | <a id="doxygen-srcs"></a>srcs |  A list of source files to generate documentation for.   |  none |
 | <a id="doxygen-dot_executable"></a>dot_executable |  Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro   |  `None` |
-| <a id="doxygen-configurations"></a>configurations |  A list of additional configuration parameters to pass to Doxygen.   |  `[]` |
-| <a id="doxygen-doxyfile_template"></a>doxyfile_template |  The template file to use to generate the Doxyfile. The following substitutions are available:<br> - `# {{INPUT}}`: Subpackage directory in the sandbox.<br> - `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.<br> - `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute.   |  `"@doxygen//:Doxyfile.template"` |
+| <a id="doxygen-configurations"></a>configurations |  A list of additional configuration parameters to pass to Doxygen.   |  `None` |
+| <a id="doxygen-doxyfile_template"></a>doxyfile_template |  The template file to use to generate the Doxyfile. The following substitutions are available:<br> - `# {{INPUT}}`: Subpackage directory in the sandbox.<br> - `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.<br> - `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute.   |  `None` |
 | <a id="doxygen-doxygen_extra_args"></a>doxygen_extra_args |  Extra arguments to pass to the doxygen executable.   |  `[]` |
 | <a id="doxygen-outs"></a>outs |  The output folders bazel will keep. If only the html outputs is of interest, the default value will do. otherwise, a list of folders to keep is expected (e.g. ["html", "latex"]).   |  `["html"]` |
 | <a id="doxygen-doxyfile_encoding"></a>doxyfile_encoding |  This tag specifies the encoding used for all characters in the configuration file that follow.   |  `None` |

docs/extensions_doc.md

@@ -75,6 +75,7 @@ doxygen_repository(
 <pre>
 doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
 doxygen_extension.configuration(<a href="#doxygen_extension.configuration-executable">executable</a>, <a href="#doxygen_extension.configuration-platform">platform</a>, <a href="#doxygen_extension.configuration-sha256">sha256</a>, <a href="#doxygen_extension.configuration-version">version</a>)
+doxygen_extension.repository()
 </pre>
 
 Module extension for declaring the doxygen configurations to use.
@@ -234,4 +235,13 @@ use_repo(doxygen_extension, "doxygen")
 | <a id="doxygen_extension.configuration-sha256"></a>sha256 |  The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used.   | String | optional |  `""`  |
 | <a id="doxygen_extension.configuration-version"></a>version |  The version of doxygen to use. If set to `0.0.0`, the doxygen executable will be assumed to be available from the PATH. Mutually exclusive with `executable`.   | String | optional |  `""`  |
 
+<a id="doxygen_extension.repository"></a>
+
+### repository
+
+**Attributes**
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+
 

doxygen/doxygen.bzl

@@ -77,7 +77,7 @@ doxygen(
         "outs": attr.string_list(default = ["html"], allow_empty = False, doc = """The output folders to keep. If only the html outputs is of interest, the default value will do. Otherwise, a list of folders to keep is expected (e.g. `["html", "latex"]`)."""),
         "doxyfile_template": attr.label(
             allow_single_file = True,
-            default = Label("@doxygen//:Doxyfile.template"),
+            default = Label(":Doxyfile.template"),
             doc = """The template file to use to generate the Doxyfile. You can provide your own or use the default one. 
 The following substitutions are available: 
 - `# {{INPUT}}`: Subpackage directory in the sandbox.
@@ -97,7 +97,7 @@ The following substitutions are available:
             executable = True,
             cfg = "exec",
             allow_single_file = True,
-            default = Label("@doxygen//:executable"),
+            default = Label(":executable"),
             doc = "The doxygen executable to use. Must refer to an executable file.",
         ),
     },
@@ -120,7 +120,7 @@ def doxygen(
         # Bazel specific attributes
         dot_executable = None,
         configurations = None,
-        doxyfile_template = "@doxygen//:Doxyfile.template",
+        doxyfile_template = None,
         doxygen_extra_args = [],
         outs = ["html"],
         # Doxygen specific attributes
@@ -1084,12 +1084,14 @@ def doxygen(
     _add_generic_configuration(configurations, "MSCGEN_TOOL", mscgen_tool)
     _add_generic_configuration(configurations, "MSCFILE_DIRS", mscfile_dirs)
 
+    if doxyfile_template:
+        kwargs["doxyfile_template"] = doxyfile_template 
+
     _doxygen(
         name = name,
         srcs = srcs,
         outs = outs,
         configurations = configurations,
-        doxyfile_template = doxyfile_template,
         doxygen_extra_args = doxygen_extra_args,
         dot_executable = dot_executable,
         **kwargs

examples/doxyfile/Doxyfile

@@ -72,7 +72,7 @@ PROJECT_ICON           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = bazel-out/k8-fastbuild/bin/custom 
+OUTPUT_DIRECTORY       = bazel-out/k8-fastbuild/bin/doxyfile 
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -947,7 +947,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = custom
+INPUT                  = doxyfile
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2899,9 +2899,9 @@ MSCGEN_TOOL            =
 
 MSCFILE_DIRS           =
 
-USE_MDFILE_AS_MAINPAGE = custom/README.md
+USE_MDFILE_AS_MAINPAGE = doxyfile/README.md
 ALIASES                = "licence=@par Licence:^^"
 
-OUTPUT_DIRECTORY       = bazel-out/k8-fastbuild/bin/custom 
+OUTPUT_DIRECTORY       = bazel-out/k8-fastbuild/bin/doxyfile 
 # Since it is not reliable, it is better to use the template substitution
 # {{OUTPUT DIRECTORY}}

extensions.bzl

@@ -228,11 +228,19 @@ def _doxygen_extension_impl(ctx):
         ctx: a [module context](https://bazel.build/rules/lib/builtins/module_ctx) object containing the module's attributes
     """
     for mod in ctx.modules:
+        name = ""
         platforms = []
         versions = []
         sha256s = []
         executables = []
 
+        for attr in mod.tags.repository:
+            if attr.name == "":
+                fail("The name of the repository cannot be empty")
+            if name != "":
+                fail("The name of the repository was already specified: '%s'. Cannot be overridden with '%s'" % (name, attr.name))
+            name = attr.name
+
         default_configurations = {
             "windows": struct(version = "1.12.0", sha256 = "07f1c92cbbb32816689c725539c0951f92c6371d3d7f66dfa3192cbe88dd3138", executable = ""),
             "mac": struct(version = "1.12.0", sha256 = "6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001", executable = ""),
@@ -266,23 +274,26 @@ def _doxygen_extension_impl(ctx):
                 executables.append(default_configurations[platform].executable)
 
         doxygen_repository(
-            name = "doxygen",
+            name = name if name != "" else "doxygen",
             versions = versions,
             sha256s = sha256s,
             platforms = platforms,
             executables = executables,
         )
 
-_doxygen_configuration = tag_class(attrs = {
+_doxygen_configuration_tag = 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.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_repository_tag = tag_class(attrs = {
+    "name": attr.string(doc = "The name of the repository the extension will create. Useful if you don't use 'rules_doxygen' as a dev_dependency, since it will avoid name collision for module depending on yours. Must be the same for all configurations. Defaults to 'doxygen'.", mandatory = True),
+})
 
 doxygen_extension = module_extension(
     implementation = _doxygen_extension_impl,
-    tag_classes = {"configuration": _doxygen_configuration},
+    tag_classes = {"configuration": _doxygen_configuration_tag, "repository": _doxygen_repository_tag},
     doc = """
 Module extension for declaring the doxygen configurations to use.
 

submodules/README.md

@@ -0,0 +1,34 @@
+# Submodules
+
+This repository simulates a situation where a root module depends on `rules_doxygen` as well as other two modules, `submodule1` and `submodule2`, which also depend on `rules_doxygen`.
+The goal is to make sure there are no conflicts between the different versions of `rules_doxygen` used by the root module and the submodules.
+
+## Using `dev_dependency`
+
+Since `rules_doxygen` is usually juts a development dependency, it is recommended to set the `dev_dependency` parameter to `True` when declaring the dependency on `rules_doxygen` in the `MODULE.bazel` file of any module.
+
+```bzl
+# MODULE.bazel file
+
+module(name = "my_module")
+
+bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
+```
+
+This way, all modules that depend on `my_module` will not inherit the dependency on `rules_doxygen`, and will be free to use their own version of `rules_doxygen`.
+
+## Build dependencies
+
+If you use `rules_doxygen` as a build dependency, make sure to use the `repository` tag to avoid conflicts when your module is used by other modules.
+
+```bzl
+# MODULE.bazel file
+
+module(name = "my_module")
+
+bazel_dep(name = "rules_doxygen", version = "...")
+
+doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
+doxygen_extension.repository(name = "submodule2_doxygen")
+use_repo(doxygen_extension, "submodule2_doxygen")
+```

submodules/root/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@doxygen//:doxygen.bzl", "doxygen")
+
+doxygen(
+    name = "doxygen",
+    srcs = glob(["*"]),
+    project_brief = "Root project for doxygen",
+    project_name = "root",
+)

submodules/root/MODULE.bazel

@@ -0,0 +1,22 @@
+module(name = "root")
+
+bazel_dep(name = "submodule1")
+local_path_override(
+    module_name = "submodule1",
+    path = "../submodule1",
+)
+
+bazel_dep(name = "submodule2")
+local_path_override(
+    module_name = "submodule2",
+    path = "../submodule2",
+)
+
+bazel_dep(name = "rules_doxygen", dev_dependency = True)
+local_path_override(
+    module_name = "rules_doxygen",
+    path = "../../",
+)
+
+doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
+use_repo(doxygen_extension, "doxygen")

submodules/root/README.md

@@ -0,0 +1,3 @@
+# Root module
+
+This is the README for the root module.

submodules/submodule1/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@submodule1_doxygen//:doxygen.bzl", "doxygen")
+
+doxygen(
+    name = "doxygen",
+    srcs = glob(["*"]),
+    project_brief = "Submodule 1 project for doxygen",
+    project_name = "submodule1",
+)

submodules/submodule1/MODULE.bazel

@@ -0,0 +1,11 @@
+module(name = "submodule1")
+
+bazel_dep(name = "rules_doxygen", version = "2.0.0")
+local_path_override(
+    module_name = "rules_doxygen",
+    path = "../../",
+)
+
+doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
+doxygen_extension.repository(name = "submodule1_doxygen")
+use_repo(doxygen_extension, "submodule1_doxygen")

submodules/submodule1/README.md

@@ -0,0 +1,3 @@
+# Submodule 1
+
+This is the README for submodule 1.

submodules/submodule2/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@submodule2_doxygen//:doxygen.bzl", "doxygen")
+
+doxygen(
+    name = "doxygen",
+    srcs = glob(["*"]),
+    project_brief = "Submodule 2 project for doxygen",
+    project_name = "submodule2",
+)

submodules/submodule2/MODULE.bazel

@@ -0,0 +1,11 @@
+module(name = "submodule2")
+
+bazel_dep(name = "rules_doxygen", version = "2.0.0")
+local_path_override(
+    module_name = "rules_doxygen",
+    path = "../../",
+)
+
+doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
+doxygen_extension.repository(name = "submodule2_doxygen")
+use_repo(doxygen_extension, "submodule2_doxygen")

submodules/submodule2/README.md

@@ -0,0 +1,3 @@
+# Submodule 2
+
+This is the README for submodule 2.