diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5874ffc --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,3 @@ +# CMake Scripts Code of Conduct + +You can find the code of conduct in the [official documentation](https://rsps.github.io/cmake-scripts/current/code_of_conduct.html). diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..5a30379 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# CMake Scripts Contribution Guide + +The contribution guide is located in the [official documentation](https://rsps.github.io/cmake-scripts/current/contribution_guide.html). diff --git a/.github/ISSUE_TEMPLATE/defect-report.md b/.github/ISSUE_TEMPLATE/defect-report.md new file mode 100644 index 0000000..99abb64 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/defect-report.md @@ -0,0 +1,41 @@ +--- +name: Bug or Defect report +about: Report a bug or defect +--- + +## Describe the bug + +A clear and concise description of what the bug is. + +## To Reproduce** + +_Steps to reproduce the behavior:_ +1. Import module xyz... +2. Call function with parameters ... +4. See error + +## Expected behavior + +_A clear and concise description of what you expected to happen._ + +## Possible solution + +_How could this defect be resolved (if you are able to provide such)_ + +## Affected version(s) +_The affected version(s) of this project._ +- Version [e.g. 1.1.0] + +## CMake Version +_The CMake version used, in which the bug or defect was encountered_ +- Version [e.g. 3.30.0] + +## OS + +_The operating system you used._ +- E.g. Ubuntu 24.04 + +## Additional context + +_Add any other context about the bug or defect..._ + diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 0000000..5d1660e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,12 @@ +--- +name: Feature Request +about: Ask for a new or change of an existing feature +--- + +## Description + +_What is the main purpose of the requested feature or change, e.g. what problem or challenge should to solve?... and why?_ + +## Possible solution + +_How should the feature be implemented?_ diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..5d6be46 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,9 @@ +_A short summary of what does this PR fixes, changes or adds..._ + +## Details + +_More details about the PR... Delete this section, if not need!_ + +## References + +* [Reference to issue(s)](www.google.com) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97e2969..38a5aa0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,5 +22,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * `tests.yaml` and `deploy-docs.yaml` GitHub Actions workflows. * `composer.json` to install [Daux.io](https://daux.io) dev-dependency (_documentation generator_). * "rsp" theme for Daux (_placed in `resources/daux/themes/rsp`_). +* Support Policy, Code of Conduct, Contribution Guide and Security Policy in the docs. +* Defect and Feature Request issue templates (_for GitHub_). +* Pull request template (_for GitHub_). [Unreleased]: https://github.com/rsps/cmake-scripts/compare/develop diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..8934020 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,3 @@ +# Security Policy + +The security policy can be found in the [official documentation](https://rsps.github.io/cmake-scripts/current/security_policy.html). diff --git a/cmake/rsp/testing.cmake b/cmake/rsp/testing.cmake index 3d90e2b..9a7af8a 100644 --- a/cmake/rsp/testing.cmake +++ b/cmake/rsp/testing.cmake @@ -69,7 +69,7 @@ if (NOT COMMAND "define_test_suite") # # @see end_test_case() # - # @param name Human readable name of test suite TODO: Can this be used for ctest labels / groups? + # @param name Human readable name of test suite # @param DIRECTORY Path to directory that contains test-cases # @param [MATCH ] Glob used to match test-case files. # Defaults to "*_test.cmake". diff --git a/cmake/rsp/testing/asserts.cmake b/cmake/rsp/testing/asserts.cmake index 8e8bdac..2e47e42 100644 --- a/cmake/rsp/testing/asserts.cmake +++ b/cmake/rsp/testing/asserts.cmake @@ -171,7 +171,7 @@ endif () if (NOT COMMAND "assert_in_list") - #! assert_in_list : Assert key (value) to be inlist + #! assert_in_list : Assert key (value) to be in given list # # @see https://cmake.org/cmake/help/latest/command/if.html#in-list # @@ -196,7 +196,7 @@ endif () if (NOT COMMAND "assert_not_in_list") - #! assert_not_in_list : Assert key (value) not to be inlist + #! assert_not_in_list : Assert key (value) not to be in given list # # @see https://cmake.org/cmake/help/latest/command/if.html#in-list # diff --git a/docs/+current/01_release-notes.md b/docs/+current/01_release-notes.md index 05b4a96..ce45fe7 100644 --- a/docs/+current/01_release-notes.md +++ b/docs/+current/01_release-notes.md @@ -11,9 +11,95 @@ author: RSP Systems A/S ## Support Policy -_TODO: ...incomplete, please review documentation at a later point_ +The following shows the supported versions of the "CMake Scripts" project. + +| Version | CMake | Release | Security Fixes Until | +|---------|-------------|---------|----------------------| +| `1.x` | `3.30 - ?` | _TBD_ | _TBD_ | +| `0.x`* | `3.30 - ? ` | _TBD_ | _N/A_ | + +_* - current supported version._ \ +_TBD - "To be decided"._ \ +_N/A - "Not available"._ ## `v0.x` Highlights -_TODO: ...incomplete, please review documentation at a later point_ +### "Mini" Testing Framework + +(_available since `v0.1`_) + +A "mini" testing framework for testing your CMake modules and scripts. + +```cmake +define_test("has built assets" "has_built_assets") +function(has_built_assets) + assert_file_exists("resources/images/menu_bg.png" MESSAGE "No menu bg") + assert_file_exists("resources/images/bg.png" MESSAGE "No background") + + # ...etc +endfunction() +``` + +See [testing module](./modules/testing/cmake/index.md) for additional information. + +### Git + +(_available since `v0.1`_) + +Git related utilities. + +```cmake +git_find_version_tag( + OUTPUT version + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} +) + +message("${version}") # 1.15.2 +``` + +See [git module](./modules/git/index.md) for additional information. + +### Version + +(_available since `v0.1`_) + +Helpers for dealing with a project’s versioning + +```cmake +version_from_file( + FILE "version" + OUTPUT my_package +) + +message("${my_package}_SEMVER") # 2.0.0-beta.3+AF1004 +``` + +See [version module](./modules/version/index.md) for additional information. + +### Cache + +(_available since `v0.1`_) + +Module that offers additional caching functionality (_via CMake’s Cache Entry mechanism_). + +```cmake +cache_set( + KEY foo + VALUE "bar" + TTL 5 +) + +# ... Elsewhere in your cmake scripts, 5 seconds later... + +cache_get(KEY foo) + +message("${foo}") # (empty string) +``` + +See [cache module](./modules/cache/index.md) for additional information. + +## Changelog + +For additional information about the latest release, new features, changes or defect fixes, please review the +[Changelog](https://github.com/rsps/cmake-scripts/blob/main/CHANGELOG.md). diff --git a/docs/+current/02_upgrade-guide.md b/docs/+current/02_upgrade-guide.md index 0b7de27..584a2d7 100644 --- a/docs/+current/02_upgrade-guide.md +++ b/docs/+current/02_upgrade-guide.md @@ -7,7 +7,7 @@ author: RSP Systems A/S # Upgrade Guide -_TODO: ...incomplete, please review documentation at a later point_ +_There is no upgrade guide for this version!_ ## Onward diff --git a/docs/+current/03_contribution-guide.md b/docs/+current/03_contribution-guide.md index 55250bf..7150d55 100644 --- a/docs/+current/03_contribution-guide.md +++ b/docs/+current/03_contribution-guide.md @@ -7,4 +7,44 @@ author: RSP Systems A/S # Contribution Guide -_TODO: ...incomplete, please review documentation at a later point_ \ No newline at end of file +We appreciate all the help that we can get to improve this project. In this section, you will find useful information +on how you can contribute. + +[TOC] + +## Bug Report + +If you have encountered a bug, feel free to [report it](https://github.com/aedart/athenaeum/issues). +When reporting the bug, please consider the following: + +* Where is the defect located? +* A good, short and precise description of the defect (_Why is it a defect?_) +* How can the defect be replicated? +* (_A possible solution for how to resolve the defect_) + +Once we have received the bug or defect report, we will address it as reasonably as we can. + +## Security Vulnerability + +See the [Security Policy](./04_security-policy.md) for details. + +## Feature Request + +If you have an idea for a new feature or perhaps changing an existing one, please feel free to create a +[feature request](https://github.com/aedart/athenaeum/issues). + +## Pull Requests + +If you are able to fix a bug or defect, or perhaps add new features, then you can send us a pull request. +Please follow this guideline: + +* Fork this project +* Create a new local branch for the given fix, addition or change +* Write your changes +* Create executable test-cases (_prove that your changes are solid!_) +* Commit and push your changes to your fork +* Send a pull-request with your changes (**_please ensure to check "Allow edits from maintainers"_**) + +We will review your pull request, as soon as time permits. If your changes are accepted, then they will be merged into +this project and released in an upcoming version. Should your pull request not be accepted, then you will be informed +about it. diff --git a/docs/+current/04_security-policy.md b/docs/+current/04_security-policy.md index 2649c08..3e480b1 100644 --- a/docs/+current/04_security-policy.md +++ b/docs/+current/04_security-policy.md @@ -7,4 +7,26 @@ author: RSP Systems A/S # Security Policy -_TODO: ...incomplete, please review documentation at a later point_ \ No newline at end of file +!!! warning "Warning" + Please do NOT disclose security related issues publicly! Use GitHub's "Security Advisories > + [Report Vulnerability](https://github.com/rsps/cmake-scripts/security/advisories/new)" mechanism instead. + + _For additional details, please read the "How to report a vulnerability" for instructions._ + +[TOC] + +## How to report a vulnerability + +To report a security related issue, please use GitHub's vulnerability reporting mechanism. Follow the +on-screen instructions. + +* [Report new Vulnerability](https://github.com/rsps/cmake-scripts/security/advisories/new) + +For additional help, please consider reading ["Best practices for writing repository security advisories"](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/best-practices-for-writing-repository-security-advisories). + +Once we have received the security related issue, we will address it to the best of our ability, as soon as +possible. + +## Supported Versions + +Please review the [Support Policy](./01_release-notes.md#support-policy) before reporting security related issues. \ No newline at end of file diff --git a/docs/+current/05_code-of-conduct.md b/docs/+current/05_code-of-conduct.md index 3fee19a..bac891f 100644 --- a/docs/+current/05_code-of-conduct.md +++ b/docs/+current/05_code-of-conduct.md @@ -7,4 +7,18 @@ author: RSP Systems A/S # Code of Conduct -_TODO: ...incomplete, please review documentation at a later point_ \ No newline at end of file +The following constitutes the code of conduct for the "CMake Scripts" project. + +* Participants must be helpful and constructive. +* Participants must be tolerant and respectful towards the opinions of other participants. +* Participants must ensure their conduct is free from harassment, harmful deeds, inappropriate language or behaviour, and malicious intent. +* Efforts towards the benefit of the overall community must always be favoured, rather than individual needs. + +## Consequences + +Participants are subject to reasonable consequences, if the code of conduct is not upheld. Such consequences can +include banning from further participation. + +## Reporting + +Any violations of the code of conduct can be reported to [RSP Systems](mailto:alin@rspsystems.com). \ No newline at end of file diff --git a/docs/+current/modules/cache/01_set.md b/docs/+current/modules/cache/01_set.md new file mode 100644 index 0000000..2544720 --- /dev/null +++ b/docs/+current/modules/cache/01_set.md @@ -0,0 +1,51 @@ +--- +title: Set +description: Cache a variable +keywords: cache, cmake +author: RSP Systems A/S +--- + +# Set + +Use `cache_set()` to cache a variable. The function accepts the following parameters: + +* `KEY`: _The variable to assign and cache._ +* `VALUE`: _Value to assign and cache._ +* `TTL`: (_optional_), _Time-To-Live of cache entry in seconds (see [TTL](#ttl) for details)._ +* `TYPE`: (_optional_), _Cmake cache entry type, BOOL, STRING,...etc. Defaults to `STRING` if not specified._ +* `DESCRIPTION`: (_optional_), _Description of cache entry._ + +!!! warning "Caution" + Invoking the `cache_set()` function, is the equivalent to using CMake's + [`set(... CACHE FORCE)`](https://cmake.org/cmake/help/latest/command/set.html#set-cache-entry). + +**Example** + +```cmake +cache_set( + KEY foo + VALUE "bar" +) + +message("${foo}") # bar +``` + +## TTL + +You can optionally specify a time-to-live (_ttl_) duration (_in seconds_), for the cache entry. +Whenever the cached variable is queried (_via [`has`](./03_has.md) or [`get`](./02_get.md)_), the entry will +automatically be removed, if it has expired. + +```cmake +cache_set( + KEY foo + VALUE "bar" + TTL 5 +) + +# ... Elsewhere in your cmake scripts, 5 seconds later... + +cache_get(KEY foo) + +message("${foo}") # (empty string) +``` diff --git a/docs/+current/modules/cache/02_get.md b/docs/+current/modules/cache/02_get.md new file mode 100644 index 0000000..a472957 --- /dev/null +++ b/docs/+current/modules/cache/02_get.md @@ -0,0 +1,52 @@ +--- +title: Get +description: Retrieve a cached variable +keywords: cache, cmake +author: RSP Systems A/S +--- + +# Get + +You can use the `cache_get()` function to retrieve a cached variable. It accepts the following parameters: + +* `KEY`: _The variable to assign resulting value to._ +* `DEFAULT`: (_optional_), _Default value to assign, if no cache entry found._ + +**Example** + +```cmake +cache_get( + KEY perform_cleanup + DEFAULT "false" +) + +if(perform_cleanup) + # ...not shown... +endif () +``` + +## Expired Entries + +The benefit of using this function to retrieve a cached variable, is that it will automatically detect if the +cached entry has expired. If this is the case, then the expired variable will be deleted. +If a `DEFAULT` parameter has been specified, then that value is returned instead of an empty string. + +```cmake +cache_set( + KEY perform_cleanup + VALUE "true" + TYPE "BOOL" + TTL 60 +) + +# ... Elsewhere in your cmake scripts, 60 seconds later... + +cache_get( + KEY perform_cleanup + DEFAULT "false" +) + +if(perform_cleanup) + # ...not shown... +endif () +``` diff --git a/docs/+current/modules/cache/03_has.md b/docs/+current/modules/cache/03_has.md new file mode 100644 index 0000000..87edaa6 --- /dev/null +++ b/docs/+current/modules/cache/03_has.md @@ -0,0 +1,31 @@ +--- +title: Has +description: Determine if a cached variable exists +keywords: cache, cmake +author: RSP Systems A/S +--- + +# Has + +Use `cache_has()` to determine if a cached variable exists. It accepts the following parameters: + +* `KEY`: _The target variable to determine if it exists._ +* `OUTPUT`: _Output variable to assign the result to._ + +**Example** + +```cmake +cache_has( + KEY build_assets + OUTPUT exists +) + +if(exists) + # ...not shown... +endif () +``` + +## Expired Entries + +Just like [`cache_get()`](./02_get.md), the `cache_has()` function respects the expiration status of a cached variable. +If the queried variable has expired, then this function will assign `false` to the `OUTPUT` variable. diff --git a/docs/+current/modules/cache/04_remember.md b/docs/+current/modules/cache/04_remember.md new file mode 100644 index 0000000..f92192d --- /dev/null +++ b/docs/+current/modules/cache/04_remember.md @@ -0,0 +1,38 @@ +--- +title: Remember +description: Retrieve a cache variable, or create it if it does not exist +keywords: cache, cmake +author: RSP Systems A/S +--- + +# Remember + +`cache_remember()` is responsible for retrieve cached entry if it exists, or invoke callback and cache resulting +output value of the callback. + +The following parameters are accepted: + +* `KEY`: _ The variable to assign and cache._ +* `CALLBACK`: _ The function or macro that returns value to be cached, if `KEY` hasn't already been cached._ +* `TTL`: (_optional_), _Time-To-Live of cache entry in seconds (see [TTL](./01_set.md#ttl) for details)._ +* `TYPE`: (_optional_), _Cmake cache entry type, BOOL, STRING,...etc. Defaults to `STRING` if not specified._ +* `DESCRIPTION`: (_optional_), _Description of cache entry._ + +**Example** + +```cmake +function(make_asset_uuid output) + # ...complex logic for generating a UUID... (not shown here)... + set("${output}" "...") + + # Assign to "output" variable + return(PROPAGATE "${output}") +endfunction() + +cache_remember( + KEY assert_uuid + CALLBACK "make_asset_uuid" +) + +message("${assert_uuid}") # E.g. 2786d7fb-6d88-4878-b1f6-4c66cee31700 +``` \ No newline at end of file diff --git a/docs/+current/modules/cache/05_forget.md b/docs/+current/modules/cache/05_forget.md new file mode 100644 index 0000000..bce51d6 --- /dev/null +++ b/docs/+current/modules/cache/05_forget.md @@ -0,0 +1,26 @@ +--- +title: Forget +description: Delete a cached variable exists +keywords: cache, cmake +author: RSP Systems A/S +--- + +# Forget + +Call `cache_forget()` to delete a cached entry. It accepts the following parameters: + +* `KEY`: _The target variable to determine if it exists._ +* `OUTPUT`: (_optional_), _Variable to assign delete status._ + +**Example** + +```cmake +cache_forget( + KEY run_cleanup + OUTPUT was_deleted +) + +if(was_deleted) + # ...not shown... +endif () +``` \ No newline at end of file diff --git a/docs/+current/modules/cache/index.md b/docs/+current/modules/cache/index.md index 715496a..5190bc0 100644 --- a/docs/+current/modules/cache/index.md +++ b/docs/+current/modules/cache/index.md @@ -7,5 +7,12 @@ author: RSP Systems A/S # Cache -_TODO: ...incomplete, please review documentation at a later point_ +The cache module offers additional functionality for CMake's [Cache Entry](https://cmake.org/cmake/help/latest/command/set.html#set-cache-entry) +mechanism. + +## How to include + +```cmake +include("rsp/cache") +``` diff --git a/docs/+current/modules/git/find-version-tag.md b/docs/+current/modules/git/find-version-tag.md new file mode 100644 index 0000000..91f3eb6 --- /dev/null +++ b/docs/+current/modules/git/find-version-tag.md @@ -0,0 +1,76 @@ +--- +title: Find Version Tag +description: Using git_find_version_tag +keywords: git, version, tag, cmake +author: RSP Systems A/S +--- + +# Find Version Tag + +The `git_find_version_tag()` function allows you to find the nearest version tag that matches a version-pattern +(_local repository_). Behind the scene, [git-describe](https://git-scm.com/docs/git-describe) is invoked. + +[TOC] + +## Example + +```cmake +include("rsp/git") + +git_find_version_tag( + OUTPUT version + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} +) + +message("${version}") # 1.15.2 +``` + +## Match Pattern + +By default, the following [glob-pattern](https://git-scm.com/docs/git-describe#Documentation/git-describe.txt---matchltpatterngt) +is used for matching a version tag: + +* `*[0-9].*[0-9].*[0-9]*` + +To customize the pattern, specify the `MATCH_PATTERN` parameter. + +```cmake +git_find_version_tag( + OUTPUT pre_release + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + MATCH_PATTERN "*[0-9].*[0-9].*[0-9]-*" +) + +message("${pre_release}") # 1.0.0-alpha.2 +``` + +## Default Version + +If unable to find a version tag, `"0.0.0"` is returned +(_See also [Exit on Failure](#exit-on-failure)_). +You can change this by setting the `DEFAULT` parameter, in situations when no version tag can be found. + +```cmake +git_find_version_tag( + OUTPUT version + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + DEFAULT "0.1.0" +) + +message("${version}") # 0.1.0 +``` + +## Exit on Failure + +A fatal error will be raised, if the `EXIT_ON_FAILURE` option is set, and no version tag can be found. +When doing so, the [default version](#default-version) parameter will be ignored. + +```cmake +git_find_version_tag( + OUTPUT version + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + DEFAULT "0.1.0" + EXIT_ON_FAILURE +) # Fatal Error: No version tag found ... +``` + diff --git a/docs/+current/modules/git/index.md b/docs/+current/modules/git/index.md index 4753b6b..fa5c723 100644 --- a/docs/+current/modules/git/index.md +++ b/docs/+current/modules/git/index.md @@ -7,5 +7,14 @@ author: RSP Systems A/S # Git -_TODO: ...incomplete, please review documentation at a later point_ +This module contains helpers and utilities for interacting with [git](https://git-scm.com/). +## Requirements + +This module requires [git](https://git-scm.com/) to be available on your system. + +## How to include + +```cmake +include("rsp/git") +``` \ No newline at end of file diff --git a/docs/+current/modules/helpers/index.md b/docs/+current/modules/helpers/index.md index 7f4114d..c0f268d 100644 --- a/docs/+current/modules/helpers/index.md +++ b/docs/+current/modules/helpers/index.md @@ -7,5 +7,11 @@ author: RSP Systems A/S # Helpers -_TODO: ...incomplete, please review documentation at a later point_ +The helpers module contains miscellaneous functions that are used by "CMake Scripts". +Feel free to use them within your own project, if you find them helpful. +## How to include + +```cmake +include("rsp/helpers") +``` \ No newline at end of file diff --git a/docs/+current/modules/testing/cmake/-asserts.md b/docs/+current/modules/testing/cmake/-asserts.md new file mode 100644 index 0000000..4b57d3f --- /dev/null +++ b/docs/+current/modules/testing/cmake/-asserts.md @@ -0,0 +1,216 @@ +--- +title: Asserts +description: Assert functions +keywords: testing, assert, cmake +author: RSP Systems A/S +--- + +# Asserts + +[TOC] + +## Failure Message + +All assert functions support an optional `MESSAGE` argument, which is shown if the assertion failed. + +```cmake +assert_truthy(false MESSAGE "My fail msg...") +``` + +## Existence + +### `assert_defined()` + +Assert key to be defined. + +```cmake +assert_defined(my_variable) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#defined. + +### `assert_not_defined()` + +The opposite of `assert_defined()`. + +```cmake +assert_not_defined(my_variable) +``` + +## Boolean + +### `assert_truthy()` + +Assert key to be truthy. + +```cmake +assert_truthy(my_variable) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#basic-expressions. + +### `assert_falsy()` + +The opposite of `assert_truthy()`. + +```cmake +assert_falsy(my_variable) +``` + +## Numbers + +### `assert_equals()` + +Assert numeric keys or values equal each other.. + +```cmake +assert_equals(expected actual) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#equal. + +### `assert_not_equals()` + +The opposite of `assert_equals()`. + +```cmake +assert_not_equals(expected actual) +``` + +### `assert_less_than()` + +Assert numeric key or value is less than specified value. + +```cmake +assert_less_than(expected actual) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#less. + +### `assert_less_than_or_equal()` + +Assert numeric key or value is less than or equal to the specified value. + +```cmake +assert_less_than_or_equal(expected actual) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#less-equal. + +### `assert_greater_than()` + +Assert numeric key or value is greater than specified value. + +```cmake +assert_greater_than(expected actual) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#greater. + +### `assert_greater_than_or_equal()` + +Assert numeric key or value is greater than or equal to the specified value. + +```cmake +assert_greater_than_or_equal(expected actual) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#greater-equal. + +## Strings + +### `assert_string_equals()` + +Assert string keys or values equal each other. + +```cmake +assert_string_equals(expected actual) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#strequal + +### `assert_string_not_equals()` + +Opposite of `assert_string_equals()`. + +```cmake +assert_string_not_equals(expected actual) +``` + +### `assert_string_empty()` + +Assert given string is empty. + +```cmake +assert_string_empty("${my_string}") +``` + +See https://cmake.org/cmake/help/latest/command/string.html#length + +### `assert_string_not_empty()` + +Opposite of `assert_string_empty()`. + +```cmake +assert_string_not_empty("${my_string}") +``` + +## Lists + +### `assert_in_list()` + +Assert key (value) to be in given list. + +```cmake +assert_in_list(item list) +``` + +See https://cmake.org/cmake/help/latest/command/if.html#in-list. + +### `assert_not_in_list()` + +Opposite of `assert_in_list()`. + +```cmake +assert_not_in_list(item list) +``` + +## Commands & Macros + +### `assert_is_callable()` + +Assert key to be a callable command or macro. + +```cmake +assert_is_callable("my_function") +``` + +See https://cmake.org/cmake/help/latest/command/if.html#command. + +### `assert_is_not_callable()` + +Opposite of `assert_is_callable()`. + +```cmake +assert_is_not_callable("my_unknown_function") +``` + +## Files & Paths + +### `assert_file_exists()` + +Assert file exists. + +```cmake +assert_file_exists("${my_file_path}") +``` + +See https://cmake.org/cmake/help/latest/command/if.html#exists. + +### `assert_file_not_exists()` + +Opposite of `assert_file_exists()`. + +```cmake +assert_file_not_exists("${my_file_path}") +``` \ No newline at end of file diff --git a/docs/+current/modules/testing/cmake/01_test_suite.md b/docs/+current/modules/testing/cmake/01_test_suite.md new file mode 100644 index 0000000..3396cea --- /dev/null +++ b/docs/+current/modules/testing/cmake/01_test_suite.md @@ -0,0 +1,71 @@ +--- +title: Test Suite +description: How to define a test suite +keywords: testing, test-suite, cmake +author: RSP Systems A/S +--- + +# Test Suite + +The `define_test_suite()` function is used to group related test cases into a +[test suite](https://en.wikipedia.org/wiki/Test_suite). + +[TOC] + +## Parameters + +The following parameters are accepted: + +* < name >: _Human readable name of test suite. The parameter is also used to label tests (see [labels](#labels))._ +* `DIRECTORY`: _Path to directory that contains test-cases._ +* `MATCH`: (_optional_), _Glob pattern used to match test-case files. Defaults to `*_test.cmake` (see [match pattern](#match-pattern))._ + +!!! warning "Rebuild Required" + Changes to function `define_test_suite()` parameters requires you to rebuild your project, before the changes take effect. + +## Example + +```cmake +include("rsp/testing") + +define_test_suite("unit" DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/unit") +define_test_suite("integration" DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/integration") +``` + +Given the above shown example, when `define_test_suite()` is invoked, it will recursively search for files¹ in the +specified directory. Each file is then [included](https://cmake.org/cmake/help/latest/command/include.html) into the +current CMake scope. This means that calls to [`define_test_case()`](./02_test_case.md) and +[`define_test()`](./03_test.md) are registered (_tests are added to ctest_). + +After you have built your CMake project, you will be able to run the tests. + +```sh +ctest --output-on-failure --test-dir /tests +``` + +¹: _See [match pattern](#match-pattern)._ + +## Match Pattern + +By default, only files that match `*_test.cmake` will be processed by `define_test_suite()`. If this is not to your +liking, then you can specify a custom match pattern: + +```cmake +define_test_suite( + "unit" + DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/unit" + MATCH "*Test.cmake" +) +``` + +## Labels + +The `< name >` parameter is used to automatically used as a [label](https://cmake.org/cmake/help/latest/prop_test/LABELS.html#prop_test:LABELS) +for all tests within the test suite. This allows you to use [ctest's label regex](https://cmake.org/cmake/help/latest/manual/ctest.1.html#cmdoption-ctest-L) +functionality and thereby only run the tests from the suite that you wish. + +```sh +ctest --output-on-failure \ + --label-regex "integration" \ + --test-dir /tests +``` \ No newline at end of file diff --git a/docs/+current/modules/testing/cmake/02_test_case.md b/docs/+current/modules/testing/cmake/02_test_case.md new file mode 100644 index 0000000..64fed08 --- /dev/null +++ b/docs/+current/modules/testing/cmake/02_test_case.md @@ -0,0 +1,150 @@ +--- +title: Test Case +description: How to define a test case +keywords: testing, test-case, cmake +author: RSP Systems A/S +--- + +# Test Case + +`define_test_case()` is used to describe a [test-case](https://en.wikipedia.org/wiki/Test_case). In this context, +a test case can be interpreted as a collection or related tests. + +[TOC] + +## Parameters + +The following parameters are accepted: + +* < name >: _Human readable name of test case. The parameter is also used as an affix for test names, in ctest._ +* `BEFORE`: (_optional_), _Command or macro to execute before each test in test-case (see [Before / After Callbacks](#before-after-callbacks))._ +* `AFTER`: (_optional_), _Command or macro to execute after each test in test-case (see [Before / After Callbacks](#before-after-callbacks))._ +* `LABELS`: (_optional_), _List of labels to associate subsequent tests with (see [labels](#labels))._ +* `RUN_SERIAL`: (_optional_), _Option that prevents test-case's tests from running in parallel with other tests._ + +!!! warning "Rebuild Required" + Changes to function `define_test_case()` parameters requires you to rebuild your project, before the changes take effect. + +## Example + +```cmake +# ...inside your test file... +include("rsp/testing") + +define_test_case( + "Assets Test" + LABELS "assets" +) + +# ...tests not shown ... +``` + +Once you have defined a test-case, in the beginning of your test file, then all subsequent [test definitions](./03_test.md) +will automatically be associated with that test-case. + +!!! warning "Caution" + You should avoid defining multiple test-cases in a single file, as it can lead to unexpected behaviour. + _See [multiple test-cases in same file](#multiple-test-cases-in-same-file) for details._ + + +## Labels + +The `LABELS` parameter allows you to specify a list of labels, which are then automatically associated with each test, +in the test-case. This also enables you to use [ctest's label regex](https://cmake.org/cmake/help/latest/manual/ctest.1.html#cmdoption-ctest-L) +functionality to limit the tests that you wish to run (_see ctest run example in [test-suite documentation](./01_test_suite.md#labels)_). + +```cmake +define_test_case( + "Assets Test" + LABELS "assets;resources;build" +) + +# ...tests not shown ... +``` + +## Before / After Callbacks + +The `BEFORE` and `AFTER` parameters allow you to specify a function or macro that must be executed before or after +each test. This can be useful in situations when your tests require setup and teardown logic. + +```cmake +define_test_case( + "Assets Test" + + BEFORE "before_assets_test" + AFTER "after_assets_test" +) + +macro(before_assets_test) + # ...your setup logic... + set(OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/output" PARENT_SCOPE) + + # ...etc +endmacro() + +function(after_assets_test) + # ... cleanup not shown ... +endfunction() + +# "Before" macro will be invoked before the test... +define_test("can build assets" "can_build_assets") +function(can_build_assets) + # ... not shown ... +endfunction() + +# "After" function will be invoked after the above test... +``` + +!!! info "Tip" + Depending on the complexity of your before and after logic, you have to set the [`RUN_SERIAL`](#run-serial), + to avoid race-conditions when tests are executed in parallel. + +## Run Serial + +If you are executing tests in [parallel](https://cmake.org/cmake/help/latest/manual/ctest.1.html#cmdoption-ctest-j), +and you have complex setup and teardown logic that could lead to +[race conditions](https://en.wikipedia.org/wiki/Race_condition#In_software), then you _SHOULD_ mark the test-case to +execute its tests in serial, by setting the `RUN_SERIAL` option. + +```cmake +define_test_case( + "Assets Test" + + BEFORE "before_assets_test" + AFTER "after_assets_test" + RUN_SERIAL +) + +# ...remaining not shown... +``` + +## Multiple Test-Cases in same file + +If you wish to define multiple test-cases in the same file, then you manually need to "end" each test-case, before +defining a new test-case. + +```cmake +# ...inside your test file... +define_test_case( + "Test-Case A" +) + +# ...tests not shown ... + +# End / Close "Test-Case A" +end_test_case() + +define_test_case( + "Test-Case B" +) + +# ...tests not shown ... + +# End / Close "Test-Case B" +end_test_case() +``` + +Normally, `define_test_suite()` automatically ensures to "end" test-cases. However, it presumes that each test file only +defines a single test-case. + +_Please review the source code for additional information._ \ No newline at end of file diff --git a/docs/+current/modules/testing/cmake/03_test.md b/docs/+current/modules/testing/cmake/03_test.md new file mode 100644 index 0000000..cb20db7 --- /dev/null +++ b/docs/+current/modules/testing/cmake/03_test.md @@ -0,0 +1,117 @@ +--- +title: Test +description: How to define a test +keywords: testing, test, cmake +author: RSP Systems A/S +--- + +# Test + +The `define_test()` function is used to describe what callback (_function_) must be invoked when tests are executed. +Behind the scene, this function is responsible to +[register](https://cmake.org/cmake/help/latest/command/add_test.html#command:add_test) the test for ctest. +This is done by adding a ctest that invokes an "intermediary" - a [test executor](./05_executor.md) - which is +responsible for invoking the specified callback, via `define_test()`. + +[TOC] + +## Parameters + +* < name >: _Human readable name of test case._ +* < callback >: _The function that contains the actual test logic._ +* `DATA_PROVIDER`: (_optional_), _Command or macro that provides data-set(s) for the test. See [data providers](#data-providers) for details._ +* `EXPECT_FAILURE`: (_optional_), _Options, if specified then callback is expected to fail. See [failure expectations](#failure-expectations) for details._ +* `SKIP`: (_optional_), _Option, if set then test will be marked as "disabled" and not executed. See [skipping tests](#skipping-tests) for details._ + +!!! warning "Rebuild Required" + Changes to function `define_test()` parameters requires you to rebuild your project, before the changes take effect. + +!!! danger "Caution" + Although the `< callback >` parameter can accept a + [marco](https://cmake.org/cmake/help/latest/command/macro.html#macro), you _SHOULD_ always use a + [function](https://cmake.org/cmake/help/latest/command/function.html#command:function) for defining the actual + test logic. Using a marco can lead to undesired side effects. Please read CMake's + ["Macro vs. Function"](https://cmake.org/cmake/help/latest/command/macro.html#macro-vs-function) for additional + details. + +## Example + +```cmake +include("rsp/testing") + +# ... previous not shown ... + +define_test("assets are ready after build" "asserts_ready") +function(asserts_ready) + + # ...actual test logic not shown here... + + assert_truthy(assets_exist MESSAGE "Assets have not been built...") +endfunction() +``` + +## Failure Expectations + +When you need to test logic that is intended to fail when certain conditions are true, then you can mark your test +to expect a failure. This is done by setting the `EXPECT_FAILURE` option. + +```cmake +define_test("fails when assets not built" "fails_when_not_ready" EXPECT_FAILURE) +function(fails_when_not_ready) + + # ...actual test logic not shown here... + + assert_truthy(false) +endfunction() +``` + +Behind the scene, ctest's [`WILL_FAIL`](https://cmake.org/cmake/help/latest/prop_test/WILL_FAIL.html#prop_test:WILL_FAIL) +property is set for the given test, when the `EXPECT_FAILURE` option is set. + +## Data Providers + +You can specify a function or marco as a test's data-provider, via the `DATA_PROVIDER` parameter. +Doing so will result in the same test being executed multiple times, with different sets of data. +The specified function or marco **MUST** assign a list of "items" (_test data_) to the given `< output >` variable. + +```cmake +function(provides_data output) + set("${output}" "a;b;c;d") + return (PROPAGATE "${output}") +endfunction() + +define_test( + "My Test" + "my_test" + DATA_PROVIDER "provides_data" +) +function(my_test letter) + string(LENGTH "${letter}" length) + + assert_greater_than(0 length MESSAGE "No letter provided: (length: ${length})") +endfunction() +``` + +In the above "My Test" will be registered multiple times, one for each item provided by the `provides_data()` function. +Each data-set item is then passed on to the test, as an argument. + +!!! warning "Rebuild Required" + Whenever you change the items provided by a "data provider" function, you will be required to rebuild + your CMake project, before the changes are reflected by the executed tests! + +## Skipping tests + +Set the `SKIP` option, if you wish to ensure that a test is not executed by ctest. + +```cmake +# Test is SKIPPED +define_test("can build with bitmap pictures" "can_build_with_bitmap" SKIP) +function(can_build_with_bitmap) + + # ...not shown... + +endfunction() +``` + +Behind the scene, ctest's [`DISABLED`](https://cmake.org/cmake/help/latest/prop_test/DISABLED.html) +property is set, when a test is marked as skipped. \ No newline at end of file diff --git a/docs/+current/modules/testing/cmake/04_run_tests.md b/docs/+current/modules/testing/cmake/04_run_tests.md new file mode 100644 index 0000000..0248fee --- /dev/null +++ b/docs/+current/modules/testing/cmake/04_run_tests.md @@ -0,0 +1,49 @@ +--- +title: Run Tests +description: How to run tests +keywords: testing, execution, cmake +author: RSP Systems A/S +--- + +# Run Tests + +To run test tests, you must first ensure that you build your CMake project. Once you have done so, use the +[ctest executable](https://cmake.org/cmake/help/latest/manual/ctest.1.html) to execute the tests. + +```sh +ctest --output-on-failure --test-dir /tests +``` + +## Run Specific Tests + +To run only certain tests, use the `--label-regex` option. + +```sh +ctest --output-on-failure \ + --label-regex "unit" \ + --test-dir /tests +``` + +For additional information, see "labels" section in [test suites](./01_test_suite.md#labels) and +[test cases](./02_test_case.md#labels). + +## Run Parallel + +To run tests in parallel, use the `--parallel` option. + +```sh +ctest --output-on-failure --parallel --test-dir /tests +``` + +## Run Failed + +To (re)run tests that have failed, use the `--rerun-failed` option. + +```sh +ctest --rerun-failed --test-dir /tests +``` + +## Onward + +For additional command line arguments and options, please review the official documentation for the +[ctest executable](). \ No newline at end of file diff --git a/docs/+current/modules/testing/cmake/05_executor.md b/docs/+current/modules/testing/cmake/05_executor.md new file mode 100644 index 0000000..cf3cb2e --- /dev/null +++ b/docs/+current/modules/testing/cmake/05_executor.md @@ -0,0 +1,39 @@ +--- +title: Executor +description: How to customise test executor +keywords: testing, execution, executor, cmake +author: RSP Systems A/S +--- + +# Test Executor + +When tests are registered (_via [ctest's `add_test()`](https://cmake.org/cmake/help/latest/command/add_test.html)_), +a "test executor" (_cmake script_) is requested executed. The executor is then responsible for invoking the actual test +callback, that has been specified via [`define_test()`](./03_test.md#parameters). +In addition, the executor is also responsible for executing eventual +[before and after callbacks](./02_test_case.md#before-after-callbacks), for the test case. + +## Location + +The executor can be found at: +[`rsp/testing/executor.cmake`](https://github.com/rsps/cmake-scripts/blob/main/cmake/rsp/testing/executor.cmake). + +## Custom Executor + +To use a custom executor, set the path to your executor via the `RSP_TEST_EXECUTOR_PATH` property. +This _SHOULD_ be done before specifying your test suites. + +```cmake +# ...in your /tests/CMakeLists.txt + +enable_testing() + +project(my_package_tests LANGUAGES NONE) + +include("rsp/testing") + +# Set path to custom test executor +set(RSP_TEST_EXECUTOR_PATH "../cmake/my_custom_test_executor.cmake") + +define_test_suite("unit" DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/unit") +``` diff --git a/docs/+current/modules/testing/cmake/index.md b/docs/+current/modules/testing/cmake/index.md new file mode 100644 index 0000000..8467c44 --- /dev/null +++ b/docs/+current/modules/testing/cmake/index.md @@ -0,0 +1,121 @@ +--- +title: Modules & Scripts +description: How to write tests for your CMake modules and scripts +keywords: testing, cmake +author: RSP Systems A/S +--- + +# Testing CMake Modules & Scripts + +The `testing` module includes a "_mini_" framework for testing your CMake modules and scripts. It is built on top of +[CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html#manual:ctest(1)). + +[TOC] + +## Getting Started + +The following guide illustrates how you can get started. It is by no means a comprehensive guide on how to write tests, +but rather just a starting point. + +### Directory Structure + +Create an appropriate directory in which your tests should reside. For instance, this can be located in the root +of your project. You can name it "tests", or whatever makes the most sense for you. The important part is to isolate +tests from the remaining of your project's CMake logic. + +The following example is a possible directory and files structure, that you can use. + +``` +/tests + /unit + /assets + build_assets_test.cmake + CMakeLists.txt +CMakeLists.txt +``` + +### Define Test Suite + +In your `/tests/CMakeLists.txt`, define the [test suite(s)](./01_test_suite.md) for your project. + +```cmake +# ...in your /tests/CMakeLists.txt + +enable_testing() + +project(my_package_tests LANGUAGES NONE) + +include("rsp/testing") + +# Define the test suites for this project +define_test_suite("unit" DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/unit") +``` + +### Define Test Case + +To define a new test case, invoke the [`define_test_case()`](./02_test_case.md) function. +This should be done in each test file (_e.g. in the `/tests/unit/assets/build_assets_tests.cmake` from the above +shown example directory and files structure)._ + +```cmake +# ... in your test file + +include("rsp/testing") + +define_test_case( + "Build Assets Test" + LABELS "assets;build" +) + +# ... remaining not shown ... +``` + +### Define Test(s) + +Once your test-case has been defined, you can define the tests. To do so, you need to define the function that must +be invoked when the test-case is executed. This is done by the [`define_test()`](./03_test.md) function. + +```cmake +# ... in your test file + +# ... previous not shown ... + +define_test("can build assets" "can_build_assets") +function(can_build_assets) + + # ... testing logic not shown ... + + assert_truthy(assets_built MESSAGE "Assets could bot be built...") +endfunction() + +define_test("fails if assets not ready" "fails_when_not_ready" EXPECT_FAILURE) +function(fails_when_not_ready) + + # ... testing logic not shown ... + + assert_truthy(false MESSAGE "Assets should not be built when not ready...") +endfunction() + +# ... etc +``` + +### Build & Run + +To run the tests, you must first build the project using CMake. After that, use +[CTests](https://cmake.org/cmake/help/latest/manual/ctest.1.html#manual:ctest(1)) to run the tests. + +```sh +ctest --output-on-failure --parallel --test-dir /tests +``` + +## Caveats + +Due to the nature of how tests are [defined (_via ctest_)](https://cmake.org/cmake/help/latest/command/add_test.html#command:add_test), +and how this "mini" testing framework has been designed, you might be required to rebuild your CMake, whenever changes +are made to the various "define" functions' parameters. This can, for instance, be when you rename a test function. + +Throughout the remain of this documentation, if a "define" function requires rebuilding before changes take effect, +then it will be highlighted via a warning, similar to the one shown below: + +!!! warning "Rebuild Required" + Changes to function `xyz` parameters requires you to rebuild your project, before the changes take effect. \ No newline at end of file diff --git a/docs/+current/modules/testing/index.md b/docs/+current/modules/testing/index.md index e6b0fef..dfc405b 100644 --- a/docs/+current/modules/testing/index.md +++ b/docs/+current/modules/testing/index.md @@ -7,5 +7,12 @@ author: RSP Systems A/S # Testing -_TODO: ...incomplete, please review documentation at a later point_ +"CMake Scripts" has been developed with testing in mind. To ensure that the provided functionality works as intended, +we have made an effort to write code that is testable. As a direct result of this, various testing utilities have been +developed (_e.g. for cmake modules and scripts_), which are offered in this module. +## How to include + +```cmake +include("rsp/testing") +``` \ No newline at end of file diff --git a/docs/+current/modules/version/index.md b/docs/+current/modules/version/index.md index 11e4723..2d9fa39 100644 --- a/docs/+current/modules/version/index.md +++ b/docs/+current/modules/version/index.md @@ -7,5 +7,14 @@ author: RSP Systems A/S # Version -_TODO: ...incomplete, please review documentation at a later point_ +This module contains helpers for dealing with a project's versioning. +## Requirements + +The same requirements as for the [git module](../git/index.md). + +## How to include + +```cmake +include("rsp/version") +``` \ No newline at end of file diff --git a/docs/+current/modules/version/semver/index.md b/docs/+current/modules/version/semver/index.md new file mode 100644 index 0000000..e2f3a83 --- /dev/null +++ b/docs/+current/modules/version/semver/index.md @@ -0,0 +1,11 @@ +--- +title: Semantic Version +description: Utils for working with Semantic Version +keywords: semver, version, cmake +author: RSP Systems A/S +--- + +# Semantic Version + +Functions and macros that are prefixed `semver_*` offer help to work with version strings, in accordance with +[Semantic Version](https://semver.org/). diff --git a/docs/+current/modules/version/semver/parse.md b/docs/+current/modules/version/semver/parse.md new file mode 100644 index 0000000..bc43e9d --- /dev/null +++ b/docs/+current/modules/version/semver/parse.md @@ -0,0 +1,102 @@ +--- +title: Parse +description: How to perse semantic version string +keywords: semver, version, parse, cmake +author: RSP Systems A/S +--- + +# Parse Semantic Version + +`semver_parse()` parses a semantic version string and assigns the various version parts to the provided output variable. + +[TOC] + +## Example + +```cmake +include("rsp/version") + +semver_parse( + VERSION "v2.0.0-beta.3+AF1004" + OUTPUT my_package +) + +# (see example output below...) +``` + +## Output + +### Full Version + +The `[OUTPUT]` variable will contain the full version string, as it was provided: + +```cmake +message("${my_package}") # v2.0.0-beta.3+AF1004 +``` + +### Major, Minor and Patch + +The `[OUTPUT]_VERSION` variable contains a CMake friendly version string (_major.minor.patch_) + +```cmake +message("${my_package}_VERSION") # 2.0.0 +``` + +### Semantic Version + +The `[OUTPUT]_SEMVER` variable contains the full semantic version, without eventual "v" prefix. + +```cmake +message("${my_package}_SEMVER") # 2.0.0-beta.3+AF1004 +``` + +### Major Version + +The `[OUTPUT]_MAJOR` variable contains the major version. + +```cmake +message("${my_package}_MAJOR") # 2 +``` + +### Minor Version + +The `[OUTPUT]_MINOR` variable contains the minor version. + +```cmake +message("${my_package}_MINOR") # 0 +``` + +### Patch Version + +The `[OUTPUT]_PATCH` variable contains the patch version. + +```cmake +message("${my_package}_PATCH") # 0 +``` + +### Pre-Release + +The `[OUTPUT]_PRE_RELEASE` variable contains the [pre-release](https://semver.org/#spec-item-9) version. + +```cmake +message("${my_package}_PRE_RELEASE") # beta.3 +``` +### Build Metadata + +The `[OUTPUT]_BUILD_METADATA` variable contains the [build metadata](https://semver.org/#spec-item-10). + +```cmake +message("${my_package}_BUILD_METADATA") # AF1004 +``` + +## Invalid Version + +A fatal error is raised, in situations when the provided version string cannot be parsed in accordance +with [Semantic Version](https://semver.org/). + +```cmake +semver_parse( + VERSION "4.11" + OUTPUT my_package +) # Fatal Error: 4.11 is not a valid semantic version +``` \ No newline at end of file diff --git a/docs/+current/modules/version/version-file.md b/docs/+current/modules/version/version-file.md new file mode 100644 index 0000000..ea00584 --- /dev/null +++ b/docs/+current/modules/version/version-file.md @@ -0,0 +1,97 @@ +--- +title: Version File +description: To to work with version files +keywords: git, semver, version, file, cmake +author: RSP Systems A/S +--- + +# Version File(s) + +In this section you can find examples on how to read and write a version string, from and to a file. + +[TOC] + +## Write Version File + +Use `write_version_file()` to write a version string to a specified file. +The function accepts two parameters: + +* `FILE`: _Path to target file in which the version must be written_ +* `VERSION`: (_optional_) _The version string to write in file (see "default version" for details)._ + +**Example** + +```cmake +include("rsp/version") + +write_version_file( + FILE "version.txt" + VERSION "v1.4.3" +) +``` + +!!! warning "Caution" + `write_version_file()` expects the `VERSION` parameter to be a valid version string + that can be parsed by [`semver_parse()`](./semver/parse.md). A fatal error is raised, + if that is not the case. + +**Default Version** + +If the `VERSION` parameter is not specified, then [`git_find_version_tag()`](../git/find-version-tag.md) is used to +obtain the nearest version tag. This will then be written to the target version file. + +## Read Version File + +The `version_from_file()` can be used to read a version string from a specified file. Once a version string has been +obtained, it will be parsed using [`semver_parse`](./semver/parse.md). + +**Example** + +```cmake +include("rsp/version") + +version_from_file( + FILE "version.txt" + OUTPUT my_package +) + +message("${my_package}_SEMVER") # 2.0.0-beta.3+AF1004 +message("${my_package}_VERSION") # 2.0.0 +``` + +!!! warning "Caution" + Just like the `write_version_file()` function, the `version_from_file()` also parses the version string using + [`semver_parse()`](./semver/parse.md). A fatal error is raised, if the version string is not valid. + +**Default Version** + +If the given file does not contain a version string, then `"0.0.0"` is returned. +To change this behaviour, specify the `DEFAULT` parameter. + +```cmake +version_from_file( + FILE "version.txt" + OUTPUT my_package + DEFAULT "1.0.0" +) + +message("${my_package}_VERSION") # 1.0.0 +``` + +## Exit on Failure + +When the `EXIT_ON_FAILURE` option is set, the function will raise a fatal error in the following situations: + +* If the version file does not exist. +* If obtained version string cannot be parsed. + +The `DEFAULT` parameter will be ignored, if this option is set. + +```cmake +version_from_file( + FILE "unknown-file" + OUTPUT my_package + DEFAULT "1.0.0" + EXIT_ON_FAILURE +) # Fatal Error: Version file unknown-file does not exist +``` \ No newline at end of file diff --git a/docs/_index.md b/docs/_index.md index fd637fd..3763bee 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -10,13 +10,6 @@ author: RSP Systems A/S The CMake Scripts package contains a collection of reusable "modules", that can be used in your `CMakeLists.txt`, for your C++ projects. -!!! warning "Work in progress" - The documentation is in a very early stage. Feel free to review it, but please do not expect it to be complete! - -## Features - -_TODO: ...(please review docs for details.)_ - ## Authors "CMake Scripts" is developed and maintained by [RSP System A/S](https://rspsystems.com/). diff --git a/resources/daux/themes/rsp/css/style.css b/resources/daux/themes/rsp/css/style.css index 011e46c..4fcd899 100644 --- a/resources/daux/themes/rsp/css/style.css +++ b/resources/daux/themes/rsp/css/style.css @@ -71,6 +71,12 @@ /* Code blocks */ --code-block-bg-color: var(--lightest-gray); + + /* table */ + --table-border: var(--lighter-gray); + --table-background: #fff; + --table-background-odd: var(--lightest-gray); + --table-header-background: var(--lighter-gray); } .dark { @@ -105,6 +111,12 @@ --hero-button-secondary-border-color: var(--color-secondary); --hero-button-secondary-color: var(--lighter-gray); --hero-button-secondary-background: var(--color-secondary); + + /* table */ + --table-border: var(--dark-gray); + --table-background: var(--body-background); + --table-background-odd: var(--dark-gray); + --table-header-background: var(--dark-gray); } /* ------------------------------------------------------------------------------------------------------------------- @@ -155,6 +167,10 @@ html { background-color: var(--code-block-bg-color); } + + a { + text-decoration: none; + } } nav {