diff --git a/.vscode/settings.json b/.vscode/settings.json index 349e9b2e..09a85859 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -33,7 +33,9 @@ "/polyfill/i", "/autosar/i", "/__cplusplus/", - "//" + "//", + "/godbolt/i", + "/cppreference/" ], "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools", "cmake.configureOnOpen": false, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5126dc1..02c0a074 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,17 @@ +# Proposing a New Type + +If you want to add to CETL you should start on the [forum](https://forum.opencyphal.org/c/app/cetl/22). Once we have +tacit approval the type should be developed using a [standard Github workflow](https://docs.github.com/en/get-started/quickstart/contributing-to-projects). + +> Please don't write code on the forum. The forum post should be used to build consensus that a given type should be +developed and contributed to CETL before you go wasting your time writing the code. Once you have that level of support +it's time to move to Github. + +For some types, however, we may want to stage introduction but make the type available to maintainers and +early-adopters. To facilitate git submodule access to CETL and to avoid noise we use feature branches upstream to +incubate such types. As such, we may request that your PR to `main` be redirected to a feature branch we setup in the +form of `preview/{your incubating feature name}`. + # Running CETLVaSt ``` diff --git a/cetlvast/suites/compile/test_cetl_h_erase.cpp b/cetlvast/suites/compile/test_cetl_h_erase.cpp new file mode 100644 index 00000000..a157b931 --- /dev/null +++ b/cetlvast/suites/compile/test_cetl_h_erase.cpp @@ -0,0 +1,21 @@ +/// @file +/// Compile test that ensures CETL_H_ERASE works as intended. +/// +/// @copyright +/// Copyright (C) OpenCyphal Development Team +/// Copyright Amazon.com Inc. or its affiliates. +/// SPDX-License-Identifier: MIT +/// + + +#ifndef CETLVAST_COMPILETEST_PRECHECK +#define CETL_H_ERASE +#endif + +// this should have an error macro that prevents compilation. +#include "cetl/cetl.hpp" + +int main() +{ + return 0; +} diff --git a/include/cetl/cetl.hpp b/include/cetl/cetl.hpp index 5f9e66fe..f7cc40a3 100644 --- a/include/cetl/cetl.hpp +++ b/include/cetl/cetl.hpp @@ -1,20 +1,59 @@ /// @file /// CETL common header. /// +/// @copyright +/// Copyright (C) OpenCyphal Development Team +/// Copyright Amazon.com Inc. or its affiliates. +/// SPDX-License-Identifier: MIT +/// /// @note /// Keep this very spare. CETL's desire is to adapt to future C++ standards /// and too many CETL-specific definitions makes it difficult for users to switch off of CETL in the /// future. /// -/// @copyright -/// Copyright (C) OpenCyphal Development Team -/// Copyright Amazon.com Inc. or its affiliates. -/// SPDX-License-Identifier: MIT +/// If `CETL_H_ERASE` is defined then all CETL types will exclude the `cetl/cetl.hpp` header which +/// removes all common dependencies, other than C++ standard headers, from CETL. The types will not build due to +/// missing macros but the user can re-define these based on subsequent compiler errors. This allows elision of +/// cetl.hpp without modifying CETL source code. The CETL types are not guaranteed to work with cetl.hpp removed; you +/// have been warned. +/// +/// @warning +/// polyfill headers cannot be used if CETL_H_ERASE is defined. Presumably, if you really want to minimize your +/// dependencies, you would not be using the polyfill headers. /// #ifndef CETL_H_INCLUDED #define CETL_H_INCLUDED +#ifdef CETL_H_ERASE +# error "CETL_H_ERASE was defined. This header should never be included when the build is trying to erase it!" +#endif + +/// @defgroup CETL_VERSION The semantic version number of the CETL library. +/// These macros are an AUTOSAR-14 Rule A16-0-1 violation but we feel it necessary to provide them. +/// @{ + +/// @def CETL_VERSION_PATCH +/// CETL Patch version. +/// Patch versions shall always be backwards compatible with the same major +/// and minor version. A patch version number change will only occur if library source code is changed. +/// Documentation or test suite changes will not require a change to `cetl/cetl.hpp` and will not bump +/// the patch version. +#define CETL_VERSION_PATCH 0 + +/// @def CETL_VERSION_MINOR +/// CETL minor version. +/// Minor versions shall only add to CETL or modify it in a backwards compatible way. +#define CETL_VERSION_MINOR 0 + +/// @def CETL_VERSION_MAJOR +/// CETL Major version. +/// New major versions shall be rare. No overarching guarantees are made about compatibility +/// between major versions. +#define CETL_VERSION_MAJOR 0 + +/// @} + /// @def CETL_DEBUG_ASSERT /// When `CETL_ENABLE_DEBUG_ASSERT` is defined and not 0 then this is redirected to /// assert as included from ``. Because assert does not support a failure message @@ -36,13 +75,18 @@ # define CETL_DEBUG_ASSERT(c, m) ((void) m) #endif // CETL_ENABLE_DEBUG_ASSERT -// For example: https://godbolt.org/z/Thsn8qf1a -// We define these in a common header since we might encounter odd values on some compilers that we'll have to -// provide special cases for. - /// @defgroup CETL_CPP_STANDARD Guaranteed CETL c++ standard numbers /// These macros are an AUTOSAR-14 Rule A16-0-1 violation but can be used to conditionally include headers which -/// is compliant with A16-0-1. +/// is compliant with A16-0-1. The values were obtained by observation of compiler output using +/// [godbolt](https://godbolt.org/z/Thsn8qf1a) and as predicted by +/// [cppreference.com](https://en.cppreference.com/w/cpp/preprocessor/replace#Predefined_macros). +/// +/// @note +/// Some CETL types don't use these values directly to reduce the number of explicit dependencies on cetl.hpp but by +/// including `cetl/cetl.hpp` these types inherit the static assertions that the only valid values of `__cplusplus` +/// found are one of the the list found in this group or a value greater than the target support `CETL_CPP_STANDARD_20` +/// value. +/// /// @{ /// @def CETL_CPP_STANDARD_14 @@ -76,4 +120,14 @@ #define CETL_CPP_STANDARD_20 202002L /// @} + +// Ensure base support. +static_assert(__cplusplus >= CETL_CPP_STANDARD_14, + "Unsupported language: ISO C14, C++14, or a newer version of either is required to use this type."); + +// Detect weird versions +static_assert(__cplusplus == CETL_CPP_STANDARD_14 || __cplusplus == CETL_CPP_STANDARD_17 || + __cplusplus >= CETL_CPP_STANDARD_20, + "Unknown __cplusplus value found?"); + #endif // CETL_H_INCLUDED diff --git a/include/cetl/pf20/span.hpp b/include/cetl/pf20/span.hpp index 9af9bbbe..47142f78 100644 --- a/include/cetl/pf20/span.hpp +++ b/include/cetl/pf20/span.hpp @@ -16,7 +16,9 @@ #include #include -#include "cetl/cetl.hpp" +#ifndef CETL_H_ERASE +# include "cetl/cetl.hpp" +#endif namespace cetl { @@ -329,7 +331,7 @@ class span /// If the span has a zero size or not. /// @return true if the span size is 0 where "size" is the same as span::extent /// for this specialization. -#if (__cplusplus >= CETL_CPP_STANDARD_17) +#if (__cplusplus >= 201703L) [[nodiscard]] #endif constexpr bool @@ -687,7 +689,7 @@ class span /// /// Returns if the span has a zero size or not. /// @return true if the span size is 0. -#if (__cplusplus >= CETL_CPP_STANDARD_17) +#if (__cplusplus >= 201703L) [[nodiscard]] #endif constexpr bool