From 237d1e3ccb045e37581eba5368f722be7376434e Mon Sep 17 00:00:00 2001 From: Mikael Persson Date: Sat, 3 Oct 2026 15:24:39 -0400 Subject: [PATCH 1/6] Added file-collection options for external/generated/data in deps --- doxygen/doxygen.bzl | 188 ++++++++++++++------ examples/MODULE.bazel | 12 +- examples/dependencies/BUILD.bazel | 35 +++- examples/dependencies/defs.bzl | 10 ++ examples/dependencies/main.cpp | 6 +- examples/third_party/BUILD.bazel | 0 examples/third_party/greet_gen/BUILD.bazel | 7 + examples/third_party/greet_gen/MODULE.bazel | 6 + examples/third_party/greet_gen/defs.bzl | 72 ++++++++ examples/third_party/greet_gen/greet.h | 27 +++ 10 files changed, 302 insertions(+), 61 deletions(-) create mode 100644 examples/dependencies/defs.bzl create mode 100644 examples/third_party/BUILD.bazel create mode 100644 examples/third_party/greet_gen/BUILD.bazel create mode 100644 examples/third_party/greet_gen/MODULE.bazel create mode 100644 examples/third_party/greet_gen/defs.bzl create mode 100644 examples/third_party/greet_gen/greet.h diff --git a/doxygen/doxygen.bzl b/doxygen/doxygen.bzl index e6bbfbe..0e5803a 100644 --- a/doxygen/doxygen.bzl +++ b/doxygen/doxygen.bzl @@ -30,14 +30,22 @@ def _collect_files_aspect_impl(_, ctx): Returns: TransitiveSourcesInfo with a depset of transitive sources """ + if (not ctx.attr._collect_external and ctx.label.workspace_root.startswith("external")): + # Nothing to gather on external targets + return [TransitiveSourcesInfo(srcs = depset())] + direct_files = [] srcs = ctx.rule.attr.srcs if hasattr(ctx.rule.attr, "srcs") else [] hdrs = ctx.rule.attr.hdrs if hasattr(ctx.rule.attr, "hdrs") else [] module_interfaces = ctx.rule.attr.module_interfaces if hasattr(ctx.rule.attr, "module_interfaces") else [] - data = ctx.rule.attr.data if hasattr(ctx.rule.attr, "data") else [] + data = ctx.rule.attr.data if (ctx.attr._collect_data_deps and hasattr(ctx.rule.attr, "data")) else [] for src in srcs + hdrs + module_interfaces + data: - if hasattr(src, "files"): - direct_files.extend(src.files.to_list()) + if not hasattr(src, "files"): + continue + for f in src.files.to_list(): + if not ctx.attr._collect_generated and f.root.path: + continue + direct_files.append(f) # Collect transitive files from dependencies transitive_files = [] @@ -49,11 +57,51 @@ def _collect_files_aspect_impl(_, ctx): srcs = depset(direct = direct_files, transitive = transitive_files), )] -collect_files_aspect = aspect( - implementation = _collect_files_aspect_impl, - attr_aspects = ["deps"], # recursively apply on deps - doc = "When applied to a target, this aspect collects the source files from the target and its dependencies, and makes them available in the TransitiveSourcesInfo provider.", -) +def collect_files_aspect_factory( + collect_external = False, + collect_generated = False, + collect_data_deps = False): + """ + Create a file collection aspect to gather files to be processed by doxygen. + + Use the factory in a `.bzl` file to instantiate an aspect: + ```starlark + load("@doxygen//:doxygen.bzl", "collect_files_aspect_factory") + + my_collect_files_aspect = collect_files_aspect_factory() + ``` + + Args: + collect_external: Collect (and document) source files from external dependencies (default: false). + collect_generated: Collect (and document) generated source files (default: false). + collect_data_deps: Collect (and document) source files from data dependencies (default: false). + """ + return aspect( + implementation = _collect_files_aspect_impl, + attr_aspects = ["deps"], # recursively apply on deps + provides = [TransitiveSourcesInfo], + doc = "When applied to a target, this aspect collects the source files from the target and its dependencies, and makes them available in the TransitiveSourcesInfo provider.", + attrs = { + "_collect_external": attr.bool( + default = collect_external, + doc = "Collect (and document) source files from external dependencies (default: false).", + ), + "_collect_generated": attr.bool( + default = collect_generated, + doc = "Collect (and document) generated source files (default: false).", + ), + "_collect_data_deps": attr.bool( + default = collect_data_deps, + doc = "Collect (and document) source files from data dependencies (default: false).", + ), + }, + ) + +# Default file collection aspect: +# - Skips external dependencies. +# - Skips generated files. +# - Skips data dependencies. +default_collect_files_aspect = collect_files_aspect_factory() def _doxygen_impl(ctx): doxyfile_prefix = ctx.attr.doxyfile_prefix @@ -110,8 +158,27 @@ def _doxygen_impl(ctx): OutputGroupInfo(**output_group_info), ] -_doxygen = rule( - doc = """Run the doxygen binary to generate the documentation. +def doxygen_rule_factory(collect_files_aspect = default_collect_files_aspect): + """ + Create an underlying doxygen rule to process files with doxygen. + + Use the factory in a `.bzl` file to instantiate a rule: + ```starlark + load("@doxygen//:doxygen.bzl", "doxygen_rule_factory") + + my_doxygen_rule = doxygen_rule_factory() + ``` + + This doxygen rule is not meant to be used directly, but instead, it should + be passed as the `doxygen_rule` argument to the `doxygen` macro. This rule + factory is only needed because some parameters affect the construction + of the build graph itself, and cannot be passed via ordinary rule arguments. + + Args: + collect_files_aspect: Custom file collection aspect, see `collect_files_aspect_factory` (default: `default_collect_files_aspect`). + """ + return rule( + doc = """Run the doxygen binary to generate the documentation. It is advised to use the `doxygen` macro instead of this rule directly. @@ -139,57 +206,59 @@ doxygen( ) ``` """, - implementation = _doxygen_impl, - attrs = { - "srcs": attr.label_list(allow_files = True, doc = "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": attr.label_list(aspects = [collect_files_aspect], doc = "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"), - "configurations": attr.string_list(doc = "Additional configuration parameters to append to the Doxyfile. For example, to set the project name, use `PROJECT_NAME = example`."), - "outs": attr.string_list(default = ["html"], allow_empty = False, doc = """Output folders to keep. If only the html outputs is of interest, the default value will do. Otherwise, a list of folders to keep is expected (e.g. `["html", "latex"]`)."""), - "doxyfile_prefix": attr.string(doc = "Prefix to add to the Doxyfile path.", default = ""), - "doxyfile_template": attr.label( - allow_single_file = True, - default = Label(":Doxyfile.template"), - doc = """Template file to use to generate the Doxyfile. You can provide your own or use the default one. + implementation = _doxygen_impl, + attrs = { + "srcs": attr.label_list(allow_files = True, doc = "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": attr.label_list(aspects = [collect_files_aspect], doc = "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"), + "configurations": attr.string_list(doc = "Additional configuration parameters to append to the Doxyfile. For example, to set the project name, use `PROJECT_NAME = example`."), + "outs": attr.string_list(default = ["html"], allow_empty = False, doc = """Output folders to keep. If only the html outputs is of interest, the default value will do. Otherwise, a list of folders to keep is expected (e.g. `["html", "latex"]`)."""), + "doxyfile_prefix": attr.string(doc = "Prefix to add to the Doxyfile path.", default = ""), + "doxyfile_template": attr.label( + allow_single_file = True, + default = Label(":Doxyfile.template"), + doc = """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. """, - ), - "use_default_shell_env": attr.bool( - default = False, - doc = "Whether to use the default shell environment when running doxygen.", - ), - "dot_executable": attr.label( - executable = True, - cfg = "exec", - allow_single_file = True, - doc = "dot executable to use. Must refer to an executable file.", - ), - "tools": attr.label_list( - allow_files = True, - doc = "List of additional tools to include in the doxygen environment. Tools are executable inputs that may have their own runfiles which are automatically made available to the action.", - ), - "doxygen_extra_args": attr.string_list(default = [], doc = "Extra arguments to pass to the doxygen executable."), - "host_platform": attr.string( - default = "other", - values = ["linux", "mac", "windows"], - doc = """The host platform to use for the doxygen executable. Can be one of: linux, mac, windows""", - ), - "env": attr.string_dict( - default = {}, - doc = "Environment variables to set when running doxygen.", - ), - "executable": attr.label( - executable = True, - cfg = "exec", - allow_single_file = True, - default = Label(":executable"), - doc = "doxygen executable to use. Must refer to an executable file.", - ), - }, -) + ), + "use_default_shell_env": attr.bool( + default = False, + doc = "Whether to use the default shell environment when running doxygen.", + ), + "dot_executable": attr.label( + executable = True, + cfg = "exec", + allow_single_file = True, + doc = "dot executable to use. Must refer to an executable file.", + ), + "tools": attr.label_list( + allow_files = True, + doc = "List of additional tools to include in the doxygen environment. Tools are executable inputs that may have their own runfiles which are automatically made available to the action.", + ), + "doxygen_extra_args": attr.string_list(default = [], doc = "Extra arguments to pass to the doxygen executable."), + "host_platform": attr.string( + default = "other", + values = ["linux", "mac", "windows"], + doc = """The host platform to use for the doxygen executable. Can be one of: linux, mac, windows""", + ), + "env": attr.string_dict( + default = {}, + doc = "Environment variables to set when running doxygen.", + ), + "executable": attr.label( + executable = True, + cfg = "exec", + allow_single_file = True, + default = Label(":executable"), + doc = "doxygen executable to use. Must refer to an executable file.", + ), + }, + ) + +default_doxygen_rule = doxygen_rule_factory() def _add_generic_configuration(configurations, name, value): if value == None: # Do not add the configuration if the value is None @@ -217,6 +286,7 @@ def doxygen( env = {}, tools = [], outs = ["html"], + doxygen_rule = default_doxygen_rule, # Doxygen specific attributes doxyfile_encoding = None, project_name = None, @@ -593,7 +663,10 @@ def doxygen( Hence, when the documentation is generated, all rules in the `srcs` attribute **will** be built, and the files they output will be passed to Doxygen. On the other hand, `deps` is a list of targets whose sources will be included in the documentation generation. - It will automatically include all the files in the `srcs`, `hdrs`, and `data` attributes of the target, and the same applies to all of its transitive dependencies, recursively. + It will automatically include all the files in the `srcs` and `hdrs` attributes of the target, and the same applies to + all of its transitive dependencies, recursively. + The `doxygen_rule` option can used to override default behaviors like skipping external, generated or + data dependencies when traversing the dependency tree. Since we are only interested in the source files, the `deps` targets **will not** be built when the documentation is generated. ```bzl @@ -724,6 +797,7 @@ def doxygen( outs: Output folders bazel will keep. If only the html outputs is of interest, the default value will do. otherwise, a list of folders to keep is expected (e.g. ["html", "latex"]). Note that the rule will also generate an output group for each folder in the outs list having the same name. + doxygen_rule: Underlying doxygen rule to use (default: default_doxygen_rule). doxyfile_encoding: This tag specifies the encoding used for all characters in the configuration file that follow. project_name: The `project_name` tag is a single word (or a sequence of words surrounded by double-quotes, unless you are using Doxywizard) that should identify the project for which the documentation is generated. @@ -1364,7 +1438,7 @@ def doxygen( if doxyfile_template: kwargs["doxyfile_template"] = doxyfile_template - _doxygen( + doxygen_rule( name = name, srcs = srcs, deps = deps, diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel index c67d7f8..b62afbe 100644 --- a/examples/MODULE.bazel +++ b/examples/MODULE.bazel @@ -14,11 +14,12 @@ bazel_dep(name = "platforms", version = "1.1.0") bazel_dep(name = "rules_java", version = "9.6.1") http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") + http_file( name = "plantuml_file", - urls = ["https://github.com/plantuml/plantuml/releases/download/v1.2025.4/plantuml-1.2025.4.jar"], - sha256 = "26518e14a3a04100cd76c0d96cab2d1171f36152215edd9790a28d20268200c1", downloaded_file_path = "plantuml.jar", + sha256 = "26518e14a3a04100cd76c0d96cab2d1171f36152215edd9790a28d20268200c1", + urls = ["https://github.com/plantuml/plantuml/releases/download/v1.2025.4/plantuml-1.2025.4.jar"], ) pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip") @@ -43,3 +44,10 @@ doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_ex # doxygen_extension.configuration(executable = "@//:doxygen") use_repo(doxygen_extension, "doxygen") + +# Example of an external dependency and code-generator. +bazel_dep(name = "greet_generator", version = "0.1.0") +local_path_override( + module_name = "greet_generator", + path = "third_party/greet_gen", +) diff --git a/examples/dependencies/BUILD.bazel b/examples/dependencies/BUILD.bazel index 130705b..a5b679d 100644 --- a/examples/dependencies/BUILD.bazel +++ b/examples/dependencies/BUILD.bazel @@ -1,5 +1,7 @@ load("@doxygen//:doxygen.bzl", "doxygen") +load("@greet_generator//:defs.bzl", "generate_greeting") load("@rules_cc//cc:defs.bzl", "cc_library") +load(":defs.bzl", "ext_and_gen_doxygen_rule") cc_library( name = "add", @@ -22,10 +24,21 @@ cc_library( ], ) +generate_greeting( + name = "greet", + greeting = "Hello world!", + greeting_version = 42, + strip_include_prefix = "//dependencies", +) + cc_library( name = "main", srcs = ["main.cpp"], - deps = [":lib"], + deps = [ + ":greet", + ":lib", + "@greet_generator//:greet_api", + ], ) genrule( @@ -49,3 +62,23 @@ doxygen( use_mdfile_as_mainpage = "dependencies/README.md", deps = [":main"], # cc_library ) + +# This demonstrates using a custom aspect and rule to also document external and generated source files. +# See defs.bzl for the custom aspect and rule construction. +doxygen( + name = "doxygen_ext_and_gen", + srcs = [ + "README.md", # file + ":section", # genrule + ], + outs = [ + "ext_and_gen/html", + "ext_and_gen/tags", + ], + doxyfile_prefix = "ext_and_gen", + doxygen_rule = ext_and_gen_doxygen_rule, + project_brief = "Example project for doxygen", + project_name = "dependencies", + use_mdfile_as_mainpage = "dependencies/README.md", + deps = [":main"], # cc_library +) diff --git a/examples/dependencies/defs.bzl b/examples/dependencies/defs.bzl new file mode 100644 index 0000000..5f60d6f --- /dev/null +++ b/examples/dependencies/defs.bzl @@ -0,0 +1,10 @@ +load("@doxygen//:doxygen.bzl", "collect_files_aspect_factory", "doxygen_rule_factory") + +collect_ext_and_gen_files_aspect = collect_files_aspect_factory( + collect_external=True, + collect_generated=True, +) + +ext_and_gen_doxygen_rule = doxygen_rule_factory( + collect_files_aspect=collect_ext_and_gen_files_aspect, +) diff --git a/examples/dependencies/main.cpp b/examples/dependencies/main.cpp index b2bdaa5..a06d736 100644 --- a/examples/dependencies/main.cpp +++ b/examples/dependencies/main.cpp @@ -1,5 +1,5 @@ /** - * @file lib.cpp + * @file main.cpp * @author Ernesto Casablanca (casablancaernesto@gmail.com) * @copyright 2024 */ @@ -7,8 +7,12 @@ #include #include "lib.h" +#include "greet.h" +#include "greet_gen.h" int main(int, char*[]) { + std::cout << greet::generated_greeting() << std::endl; + std::cout << greet::greeting_version << std::endl; int a = 5; int b = 10; std::cout << "a + b: " << lib::add(a, b) << std::endl; diff --git a/examples/third_party/BUILD.bazel b/examples/third_party/BUILD.bazel new file mode 100644 index 0000000..e69de29 diff --git a/examples/third_party/greet_gen/BUILD.bazel b/examples/third_party/greet_gen/BUILD.bazel new file mode 100644 index 0000000..8042048 --- /dev/null +++ b/examples/third_party/greet_gen/BUILD.bazel @@ -0,0 +1,7 @@ +load("@rules_cc//cc:defs.bzl", "cc_library") + +cc_library( + name="greet_api", + hdrs=["greet.h"], + visibility=["//visibility:public"], +) diff --git a/examples/third_party/greet_gen/MODULE.bazel b/examples/third_party/greet_gen/MODULE.bazel new file mode 100644 index 0000000..9b01de9 --- /dev/null +++ b/examples/third_party/greet_gen/MODULE.bazel @@ -0,0 +1,6 @@ +module( + name="greet_generator", + version="0.1.0", +) + +bazel_dep(name="rules_cc", version="0.2.17") diff --git a/examples/third_party/greet_gen/defs.bzl b/examples/third_party/greet_gen/defs.bzl new file mode 100644 index 0000000..674b1ca --- /dev/null +++ b/examples/third_party/greet_gen/defs.bzl @@ -0,0 +1,72 @@ +load("@rules_cc//cc:defs.bzl", "cc_library") + +GeneratedCcCode = provider( + doc="Holds generated source and header files", + fields={ + "src": "The generated .cpp file", + "hdr": "The generated .h file", + }, +) + + +def _generate_greeting_impl(ctx): + out_src_filename = ctx.attr.name + ".cpp" + out_src_file = ctx.actions.declare_file(out_src_filename) + + greeting_content = '/// @file {}\n/// @author Generated\n#include "greet.h"\n#include \nnamespace greet {{\nstd::string generated_greeting() {{\n return "{}";\n}}\n}} // namespace greet\n'.format( + out_src_filename, + ctx.attr.greeting, + ) + + ctx.actions.write( + output=out_src_file, + content=greeting_content, + ) + + out_hdr_filename = ctx.attr.name + ".h" + out_hdr_file = ctx.actions.declare_file(out_hdr_filename) + + greeting_version = "/// @file {}\n/// @author Generated\n#pragma once\nnamespace greet {{\nstatic const int greeting_version = {};\n}} // namespace greet\n".format( + out_hdr_filename, + ctx.attr.greeting_version, + ) + + ctx.actions.write( + output=out_hdr_file, + content=greeting_version, + ) + + # Return the file wrapped in DefaultInfo so other targets or command-line requests can find it + return [ + DefaultInfo(files=depset([out_src_file, out_hdr_file])), + GeneratedCcCode(src=out_src_file, hdr=out_hdr_file), + ] + + +# Define the custom rule schema +_generate_greeting = rule( + implementation=_generate_greeting_impl, + attrs={ + "greeting": attr.string(mandatory=True, doc="The text of the custom greeting."), + "greeting_version": attr.int( + mandatory=True, + doc="The version of the custom greeting.", + ), + }, +) + + +def generate_greeting(name, greeting, greeting_version, **kwargs): + _generate_greeting( + name=name + "_gen", + greeting=greeting, + greeting_version=greeting_version, + visibility=["//visibility:private"], + ) + cc_library( + name=name, + srcs=[name + "_gen"], + hdrs=[name + "_gen"], + deps=["@greet_generator//:greet_api"], + **kwargs + ) diff --git a/examples/third_party/greet_gen/greet.h b/examples/third_party/greet_gen/greet.h new file mode 100644 index 0000000..c083779 --- /dev/null +++ b/examples/third_party/greet_gen/greet.h @@ -0,0 +1,27 @@ +/** + * @file greet.h + * @author Ernesto Casablanca (casablancaernesto@gmail.com) + * @copyright 2026 + */ + +#ifndef GREET_GEN_GREET_H_ +#define GREET_GEN_GREET_H_ + +#include + +/** + * @brief Namespace for all greeting library functions. + */ +namespace greet { + +/** + * @brief Provides a custom generated greeting. + * + * Provides a custom generated greeting. + * @return Custom generated greeting. + */ +std::string generated_greeting(); + +} // namespace greet + +#endif // GREET_GEN_GREET_H_ From 74bc1fcc4c9305009883d1696b4f6c54fcbe8a50 Mon Sep 17 00:00:00 2001 From: Mikael Persson Date: Sat, 3 Oct 2026 15:39:03 -0400 Subject: [PATCH 2/6] Oops, removed stray provide --- examples/third_party/greet_gen/defs.bzl | 9 --------- 1 file changed, 9 deletions(-) diff --git a/examples/third_party/greet_gen/defs.bzl b/examples/third_party/greet_gen/defs.bzl index 674b1ca..ef2cb59 100644 --- a/examples/third_party/greet_gen/defs.bzl +++ b/examples/third_party/greet_gen/defs.bzl @@ -1,13 +1,5 @@ load("@rules_cc//cc:defs.bzl", "cc_library") -GeneratedCcCode = provider( - doc="Holds generated source and header files", - fields={ - "src": "The generated .cpp file", - "hdr": "The generated .h file", - }, -) - def _generate_greeting_impl(ctx): out_src_filename = ctx.attr.name + ".cpp" @@ -39,7 +31,6 @@ def _generate_greeting_impl(ctx): # Return the file wrapped in DefaultInfo so other targets or command-line requests can find it return [ DefaultInfo(files=depset([out_src_file, out_hdr_file])), - GeneratedCcCode(src=out_src_file, hdr=out_hdr_file), ] From f71f65c9fb3946c9e45128f8e9ba99964deae9bf Mon Sep 17 00:00:00 2001 From: Mikael Persson Date: Sun, 4 Oct 2026 12:13:41 -0400 Subject: [PATCH 3/6] Fixed issues reported in PR --- examples/dependencies/main.cpp | 2 +- examples/third_party/greet_gen/WORKSPACE | 14 ++++++ examples/third_party/greet_gen/defs.bzl | 58 ++++++++++++++---------- examples/third_party/greet_gen/greet.h | 6 +-- 4 files changed, 51 insertions(+), 29 deletions(-) create mode 100644 examples/third_party/greet_gen/WORKSPACE diff --git a/examples/dependencies/main.cpp b/examples/dependencies/main.cpp index a06d736..2888c8d 100644 --- a/examples/dependencies/main.cpp +++ b/examples/dependencies/main.cpp @@ -6,9 +6,9 @@ #include -#include "lib.h" #include "greet.h" #include "greet_gen.h" +#include "lib.h" int main(int, char*[]) { std::cout << greet::generated_greeting() << std::endl; diff --git a/examples/third_party/greet_gen/WORKSPACE b/examples/third_party/greet_gen/WORKSPACE new file mode 100644 index 0000000..fd205a8 --- /dev/null +++ b/examples/third_party/greet_gen/WORKSPACE @@ -0,0 +1,14 @@ +workspace(name = "greet_generator") + +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + +http_archive( + name = "rules_cc", + sha256 = "283fa1cdaaf172337898749cf4b9b1ef5ea269da59540954e51fba0e7b8f277a", + strip_prefix = "rules_cc-0.2.17", + url = "https://github.com/bazelbuild/rules_cc/releases/download/0.2.17/rules_cc-0.2.17.tar.gz", +) + +load("@rules_cc//cc:extensions.bzl", "compatibility_proxy_repo") + +compatibility_proxy_repo() diff --git a/examples/third_party/greet_gen/defs.bzl b/examples/third_party/greet_gen/defs.bzl index ef2cb59..be2dacf 100644 --- a/examples/third_party/greet_gen/defs.bzl +++ b/examples/third_party/greet_gen/defs.bzl @@ -1,63 +1,75 @@ load("@rules_cc//cc:defs.bzl", "cc_library") - def _generate_greeting_impl(ctx): out_src_filename = ctx.attr.name + ".cpp" out_src_file = ctx.actions.declare_file(out_src_filename) - greeting_content = '/// @file {}\n/// @author Generated\n#include "greet.h"\n#include \nnamespace greet {{\nstd::string generated_greeting() {{\n return "{}";\n}}\n}} // namespace greet\n'.format( + greeting_content = """/// @file {} +/// @author Generated +#include "greet.h" +#include +namespace greet {{ +std::string generated_greeting() {{ + return "{}"; +}} +}} // namespace greet +""".format( out_src_filename, ctx.attr.greeting, ) ctx.actions.write( - output=out_src_file, - content=greeting_content, + output = out_src_file, + content = greeting_content, ) out_hdr_filename = ctx.attr.name + ".h" out_hdr_file = ctx.actions.declare_file(out_hdr_filename) - greeting_version = "/// @file {}\n/// @author Generated\n#pragma once\nnamespace greet {{\nstatic const int greeting_version = {};\n}} // namespace greet\n".format( + greeting_version = """/// @file {} +/// @author Generated +#pragma once +namespace greet {{ +static const int greeting_version = {}; +}} // namespace greet +""".format( out_hdr_filename, ctx.attr.greeting_version, ) ctx.actions.write( - output=out_hdr_file, - content=greeting_version, + output = out_hdr_file, + content = greeting_version, ) # Return the file wrapped in DefaultInfo so other targets or command-line requests can find it return [ - DefaultInfo(files=depset([out_src_file, out_hdr_file])), + DefaultInfo(files = depset([out_src_file, out_hdr_file])), ] - # Define the custom rule schema _generate_greeting = rule( - implementation=_generate_greeting_impl, - attrs={ - "greeting": attr.string(mandatory=True, doc="The text of the custom greeting."), + implementation = _generate_greeting_impl, + attrs = { + "greeting": attr.string(mandatory = True, doc = "The text of the custom greeting."), "greeting_version": attr.int( - mandatory=True, - doc="The version of the custom greeting.", + mandatory = True, + doc = "The version of the custom greeting.", ), }, ) - def generate_greeting(name, greeting, greeting_version, **kwargs): _generate_greeting( - name=name + "_gen", - greeting=greeting, - greeting_version=greeting_version, - visibility=["//visibility:private"], + name = name + "_gen", + greeting = greeting, + greeting_version = greeting_version, + visibility = ["//visibility:private"], ) cc_library( - name=name, - srcs=[name + "_gen"], - hdrs=[name + "_gen"], - deps=["@greet_generator//:greet_api"], + name = name, + srcs = [name + "_gen"], + hdrs = [name + "_gen"], + deps = ["@greet_generator//:greet_api"], **kwargs ) diff --git a/examples/third_party/greet_gen/greet.h b/examples/third_party/greet_gen/greet.h index c083779..dcaf65d 100644 --- a/examples/third_party/greet_gen/greet.h +++ b/examples/third_party/greet_gen/greet.h @@ -3,9 +3,7 @@ * @author Ernesto Casablanca (casablancaernesto@gmail.com) * @copyright 2026 */ - -#ifndef GREET_GEN_GREET_H_ -#define GREET_GEN_GREET_H_ +#pragma once #include @@ -23,5 +21,3 @@ namespace greet { std::string generated_greeting(); } // namespace greet - -#endif // GREET_GEN_GREET_H_ From 04b91ac801a2b751a3d64a97927b2ed923779d70 Mon Sep 17 00:00:00 2001 From: Mikael Persson Date: Sun, 4 Oct 2026 20:13:39 -0400 Subject: [PATCH 4/6] Renamed TransitiveSourcesInfo to DoxygenCollectedSourcesInfo --- doxygen/doxygen.bzl | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doxygen/doxygen.bzl b/doxygen/doxygen.bzl index 8000414..8ba8f71 100644 --- a/doxygen/doxygen.bzl +++ b/doxygen/doxygen.bzl @@ -15,8 +15,8 @@ def _expand_make_variables(string, ctx, extra_sub_vars = {}): string = string.replace("$(%s)" % variable, value) return string -TransitiveSourcesInfo = provider( - "A provider to collect source files transitively from the target and its dependencies", +DoxygenCollectedSourcesInfo = provider( + "A provider to collect source files for doxygen that are transitively upstream from a target", fields = {"srcs": "depset of source files collected from the target and its dependencies"}, ) @@ -28,11 +28,11 @@ def _collect_files_aspect_impl(_, ctx): ctx: aspect context Returns: - TransitiveSourcesInfo with a depset of transitive sources + DoxygenCollectedSourcesInfo with a depset of transitive sources """ if (not ctx.attr._collect_external and ctx.label.workspace_root.startswith("external")): # Nothing to gather on external targets - return [TransitiveSourcesInfo(srcs = depset())] + return [DoxygenCollectedSourcesInfo(srcs = depset())] direct_files = [] srcs = ctx.rule.attr.srcs if hasattr(ctx.rule.attr, "srcs") else [] @@ -50,10 +50,10 @@ def _collect_files_aspect_impl(_, ctx): # Collect transitive files from dependencies transitive_files = [] for dep in ctx.rule.attr.deps if hasattr(ctx.rule.attr, "deps") else []: - if TransitiveSourcesInfo in dep: - transitive_files.append(dep[TransitiveSourcesInfo].srcs) + if DoxygenCollectedSourcesInfo in dep: + transitive_files.append(dep[DoxygenCollectedSourcesInfo].srcs) - return [TransitiveSourcesInfo( + return [DoxygenCollectedSourcesInfo( srcs = depset(direct = direct_files, transitive = transitive_files), )] @@ -79,8 +79,8 @@ def collect_files_aspect_factory( return aspect( implementation = _collect_files_aspect_impl, attr_aspects = ["deps"], # recursively apply on deps - provides = [TransitiveSourcesInfo], - doc = "When applied to a target, this aspect collects the source files from the target and its dependencies, and makes them available in the TransitiveSourcesInfo provider.", + provides = [DoxygenCollectedSourcesInfo], + doc = "When applied to a target, this aspect collects the source files from the target and its dependencies, and makes them available in the DoxygenCollectedSourcesInfo provider.", attrs = { "_collect_external": attr.bool( default = collect_external, @@ -119,7 +119,7 @@ def _doxygen_impl(ctx): if len(outs) == 0: fail("At least one output folder must be specified") - deps = depset(transitive = [dep[TransitiveSourcesInfo].srcs for dep in ctx.attr.deps]).to_list() + deps = depset(transitive = [dep[DoxygenCollectedSourcesInfo].srcs for dep in ctx.attr.deps]).to_list() input_dirs = {(file.dirname or "."): None for file in ctx.files.srcs + deps} ctx.actions.expand_template( template = ctx.file.doxyfile_template, @@ -618,7 +618,7 @@ def doxygen( For the complete list of Doxygen configuration options, please refer to the [Doxygen documentation](https://www.doxygen.nl/manual/config.html). - > [!NOTE] + > [!NOTE] > If not istructed otherwise, the rule will use the Doxyfile from its default `doxygen` version. > Any update could change some default values or add some flags which will be unrecognized by older `doxygen` versions, resulting in innocuous warnings. > If you want to use a specific Doxyfile, just generate one with `doxygen -g` and specify it in the `doxyfile_template` attribute. @@ -646,7 +646,7 @@ def doxygen( ) ``` - > [!NOTE] + > [!NOTE] > Make sure that generated files are put in some directory and that directory is included in the `outs` attribute. You can add your own substitutions by adding a rule that returns a TemplateVariableInfo provider in the `toolchains` attribute of the `doxygen` rule. From 163917f774253fbe8bcb23b1864fe5e3dd8471f0 Mon Sep 17 00:00:00 2001 From: Mikael Persson Date: Sat, 10 Oct 2026 14:34:55 -0400 Subject: [PATCH 5/6] Added doxygen_skip tag. Updated markdown docs with new features --- README.md | 7 +- docs/doxygen_doc.md | 110 ++++++++++++++++++++++----- doxygen/doxygen.bzl | 3 +- examples/dependencies/BUILD.bazel | 7 ++ examples/dependencies/main.cpp | 3 +- examples/dependencies/weird_header.h | 18 +++++ 6 files changed, 124 insertions(+), 24 deletions(-) create mode 100644 examples/dependencies/weird_header.h diff --git a/README.md b/README.md index 0ab9c42..342bedb 100644 --- a/README.md +++ b/README.md @@ -154,8 +154,8 @@ doxygen( "*.cpp", ]) + ["README.md"], # Additionally, you can use the `deps` attribute to select a target - # and automatically include all of the files in its `srcs`, `hdrs`, and `data` attributes, - # along with all of its transitive dependencies. + # and automatically include all of the files in its `srcs` and `hdrs` attributes, + # along with all of its transitive dependencies (excluding external or generated files). # deps = [":my_cc_target"], project_brief = DESCRIPTION, # Brief description of the project project_name = NAME, # Name of the project @@ -180,7 +180,8 @@ doxygen( > [!NOTE] > `srcs` and `deps` attributes are **not** interchangeable. -> Use `srcs` with files and when you want to capture the output of another rule, and use `deps` when you want to capture the source files of other rules transitively. +> Use `srcs` with files and when you want to capture the output of another rule, and use `deps` when you want to capture the source files of other rules transitively. See the [documentation](docs/doxygen_doc.md) for more information. The `"doxygen_skip"` tag can be added to the `tags` attribute of +a target to exclude it during the transitive dependencies being gathered. Use the [Doxygen documentation](https://www.doxygen.nl/manual/config.html) or generate a brand new _Doxyfile_ with `doxygen -g` to see all the available options to put in the `configurations` list. They will simply be appended at the end of the file, overriding the default values. diff --git a/docs/doxygen_doc.md b/docs/doxygen_doc.md index 0d02a6a..909ac02 100755 --- a/docs/doxygen_doc.md +++ b/docs/doxygen_doc.md @@ -2,14 +2,14 @@ Doxygen rule for Bazel. - + -## TransitiveSourcesInfo +## DoxygenCollectedSourcesInfo
-load("@rules_doxygen//doxygen:doxygen.bzl", "TransitiveSourcesInfo")
+load("@rules_doxygen//doxygen:doxygen.bzl", "DoxygenCollectedSourcesInfo")
 
-TransitiveSourcesInfo(srcs)
+DoxygenCollectedSourcesInfo(srcs)
 
A provider to collect source files transitively from the target and its dependencies @@ -18,7 +18,7 @@ A provider to collect source files transitively from the target and its dependen | Name | Description | | :------------- | :------------- | -| srcs | depset of source files collected from the target and its dependencies | +| srcs | depset of source files collected from the target and its dependencies | @@ -29,7 +29,7 @@ A provider to collect source files transitively from the target and its dependen load("@doxygen//:doxygen.bzl", "doxygen") doxygen(name, srcs, deps, executable, dot_executable, configurations, doxyfile_prefix, - doxyfile_template, doxygen_extra_args, use_default_shell_env, env, tools, outs, + doxyfile_template, doxygen_extra_args, use_default_shell_env, env, tools, outs, doxygen_rule, doxyfile_encoding, project_name, project_number, project_brief, project_logo, project_icon, create_subdirs, create_subdirs_level, allow_unicode_names, output_language, brief_member_desc, repeat_brief, abbreviate_brief, always_detailed_sec, inline_inherited_memb, full_path_names, @@ -155,9 +155,18 @@ More precisely, the files in the DefaultInfo provider the target returns. Hence, when the documentation is generated, all rules in the `srcs` attribute **will** be built, and the files they output will be passed to Doxygen. On the other hand, `deps` is a list of targets whose sources will be included in the documentation generation. -It will automatically include all the files in the `srcs`, `hdrs`, and `data` attributes of the target, and the same applies to all of its transitive dependencies, recursively. +It will automatically include all the files in the `srcs` and `hdrs` attributes of the target, and the same applies to all +of its transitive `deps` dependencies, recursively, unless a target has `"doxygen_skip"` in its `tags` attribute. Since we are only interested in the source files, the `deps` targets **will not** be built when the documentation is generated. +Furthermore, collection of source files through the `deps` targets and their dependencies will stop at (and exclude) +external targets, generated source files, and `data` dependencies, since those are not files that users +typically want to document and only excluding them via the doxygen `exclude_patterns` parameter will still require them +in the build-graph (and Bazel's cache). Specific files that should be included, but get excluded from `deps` as described, +can be passed through the `srcs` attribute instead. To customize this behavior, see +the `doxygen_rule` parameter and +the `collect_files_aspect_factory` factory function for the file collection aspect. + ```bzl # My BUILD.bazel file load("@doxygen//:doxygen.bzl", "doxygen") @@ -169,10 +178,17 @@ cc_library( srcs = ["add.cpp", "sub.cpp"], ) +cc_library( + name = "weird_lib", + hdrs = ["weird_header.h"], + # This weird library breaks doxygen, so skip it. + tags = ["doxygen_skip"], +) + cc_library( name = "main", srcs = ["main.cpp"], - deps = [":lib"], + deps = [":lib", ":weird_lib"], ) @@ -211,12 +227,17 @@ doxygen( ) ``` -### Excluding Bazel specific folders +### Excluding Bazel specific folders or targets Including the root directory among the input directories, which happens when a target starting with `//:` is used as a source, may cause Bazel specific folders, such as `external`, to be explored by Doxygen. This can slow down the documentation generation or even cause an input buffer overflow. -To avoid this, it is recommended to use the `exclude_patterns` parameter and set it to something like `["*/external/*"]`, extending it with other patterns as needed. +To avoid this, it is recommended to use the `exclude_patterns` parameter and set it to something like `["*/external/*"]`, +extending it with other patterns as needed. + +Furthermore, when using the `deps` parameter which collects transitive dependencies (preferred for source code files), +the default behavior is to **exclude** external files, generated files and data dependencies. Also, any target +not falling into one of these categories can also be excluded by adding the `"doxygen_skip"` tag to its `tags` attribute. ### Example @@ -279,6 +300,7 @@ doxygen( | env | Additional environment variables to set when running doxygen. | `{}` | | tools | List of additional tools to include in the doxygen environment. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. | `[]` | | outs | Output folders bazel will keep. If only the html outputs is of interest, the default value will do. otherwise, a list of folders to keep is expected (e.g. ["html", "latex"]). Note that the rule will also generate an output group for each folder in the outs list having the same name. | `["html"]` | +| doxygen_rule | Underlying doxygen rule to use. Custom doxygen rules can be created via `doxygen_rule_factory` and `collect_files_aspect_factory` from `doxygen.bzl` to modify the default behaviors. | `default_doxygen_rule` } | doxyfile_encoding | This tag specifies the encoding used for all characters in the configuration file that follow. | `None` | | project_name | The `project_name` tag is a single word (or a sequence of words surrounded by double-quotes, unless you are using Doxywizard) that should identify the project for which the documentation is generated. | `None` | | project_number | The `project_number` tag can be used to enter a project or revision number. | `None` | @@ -598,25 +620,75 @@ doxygen( | kwargs | Additional arguments to pass to the rule (e.g. `visibility = ["//visibility:public"], tags = ["manual"]`) | none | - + -## collect_files_aspect +## default_collect_files_aspect
-load("@rules_doxygen//doxygen:doxygen.bzl", "collect_files_aspect")
+load("@rules_doxygen//doxygen:doxygen.bzl", "default_collect_files_aspect")
+
+ +When applied to a target, this aspect collects the source files from the target and its dependencies, and makes them available +in the DoxygenCollectedSourcesInfo provider. + + -collect_files_aspect() +## default_doxygen_rule + +
+load("@rules_doxygen//doxygen:doxygen.bzl", "default_doxygen_rule")
 
-When applied to a target, this aspect collects the source files from the target and its dependencies, and makes them available in the TransitiveSourcesInfo provider. +This is the default doxygen rule used by the `doxygen` macro, which can be changed using +the `doxygen_rule` parameter of the macro. +This default rule is tied to the default collection aspect `default_collect_files_aspect` +whose behavior is described in the `doxygen` macro documentation above. -**ASPECT ATTRIBUTES** + +## doxygen_rule_factory -| Name | Type | -| :------------- | :------------- | -| deps| String | +
+load("@rules_doxygen//doxygen:doxygen.bzl", "doxygen_rule_factory")
+
+my_doxygen_rule = doxygen_rule_factory(collect_files_aspect = my_collect_files_aspect)
+
+ +This is a factory function (macro) to construct a doxygen rule (see parameter `doxygen_rule`) +suitable for the doxygen macro to use. Its primary purpose is to make the doxygen rule use a particular +aspect for collecting files to hand down to doxygen by walking through the transitive dependencies. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| collect_files_aspect | Custom file collection aspect, see `collect_files_aspect_factory`. | default_collect_files_aspect | + + + +## collect_files_aspect_factory + +
+load("@rules_doxygen//doxygen:doxygen.bzl", "collect_files_aspect_factory")
 
+my_collect_files_aspect = collect_files_aspect_factory()
+
+ +This is a factory function (macro) to construct a file collection aspect (see parameter `doxygen_rule`) +suitable for a doxygen rule created with `doxygen_rule_factory`. This can be used +to customize the collection of files when walking through the transitive dependencies. +Alternatively, the user can also create an entirely custom aspect that provides +the DoxygenCollectedSourcesInfo provider to have full control over file collection. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| collect_external | Collect files from external dependencies. | False | +| collect_generated | Collect files from generated files (e.g., protobuf generated sources). | False | +| collect_external | Collect files from data dependencies. | False | diff --git a/doxygen/doxygen.bzl b/doxygen/doxygen.bzl index 8ba8f71..bbb99f9 100644 --- a/doxygen/doxygen.bzl +++ b/doxygen/doxygen.bzl @@ -30,7 +30,8 @@ def _collect_files_aspect_impl(_, ctx): Returns: DoxygenCollectedSourcesInfo with a depset of transitive sources """ - if (not ctx.attr._collect_external and ctx.label.workspace_root.startswith("external")): + hasskiptag = (hasattr(ctx.rule.attr, "tags") and "doxygen_skip" in ctx.rule.attr.tags) + if hasskiptag or (not ctx.attr._collect_external and ctx.label.workspace_root.startswith("external")): # Nothing to gather on external targets return [DoxygenCollectedSourcesInfo(srcs = depset())] diff --git a/examples/dependencies/BUILD.bazel b/examples/dependencies/BUILD.bazel index a5b679d..5663da1 100644 --- a/examples/dependencies/BUILD.bazel +++ b/examples/dependencies/BUILD.bazel @@ -15,6 +15,12 @@ cc_library( hdrs = ["sub.h"], ) +cc_library( + name = "weird_lib", + hdrs = ["weird_header.h"], + tags = ["doxygen_skip"], +) + cc_library( name = "lib", hdrs = ["lib.h"], @@ -37,6 +43,7 @@ cc_library( deps = [ ":greet", ":lib", + ":weird_lib", "@greet_generator//:greet_api", ], ) diff --git a/examples/dependencies/main.cpp b/examples/dependencies/main.cpp index 2888c8d..f14be4f 100644 --- a/examples/dependencies/main.cpp +++ b/examples/dependencies/main.cpp @@ -9,11 +9,12 @@ #include "greet.h" #include "greet_gen.h" #include "lib.h" +#include "weird_header.h" int main(int, char*[]) { std::cout << greet::generated_greeting() << std::endl; std::cout << greet::greeting_version << std::endl; - int a = 5; + int a = lib::pointless_identity<5>(); int b = 10; std::cout << "a + b: " << lib::add(a, b) << std::endl; std::cout << "a - b: " << lib::sub(a, b) << std::endl; diff --git a/examples/dependencies/weird_header.h b/examples/dependencies/weird_header.h new file mode 100644 index 0000000..abf789d --- /dev/null +++ b/examples/dependencies/weird_header.h @@ -0,0 +1,18 @@ +/** + * @file weird_header.h + * @author Ernesto Casablanca (casablancaernesto@gmail.com) + * @copyright 2024 + */ +#pragma once + +namespace lib { + +/** + * @briefly_described Provide the int you gave. + * + * Provide the int you gave. + * @be_warned I like to use custom doxygen tags that break everyone's workflows for no reason. + */ +template int pointless_identity() { return I; } + +} // namespace lib \ No newline at end of file From 11a3e3f7418660fdb82c920185536920a979ed0b Mon Sep 17 00:00:00 2001 From: Mikael Persson Date: Sat, 10 Oct 2026 14:49:57 -0400 Subject: [PATCH 6/6] A little oopsie --- docs/doxygen_doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/doxygen_doc.md b/docs/doxygen_doc.md index 909ac02..4ad44d2 100755 --- a/docs/doxygen_doc.md +++ b/docs/doxygen_doc.md @@ -300,7 +300,7 @@ doxygen( | env | Additional environment variables to set when running doxygen. | `{}` | | tools | List of additional tools to include in the doxygen environment. Tools are executable inputs that may have their own runfiles which are automatically made available to the action. | `[]` | | outs | Output folders bazel will keep. If only the html outputs is of interest, the default value will do. otherwise, a list of folders to keep is expected (e.g. ["html", "latex"]). Note that the rule will also generate an output group for each folder in the outs list having the same name. | `["html"]` | -| doxygen_rule | Underlying doxygen rule to use. Custom doxygen rules can be created via `doxygen_rule_factory` and `collect_files_aspect_factory` from `doxygen.bzl` to modify the default behaviors. | `default_doxygen_rule` } +| doxygen_rule | Underlying doxygen rule to use. Custom doxygen rules can be created via `doxygen_rule_factory` and `collect_files_aspect_factory` from `doxygen.bzl` to modify the default behaviors. | `default_doxygen_rule` | | doxyfile_encoding | This tag specifies the encoding used for all characters in the configuration file that follow. | `None` | | project_name | The `project_name` tag is a single word (or a sequence of words surrounded by double-quotes, unless you are using Doxywizard) that should identify the project for which the documentation is generated. | `None` | | project_number | The `project_number` tag can be used to enter a project or revision number. | `None` |