You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+71Lines changed: 71 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -150,6 +150,10 @@ doxygen(
150
150
"*.h", # Usually includes the source files and the markdown files.
151
151
"*.cpp",
152
152
]) + ["README.md"],
153
+
# Additionally, you can use the `deps` attribute to select a target
154
+
# and automatically include all of the files in its `srcs`, `hdrs`, and `data` attributes,
155
+
# along with all of its transitive dependencies.
156
+
# deps = [":my_cc_target"],
153
157
project_brief=DESCRIPTION, # Brief description of the project
154
158
project_name=NAME, # Name of the project
155
159
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
173
177
> [!Note]
174
178
> See the [documentation](docs/doxygen_doc.md) for more information or the [examples](examples) directory for examples of how to use the rules.
175
179
180
+
### Differences between `srcs` and `deps`
181
+
182
+
The `srcs` and `deps` attributes work differently, and are not interchangeable.
183
+
184
+
`srcs` is a list of files that will be passed to Doxygen for documentation generation.
185
+
You can use `glob` to include a collection of multiple files.
186
+
On the other hand, if you indicate a target (e.g., `:my_genrule`), it will include all the files produced by that target.
187
+
More precisely, the files in the DefaultInfo provider the target returns.
188
+
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.
189
+
190
+
On the other hand, `deps` is a list of targets whose sources will be included in the documentation generation.
191
+
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.
192
+
Since we are only interested in the source files, the `deps` targets **will not** be built when the documentation is generated.
193
+
194
+
```bzl
195
+
# My BUILD.bazel file
196
+
load("@doxygen//:doxygen.bzl", "doxygen")
197
+
load("@rules_cc//cc:defs.bzl", "cc_library")
198
+
199
+
cc_library(
200
+
name="lib",
201
+
hdrs= ["add.h", "sub.h"],
202
+
srcs= ["add.cpp", "sub.cpp"],
203
+
)
204
+
205
+
cc_library(
206
+
name="main",
207
+
srcs= ["main.cpp"],
208
+
deps= [":lib"],
209
+
)
210
+
211
+
212
+
genrule(
213
+
name="section",
214
+
outs= ["Section.md"],
215
+
cmd="""
216
+
echo "# Section " > $@
217
+
echo "This is some amazing documentation with section!! " >> $@
218
+
echo "Incredible." >> $@
219
+
""",
220
+
)
221
+
222
+
doxygen(
223
+
name="doxygen",
224
+
project_name="dependencies",
225
+
226
+
# The output of the genrule will be included in the documentation.
227
+
# The genrule will be executed when the documentation is generated.
228
+
srcs= [
229
+
"README.md", # file
230
+
":section", # genrule
231
+
232
+
# WARNING: By adding this, the main target will be built
233
+
# and only the output file `main.o` will be passed to Doxygen,
234
+
# which is likely not what you want.
235
+
# ":main"
236
+
],
237
+
238
+
# The sources of the main target and its dependencies will be included.
239
+
# No compilation will be performed, so compile error won't be reported.
240
+
deps= [":main"], # cc_library
241
+
242
+
# Always starts at the root folder
243
+
use_mdfile_as_mainpage="dependencies/README.md",
244
+
)
245
+
```
246
+
176
247
## Build
177
248
178
249
To build the documentation, run the following command:
| <aid="doxygen-name"></a>name | A name for the target. | none |
124
-
| <aid="doxygen-srcs"></a>srcs | A list of source files to generate documentation for. | none |
159
+
| <aid="doxygen-srcs"></a>srcs | A list of source files to generate documentation for. |`[]`|
160
+
| <aid="doxygen-deps"></a>deps | A list of dependencies whose source, header and data files, and those or the transitive dependencies, will be included in the documentation. |`[]`|
125
161
| <aid="doxygen-dot_executable"></a>dot_executable | Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro |`None`|
126
162
| <aid="doxygen-configurations"></a>configurations | A list of additional configuration parameters to pass to Doxygen. |`None`|
127
163
| <aid="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. |`None`|
@@ -435,3 +471,25 @@ doxygen(
435
471
| <aid="doxygen-kwargs"></a>kwargs | Additional arguments to pass to the rule (e.g. `visibility = ["//visibility:public"], tags = ["manual"]`) | none |
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.
0 commit comments