Merge branch 'master' into feature/faster-CI

CMakeLists.txt

@@ -24,16 +24,25 @@ cmake_minimum_required(VERSION 3.25)
 project(mp-units-dev LANGUAGES CXX)
 
 list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
+list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/src/cmake")
+include(CheckCacheVarValues)
 
 set(projectPrefix MP_UNITS_)
 
 option(${projectPrefix}DEV_BUILD_LA "Build code depending on the linear algebra library" OFF)
 option(${projectPrefix}DEV_IWYU "Enables include-what-you-use" OFF)
 option(${projectPrefix}DEV_CLANG_TIDY "Enables clang-tidy" OFF)
+set(${projectPrefix}DEV_TIME_TRACE
+    NONE
+    CACHE STRING
+          "Enables `-ftime-trace` for a selected scope: NONE, ALL, MODULES, HEADERS. MODULES and HEADERS do not affect unit tests."
+)
+check_cache_var_values(DEV_TIME_TRACE NONE ALL MODULES HEADERS)
 
 message(STATUS "${projectPrefix}DEV_BUILD_LA: ${${projectPrefix}DEV_BUILD_LA}")
 message(STATUS "${projectPrefix}DEV_IWYU: ${${projectPrefix}DEV_IWYU}")
 message(STATUS "${projectPrefix}DEV_CLANG_TIDY: ${${projectPrefix}DEV_CLANG_TIDY}")
+message(STATUS "${projectPrefix}DEV_TIME_TRACE: ${${projectPrefix}DEV_TIME_TRACE}")
 
 # make sure that the file is being used as an entry point
 include(modern_project_structure)
@@ -74,5 +83,4 @@ endif()
 
 # add unit tests
 enable_testing()
-
 add_subdirectory(test)

CONTRIBUTING.md

@@ -3,16 +3,27 @@
 👍🎉 First off, thanks for taking the time to contribute! 🎉👍
 
 
