diff --git a/docs/doxygen_doc.md b/docs/doxygen_doc.md index aa8f930..88f46cf 100755 --- a/docs/doxygen_doc.md +++ b/docs/doxygen_doc.md @@ -270,7 +270,7 @@ doxygen( | srcs | List of source files to generate documentation for. Can include any file that Doxygen can parse, as well as targets that return a DefaultInfo provider (usually genrules). Since we are only considering the outputs files and not the sources, these targets **will** be built if necessary. | `[]` | | deps | List of dependencies targets whose files present in the 'src', 'hdrs' and 'data' attributes will be collected to generate the documentation. Transitive dependencies are also taken into account. Since we are only considering the source files and not the outputs, these targets **will not** be built. | `[]` | | executable | Label of the doxygen executable. | `None` | -| dot_executable | Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro | `None` | +| dot_executable | Label of the dot executable. | `None` | | configurations | List of additional configuration parameters to pass to Doxygen. | `None` | | doxyfile_prefix | Prefix to add to the Doxyfile path. | `""` | | doxyfile_template | The template file to use to generate the Doxyfile. The following substitutions are available:
- `# {{INPUT}}`: Subpackage directory in the sandbox.
- `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.
- `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute.
- `{{OUTDIR}}`: The output directory where the generated documentation will be placed. Can be used anywhere in the Doxyfile, usually to generate additional output files, like tag files. | `None` | diff --git a/doxygen/doxygen.bzl b/doxygen/doxygen.bzl index e6bbfbe..acf8d46 100644 --- a/doxygen/doxygen.bzl +++ b/doxygen/doxygen.bzl @@ -73,19 +73,25 @@ def _doxygen_impl(ctx): deps = depset(transitive = [dep[TransitiveSourcesInfo].srcs for dep in ctx.attr.deps]).to_list() input_dirs = {(file.dirname or "."): None for file in ctx.files.srcs + deps} + dot_dir = ctx.executable.dot_executable.dirname if ctx.executable.dot_executable else "" + ctx.actions.expand_template( template = ctx.file.doxyfile_template, output = doxyfile, substitutions = { "# {{INPUT}}": "INPUT = %s" % " ".join(input_dirs.keys()), - "# {{DOT_PATH}}": ("DOT_PATH = %s" % ctx.executable.dot_executable.dirname) if ctx.executable.dot_executable else "", + "# {{DOT_PATH}}": "DOT_PATH = $(DOT_PATH)" if dot_dir else "", "# {{ADDITIONAL PARAMETERS}}": "\n".join(configurations), "# {{OUTPUT DIRECTORY}}": "OUTPUT_DIRECTORY = %s" % doxyfile.dirname, "{{OUTDIR}}": "%s" % doxyfile.dirname, }, ) - tools_path = {tool.dirname: None for tool in ctx.files.tools}.keys() + tools_list = list(ctx.files.tools) + if ctx.executable.dot_executable: + tools_list.append(ctx.executable.dot_executable) + + tools_path = {tool.dirname: None for tool in tools_list}.keys() tools_path += [ctx.attr.env.get("PATH", "")] if ctx.attr.env.get("PATH", "") != "" else [] if ctx.attr.host_platform == "windows": path = ";".join(tools_path + ["C:\\Windows\\system32"]) @@ -93,15 +99,23 @@ def _doxygen_impl(ctx): path = ":".join(tools_path) env = (ctx.attr.env | {"PATH": path}) if path != "" else ctx.attr.env - ctx.actions.run( + command = """\ +if [ -n "{dot_dir}" ]; then + export DOT_PATH="$PWD/{dot_dir}" + export PATH="$DOT_PATH:$PATH" +fi +exec "$@" +""".format(dot_dir = dot_dir) + + ctx.actions.run_shell( inputs = ctx.files.srcs + deps + [doxyfile], outputs = outs, - arguments = [doxyfile.path] + ctx.attr.doxygen_extra_args, - executable = ctx.executable.executable, + command = command, + arguments = [ctx.executable.executable.path, doxyfile.path] + ctx.attr.doxygen_extra_args, mnemonic = "DoxygenBuild", progress_message = "Building doxygen documentation for rule '%s'" % ctx.label.name, use_default_shell_env = ctx.attr.use_default_shell_env, - tools = ctx.files.tools, + tools = tools_list + [ctx.executable.executable], env = env, ) @@ -707,7 +721,7 @@ def doxygen( Transitive dependencies are also taken into account. Since we are only considering the source files and not the outputs, these targets **will not** be built. executable: Label of the doxygen executable. - dot_executable: Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro + dot_executable: Label of the dot executable. configurations: List of additional configuration parameters to pass to Doxygen. doxyfile_prefix: Prefix to add to the Doxyfile path. doxyfile_template: The template file to use to generate the Doxyfile. diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel index c67d7f8..03383b0 100644 --- a/examples/MODULE.bazel +++ b/examples/MODULE.bazel @@ -6,12 +6,14 @@ local_path_override( path = "../", ) -bazel_dep(name = "rules_cc", version = "0.2.17") bazel_dep(name = "aspect_bazel_lib", version = "2.22.5") bazel_dep(name = "bazel_skylib", version = "1.9.0") -bazel_dep(name = "rules_python", version = "1.9.0-rc1") +# Hermetic graphviz dependency (requires Bazel >= 8; see examples/graphviz/README.md) +# bazel_dep(name = "graphviz", version = "14.0.0.bcr.3") bazel_dep(name = "platforms", version = "1.1.0") +bazel_dep(name = "rules_cc", version = "0.2.17") bazel_dep(name = "rules_java", version = "9.6.1") +bazel_dep(name = "rules_python", version = "1.9.0-rc1") http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") http_file( diff --git a/examples/graphviz/BUILD.bazel b/examples/graphviz/BUILD.bazel index 4c40c25..670cfc0 100644 --- a/examples/graphviz/BUILD.bazel +++ b/examples/graphviz/BUILD.bazel @@ -1,14 +1,20 @@ load("@doxygen//:doxygen.bzl", "doxygen") -# WARNINING: this assume the existence of a repository @graphviz exposing the target :executable +# By default, uses dot from the host system PATH (or dot_path). +# To use a hermetic BCR target with Bazel >= 8: +# 1. Enable `bazel_dep(name = "graphviz", ...)` in examples/MODULE.bazel +# 2. Set `dot_executable = "@graphviz//:dot"` doxygen( name = "doxygen", - srcs = glob([ - "*.h", - "*.cpp", - "*.sh", - ]) + ["@graphviz//:executable"], - dot_executable = "@graphviz//:executable", + srcs = glob( + [ + "*.h", + "*.cpp", + "*.sh", + ], + allow_empty = True, + ), + # dot_executable = "@graphviz//:dot", have_dot = True, project_brief = "Example project for doxygen", project_name = "graphviz", diff --git a/examples/graphviz/README.md b/examples/graphviz/README.md index 7c8bf51..10ece5e 100644 --- a/examples/graphviz/README.md +++ b/examples/graphviz/README.md @@ -1,46 +1,58 @@ -# Graphiz path example +# Graphviz example -This is an example of how to use the `doxygen` alongside `graphviz` to generate inheritance diagrams for C++ classes. -By default, `doxygen` looks for the `dot` executable in the system path, meaning that a system installation of `graphviz` will work out of the box. -If you want to make the build fully hermetic, you can specify the path to the `dot` executable in the `doxygen` rule, making it point to a `dot` binary of your choosing. +This is an example of how to use `doxygen` alongside `graphviz` to generate inheritance, collaboration, and dependency diagrams for C++ classes. + +Remember to set `have_dot = True`, otherwise no graphs will be produced. ```bash -bazel build //doxyfile:doxygen +bazel build //graphviz:doxygen ``` -## Custom dot binary +## Hermetic vs. Non-Hermetic Dot -To ensure the `dot` binary is available to the rule, make sure to add it to the sources of the macro. -Also, remember to add the `have_dot = True` parameter, otherwise no graphs will be produced. +Depending on how `graphviz` is provided, there are two mutually exclusive ways to configure the `dot` tool: -```bzl -load("@doxygen//:doxygen.bzl", "doxygen") +### 1. Hermetic Bazel target (`dot_executable`) -# Assuming the binary is located in the same folder - -filegroup( - name = "dot_executable", - srcs = select( - { - "@platforms//os:linux": ["dot"], - "@platforms//os:macos": ["dot"], - "@platforms//os:windows": ["dot"], - }, - "Unsupported platform", - ), -) +For a fully hermetic build using a Bazel target (e.g. from the BCR's [`@graphviz`](https://registry.bazel.build/modules/graphviz) module or a local target), pass the label to the **`dot_executable`** attribute. -# Ideally, instead of using a local filegroup, you would want and external module, like "@graphviz//:bin/dot" +> [!NOTE] +> The `@graphviz` module in BCR requires **Bazel >= 8.0.0**. If you are using Bazel >= 8, enable `bazel_dep(name = "graphviz", version = "14.0.0.bcr.3")` in `examples/MODULE.bazel`. + +```bzl +load("@doxygen//:doxygen.bzl", "doxygen") doxygen( name = "doxygen", srcs = glob([ "*.h", "*.cpp", - "*.sh", - ]) + [":dot_executable"], - dot_executable = ":dot_executable", + ]), + dot_executable = "@graphviz//:dot", have_dot = True, project_name = "graphviz", ) ``` + +`rules_doxygen` automatically stages the executable into the execution sandbox tools and ensures Doxygen can resolve it regardless of working directory changes during documentation generation. + +### 2. Non-hermetic host installation (`dot_path` or system `PATH`) + +For a non-hermetic build using a host installation (such as Homebrew or a system package manager): + +- **Specific host directory (`dot_path`)**: Specify the host directory containing the `dot` executable with `dot_path`, which corresponds directly to `DOT_PATH` in the generated `Doxyfile`: + + ```bzl + doxygen( + name = "doxygen", + srcs = glob([ + "*.h", + "*.cpp", + ]), + dot_path = "/home/linuxbrew/.linuxbrew/bin", # or "/opt/homebrew/bin" + have_dot = True, + project_name = "graphviz", + ) + ``` + +- **System `PATH` lookup**: If `dot` is installed in a standard location on your `PATH` (such as `/usr/bin/dot`), leave both `dot_executable` and `dot_path` unset. Doxygen will automatically search the system `PATH`.