Merge pull request #3 from TendTo/feat/hermetic-dot

Feat/hermetic dot

CHANGELOG.md

@@ -46,10 +46,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Updated documentation
 
+## [1.1.3]
+
+### Added
+
+- `dot_executable` parameter in the macro
+- Example of how to use the `doxygen` alongside `graphviz` in hermetic builds
+
 ## [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
 [1.1.2]: https://github.com/TendTo/rules_doxygen/compare/1.1.1...1.1.2
-[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/1.1.2...HEAD
+[1.1.3]: https://github.com/TendTo/rules_doxygen/compare/1.1.2...1.1.3
+[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/1.1.3...HEAD

Doxyfile.template

@@ -2903,6 +2903,8 @@ MSCFILE_DIRS           =
 
 # {{INPUT}}
 
+# {{DOT_PATH}}
+
 # {{ADDITIONAL PARAMETERS}}
 
 # {{OUTPUT DIRECTORY}}

MODULE.bazel

@@ -1,5 +1,5 @@
 """rules_doxygen module"""
-module(name = "rules_doxygen", version = "1.1.2", compatibility_level = 1)
+module(name = "rules_doxygen", version = "1.1.3", compatibility_level = 1)
 
 bazel_dep(name = "platforms", version = "0.0.5")
 bazel_dep(name = "stardoc", version = "0.6.2", dev_dependency = True)

README.md

@@ -9,13 +9,13 @@ This repository contains a Starlark implementation of Doxygen rules in Bazel.
 Add the following to your _MODULE.bazel_:
 
 ```bzl
-bazel_dep(name = "rules_doxygen", version = "1.1.2", dev_dependency = True)
+bazel_dep(name = "rules_doxygen", version = "1.1.3", 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:
 
 ```bzl
-bazel_dep(name = "rules_doxygen", version = "1.1.2", dev_dependency = True)
+bazel_dep(name = "rules_doxygen", version = "1.1.3", dev_dependency = True)
 archive_override(
     module_name = "rules_doxygen",
     urls = "https://github.com/TendTo/rules_doxygen/archive/refs/heads/main.tar.gz",

docs/doxygen_doc.md

@@ -12,8 +12,8 @@ doxygen(<a href="#doxygen-name">name</a>, <a href="#doxygen-srcs">srcs</a>, <a h
         <a href="#doxygen-use_mathjax">use_mathjax</a>, <a href="#doxygen-html_extra_stylesheet">html_extra_stylesheet</a>, <a href="#doxygen-html_extra_files">html_extra_files</a>, <a href="#doxygen-html_colorstyle">html_colorstyle</a>, <a href="#doxygen-aliases">aliases</a>, <a href="#doxygen-have_dot">have_dot</a>,
         <a href="#doxygen-dot_image_format">dot_image_format</a>, <a href="#doxygen-dot_transparent">dot_transparent</a>, <a href="#doxygen-disable_index">disable_index</a>, <a href="#doxygen-full_sidebar">full_sidebar</a>, <a href="#doxygen-generate_treeview">generate_treeview</a>,
         <a href="#doxygen-javadoc_autobrief">javadoc_autobrief</a>, <a href="#doxygen-builtin_stl_support">builtin_stl_support</a>, <a href="#doxygen-hide_undoc_members">hide_undoc_members</a>, <a href="#doxygen-hide_in_body_docs">hide_in_body_docs</a>,
-        <a href="#doxygen-exclude_symbols">exclude_symbols</a>, <a href="#doxygen-example_path">example_path</a>, <a href="#doxygen-configurations">configurations</a>, <a href="#doxygen-doxyfile_template">doxyfile_template</a>, <a href="#doxygen-doxygen_extra_args">doxygen_extra_args</a>, <a href="#doxygen-outs">outs</a>,
-        <a href="#doxygen-kwargs">kwargs</a>)
+        <a href="#doxygen-exclude_symbols">exclude_symbols</a>, <a href="#doxygen-example_path">example_path</a>, <a href="#doxygen-dot_executable">dot_executable</a>, <a href="#doxygen-configurations">configurations</a>, <a href="#doxygen-doxyfile_template">doxyfile_template</a>,
+        <a href="#doxygen-doxygen_extra_args">doxygen_extra_args</a>, <a href="#doxygen-outs">outs</a>, <a href="#doxygen-kwargs">kwargs</a>)
 </pre>
 
 Generates documentation using Doxygen.
@@ -77,6 +77,7 @@ doxygen(
 | <a id="doxygen-hide_in_body_docs"></a>hide_in_body_docs |  Whether to hide in body docs.   |  `None` |
 | <a id="doxygen-exclude_symbols"></a>exclude_symbols |  A list of symbols to exclude.   |  `[]` |
 | <a id="doxygen-example_path"></a>example_path |  The path to the examples. They must be added to the source files.   |  `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-doxygen_extra_args"></a>doxygen_extra_args |  Extra arguments to pass to the doxygen executable.   |  `[]` |

doxygen.bzl

@@ -13,6 +13,7 @@ def _doxygen_impl(ctx):
         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,17 +68,24 @@ doxygen(
             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. Must refer to an executable file.",
+        ),
         "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.",
+            doc = "The doxygen executable to use. Must refer to an executable file.",
         ),
     },
 )
@@ -112,6 +120,7 @@ def doxygen(
         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 @@ def doxygen(
         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 @@ def doxygen(
         configurations = configurations,
         doxyfile_template = doxyfile_template,
         doxygen_extra_args = doxygen_extra_args,
+        dot_executable = dot_executable,
         **kwargs
     )

examples/awesome/README.md

@@ -34,11 +34,3 @@ graph TD;
     B-->D;
     C-->D;
 </pre>
-
-<pre class="mermaid">
-graph TD;
-    A-->B;
-    A-->C;
-    B-->D;
-    C-->D;
-</pre>

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",
+)

examples/graphviz/README.md

@@ -0,0 +1,46 @@
+# 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",
+    ),
+)
+
+# Ideally, instead of using a local filegroup, you would want and external module, like "@graphviz//:bin/dot"
+
+doxygen(
+    name = "doxygen",
+    srcs = glob([
+        "*.h",
+        "*.cpp",
+        "*.sh",
+    ]) + [":dot_executable"],
+    dot_executable = ":dot_executable",
+    have_dot = True,
+    project_name = "graphviz",
+)
+```

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; }

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;
+};

extensions.bzl

@@ -54,14 +54,14 @@ def _doxygen_extension_impl(ctx):
             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.