+## **mp-units** documentation
+
+Before contributing, it is highly recommended to familiarize yourself with our
+[official documentation](https://mpusz.github.io/mp-units).
+
+This file is also a part of it, and this is why it has non-standard Markdown formatting (which can
+be seen when reading in a regular Markdown renderer). To benefit from full mkdocs rendering, please
+switch to the [Contributing](https://mpusz.github.io/mp-units/latest/getting_started/contributing)
+chapter of our documentation.
+
+
 ## Where to start?
 
 If you are looking for a good issue to start with, please check the following:
 
 - [good first issue](https://github.com/mpusz/mp-units/labels/good%20first%20issue) - issues that
- should be pretty simple to implement,
+  should be pretty simple to implement,
 - [help wanted](https://github.com/mpusz/mp-units/labels/help%20wanted) - issues that typically are
- a bit more involved than beginner issues,
+  a bit more involved than beginner issues,
 - [high priority](https://github.com/mpusz/mp-units/labels/high%20priority) - things to fix ASAP
- but often of higher complexity.
+  but often of higher complexity.
 
 
 ## Gitpod
@@ -46,28 +57,28 @@ if you want to set up a development environment on your local machine.
 
 [`user.mp-units.build:all`](#user.mp-units.build-all){ #user.mp-units.build-all }
 
- Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in
- [Repository directory tree and dependencies](https://mpusz.github.io/mp-units/latest/getting_started/project_structure#cmake-projects-and-dependencies).
- It also runs unit tests during the Conan build (unless
- [`tools.build:skip_test`](https://docs.conan.io/2/reference/commands/config.html?highlight=tools.build:skip_test#conan-config-list)
- configuration property is set to `True`).
+:   Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in
+    [Repository directory tree and dependencies](https://mpusz.github.io/mp-units/latest/getting_started/project_structure#cmake-projects-and-dependencies).
+    It also runs unit tests during the Conan build (unless
+    [`tools.build:skip_test`](https://docs.conan.io/2/reference/commands/config.html?highlight=tools.build:skip_test#conan-config-list)
+    configuration property is set to `True`).
 
- [conan build all support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+    [conan build all support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
 
 [`user.mp-units.build:skip_la`](#user-skip-la){ #user-skip-la }
 
- If `user.mp-units.build:all` is enabled, among others, Conan installs the external
- [wg21-linear_algebra](https://conan.io/center/recipes/wg21-linear_algebra)
- dependency and enables the compilation of linear algebra-based tests and usage examples.
- Such behavior can be disabled with this option.
+:   If `user.mp-units.build:all` is enabled, among others, Conan installs the external
+    [wg21-linear_algebra](https://conan.io/center/recipes/wg21-linear_algebra)
+    dependency and enables the compilation of linear algebra-based tests and usage examples.
+    Such behavior can be disabled with this option.
 
- [conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+    [conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
 
 [`user.mp-units.analyze:clang-tidy`](#user.mp-units.analyze-clang-tidy){ #user.mp-units.analyze-clang-tidy }
 
- Enables clang-tidy analysis.
+:   Enables clang-tidy analysis.
 
- [conan clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+    [conan clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
 
 
 ### CMake options for mp-units project developers
@@ -76,25 +87,39 @@ if you want to set up a development environment on your local machine.
 
 :   [:octicons-tag-24: 2.2.0][cmake build la support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
 
- Enables building code depending on the linear algebra library.
+    Enables building code depending on the linear algebra library.
 
- [cmake build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+    [cmake build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
 
 [`MP_UNITS_DEV_IWYU`](#MP_UNITS_DEV_IWYU){ #MP_UNITS_DEV_IWYU }
 
 :   [:octicons-tag-24: 2.2.0][cmake iwyu support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
 
- Enables include-what-you-use analysis.
+    Enables include-what-you-use analysis.
 
- [cmake iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+    [cmake iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
 
 [`MP_UNITS_DEV_CLANG_TIDY`](#MP_UNITS_DEV_CLANG_TIDY){ #MP_UNITS_DEV_CLANG_TIDY }
 
 :   [:octicons-tag-24: 2.2.0][cmake clang-tidy support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
 
- Enables clang-tidy analysis.
+    Enables clang-tidy analysis.
+
+    [cmake clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+
+[`MP_UNITS_DEV_TIME_TRACE`](#MP_UNITS_DEV_TIME_TRACE){ #MP_UNITS_DEV_TIME_TRACE }
+
+:   [:octicons-tag-24: 2.5.0][cmake time-trace support] · :octicons-milestone-24: `NONE`/`ALL`/`MODULES`/`HEADERS` (Default: `NONE`)
+
+    Enables compilation performance data collection with `-ftime-trace` for clang compilers.
 
- [cmake clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+    All our unit tests compile only for headers and never for modules. To allow fair
+    comparison, `MODULES` and `HEADERS` do not enable the data collection for unit tests.
+    This means that they affect only the core, systems, and examples.
+
+    Please use `ALL` to profile unit tests as well.
+
+    [cmake time-trace support]: https://github.com/mpusz/mp-units/releases/tag/v2.5.0
 
 
 ### Building the entire repository
@@ -105,7 +130,7 @@ To build all the **mp-units** source code (with unit tests and examples), you sh
 2. Run Conan with [`user.mp-units.build:all`](#user.mp-units.build-all) = `True`.
 
 ```shell
-git clone https://github.com/mpusz/mp-units.git && cd units
+git clone https://github.com/mpusz/mp-units.git && cd mp-units
 conan build . -pr <your_conan_profile> -s compiler.cppstd=23 -c user.mp-units.build:all=True -b missing
 ```
 
@@ -167,15 +192,15 @@ After that, you can either:
 
 - easily [start a live server to preview the documentation as you write](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write)
 
-```shell
-mkdocs serve
-```
+    ```shell
+    mkdocs serve
+    ```
 
 - [build the documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#building-your-site)
 
-```shell
-mkdocs build
-```
+    ```shell
+    mkdocs build
+    ```
 
 ### Generating API reference
 

example/CMakeLists.txt

@@ -42,11 +42,17 @@ function(add_example target)
         target_compile_features(${target} PRIVATE cxx_std_20)
         target_compile_definitions(${target} PRIVATE ${projectPrefix}MODULES)
         target_link_libraries(${target} PRIVATE mp-units::mp-units ${ARGN})
+        if(${projectPrefix}DEV_TIME_TRACE STREQUAL "MODULES")
+            target_compile_options(${target} PRIVATE "-ftime-trace")
+        endif()
     endif()
 
     add_executable(${target}-headers ${target}.cpp)
     list(TRANSFORM ARGN APPEND "-headers")
     target_link_libraries(${target}-headers PRIVATE mp-units::mp-units ${ARGN})
+    if(${projectPrefix}DEV_TIME_TRACE STREQUAL "HEADERS")
+        target_compile_options(${target}-headers PRIVATE "-ftime-trace")
+    endif()
 endfunction()
 
 add_example(avg_speed)

example/glide_computer_lib/CMakeLists.txt

@@ -24,11 +24,18 @@ add_library(glide_computer_lib-headers STATIC glide_computer_lib.cpp include/gli
 target_compile_features(glide_computer_lib-headers PUBLIC cxx_std_20)
 target_link_libraries(glide_computer_lib-headers PUBLIC mp-units::mp-units example_utils-headers)
 target_include_directories(glide_computer_lib-headers PUBLIC include)
+if(${projectPrefix}DEV_TIME_TRACE STREQUAL "HEADERS")
+    target_compile_options(glide_computer_lib-headers PRIVATE "-ftime-trace")
+endif()
 
 if(${projectPrefix}BUILD_CXX_MODULES)
     add_library(glide_computer_lib STATIC glide_computer_lib.cpp include/glide_computer_lib.h)
     target_compile_features(glide_computer_lib PUBLIC cxx_std_20)
     target_compile_definitions(glide_computer_lib PUBLIC ${projectPrefix}MODULES)
     target_link_libraries(glide_computer_lib PUBLIC mp-units::mp-units example_utils)
     target_include_directories(glide_computer_lib PUBLIC include)
+
+    if(${projectPrefix}DEV_TIME_TRACE STREQUAL "MODULES")
+        target_compile_options(glide_computer_lib PRIVATE "-ftime-trace")
+    endif()
 endif()

src/CMakeLists.txt

@@ -27,8 +27,9 @@ set(projectPrefix MP_UNITS_)
 
 list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
 
-include(CheckCXXFeatureSupported)
 include(AddMPUnitsModule)
+include(CheckCacheVarValues)
+include(CheckCXXFeatureSupported)
 include(GNUInstallDirs)
 
 # check if libc++ is being used
@@ -77,21 +78,12 @@ option(${projectPrefix}API_NO_CRTP "Enable class definitions without CRTP idiom"
 )
 option(${projectPrefix}API_FREESTANDING "Builds only freestanding part of the library" OFF)
 set(${projectPrefix}API_CONTRACTS GSL-LITE CACHE STRING "Enable contract checking")
+check_cache_var_values(API_CONTRACTS NONE GSL-LITE MS-GSL)
 
 message(STATUS "${projectPrefix}API_STD_FORMAT: ${${projectPrefix}API_STD_FORMAT}")
 message(STATUS "${projectPrefix}API_NO_CRTP: ${${projectPrefix}API_NO_CRTP}")
 message(STATUS "${projectPrefix}API_FREESTANDING: ${${projectPrefix}API_FREESTANDING}")
-
-function(cache_var_values name)
-    set_property(CACHE ${projectPrefix}${name} PROPERTY STRINGS ${ARGN})
-    if(NOT ${projectPrefix}${name} IN_LIST ARGN)
-        message(FATAL_ERROR
-                    "Invalid value '${${projectPrefix}${name}}' provided for a cache variable ${projectPrefix}${name} (${ARGN} allowed)"
-        )
-    endif()
-    message(STATUS "${projectPrefix}${name}: ${${projectPrefix}${name}}")
-endfunction()
-cache_var_values(API_CONTRACTS NONE GSL-LITE MS-GSL)
+message(STATUS "${projectPrefix}API_CONTRACTS: ${${projectPrefix}API_CONTRACTS}")
 
 # validate options
 if(${projectPrefix}API_FREESTANDING AND NOT ${projectPrefix}API_CONTRACTS STREQUAL "NONE")

src/cmake/CheckCacheVarValues.cmake

@@ -0,0 +1,32 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2018 Mateusz Pusz
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+cmake_minimum_required(VERSION 3.25)
+
+function(check_cache_var_values name)
+    set_property(CACHE ${projectPrefix}${name} PROPERTY STRINGS ${ARGN})
+    if(NOT ${projectPrefix}${name} IN_LIST ARGN)
+        message(FATAL_ERROR
+                    "Invalid value '${${projectPrefix}${name}}' provided for a cache variable ${projectPrefix}${name} (${ARGN} allowed)"
+        )
+    endif()
+endfunction()

src/core/CMakeLists.txt

@@ -151,3 +151,9 @@ target_compile_definitions(
     mp-units-core ${${projectPrefix}TARGET_SCOPE}
                   ${projectPrefix}HOSTED=$<NOT:$<BOOL:${${projectPrefix}API_FREESTANDING}>>
 )
+
+if(${projectPrefix}DEV_TIME_TRACE STREQUAL "ALL")
+    target_compile_options(mp-units-core ${${projectPrefix}TARGET_SCOPE} "-ftime-trace")
+elseif(${projectPrefix}DEV_TIME_TRACE STREQUAL "MODULES")
+    target_compile_options(mp-units-core PRIVATE "-ftime-trace")
+endif()

src/core/include/mp-units/framework/unit.h

@@ -120,25 +120,23 @@ struct get_canonical_unit_result {
   inline static constexpr auto value = get_canonical_unit_impl(U{}, U{});
 };
 
-template<Unit Lhs, Unit Rhs>
-struct unit_less : std::bool_constant<type_name<Lhs>() < type_name<Rhs>()> {};
+}  // namespace detail
 
-template<typename T1, typename T2>
-using type_list_of_unit_less = expr_less<T1, T2, unit_less>;
+// TODO this should really be in the `details` namespace but is used in `chrono.h` (a part of mp_units.systems)
+// Even though it is not exported, it is visible to the other module via ADL
+[[nodiscard]] consteval auto get_canonical_unit(Unit auto u)
+{
+  return detail::get_canonical_unit_result<decltype(u)>::value;
+}
+
+namespace detail {
 
 template<typename From, typename To>
 concept PotentiallyConvertibleTo = Unit<From> && Unit<To> &&
                                    ((AssociatedUnit<From> && AssociatedUnit<To> &&
                                      implicitly_convertible(get_quantity_spec(From{}), get_quantity_spec(To{}))) ||
                                     (!AssociatedUnit<From> && !AssociatedUnit<To>));
 
-}  // namespace detail
-
-// TODO this should really be in the `details` namespace but is used in `chrono.h` (a part of mp_units.systems)
-// Even though it is not exported, it is visible to the other module via ADL
-[[nodiscard]] consteval auto get_canonical_unit(Unit auto u)
-{
-  return detail::get_canonical_unit_result<decltype(u)>::value;
 }
 
 // convertible
@@ -159,6 +157,12 @@ struct derived_unit;
 
 namespace detail {
 
+template<Unit Lhs, Unit Rhs>
+struct unit_less : std::bool_constant<type_name<Lhs>() < type_name<Rhs>()> {};
+
+template<typename T1, typename T2>
+using type_list_of_unit_less = expr_less<T1, T2, unit_less>;
+
 struct unit_interface {
   /**
    * Multiplication by `1` returns the same unit, otherwise `scaled_unit` is being returned.

src/systems/CMakeLists.txt

@@ -71,3 +71,7 @@ if(NOT ${projectPrefix}API_FREESTANDING)
                include/mp-units/systems/si/chrono.h
     )
 endif()
+
+if(${projectPrefix}DEV_TIME_TRACE STREQUAL "MODULES")
+    target_compile_options(mp-units-systems PRIVATE "-ftime-trace")
+endif()