This repository contains a Starlark implementation of Doxygen rules in Bazel.
Add the following to your MODULE.bazel:
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "1.3.0", dev_dependency = True)If you don't want to depend on the Bazel package registry 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:
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "1.3.0", dev_dependency = True)
archive_override(
module_name = "rules_doxygen",
urls = "https://github.com/TendTo/rules_doxygen/archive/refs/heads/main.tar.gz",
strip_prefix = "rules_doxygen-main",
# The SHA256 checksum of the archive file, based on the rules' version
# integrity = "sha256-0SCaZuAerluoDs6HXMb0Bj9FttZVieM4+Dpd9gnMM+o=", # Example
)To select a doxygen version to use, use the doxygen_extension module extension below the bazel_dep rule in your MODULE.bazel file.
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
use_repo(doxygen_extension, "doxygen")By default, version 1.12.0 of Doxygen is used.
You can override this value with a custom one for each supported platform, i.e. windows, mac and linux.
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
# Download doxygen version 1.10.0 on linux, default version on all other platforms
doxygen_extension.version(
version = "1.10.0",
sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747",
platform = "linux",
)
use_repo(doxygen_extension, "doxygen")When you do so, you must also provide the SHA256 of the given doxygen installation. If you don't know the SHA256 value, just leave it empty. The build will fail with an error message containing the correct SHA256.
Download from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.windows.x64.bin.zip failed: class com.google.devtools.build.lib.bazel.repository.downloader.UnrecoverableHttpException Checksum was 2135c1d5bdd6e067b3d0c40a4daac5d63d0fee1b3f4d6ef1e4f092db0d632d5b but wanted 0000000000000000000000000000000000000000000000000000000000000000If you set the version to 0.0.0, the doxygen executable will be assumed to be available from the PATH.
No download will be performed and bazel will use the installed version of doxygen.
Warning
Setting the version to 0.0.0 this will break the hermeticity of your build, as it will now depend on the environment.
Tip
Not indicating the platform will make the configuration apply to the platform it is running on. The build will fail when the downloaded file does not match the SHA256 checksum, i.e. when the platform changes. Unless you are using a system-wide doxygen installation, you should always specify the platform.
Different strategies can be combined in the same file, one for each platform, as shown below:
# MODULE.bazel file
bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
# Download doxygen version 1.10.0 on linux
doxygen_extension.version(
version = "1.10.0",
sha256 = "dcfc9aa4cc05aef1f0407817612ad9e9201d9bf2ce67cecf95a024bba7d39747",
platform = "linux",
)
# Use the local doxygen installation on mac
doxygen_extension.version(
version = "0.0.0",
platform = "mac",
)
# Since no configuration has been provided, windows will fallback to the default version
use_repo(doxygen_extension, "doxygen")Note
See the documentation for more information.
The main macro exposed by this module is doxygen.
It generates a Doxygen documentation target from a list of sources.
Only the sources are required, the rest of the parameters are optional.
# My BUILD.bazel file
load("@doxygen//:doxygen.bzl", "doxygen")
doxygen(
name = "doxygen", # Name of the rule, can be anything
srcs = glob([ # List of sources to document.
"*.h", # Usually includes the source files and the markdown files.
"*.cpp",
]) + ["README.md"],
project_brief = "Example project for doxygen", # Brief description of the project
project_name = "base", # Name of the project
configurations = [ # Customizable configurations
"GENERATE_HTML = YES", # that override the default ones
"GENERATE_LATEX = NO", # from the Doxyfile
"USE_MDFILE_AS_MAINPAGE = README.md",
]
tags = ["manual"] # Tags to add to the target.
# This way the target won't run unless explicitly called
)Use the Doxygen documentation 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.
Note
See the documentation for more information or the examples directory for examples of how to use the rules.
To build the documentation, run the following command:
bazel build //path/to:doxygen_targetFor example, if the BUILD.bazel file is in the root of the repository, and the target is named doxygen
# BUILD.bazel file in the root of the repository
load("@doxygen//:doxygen.bzl", "doxygen")
doxygen(
name = "doxygen",
srcs = glob([
"*.h",
"*.cpp",
]),
project_name = "base",
)the build command would be:
bazel build //:doxygenThe generated documentation will be in the bazel-bin/<subpackage> directory.
If the BUILD.bazel file was in the root of the repository, the <subpackage> would be an empty string.
The documentation can be viewed by opening the index.html file in a browser using any web server:
# Using Python 3
cd bazel-bin/<subpackage>/html
python3 -m http.server 8000Lastly, you may want to compress the documentation to share it with others:
tar -czvf doxygen.tar.gz bazel-bin/<subpackage>/html- Add more easy-to-use common configuration for the Doxyfile