Skip to content

[backport 1.1] doxygen: use CMake build dir intead of source dir to host generated files #760

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
valeriosetti wants to merge 8 commits into
base: tf-psa-crypto-1.1
Choose a base branch
from
+29 −7
Open

[backport 1.1] doxygen: use CMake build dir intead of source dir to host generated files #760

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ace9d6d
doxygen: use CMake build dir intead of source dir to host generated f…
valeriosetti Mar 19, 2026
def13c7
doxygen: use PROJECT_BINARY_DIR to represent the root path of TF-PSA-…
valeriosetti Apr 14, 2026
f0393b0
README: update path of apidoc
valeriosetti Apr 14, 2026
b67abe4
changelog: add note about apidoc build folder change
valeriosetti Apr 14, 2026
7b435c2
doxygen: add quotes to directory paths to prevent failures due to whi…
valeriosetti Apr 14, 2026
38bf41f
doxygen: create symlink to the apidoc in the build folder
valeriosetti Apr 22, 2026
a32d8fc
changelog: remove a new-line char from changelog message
valeriosetti Apr 29, 2026
db8d277
cmake: fix symlink creation for apidoc
valeriosetti Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,12 +71,29 @@ set(version_number_files
doxygen/tfpsacrypto.doxyfile)
foreach(file ${version_number_files})
configure_file(${file}.in
${PROJECT_SOURCE_DIR}/${file})
${PROJECT_BINARY_DIR}/${file})
endforeach(file)

ADD_CUSTOM_TARGET(${TF_PSA_CRYPTO_TARGET_PREFIX}tfpsacrypto-apidoc
COMMAND doxygen tfpsacrypto.doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/doxygen)
WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/doxygen)

# Create an in-tree symlink to the apidoc built in the binary folder. This is
# only performed on Unix platforms and for out-of-tree builds. The existence
# check is deferred to build time so that multiple out-of-tree build dirs each
# register the command, but only the first one to build actually creates the
# symlink.
if(UNIX AND NOT CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR)
file(RELATIVE_PATH _apidoc_rel_path
${CMAKE_CURRENT_SOURCE_DIR}
${PROJECT_BINARY_DIR}/apidoc)
add_custom_command(TARGET ${TF_PSA_CRYPTO_TARGET_PREFIX}tfpsacrypto-apidoc POST_BUILD
COMMAND sh -c
Copy link
Copy Markdown
Contributor

@gilles-peskine-arm gilles-peskine-arm May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

$ cmake -B build-default-cmake
…
$ make -C build-default-cmake tfpsacrypto-apidoc
…
/bin/sh: 1:               /usr/bin/cmake -E create_symlink              build-default-cmake/apidoc /home/gilpes01/z/dev/crypto/reviewing/760-backport-pr718/apidoc: not found
make[3]: *** [CMakeFiles/tfpsacrypto-apidoc.dir/build.make:75: tfpsacrypto-apidoc] Error 127

Looks like there's a quoting problem here.

"test -e '${CMAKE_CURRENT_SOURCE_DIR}/apidoc' || \
'${CMAKE_COMMAND}' -E create_symlink \
'${_apidoc_rel_path}' '${CMAKE_CURRENT_SOURCE_DIR}/apidoc'"
COMMENT "Creating in-tree symlink to apidoc documentation")
endif()

option(ENABLE_PROGRAMS "Build TF-PSA-Crypto programs." ON)

Expand Down
5 changes: 5 additions & 0 deletions ChangeLog.d/doxygen-build-folder.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Bugfix
* Doxygen documentation `apidoc` is now built into CMake's binary folder,
not in-tree. For backward compatibility on Unix platforms an in-tree
symlink named `apidoc` is created pointing to the folder in the build
directory. Fixes #381.
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,8 +97,8 @@ To generate a local copy of the library documentation in HTML format:
1. Run `cmake -B /path/to/build_dir /path/to/TF-PSA-Crypto/source`
1. Run `cmake --build /path/to/build_dir --target tfpsacrypto-apidoc`
1. Open one of the main generated HTML files:
* `apidoc/index.html`
* `apidoc/modules.html` or `apidoc/topics.html`
* `/path/to/build_dir/apidoc/index.html`
* `/path/to/build_dir/apidoc/modules.html`

Compiling
---------
Expand Down
6 changes: 3 additions & 3 deletions doxygen/tfpsacrypto.doxyfile.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
CASE_SENSE_NAMES = NO
INPUT = ../include input ../tests/include/alt-dummy
INPUT = "@PROJECT_SOURCE_DIR@/include" "input" "@PROJECT_SOURCE_DIR@/tests/include/alt-dummy"
FILE_PATTERNS = *.h
EXCLUDE = ../include/mbedtls/private
EXCLUDE = "@PROJECT_SOURCE_DIR@/include/mbedtls/private"
RECURSIVE = YES
EXCLUDE_SYMLINKS = YES
SOURCE_BROWSER = YES
Expand All @@ -21,7 +21,7 @@ SEARCHENGINE = YES
GENERATE_LATEX = NO
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
INCLUDE_PATH = ../include ../drivers/builtin/include
INCLUDE_PATH = "@PROJECT_SOURCE_DIR@/include" "@PROJECT_SOURCE_DIR@/drivers/builtin/include"
EXPAND_AS_DEFINED = MBEDTLS_PRIVATE
CLASS_DIAGRAMS = NO
HAVE_DOT = YES
Expand Down