From da9340005f77a8e0aa7712548f59443459d7b699 Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Wed, 17 Apr 2024 12:16:40 +0100 Subject: [PATCH] docs: 2.2 release announcement updated --- docs/blog/posts/2.2.0-released.md | 49 ++++++++++++++++++++++++++----- 1 file changed, 42 insertions(+), 7 deletions(-) diff --git a/docs/blog/posts/2.2.0-released.md b/docs/blog/posts/2.2.0-released.md index 95699623..02e23690 100644 --- a/docs/blog/posts/2.2.0-released.md +++ b/docs/blog/posts/2.2.0-released.md @@ -1,6 +1,6 @@ --- draft: true -date: 2024-01-09 +date: 2024-04-17 authors: - mpusz categories: @@ -35,7 +35,7 @@ the C++ modules' support is still really limited. - Ninja 1.11 - clang-17 -In the upcoming months, hopefully the situation will improve with the gcc-14 release and +In the upcoming months, hopefully, the situation will improve with the gcc-14 release and bug fixes in MSVC. !!! note @@ -68,7 +68,7 @@ In this release, we also highly limited the number of CMake targets (**breaking correspond exactly to the C++ modules they provide. This means that many smaller partial targets were removed. We also merged text output targets with the core library's definition. -The table below specifies where we can find now the contents of previously available CMake targets: +The table below specifies where we can now find the contents of previously available CMake targets: | Before | Now | |---------------------------|---------------------| @@ -95,6 +95,41 @@ _mp-units/compat_macros.h_. This header file should be explicitly included befor modules if we want to benefit from the [Wide Compatibility tools](../../users_guide/use_cases/wide_compatibility.md). +## Better control over the library's API + +With this release, nearly all of the Conan and CMake build options were refactored with the intent +of providing better control over the library's API. + +Previously, the library used the latest available feature set supported by a specific +compiler. For example, +[`quantity_spec` definitions would use CRTP](../../users_guide/framework_basics/systems_of_quantities.md#defining-quantities) +on an older compiler or provide a simpler API on a newer one thanks to the C++23 `this` deduction +feature. This could lead to surprising results where the same code written by the user would +compile fine on one compiler but not the other. + +From this release, all API extensions have their corresponding configuration options in Conan and +CMake. With this, a user has full control over the API exposed by the library. Those options expose +three values: + +- `True` - The feature is always enabled (the configuration error will happen if the compiler does + not support this feature) +- `False` - The feature is disabled, and an older alternative is always used. +- `Auto` - The feature is automatically enabled if the compiler supports it (old behavior). + +Additionally, some CMake options were renamed to better express the impact on our users +(**breaking change**). For example, now CMake options include: + +- `MP_UNITS_API_*` - options affecting the library's API, +- `MP_UNITS_BUILD_*` - options affecting the build process, +- `MP_UNITS_DEV_*` - options primarily useful for the project developers or people who want to + compile our unit tests and examples. + +!!! info + + To learn more, please refer to the [Build options](../../getting_started/installation_and_usage.md#build-options) + chapter. + + ## Simplified quantity point support This release significantly simplifies the usage of quantity points and affine space abstractions @@ -124,7 +159,7 @@ As we can see above, the new design allows of the implicit point origin. Otherwise, an explicit origin still always has to be provided during initialization. -Also, we introduced a possibility to specify a default point origin in the units definition. +Also, we introduced the possibility of specifying a default point origin in the unit definition. With that, we could provide proper temperature scales without forcing the user to always use the origins explicitly. Also, a new member function, `.quantity_from_zero(),` was introduced that always returns the quantity from the unit's specific point origin or from the absolute @@ -188,14 +223,14 @@ requires the Unicode symbol to be provided as a UTF-8 literal: ## Improved text output -With this release we can print not only whole quantities but also just their units or dimensions. +With this release, we can print not only whole quantities but also just their units or dimensions. Also, we fixed the `std::format` support so users can now enjoy full C++20 compatibility and don't have to use [fmtlib](https://github.com/fmtlib/fmt) anymore. We have also changed the grammar for quantities formatting (**breaking change**). It introduces the composition of underlying formatters that finally allows us to properly format user-defined representation types (assuming they have `std::format` support). Additionally, thanks to a -new `%?` token we can provide a custom format string that will properly print quantity of any unit. +new `%?` token, we can provide a custom format string that will properly print quantity of any unit. Here is a small preview of what is now available: @@ -237,7 +272,7 @@ quantity points. ## Even better error messages -This release made a few small refactorings that without changing the user-facing API allowed us +This release made a few small refactorings that, without changing the user-facing API, allowed us to improve the readability of the generated types that can be observed in the compilation errors. Example 1 (clang):