diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ff6b6e..57eaf6c 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/Doxyfile.template b/Doxyfile.template index c8f2e0d..2d36514 100644 --- a/Doxyfile.template +++ b/Doxyfile.template @@ -2903,6 +2903,8 @@ MSCFILE_DIRS = # {{INPUT}} +# {{DOT_PATH}} + # {{ADDITIONAL PARAMETERS}} # {{OUTPUT DIRECTORY}} diff --git a/MODULE.bazel b/MODULE.bazel index 8a5ec9d..61ea031 100644 --- a/MODULE.bazel +++ b/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) diff --git a/README.md b/README.md index 73879e5..ce44c75 100644 --- a/README.md +++ b/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", diff --git a/docs/doxygen_doc.md b/docs/doxygen_doc.md index 584d5fc..bd24a90 100755 --- a/docs/doxygen_doc.md +++ b/docs/doxygen_doc.md @@ -12,8 +12,8 @@ doxygen(name, srcs, use_mathjax, html_extra_stylesheet, html_extra_files, html_colorstyle, aliases, have_dot, dot_image_format, dot_transparent, disable_index, full_sidebar, generate_treeview, javadoc_autobrief, builtin_stl_support, hide_undoc_members, hide_in_body_docs, - exclude_symbols, example_path, configurations, doxyfile_template, doxygen_extra_args, outs, - kwargs) + exclude_symbols, example_path, dot_executable, configurations, doxyfile_template, + doxygen_extra_args, outs, kwargs) Generates documentation using Doxygen. @@ -77,6 +77,7 @@ doxygen( | hide_in_body_docs | Whether to hide in body docs. | `None` | | exclude_symbols | A list of symbols to exclude. | `[]` | | example_path | The path to the examples. They must be added to the source files. | `None` | +| dot_executable | Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro | `None` | | 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:
- `# {{INPUT}}`: Subpackage directory in the sandbox.
- `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.
- `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute. | `"@doxygen//:Doxyfile.template"` | | doxygen_extra_args | Extra arguments to pass to the doxygen executable. | `[]` | diff --git a/doxygen.bzl b/doxygen.bzl index d62bb1b..b5329fd 100644 --- a/doxygen.bzl +++ b/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:
@@ -271,5 +281,6 @@ def doxygen( 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 @@ graph TD; B-->D; C-->D; - -
-graph TD;
-    A-->B;
-    A-->C;
-    B-->D;
-    C-->D;
-
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..7c8bf51 --- /dev/null +++ b/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", +) +``` 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 @@ 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.