Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/doxygen_doc.md
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,7 @@ doxygen(
| <a id="doxygen-srcs"></a>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. | `[]` |
| <a id="doxygen-deps"></a>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. | `[]` |
| <a id="doxygen-executable"></a>executable | Label of the doxygen executable. | `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-dot_executable"></a>dot_executable | Label of the dot executable. | `None` |
| <a id="doxygen-configurations"></a>configurations | List of additional configuration parameters to pass to Doxygen. | `None` |
| <a id="doxygen-doxyfile_prefix"></a>doxyfile_prefix | Prefix to add to the Doxyfile path. | `""` |
| <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.<br> - `{{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` |
Expand Down
28 changes: 21 additions & 7 deletions doxygen/doxygen.bzl
Original file line number Diff line number Diff line change
Expand Up @@ -73,35 +73,49 @@ 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"])
else:
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,
)

Expand Down Expand Up @@ -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.
Expand Down
6 changes: 4 additions & 2 deletions examples/MODULE.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
20 changes: 13 additions & 7 deletions examples/graphviz/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
66 changes: 39 additions & 27 deletions examples/graphviz/README.md
Original file line number Diff line number Diff line change
@@ -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`.
Loading