From b58c2254d6733346aeded8656b4ecde65a95aedb Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Fri, 4 Oct 2024 17:19:50 +0200 Subject: [PATCH] tf-psa-crypto: cmake: Add build of documentation Signed-off-by: Ronald Cron --- tf-psa-crypto/CMakeLists.txt | 7 ++- tf-psa-crypto/TF-PSA-Crypto.cmake | 13 +++++ tf-psa-crypto/doxygen/.gitignore | 1 + tf-psa-crypto/doxygen/input/.gitignore | 1 + tf-psa-crypto/doxygen/input/doc_mainpage.h.in | 19 +++++++ tf-psa-crypto/doxygen/tfpsacrypto.doxyfile.in | 54 +++++++++++++++++++ 6 files changed, 93 insertions(+), 2 deletions(-) create mode 100644 tf-psa-crypto/doxygen/.gitignore create mode 100644 tf-psa-crypto/doxygen/input/.gitignore create mode 100644 tf-psa-crypto/doxygen/input/doc_mainpage.h.in create mode 100644 tf-psa-crypto/doxygen/tfpsacrypto.doxyfile.in diff --git a/tf-psa-crypto/CMakeLists.txt b/tf-psa-crypto/CMakeLists.txt index 63a71fc01..4827e0f61 100644 --- a/tf-psa-crypto/CMakeLists.txt +++ b/tf-psa-crypto/CMakeLists.txt @@ -57,15 +57,18 @@ endif() else(NOT (CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)) +set(TF_PSA_CRYPTO_VERSION 0.1.0) +set(TF_PSA_CRYPTO_SOVERSION 0) + if(TEST_CPP) project("TF-PSA-Crypto" LANGUAGES C CXX - VERSION 0.1.0 + VERSION ${TF_PSA_CRYPTO_VERSION} ) else() project("TF-PSA-Crypto" LANGUAGES C - VERSION 0.1.0 + VERSION ${TF_PSA_CRYPTO_VERSION} ) endif() diff --git a/tf-psa-crypto/TF-PSA-Crypto.cmake b/tf-psa-crypto/TF-PSA-Crypto.cmake index 1ccb87cf6..8c8768433 100644 --- a/tf-psa-crypto/TF-PSA-Crypto.cmake +++ b/tf-psa-crypto/TF-PSA-Crypto.cmake @@ -13,6 +13,19 @@ set(TF_PSA_CRYPTO_DIR ${CMAKE_CURRENT_SOURCE_DIR}) set(MBEDTLS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/..) set(MBEDTLS_FRAMEWORK_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../framework) +# Put the version numbers into relevant files +set(version_number_files + doxygen/input/doc_mainpage.h + doxygen/tfpsacrypto.doxyfile) +foreach(file ${version_number_files}) + configure_file(${file}.in + ${TF_PSA_CRYPTO_DIR}/${file}) +endforeach(file) + +ADD_CUSTOM_TARGET(${TF_PSA_CRYPTO_TARGET_PREFIX}apidoc + COMMAND doxygen tfpsacrypto.doxyfile + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/doxygen) + option(ENABLE_PROGRAMS "Build TF-PSA-Crypto programs." ON) option(UNSAFE_BUILD "Allow unsafe builds. These builds ARE NOT SECURE." OFF) diff --git a/tf-psa-crypto/doxygen/.gitignore b/tf-psa-crypto/doxygen/.gitignore new file mode 100644 index 000000000..3d1b31d63 --- /dev/null +++ b/tf-psa-crypto/doxygen/.gitignore @@ -0,0 +1 @@ +tfpsacrypto.doxyfile diff --git a/tf-psa-crypto/doxygen/input/.gitignore b/tf-psa-crypto/doxygen/input/.gitignore new file mode 100644 index 000000000..b806578c4 --- /dev/null +++ b/tf-psa-crypto/doxygen/input/.gitignore @@ -0,0 +1 @@ +doc_mainpage.h diff --git a/tf-psa-crypto/doxygen/input/doc_mainpage.h.in b/tf-psa-crypto/doxygen/input/doc_mainpage.h.in new file mode 100644 index 000000000..7c6ccb640 --- /dev/null +++ b/tf-psa-crypto/doxygen/input/doc_mainpage.h.in @@ -0,0 +1,19 @@ +/** + * \file doc_mainpage.h + * + * \brief Main page documentation file. + */ +/* + * + * Copyright The Mbed TLS Contributors + * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later + */ + +/** + * @mainpage TF-PSA-Crypto v@TF-PSA-Crypto_VERSION@ source code documentation + * + * This documentation describes the internal structure of the TF-PSA-Crypto + * library. It was automatically generated from specially formatted comment + * blocks in TF-PSA-Crypto source code using Doxygen (see + * http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen). + */ diff --git a/tf-psa-crypto/doxygen/tfpsacrypto.doxyfile.in b/tf-psa-crypto/doxygen/tfpsacrypto.doxyfile.in new file mode 100644 index 000000000..56de48761 --- /dev/null +++ b/tf-psa-crypto/doxygen/tfpsacrypto.doxyfile.in @@ -0,0 +1,54 @@ +PROJECT_NAME = "TF-PSA-Crypto v@TF-PSA-Crypto_VERSION@" +OUTPUT_DIRECTORY = ../apidoc/ +FULL_PATH_NAMES = NO +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +CASE_SENSE_NAMES = NO +INPUT = ../include input +FILE_PATTERNS = *.h +EXCLUDE = ../include/psa/crypto_se_driver.h +RECURSIVE = YES +EXCLUDE_SYMLINKS = YES +SOURCE_BROWSER = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +ALPHABETICAL_INDEX = NO +HTML_OUTPUT = . +HTML_TIMESTAMP = YES +SEARCHENGINE = YES +GENERATE_LATEX = NO +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +INCLUDE_PATH = ../include +EXPAND_AS_DEFINED = MBEDTLS_PRIVATE +CLASS_DIAGRAMS = NO +HAVE_DOT = YES +DOT_GRAPH_MAX_NODES = 200 +MAX_DOT_GRAPH_DEPTH = 1000 +DOT_TRANSPARENT = YES + +# We mostly use \retval declarations to document which error codes a function +# can return. The reader can follow the hyperlink to the definition of the +# constant to get the generic documentation of that error code. If we don't +# have anything to say about the specific error code for the specific +# function, we can leave the description part of the \retval command blank. +# This is perfectly valid as far as Doxygen is concerned. However, with +# Clang >=15, the -Wdocumentation option emits a warning for empty +# descriptions. +# https://github.com/Mbed-TLS/mbedtls/issues/6960 +# https://github.com/llvm/llvm-project/issues/60315 +# As a workaround, you can write something like +# \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription +# This avoids writing redundant text and keeps Clang happy. +ALIASES += emptydescription="" + +# Define away macros that make parsing definitions difficult. +# MBEDTLS_DEPRECATED is not included in this list as it's important to +# display deprecated status in the documentation. +PREDEFINED = "MBEDTLS_CHECK_RETURN_CRITICAL=" \ + "MBEDTLS_CHECK_RETURN_TYPICAL=" \ + "MBEDTLS_CHECK_RETURN_OPTIONAL=" \ + "MBEDTLS_PRINTF_ATTRIBUTE(a,b)=" \ + "__DOXYGEN__" \