diff --git a/.bcr/presubmit.yml b/.bcr/presubmit.yml
index fa8c97e..612cb37 100644
--- a/.bcr/presubmit.yml
+++ b/.bcr/presubmit.yml
@@ -17,3 +17,4 @@ bcr_test_module:
- "//awesome:doxygen"
- "//kwargs:doxygen"
- "//substitutions:doxygen"
+ - "//dependencies:doxygen"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f343f53..e52ccc5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,6 +25,7 @@ jobs:
custom,
awesome,
substitutions,
+ dependencies,
]
exclude:
# In substitution example we use `string_keyed_label_dict`, which is not supported in bazel 7.0.0
@@ -54,17 +55,7 @@ jobs:
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
- subdir:
- [
- base,
- kwargs,
- doxyfile,
- latex,
- nested,
- custom,
- awesome,
- substitutions,
- ]
+ subdir: [base]
runs-on: ${{ matrix.os }}
steps:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b5a423..75f385e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [2.2.3]
+
+### Added
+
+- Support for dependency inclusion in the `doxygen` rule [#24](https://github.com/TendTo/rules_doxygen/pull/24) (thanks to @oxidase)
+
+### Changed
+
+- `srcs` attribute in the `doxygen` macro is now optional, as it defaults to `[]`
+- Updated documentation
+
## [2.2.2]
### Added
@@ -155,4 +166,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
[2.2.0]: https://github.com/TendTo/rules_doxygen/compare/2.1.0...2.2.0
[2.2.1]: https://github.com/TendTo/rules_doxygen/compare/2.2.0...2.2.1
[2.2.2]: https://github.com/TendTo/rules_doxygen/compare/2.2.1...2.2.2
-[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/2.2.2...HEAD
+[2.2.3]: https://github.com/TendTo/rules_doxygen/compare/2.2.2...2.2.3
+[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/2.2.3...HEAD
diff --git a/README.md b/README.md
index 587df59..2dc2e1f 100644
--- a/README.md
+++ b/README.md
@@ -150,6 +150,10 @@ doxygen(
"*.h", # Usually includes the source files and the markdown files.
"*.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.
+ # deps = [":my_cc_target"],
project_brief = DESCRIPTION, # Brief description of the project
project_name = NAME, # Name of the project
generate_html = True, # Whether to generate HTML output
@@ -173,6 +177,73 @@ They will simply be appended at the end of the file, overriding the default valu
> [!Note]
> See the [documentation](docs/doxygen_doc.md) for more information or the [examples](examples) directory for examples of how to use the rules.
+### Differences between `srcs` and `deps`
+
+The `srcs` and `deps` attributes work differently, and are not interchangeable.
+
+`srcs` is a list of files that will be passed to Doxygen for documentation generation.
+You can use `glob` to include a collection of multiple files.
+On the other hand, if you indicate a target (e.g., `:my_genrule`), it will include all the files produced by that target.
+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.
+Since we are only interested in the source files, the `deps` targets **will not** be built when the documentation is generated.
+
+```bzl
+# My BUILD.bazel file
+load("@doxygen//:doxygen.bzl", "doxygen")
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+cc_library(
+ name = "lib",
+ hdrs = ["add.h", "sub.h"],
+ srcs = ["add.cpp", "sub.cpp"],
+)
+
+cc_library(
+ name = "main",
+ srcs = ["main.cpp"],
+ deps = [":lib"],
+)
+
+
+genrule(
+ name = "section",
+ outs = ["Section.md"],
+ cmd = """
+ echo "# Section " > $@
+ echo "This is some amazing documentation with section!! " >> $@
+ echo "Incredible." >> $@
+ """,
+)
+
+doxygen(
+ name = "doxygen",
+ project_name = "dependencies",
+
+ # The output of the genrule will be included in the documentation.
+ # The genrule will be executed when the documentation is generated.
+ srcs = [
+ "README.md", # file
+ ":section", # genrule
+
+ # WARNING: By adding this, the main target will be built
+ # and only the output file `main.o` will be passed to Doxygen,
+ # which is likely not what you want.
+ # ":main"
+ ],
+
+ # The sources of the main target and its dependencies will be included.
+ # No compilation will be performed, so compile error won't be reported.
+ deps = [":main"], # cc_library
+
+ # Always starts at the root folder
+ use_mdfile_as_mainpage = "dependencies/README.md",
+)
+```
+
## Build
To build the documentation, run the following command:
diff --git a/docs/doxygen_doc.md b/docs/doxygen_doc.md
index 9a0c76c..be8c6fe 100755
--- a/docs/doxygen_doc.md
+++ b/docs/doxygen_doc.md
@@ -2,6 +2,25 @@
Doxygen rule for Bazel.
+
+
+## TransitiveSourcesInfo
+
+
+load("@rules_doxygen//doxygen:doxygen.bzl", "TransitiveSourcesInfo")
+
+TransitiveSourcesInfo(srcs)
+
+
+A provider to collect source files transitively from the target and its dependencies
+
+**FIELDS**
+
+| Name | Description |
+| :------------- | :------------- |
+| srcs | depset of source files collected from the target and its dependencies |
+
+
## doxygen
@@ -9,22 +28,23 @@ Doxygen rule for Bazel.
load("@doxygen//:doxygen.bzl", "doxygen")
-doxygen(name, srcs, dot_executable, configurations, doxyfile_template, doxygen_extra_args, outs,
- 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,
- strip_from_path, strip_from_inc_path, short_names, javadoc_autobrief, javadoc_banner,
- qt_autobrief, multiline_cpp_is_brief, python_docstring, inherit_docs, separate_member_pages,
- tab_size, aliases, optimize_output_for_c, optimize_output_java, optimize_for_fortran,
- optimize_output_vhdl, optimize_output_slice, extension_mapping, markdown_support,
- toc_include_headings, markdown_id_style, autolink_support, autolink_ignore_words,
- builtin_stl_support, cpp_cli_support, sip_support, idl_property_support, distribute_group_doc,
- group_nested_compounds, subgrouping, inline_grouped_classes, inline_simple_structs,
- typedef_hides_struct, lookup_cache_size, num_proc_threads, timestamp, extract_all,
- extract_private, extract_priv_virtual, extract_package, extract_static, extract_local_classes,
- extract_local_methods, extract_anon_nspaces, resolve_unnamed_params, hide_undoc_members,
- hide_undoc_classes, hide_undoc_namespaces, hide_friend_compounds, hide_in_body_docs,
- internal_docs, case_sense_names, hide_scope_names, hide_compound_reference, show_headerfile,
+doxygen(name, srcs, deps, dot_executable, configurations, doxyfile_template, doxygen_extra_args,
+ outs, 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, strip_from_path, strip_from_inc_path, short_names, javadoc_autobrief,
+ javadoc_banner, qt_autobrief, multiline_cpp_is_brief, python_docstring, inherit_docs,
+ separate_member_pages, tab_size, aliases, optimize_output_for_c, optimize_output_java,
+ optimize_for_fortran, optimize_output_vhdl, optimize_output_slice, extension_mapping,
+ markdown_support, toc_include_headings, markdown_id_style, autolink_support,
+ autolink_ignore_words, builtin_stl_support, cpp_cli_support, sip_support,
+ idl_property_support, distribute_group_doc, group_nested_compounds, subgrouping,
+ inline_grouped_classes, inline_simple_structs, typedef_hides_struct, lookup_cache_size,
+ num_proc_threads, timestamp, extract_all, extract_private, extract_priv_virtual,
+ extract_package, extract_static, extract_local_classes, extract_local_methods,
+ extract_anon_nspaces, resolve_unnamed_params, hide_undoc_members, hide_undoc_classes,
+ hide_undoc_namespaces, hide_friend_compounds, hide_in_body_docs, internal_docs,
+ case_sense_names, hide_scope_names, hide_compound_reference, show_headerfile,
show_include_files, show_grouped_memb_inc, force_local_includes, inline_info,
sort_member_docs, sort_brief_docs, sort_members_ctors_1st, sort_group_names,
sort_by_scope_name, strict_proto_matching, generate_todolist, generate_testlist,
@@ -85,25 +105,40 @@ Depending on the type of the attribute, the macro will convert it to the appropr
- list: the value of the attribute is a string with the elements separated by spaces and enclosed in double quotes
- str: the value of the attribute is will be set to the string, unchanged. You may need to provide proper quoting if the value contains spaces
+For the complete list of Doxygen configuration options, please refer to the [Doxygen documentation](https://www.doxygen.nl/manual/config.html).
+
### Example
-```starlark
+```bzl
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", dev_dependency = True)
doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
use_repo(doxygen_extension, "doxygen")
```
-```starlark
+```bzl
# BUILD.bazel file
load("@doxygen//:doxygen.bzl", "doxygen")
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+cc_library(
+ name = "lib",
+ srcs = ["add.cpp", "sub.cpp"],
+ hdrs = ["add.h", "sub.h"],
+)
+
+cc_library(
+ name = "main",
+ srcs = ["main.cpp"],
+ deps = [":lib"],
+)
doxygen(
name = "doxygen",
srcs = glob([
- "*.h",
- "*.cpp",
+ "*.md",
]),
+ deps = [":main"]
aliases = [
"licence=@par Licence:^^",
"verb{1}=@verbatim \\1 @endverbatim",
@@ -121,7 +156,8 @@ doxygen(
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | A name for the target. | none |
-| srcs | A list of source files to generate documentation for. | none |
+| srcs | A list of source files to generate documentation for. | `[]` |
+| deps | A list of dependencies whose source, header and data files, and those or the transitive dependencies, will be included in the documentation. | `[]` |
| 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. | `None` |
| 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. | `None` |
@@ -435,3 +471,25 @@ doxygen(
| kwargs | Additional arguments to pass to the rule (e.g. `visibility = ["//visibility:public"], tags = ["manual"]`) | none |
+
+
+## collect_files_aspect
+
+
+load("@rules_doxygen//doxygen:doxygen.bzl", "collect_files_aspect")
+
+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 TransitiveSourcesInfo provider.
+
+**ASPECT ATTRIBUTES**
+
+
+| Name | Type |
+| :------------- | :------------- |
+| deps| String |
+
+
+
+
diff --git a/docs/extensions_doc.md b/docs/extensions_doc.md
index 25aeea5..d7d6c55 100755
--- a/docs/extensions_doc.md
+++ b/docs/extensions_doc.md
@@ -72,7 +72,7 @@ You can further customize the repository by specifying the `doxygen_bzl`, `build
### Example
-```starlark
+```bzl
# Download the os specific version 1.12.0 of doxygen supporting all the indicated platforms
doxygen_repository(
name = "doxygen",
@@ -180,7 +180,7 @@ No download will be performed, and the file indicated by the label will be used
### Examples
-```starlark
+```bzl
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
@@ -198,7 +198,7 @@ doxygen_extension.configuration(
use_repo(doxygen_extension, "doxygen")
```
-```starlark
+```bzl
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
diff --git a/doxygen/doxygen.bzl b/doxygen/doxygen.bzl
index 02e0828..7d9ed8e 100644
--- a/doxygen/doxygen.bzl
+++ b/doxygen/doxygen.bzl
@@ -2,7 +2,7 @@
def _expand_make_variables(string, ctx):
"""Replace make variables in a string with their values.
-
+
Args:
string: The string to expand.
ctx: The context object.
@@ -12,6 +12,45 @@ def _expand_make_variables(string, ctx):
string = string.replace("$(%s)" % variable, value)
return string
+TransitiveSourcesInfo = provider(
+ "A provider to collect source files transitively from the target and its dependencies",
+ fields = {"srcs": "depset of source files collected from the target and its dependencies"},
+)
+
+def _collect_files_aspect_impl(_, ctx):
+ """Collect transitive source files from dependencies.
+
+ Args:
+ _: target context. Not used in this aspect
+ ctx: aspect context
+
+ Returns:
+ TransitiveSourcesInfo with a depset of transitive sources
+ """
+ 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 []
+ data = ctx.rule.attr.data if hasattr(ctx.rule.attr, "data") else []
+ for src in srcs + hdrs + data:
+ if hasattr(src, "files"):
+ direct_files.extend(src.files.to_list())
+
+ # 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)
+
+ return [TransitiveSourcesInfo(
+ 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 _doxygen_impl(ctx):
doxyfile = ctx.actions.declare_file("Doxyfile")
@@ -27,7 +66,8 @@ def _doxygen_impl(ctx):
if len(outs) == 0:
fail("At least one output folder must be specified")
- input_dirs = {(file.dirname or "."): None for file in ctx.files.srcs}
+ 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}
ctx.actions.expand_template(
template = ctx.file.doxyfile_template,
output = doxyfile,
@@ -40,7 +80,7 @@ def _doxygen_impl(ctx):
)
ctx.actions.run(
- inputs = ctx.files.srcs + [doxyfile],
+ inputs = ctx.files.srcs + deps + [doxyfile],
outputs = outs,
arguments = [doxyfile.path] + ctx.attr.doxygen_extra_args,
progress_message = "Running doxygen",
@@ -59,14 +99,14 @@ It is advised to use the `doxygen` macro instead of this rule directly.
### Example
-```starlark
+```bzl
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", dev_dependency = True)
doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
use_repo(doxygen_extension, "doxygen")
```
-```starlark
+```bzl
# BUILD.bazel file
load("@doxygen//:doxygen.bzl", "doxygen")
@@ -83,14 +123,15 @@ doxygen(
""",
implementation = _doxygen_impl,
attrs = {
- "srcs": attr.label_list(allow_files = True, doc = "The source files to generate documentation for. Can include header files, source files, and any other file Doxygen can parse."),
+ "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 = """The 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"]`)."""),
+ "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_template": attr.label(
allow_single_file = True,
default = Label(":Doxyfile.template"),
- 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:
+ 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.
@@ -101,7 +142,7 @@ The following substitutions are available:
executable = True,
cfg = "exec",
allow_single_file = True,
- doc = "The dot executable to use. Must refer to an executable file.",
+ doc = "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(
@@ -109,7 +150,7 @@ The following substitutions are available:
cfg = "exec",
allow_single_file = True,
default = Label(":executable"),
- doc = "The doxygen executable to use. Must refer to an executable file.",
+ doc = "doxygen executable to use. Must refer to an executable file.",
),
},
)
@@ -127,7 +168,8 @@ def _add_generic_configuration(configurations, name, value):
def doxygen(
name,
- srcs,
+ srcs = [],
+ deps = [],
# Bazel specific attributes
dot_executable = None,
configurations = None,
@@ -452,25 +494,40 @@ def doxygen(
- list: the value of the attribute is a string with the elements separated by spaces and enclosed in double quotes
- str: the value of the attribute is will be set to the string, unchanged. You may need to provide proper quoting if the value contains spaces
+ For the complete list of Doxygen configuration options, please refer to the [Doxygen documentation](https://www.doxygen.nl/manual/config.html).
+
### Example
- ```starlark
+ ```bzl
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", dev_dependency = True)
doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
use_repo(doxygen_extension, "doxygen")
```
- ```starlark
+ ```bzl
# BUILD.bazel file
load("@doxygen//:doxygen.bzl", "doxygen")
+ load("@rules_cc//cc:defs.bzl", "cc_library")
+
+ cc_library(
+ name = "lib",
+ srcs = ["add.cpp", "sub.cpp"],
+ hdrs = ["add.h", "sub.h"],
+ )
+
+ cc_library(
+ name = "main",
+ srcs = ["main.cpp"],
+ deps = [":lib"],
+ )
doxygen(
name = "doxygen",
srcs = glob([
- "*.h",
- "*.cpp",
+ "*.md",
]),
+ deps = [":main"]
aliases = [
"licence=@par Licence:^^",
"verb{1}=@verbatim \\\\1 @endverbatim",
@@ -482,17 +539,22 @@ def doxygen(
```
Args:
- name: A name for the target.
- srcs: A list of source files to generate documentation for.
+ name: Name for the target.
+ 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.
+ 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.
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.
+ configurations: 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_extra_args: Extra arguments to pass to the doxygen executable.
- outs: The output folders bazel will keep. If only the html outputs is of interest, the default value will do.
+ 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.
@@ -1113,11 +1175,12 @@ def doxygen(
_add_generic_configuration(configurations, "MSCFILE_DIRS", mscfile_dirs)
if doxyfile_template:
- kwargs["doxyfile_template"] = doxyfile_template
+ kwargs["doxyfile_template"] = doxyfile_template
_doxygen(
name = name,
srcs = srcs,
+ deps = deps,
outs = outs,
configurations = configurations,
doxygen_extra_args = doxygen_extra_args,
diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel
index f54d398..85f562d 100644
--- a/examples/MODULE.bazel
+++ b/examples/MODULE.bazel
@@ -6,6 +6,7 @@ local_path_override(
path = "../",
)
+bazel_dep(name = "rules_cc", version = "0.1.1")
bazel_dep(name = "aspect_bazel_lib", version = "2.10.0")
bazel_dep(name = "bazel_skylib", version = "1.7.1")
diff --git a/examples/dependencies/BUILD.bazel b/examples/dependencies/BUILD.bazel
new file mode 100644
index 0000000..130705b
--- /dev/null
+++ b/examples/dependencies/BUILD.bazel
@@ -0,0 +1,51 @@
+load("@doxygen//:doxygen.bzl", "doxygen")
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+cc_library(
+ name = "add",
+ srcs = ["add.cpp"],
+ hdrs = ["add.h"],
+)
+
+cc_library(
+ name = "sub",
+ srcs = ["sub.cpp"],
+ hdrs = ["sub.h"],
+)
+
+cc_library(
+ name = "lib",
+ hdrs = ["lib.h"],
+ deps = [
+ ":add",
+ ":sub",
+ ],
+)
+
+cc_library(
+ name = "main",
+ srcs = ["main.cpp"],
+ deps = [":lib"],
+)
+
+genrule(
+ name = "section",
+ outs = ["Section.md"],
+ cmd = """
+ echo "# Section " > $@
+ echo "This is some amazing documentation with section!! " >> $@
+ echo "Incredible." >> $@
+ """,
+)
+
+doxygen(
+ name = "doxygen",
+ srcs = [
+ "README.md", # file
+ ":section", # genrule
+ ],
+ 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/README.md b/examples/dependencies/README.md
new file mode 100644
index 0000000..7236f16
--- /dev/null
+++ b/examples/dependencies/README.md
@@ -0,0 +1,66 @@
+# Dependencies example
+
+In this example, instead of specifying the files to be included in the Doxygen documentation using the `srcs` attribute with a glob, we use the `deps` attribute.
+This allows us to select a target and immediately include all of the files in its `srcs`, `hdrs`, and `data` attributes, along with all of its transitive dependencies.
+
+```bash
+bazel build //dependencies:doxygen
+```
+
+## Showcase
+
+In a very common scenario, imagine working on a C++ project with the following build file:
+
+```bzl
+# BUILD.bazel
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+cc_library(
+ name = "add",
+ srcs = ["add.cpp"],
+ hdrs = ["add.h"],
+)
+
+cc_library(
+ name = "sub",
+ srcs = ["sub.cpp"],
+ hdrs = ["sub.h"],
+)
+
+cc_library(
+ name = "lib",
+ hdrs = ["lib.h"],
+ deps = [
+ ":add",
+ ":sub",
+ ],
+)
+
+cc_library(
+ name = "main",
+ srcs = ["main.cpp"],
+ deps = [":lib"],
+)
+```
+
+The graph of dependencies looks like this:
+
+```mermaid
+graph TD;
+ A[main.cpp] --> B[lib.h];
+ B --> C[add.h
add.cpp];
+ B --> D[sub.h
sub.cpp];
+```
+
+If we want to include all of the files in the documentation, we can use the `deps` attribute to collect the `main` target's files and those of its transitive dependencies, like this:
+
+```bzl
+# BUILD.bazel
+load("@doxygen//:doxygen.bzl", "doxygen")
+
+doxygen(
+ name = "doxygen",
+ deps = [":main"],
+ doxygen_config = ":Doxyfile",
+)
+```
diff --git a/examples/dependencies/add.cpp b/examples/dependencies/add.cpp
new file mode 100644
index 0000000..47419aa
--- /dev/null
+++ b/examples/dependencies/add.cpp
@@ -0,0 +1,13 @@
+/**
+ * @file add.cpp
+ * @author Ernesto Casablanca (casablancaernesto@gmail.com)
+ * @copyright 2024
+ */
+
+#include "add.h"
+
+namespace lib {
+
+int add(int a, int b) { return a + b; }
+
+}
\ No newline at end of file
diff --git a/examples/dependencies/add.h b/examples/dependencies/add.h
new file mode 100644
index 0000000..39de229
--- /dev/null
+++ b/examples/dependencies/add.h
@@ -0,0 +1,22 @@
+/**
+ * @file add.h
+ * @author Ernesto Casablanca (casablancaernesto@gmail.com)
+ * @copyright 2024
+ */
+#pragma once
+
+namespace lib {
+
+/**
+ * @brief Add two integers
+ *
+ * Who knows what the result will be?
+ * @note This function is very complex. Use it with caution.
+ * @warning The result can be greater than the maximum value that can be stored!
+ * @param a First integer
+ * @param b Second integer
+ * @return Sum of a and b
+ */
+int add(int a, int b);
+
+} // namespace lib
\ No newline at end of file
diff --git a/examples/dependencies/lib.h b/examples/dependencies/lib.h
new file mode 100644
index 0000000..2232808
--- /dev/null
+++ b/examples/dependencies/lib.h
@@ -0,0 +1,16 @@
+/**
+ * @file lib.h
+ * @author Ernesto Casablanca (casablancaernesto@gmail.com)
+ * @copyright 2024
+ */
+#pragma once
+
+#include "add.h"
+#include "sub.h"
+
+/**
+ * @namespace lib
+ * An amazing library providing a lot of functions to do math operations.
+ * @note This library is very complex. Use it with caution.
+ */
+namespace lib {} // namespace lib
\ No newline at end of file
diff --git a/examples/dependencies/main.cpp b/examples/dependencies/main.cpp
new file mode 100644
index 0000000..b2bdaa5
--- /dev/null
+++ b/examples/dependencies/main.cpp
@@ -0,0 +1,17 @@
+/**
+ * @file lib.cpp
+ * @author Ernesto Casablanca (casablancaernesto@gmail.com)
+ * @copyright 2024
+ */
+
+#include
+
+#include "lib.h"
+
+int main(int, char*[]) {
+ int a = 5;
+ int b = 10;
+ std::cout << "a + b: " << lib::add(a, b) << std::endl;
+ std::cout << "a - b: " << lib::sub(a, b) << std::endl;
+ return 0;
+}
diff --git a/examples/dependencies/sub.cpp b/examples/dependencies/sub.cpp
new file mode 100644
index 0000000..1819360
--- /dev/null
+++ b/examples/dependencies/sub.cpp
@@ -0,0 +1,13 @@
+/**
+ * @file sub.cpp
+ * @author Ernesto Casablanca (casablancaernesto@gmail.com)
+ * @copyright 2024
+ */
+
+#include "sub.h"
+
+namespace lib {
+
+int sub(int a, int b) { return a - b; }
+
+} // namespace lib
\ No newline at end of file
diff --git a/examples/dependencies/sub.h b/examples/dependencies/sub.h
new file mode 100644
index 0000000..d50df5c
--- /dev/null
+++ b/examples/dependencies/sub.h
@@ -0,0 +1,22 @@
+/**
+ * @file sub.h
+ * @author Ernesto Casablanca (casablancaernesto@gmail.com)
+ * @copyright 2024
+ */
+#pragma once
+
+namespace lib {
+
+/**
+ * @brief Substract two integers
+ *
+ * Who knows what the result will be?
+ * @note This function is very complex. Use it with caution.
+ * @warning The result can be greater than the maximum value that can be stored!
+ * @param a First integer
+ * @param b Second integer
+ * @return Subtraction of a and b
+ */
+int sub(int a, int b);
+
+} // namespace lib
\ No newline at end of file
diff --git a/extensions.bzl b/extensions.bzl
index ac72623..555884c 100644
--- a/extensions.bzl
+++ b/extensions.bzl
@@ -192,7 +192,7 @@ You can further customize the repository by specifying the `doxygen_bzl`, `build
### Example
-```starlark
+```bzl
# Download the os specific version 1.12.0 of doxygen supporting all the indicated platforms
doxygen_repository(
name = "doxygen",
@@ -389,7 +389,7 @@ No download will be performed, and the file indicated by the label will be used
### Examples
-```starlark
+```bzl
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
@@ -407,7 +407,7 @@ doxygen_extension.configuration(
use_repo(doxygen_extension, "doxygen")
```
-```starlark
+```bzl
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)