From d5d9bcdbe2fbac6eae3dec27a096a0d824432602 Mon Sep 17 00:00:00 2001 From: silverqx Date: Mon, 9 Dec 2024 13:17:55 +0100 Subject: [PATCH] cmake added/revisited all Synopsis Function descriptions for functions which call cmake_parse_arguments(). --- cmake/CommonModules/TinyCommon.cmake | 15 +++++- cmake/CommonModules/TinyFeatureOptions.cmake | 39 +++++++++----- cmake/CommonModules/TinyHelpers.cmake | 52 ++++++++++++++++--- .../TinyResourceAndManifest.cmake | 18 +++++++ .../TinyToolchainRequirement.cmake | 19 ++++++- cmake/Modules/TinySources.cmake | 36 ++++++++----- cmake/Modules/TinyTestCommon.cmake | 22 +++++++- 7 files changed, 163 insertions(+), 38 deletions(-) diff --git a/cmake/CommonModules/TinyCommon.cmake b/cmake/CommonModules/TinyCommon.cmake index 7cfba2cde..47e33baf5 100644 --- a/cmake/CommonModules/TinyCommon.cmake +++ b/cmake/CommonModules/TinyCommon.cmake @@ -2,9 +2,22 @@ include_guard(GLOBAL) include(CheckCXXCompilerFlag) +# Common interface library used by all TinyORM targets +# # Set common variables and create interface-only library target so all other targets # will be able to link to, either directly or transitively, to consume common compile -# options/definitions +# options/definitions. +# +# Synopsis: +# tiny_common( +# NAMESPACE +# [EXPORT] NAME +# ) +# +# name to operate on. +# NAMESPACE name used for an Alias Target. +# EXPORT set the EXPORT_NAME target property to . +# NAME used for an Alias Target name and EXPORT_NAME target property. function(tiny_common target) # Arguments diff --git a/cmake/CommonModules/TinyFeatureOptions.cmake b/cmake/CommonModules/TinyFeatureOptions.cmake index dec263c95..f57a8e684 100644 --- a/cmake/CommonModules/TinyFeatureOptions.cmake +++ b/cmake/CommonModules/TinyFeatureOptions.cmake @@ -145,27 +145,38 @@ depends on condition: ${depends})") endmacro() -# Add a simple build option which controls compile definition(s) for a target. +# Add the boolean build option and compile definition/s for a target in one shot. +# +# Call the option() command if an option is not defined yet and initialize its +# default value from the if given, otherwise +# from the . Call the target_compile_definitions() +# with the if an option is enabled (ON), otherwise use +# the . Call the add_feature_info() and mark_as_advanced() +# functions if FEATURE or ADVANCED is given. # # Synopsis: # target_optional_compile_definitions( [ADVANCED] [FEATURE] -# NAME DESCRIPTION DEFAULT -# DEFAULT_FROM_ENVIRONMENT -# [ENABLED [enabled_compile_definitions...]] -# [DISABLED [disabled_compile_definitions...]] +# NAME DESCRIPTION DEFAULT +# [DEFAULT_FROM_ENVIRONMENT ] +# [ENABLED [...]] +# [DISABLED [...]] # ) # -# NAME, DESCRIPTION and DEFAULT are passed to option() command. -# If FEATURE is given, they are also passed to add_feature_info() command. -# ADVANCED calls the mark_as_advanced() command. -# determines the scope for the following compile definitions. -# ENABLED lists compile definitions that will be set on when option is enabled. -# DISABLED lists compile definitions that will be set on when option is disabled. +# name to operate on. +# for the target_compile_definitions() command. +# NAME of a variable to process, it's directly passed to the option() and +# add_feature_info() commands. +# DESCRIPTION for the option() and add_feature_info() commands. +# DEFAULT initial value for the option() command, used if the +# is not empty or undefined. +# ADVANCED call the mark_as_advanced() command. +# FEATURE pass the and values also to the add_feature_info() command. +# ENABLED to set on the when option is enabled. +# DISABLED to set on the when option is disabled. # ENABLED or DISABLE are passed to the target_compile_definitions() command. # DEFAULT_FROM_ENVIRONMENT get a default value for the option() command from the given -# environment variable if it's defined otherwise use a value from the given -# argument. -# DEFAULT and DEFAULT_FROM_ENVIRONMENT can't be if they are passed and they must be +# if defined, otherwise use the . +# DEFAULT and DEFAULT_FROM_ENVIRONMENT can't be empty if they are passed and they must be # of the boolean type. function(target_optional_compile_definitions target scope) diff --git a/cmake/CommonModules/TinyHelpers.cmake b/cmake/CommonModules/TinyHelpers.cmake index 4baab15e6..5906bf596 100644 --- a/cmake/CommonModules/TinyHelpers.cmake +++ b/cmake/CommonModules/TinyHelpers.cmake @@ -166,8 +166,23 @@ function(tiny_create_buildtree_tagfiles filepaths) endfunction() -# Find version numbers in the version header file, search following tokens -# _VERSION_ +# Find version numbers in the version header file using the given +# +# Search following tokens _VERSION_ and return obtained +# values using the variables. +# +# Synopsis: +# tiny_read_version(out_version out_major out_minor out_patch out_tweak +# VERSION_HEADER +# PREFIX +# HEADER_FOR +# ) +# +# output variable for the whole version number. +# output variables for individual version numbers. +# VERSION_HEADER absolute filepath is directly passed to the file(STRINGS). +# PREFIX for the file(STRINGS REGEX) to find #define _VERSION_ lines. +# HEADER_FOR project name used in the message(DEBUG) (use TinyXyz_ns variables for this). function(tiny_read_version out_version out_major out_minor out_patch out_tweak) # Arguments @@ -180,9 +195,11 @@ function(tiny_read_version out_version out_major out_minor out_patch out_tweak) ${TINY_UNPARSED_ARGUMENTS}") endif() - if("${TINY_VERSION_HEADER}" STREQUAL "" OR "${TINY_HEADER_FOR}" STREQUAL "") + if("${TINY_VERSION_HEADER}" STREQUAL "" OR "${TINY_PREFIX}" STREQUAL "" OR + "${TINY_HEADER_FOR}" STREQUAL "" + ) message(FATAL_ERROR "The ${CMAKE_CURRENT_FUNCTION}() is missing single-valued \ -keyword or its value is empty: HEADER_FOR, VERSION_HEADER") +keyword or its value is empty: HEADER_FOR, PREFIX, VERSION_HEADER") endif() # Body @@ -237,17 +254,22 @@ endfunction() # Command for manipulating CMAKE_RC_FLAGS, supports APPEND and RESTORE operations # -# Append flags to the CMAKE_RC_FLAGS. It will also save and restore original content +# Append flags to the CMAKE_RC_FLAGS. It will also save and restore the original content # of the CMAKE_RC_FLAGS variable, so that rc/windres compilation commands are not -# polluted with include paths from previous calls. +# polluted with include paths from previous tiny_rc_flags(APPEND) function calls. # # Synopsis: # tiny_rc_flags(APPEND [...]) # +# APPEND the given flags, it only restores the original CMAKE_RC_FLAGS value and +# appends nothing if the value is empty. +# # Restore the original value of CMAKE_RC_FLAGS. # # Synopsis: # tiny_rc_flags(RESTORE) +# +# RESTORE the original CMAKE_RC_FLAGS value. function(tiny_rc_flags) # Arguments @@ -697,8 +719,22 @@ function(tiny_fix_ccache) endfunction() -# Set the Compatible Interface Requirement for the project's major version using -# the given target +# Set the Compatible Interface Requirement for the given property names +# +# They are passed to the foreach() loop, set the INTERFACE_ property value +# that is obtained from the 's property , and then the is appended +# to the COMPATIBLE_INTERFACE_STRING property. +# +# Every TinyORM library sets the Compatible Interface Requirement for the VERSION_MAJOR +# and SOVERSION target properties. +# +# Synopsis: +# tiny_set_compatible_interface_string( +# PROPERTIES ... +# ) +# +# name to operate on. +# PROPERTIES names list for which to add the Compatible Interface Requirements. function(tiny_set_compatible_interface_string target) # Arguments diff --git a/cmake/CommonModules/TinyResourceAndManifest.cmake b/cmake/CommonModules/TinyResourceAndManifest.cmake index e86397c05..35d8bb2e5 100644 --- a/cmake/CommonModules/TinyResourceAndManifest.cmake +++ b/cmake/CommonModules/TinyResourceAndManifest.cmake @@ -1,6 +1,24 @@ include_guard(GLOBAL) # Configure Windows resource and manifest files +# +# Synopsis: +# tiny_resource_and_manifest( [TEST] +# [OUTPUT_DIR ] +# [RESOURCES_DIR ] +# [RESOURCE_BASENAME ] +# [MANIFEST_BASENAME ] +# ) +# +# name to operate on. +# TEST to configure the test , all tests use the same TinyTest.rc.in file. +# OUTPUT_DIR relative folder path for the configure_file() for generated content. +# RESOURCES_DIR relative or absolute folder path where the TinyXyz.rc.in file is located. +# RESOURCE_BASENAME basename for the resource file, eg. TinyOrm will use TinyOrm.rc.in. +# The name and for TEST the TinyTest will be used if is empty or undefined. +# MANIFEST_BASENAME basename for the manifest file, eg. TinyOrm library will use +# TinyOrm.dll.manifest, for executables it will be eg. tom.exe.manifest. +# The will be used if empty or undefined. function(tiny_resource_and_manifest target) # Arguments diff --git a/cmake/CommonModules/TinyToolchainRequirement.cmake b/cmake/CommonModules/TinyToolchainRequirement.cmake index 71f2b9638..0a769001c 100644 --- a/cmake/CommonModules/TinyToolchainRequirement.cmake +++ b/cmake/CommonModules/TinyToolchainRequirement.cmake @@ -69,7 +69,24 @@ satisfied (also used by tiny_configure_test_pch()).") endfunction() -# Make minimum toolchain version a requirement +# Verify the minimum toolchain and Qt versions +# +# Make the minimum toolchain and Qt versions a requirement and throw the FATAL_ERROR if +# this requirement is not satisfied (version is less than required). It checks compilers +# and Qt framework versions. All argument values are required. +# +# Synopsis: +# tiny_toolchain_requirement( +# MSVC GCC +# CLANG CLANG_CL +# QT +# ) +# +# MSVC minimum required. +# GCC minimum required. +# CLANG minimum required. +# CLANG_CL minimum required. +# QT framework minimum required. function(tiny_toolchain_requirement) # Arguments diff --git a/cmake/Modules/TinySources.cmake b/cmake/Modules/TinySources.cmake index ff7472899..c99273e21 100644 --- a/cmake/Modules/TinySources.cmake +++ b/cmake/Modules/TinySources.cmake @@ -849,38 +849,48 @@ endfunction() # Wrapper function for the target_sources() (for both overloads) # -# Create header file sets (or add to the existing sets) or add header files and add -# source files to the given target and call target_include_directories($) -# in one shot. +# Create header file sets (or add to the existing sets) or add header and source files +# to the given target and call target_include_directories($) in one shot. # # Obtain public and private headers and source files, and create public/private # file set/s, or add files to an existing file set/s, and add source files # for the given target. # +# Synopsis: # tiny_target_sources( -# [FILE_SET] PREFIX [BASE_DIRS ...] +# FILE_SET PREFIX +# [BASE_DIRS [...]] # ) # +# name to operate on. # FILE_SET call the target_sources(FILE_SET) overload. -# PREFIX prefix for FILE_SET argument value and for calling tinyxyz_sources() -# function to obtain header and source files. Cannot be undefined or empty. +# PREFIX for the FILE_SET argument value and for calling the tinyxyz_sources() function +# to obtain header and source files. Cannot be empty or undefined. # BASE_DIRS these directories are directly passed to the target_sources(BASE_DIRS) # for public and private header files. The _private suffix is appended for every -# directory path for private header files. It cannot end with slahes❗ Empty or undefined -# BASE_DIRS is handled the same way as for the target_sources(). +# directory path for private header files. It cannot end with slahes❗ If it's empty or +# undefined, an empty string will be passed to the target_sources(BASE_DIRS). It's handled +# the same way as for the target_sources(). # # Obtain header and source files (ignoring private headers) and add source files # for the given target. # # Synopsis: # tiny_target_sources( -# [PRIVATE] PREFIX BASE_DIR +# [PRIVATE] PREFIX +# [BASE_DIR []] # ) # -# PRIVATE add obtained headers from the tinyxyz_sources() function as private headers. -# PREFIX prefix for calling tinyxyz_sources() function to obtain header and source files. -# Cannot be undefined or empty. -# BASE_DIR this directory is added to target_include_directories($). +# name to operate on. +# PRIVATE add obtained public headers from the tinyxyz_sources() function as private +# headers using target_sources(PRIVATE) (especially needed for executables). +# PREFIX for calling the tinyxyz_sources() function to obtain header and source files. +# Cannot be empty or undefined. +# BASE_DIR is added to the target_include_directories($). +# If is a relative path (cmake_path(IS_RELATIVE) is true), it's evaluated relative +# to the CMAKE_CURRENT_SOURCE_DIR and normalized. The absolute path stays untouched. +# If empty or undefined the CMAKE_CURRENT_SOURCE_DIR is used. Symbolic link and tilde +# is not resolved. function(tiny_target_sources target) # Arguments diff --git a/cmake/Modules/TinyTestCommon.cmake b/cmake/Modules/TinyTestCommon.cmake index 03990e50e..a288f342f 100644 --- a/cmake/Modules/TinyTestCommon.cmake +++ b/cmake/Modules/TinyTestCommon.cmake @@ -1,6 +1,26 @@ include_guard(GLOBAL) -# Configure a passed auto test +# Configure the given test target +# +# Synopsis: +# tiny_configure_test( +# [DEPENDS_ON_UNITTESTS] +# [INCLUDE_MIGRATIONS] [INCLUDE_MODELS] +# [PROVIDES_PCH] [RUN_SERIAL] +# ) +# +# name to operate on. +# DEPENDS_ON_UNITTESTS make the functional test dependent on all unit tests, +# it should only be enablved for functional tests. Primarily to make functional tests +# dependent on all unit tests. +# INCLUDE_MIGRATIONS add migrations headers on the include path and call +# the target_sources(PRIVATE) for these headers (calls tiny_target_sources(PRIVATE)). +# INCLUDE_MODELS add models headers on the include path and call +# the target_sources(PRIVATE) for these headers (calls tiny_target_sources(PRIVATE)). +# PROVIDES_PCH tag a test that will provide PCH for all other test targets, +# only one test can be tagged with it and all other test targets will use +# this PCH without compilation (reuse PCH). +# RUN_SERIAL set the RUN_SERIAL test property for the . function(tiny_configure_test target) # Arguments