feat: add dot_path parameter to support hermetic graphviz
diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ff6b6e..ac7aae8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md
@@ -48,6 +48,11 @@ ## [NEXT.VERSION] +### Added + +- `dot_executable` parameter in the macro +- Example of how to use the `doxygen` alongside `graphviz` in hermetic builds + [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/Doxyfile.template b/Doxyfile.template index c8f2e0d..2d36514 100644 --- a/Doxyfile.template +++ b/Doxyfile.template
@@ -2903,6 +2903,8 @@ # {{INPUT}} +# {{DOT_PATH}} + # {{ADDITIONAL PARAMETERS}} # {{OUTPUT DIRECTORY}}
diff --git a/doxygen.bzl b/doxygen.bzl index d62bb1b..5170f7d 100644 --- a/doxygen.bzl +++ b/doxygen.bzl
@@ -13,6 +13,7 @@ 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 "", "# {{ADDITIONAL PARAMETERS}}": "\n".join(ctx.attr.configurations), "# {{OUTPUT DIRECTORY}}": "OUTPUT_DIRECTORY = %s" % doxyfile.dirname, }, @@ -67,15 +68,22 @@ 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. +- `# {{DOT_PATH}}`: Indicate to doxygen the location of the `dot_executable` - `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute. - `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute. """, ), + "dot_executable": attr.label( + executable = True, + cfg = "exec", + allow_single_file = True, + doc = "The dot executable to use.", + ), "doxygen_extra_args": attr.string_list(default = [], doc = "Extra arguments to pass to the doxygen executable."), "_executable": attr.label( executable = True, cfg = "exec", - allow_files = True, + allow_single_file = True, default = Label("@doxygen//:executable"), doc = "The doxygen executable to use.", ), @@ -112,6 +120,7 @@ hide_in_body_docs = None, exclude_symbols = [], example_path = None, + dot_executable = None, configurations = [], doxyfile_template = "@doxygen//:Doxyfile.template", doxygen_extra_args = [], @@ -174,6 +183,7 @@ hide_in_body_docs: Whether to hide in body docs. exclude_symbols: A list of symbols to exclude. example_path: The path to the examples. They must be added to the source files. + dot_executable: Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro configurations: A list of additional configuration parameters to pass to Doxygen. doxyfile_template: The template file to use to generate the Doxyfile. The following substitutions are available:<br> @@ -271,5 +281,6 @@ configurations = configurations, doxyfile_template = doxyfile_template, doxygen_extra_args = doxygen_extra_args, + dot_executable = dot_executable, **kwargs )
diff --git a/examples/awesome/README.md b/examples/awesome/README.md index 8b3d858..854c517 100644 --- a/examples/awesome/README.md +++ b/examples/awesome/README.md
@@ -34,11 +34,3 @@ B-->D; C-->D; </pre> - -<pre class="mermaid"> -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; -</pre>
diff --git a/examples/graphviz/BUILD.bazel b/examples/graphviz/BUILD.bazel new file mode 100644 index 0000000..4c40c25 --- /dev/null +++ b/examples/graphviz/BUILD.bazel
@@ -0,0 +1,15 @@ +load("@doxygen//:doxygen.bzl", "doxygen") + +# WARNINING: this assume the existence of a repository @graphviz exposing the target :executable +doxygen( + name = "doxygen", + srcs = glob([ + "*.h", + "*.cpp", + "*.sh", + ]) + ["@graphviz//:executable"], + dot_executable = "@graphviz//:executable", + have_dot = True, + project_brief = "Example project for doxygen", + project_name = "graphviz", +)
diff --git a/examples/graphviz/README.md b/examples/graphviz/README.md new file mode 100644 index 0000000..04cc6b9 --- /dev/null +++ b/examples/graphviz/README.md
@@ -0,0 +1,44 @@ +# Graphiz path 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. + +```bash +bazel build //doxyfile:doxygen +``` + +## Custom dot binary + +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. + +```bzl +load("@doxygen//:doxygen.bzl", "doxygen") + +# 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", + ), +) + +doxygen( + name = "doxygen", + srcs = glob([ + "*.h", + "*.cpp", + "*.sh", + ]) + [":dot_executable"], + dot_executable = ":dot_executable", + have_dot = True, + project_name = "graphviz", +) +```
diff --git a/examples/graphviz/lib.cpp b/examples/graphviz/lib.cpp new file mode 100644 index 0000000..07d09b0 --- /dev/null +++ b/examples/graphviz/lib.cpp
@@ -0,0 +1,10 @@ +/** + * @file lib.cpp + * @author Ernesto Casablanca (casablancaernesto@gmail.com) + * @copyright 2024 + */ + +#include "lib.h" + +int Adder::op(int a, int b) { return a + b; } +int Subtractor::op(int a, int b) { return a - b; } \ No newline at end of file
diff --git a/examples/graphviz/lib.h b/examples/graphviz/lib.h new file mode 100644 index 0000000..8df277a --- /dev/null +++ b/examples/graphviz/lib.h
@@ -0,0 +1,52 @@ +/** + * @file lib.h + * @author Ernesto Casablanca (casablancaernesto@gmail.com) + * @copyright 2024 + */ +#pragma once + +/** + * @brief Run a calculation on two integers. + */ +class Calculator { + public: + /** + * @brief Run a calculation on two integers. + * + * The actual operation is defined by the derived class. + * @param a first integer + * @param b second integer + * @return result of the operation + */ + virtual int op(int a, int b) = 0; +}; + +/** + * @brief Add two integers. + */ +class Adder : public Calculator { + public: + /** + * @brief Add two integers. + * + * @param a first integer + * @param b second integer + * @return sum of a and b + */ + int op(int a, int b) override; +}; + +/** + * @brief Subtract two integers. + */ +class Subtractor : public Calculator { + public: + /** + * @brief Subtract two integers. + * + * @param a first integer + * @param b second integer + * @return difference of a and b + */ + int op(int a, int b) override; +};
diff --git a/extensions.bzl b/extensions.bzl index e3fd143..9a9161e 100644 --- a/extensions.bzl +++ b/extensions.bzl
@@ -54,14 +54,14 @@ strip_prefix = strip_prefix, ) -_version = tag_class(attrs = { +_doxygen_version = tag_class(attrs = { "version": attr.string(doc = "The version of doxygen to use", mandatory = True), "sha256": attr.string(doc = "The sha256 hash of the doxygen archive. If not specified, an all-zero hash will be used."), }) doxygen_extension = module_extension( implementation = _doxygen_extension_impl, - tag_classes = {"version": _version}, + tag_classes = {"version": _doxygen_version}, doc = """ Module extension for declaring the doxygen version to use.