Difference between revisions of "cpp/freestanding"
m (→Notes: +fresh FTMs, some wording update.) |
|||
(18 intermediate revisions by 6 users not shown) | |||
Line 2: | Line 2: | ||
{{cpp/navbar}} | {{cpp/navbar}} | ||
− | There are two kinds of implementations defined by the C++ standard: '''''hosted''''' and '''''freestanding''''' implementations. For ''hosted'' implementations the set of standard library headers required by the C++ standard is much larger than for ''freestanding'' ones. In a ''freestanding'' implementation execution may happen without an operating system. | + | There are two kinds of implementations defined by the C++ standard: '''''hosted''''' and '''''freestanding''''' implementations. For ''hosted'' implementations, the set of standard library headers required by the C++ standard is much larger than for ''freestanding'' ones. In a ''freestanding'' implementation, execution may happen without an operating system. |
The kind of the implementation is implementation-defined. {{rev inl|since=c++11|The macro {{tt|__STDC_HOSTED__}} is predefined to {{tt|1}} for hosted implementations and {{tt|0}} for freestanding implementations.}} | The kind of the implementation is implementation-defined. {{rev inl|since=c++11|The macro {{tt|__STDC_HOSTED__}} is predefined to {{tt|1}} for hosted implementations and {{tt|0}} for freestanding implementations.}} | ||
Line 12: | Line 12: | ||
{{!}}- | {{!}}- | ||
{{!}} Under a ''freestanding'' implementation, it is implementation-defined whether a program can have more than one [[cpp/thread|thread of execution]]. | {{!}} Under a ''freestanding'' implementation, it is implementation-defined whether a program can have more than one [[cpp/thread|thread of execution]]. | ||
− | {{!}} Under a ''hosted'' implementation, a C++ program can have more than one | + | {{!}} Under a ''hosted'' implementation, a C++ program can have more than one {{lt|cpp/thread}} running concurrently. |
{{!)}} | {{!)}} | ||
}} | }} | ||
Line 22: | Line 22: | ||
! ''freestanding'' !! ''hosted'' | ! ''freestanding'' !! ''hosted'' | ||
|- | |- | ||
− | | In a ''freestanding'' implementation, it is implementation-defined whether a program is required to define a {{ltt|cpp/language/main function|main}} function. Start-up and termination is implementation-defined; start-up contains the execution of | + | | In a ''freestanding'' implementation, it is implementation-defined whether a program is required to define a {{ltt|cpp/language/main function|main}} function. Start-up and termination is implementation-defined; start-up contains the execution of {{lt|cpp/language/constructor}}s for objects of {{lsd|cpp/language/scope#Namespace scope}} with static storage duration; termination contains the execution of {{lt|cpp/language/destructor}}s for objects with static {{lt|cpp/language/storage duration}}. |
− | | In a ''hosted'' implementation, a program must contain a global function called {{ltt|cpp/language/main function|main}}. Executing a program starts a main [[cpp/thread|thread of execution]] in which the {{tt|main}} function is invoked, and in which variables of static | + | | In a ''hosted'' implementation, a program must contain a global function called {{ltt|cpp/language/main function|main}}. Executing a program starts a main [[cpp/thread|thread of execution]] in which the {{tt|main}} function is invoked, and in which variables of static {{lt|cpp/language/storage duration}} might be initialized and destroyed. |
|} | |} | ||
{{anchor|header requirements}} | {{anchor|header requirements}} | ||
+ | |||
===Requirements on [[cpp/header|standard library headers]]=== | ===Requirements on [[cpp/header|standard library headers]]=== | ||
+ | A ''freestanding'' implementation has an implementation-defined set of headers. This set includes at least the headers in the following table. | ||
− | + | For partially freestanding headers, freestanding implementations only needs to provide part of the entities in the corresponding synopsis: | |
+ | * If an entity is commented {{c/core|// freestanding}}, it is guaranteed to be provided. | ||
+ | {{rrev|since=c++26| | ||
+ | * If an entity (function or function template) is commented {{c/core|// freestanding-deleted}}, it is guaranteed to be either provided or deleted. | ||
+ | }} | ||
− | {| class="wikitable" | + | {|class="wikitable sortable" |
− | |+ style="padding:6px;"| Headers required for a | + | |+style="padding:6px;"|Headers required for a freestanding implementation |
|- | |- | ||
− | + | !Library | |
+ | !Component | ||
+ | !Headers | ||
+ | !{{nbsp}}Freestanding{{nbsp}} | ||
|- | |- | ||
− | | | + | |rowspan=13|{{ls|cpp/utility#Language support}} |
+ | |Common definitions | ||
+ | |{{header|cstddef}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |C standard library |
+ | |{{header|cstdlib}} | ||
+ | |{{maybe|Partial}} | ||
|- | |- | ||
− | | | + | |Implementation properties |
+ | |{{header|cfloat}}<br>{{header|climits}} {{mark since c++11}}<br>{{header|limits}}<br>{{header|version}} {{mark since c++20}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Integer types |
+ | |{{header|cstdint}} {{mark since c++11}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Dynamic memory management |
+ | |{{header|new}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Type identification |
+ | |{{header|typeinfo}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Source location |
+ | |{{header|source_location}} {{mark since c++20}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Exception handling |
+ | |{{header|exception}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Initializer lists |
+ | |{{header|initializer_list}} {{mark since c++11}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Comparisons |
+ | |{{header|compare}} {{mark since c++20}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Coroutines support |
+ | |{{header|coroutine}} {{mark since c++20}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Other runtime support |
+ | |{{header|cstdarg}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Debugging support |
+ | |{{header|debugging}} {{mark since c++26}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |colspan=2|[[cpp/concepts|Concepts]] |
+ | |{{header|concepts}} {{mark since c++20}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |rowspan=2|[[cpp/error|Diagnostics]] |
+ | |Error numbers | ||
+ | |{{header|cerrno}} {{mark since c++26}} | ||
+ | |{{maybe|Partial}} | ||
|- | |- | ||
− | | | + | |System error support |
+ | |{{header|system_error}} {{mark since c++26}} | ||
+ | |{{maybe|Partial}} | ||
|- | |- | ||
− | | | + | |[[cpp/memory|Memory management]]{{nbsp}} |
+ | |Memory | ||
+ | |{{header|memory}} {{mark since c++23}} | ||
+ | |{{maybe|Partial}} | ||
|- | |- | ||
− | | | + | |rowspan=2|[[cpp/meta|Metaprogramming]] |
+ | |Type traits | ||
+ | |{{header|type_traits}} {{mark since c++11}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Compile-time rational arithmetic{{nbsp}} |
+ | |{{header|ratio}} {{mark since c++23}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |rowspan=5|[[cpp/utility#General-purpose utilities|General utilities]] |
+ | |Utility components | ||
+ | |{{header|utility}} {{mark since c++23}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Tuples |
+ | |{{header|tuple}} {{mark since c++23}} | ||
+ | |{{yes|All}} | ||
|- | |- | ||
− | | | + | |Function objects |
+ | |{{header|functional}} {{mark since c++20}} | ||
+ | |{{maybe|Partial}} | ||
|- | |- | ||
− | | Deprecated headers | + | |Primitive numeric conversions |
+ | |{{header|charconv}} {{mark since c++26}} | ||
+ | |{{maybe|Partial}} | ||
+ | |- | ||
+ | |Bit manipulation | ||
+ | |{{header|bit}} {{mark since c++20}} | ||
+ | |{{yes|All}} | ||
+ | |- | ||
+ | |rowspan=2|[[cpp/string|Strings]] | ||
+ | |String classes | ||
+ | |{{header|string}} {{mark since c++26}} | ||
+ | |{{maybe|Partial}} | ||
+ | |- | ||
+ | |Null-terminated<br>sequence utilities | ||
+ | |{{header|cstring}} {{mark since c++26}}<br>{{header|cwchar}} {{mark since c++26}} | ||
+ | |{{maybe|Partial}} | ||
+ | |- | ||
+ | |colspan=2|[[cpp/iterator|Iterators]] | ||
+ | |{{header|iterator}} {{mark since c++23}} | ||
+ | |{{maybe|Partial}} | ||
+ | |- | ||
+ | |colspan=2|[[cpp/ranges|Ranges]] | ||
+ | |{{header|ranges}} {{mark since c++23}} | ||
+ | |{{maybe|Partial}} | ||
+ | |- | ||
+ | |[[cpp/numeric|Numerics]] | ||
+ | |Mathematical functions<br>for floating-point types | ||
+ | |{{header|cmath}} {{mark since c++26}} | ||
+ | |{{maybe|Partial}} | ||
+ | |- | ||
+ | |[[cpp/thread|Concurrency support]] | ||
+ | |Atomics | ||
+ | |{{header|atomic}} {{mark since c++11}} | ||
+ | |{{yes|{{nbsp|4}}All<ref>{{rev inl|since=c++20|Support for always lock-free integral atomic types and presence of type aliases {{lc|std::atomic_signed_lock_free}} and {{lc|std::atomic_unsigned_lock_free}} are implementation-defined in a freestanding implementation.}}</ref>}} | ||
+ | |- | ||
+ | |colspan=2|'''Deprecated''' headers | ||
+ | |{{header|ciso646}} {{mark until c++20}}<br>{{header|cstdalign}} {{mark life|since=c++11|until=c++20}}{{nbsp}}<br>{{header|cstdbool}} {{mark life|since=c++11|until=c++20}} | ||
+ | |{{yes|All}} | ||
|} | |} | ||
<references/> | <references/> | ||
===Notes=== | ===Notes=== | ||
+ | Some compiler vendors may not fully support freestanding implementation. For example, GCC libstdc++ has had implementation and build issues before version 13, while LLVM libcxx and MSVC STL do not support freestanding. | ||
+ | |||
+ | In C++23, many features are made freestanding with partial headers. However, it is still up for discussion in WG21 whether some headers will be made freestanding in the future standards. Regardless, containers like {{lc|std::vector|vector}}, {{lc|std::list|list}}, {{lc|std::deque|deque}}, and {{lc|std::map|map}} will never be freestanding due to their dependencies on exceptions and heap. | ||
− | + | GCC 13 provides more headers, such as {{header|optional}}, {{header|span}}, {{header|array}}, and {{header|bitset}}, for freestanding, although these headers may not be portable or provide the same capabilities as a hosted implementation. It is better to avoid using them in a freestanding environment, even if the toolchain provides them. | |
− | + | {{ftm begin|sort=yes}} | |
+ | {{ftm|__cpp_lib_freestanding_feature_test_macros|value=202306L|std=C++26|freestanding feature test macros}} | ||
+ | {{ftm|__cpp_lib_freestanding_algorithm|value=202311L|std=C++26|freestanding {{header|algorithm}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_array|value=202311L|std=C++26|freestanding {{header|array}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_char_traits|value=202306L|std=C++26|freestanding {{lc|std::char_traits}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_charconv|value=202306L|std=C++26|freestanding {{header|charconv}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_cstdlib|value=202306L|std=C++26|freestanding {{header|cstdlib}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_cstring|value=202311L|std=C++26|freestanding {{header|cstring}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_cwchar|value=202306L|std=C++26|freestanding {{header|cwchar}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_errc|value=202306L|std=C++26|freestanding {{lc|std::errc}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_expected|value=202311L|std=C++26|freestanding {{header|expected}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_functional|value=202306L|std=C++26|freestanding {{header|functional}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_iterator|value=202306L|std=C++26|freestanding {{header|iterator}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_mdspan|value=202311L|std=C++26|freestanding {{header|mdspan}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_memory|value=202306L|std=C++26|freestanding {{header|memory}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_numeric|value=202311L|std=C++26|freestanding {{header|numeric}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_optional|value=202311L|std=C++26|freestanding {{header|optional}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_ranges|value=202306L|std=C++26|freestanding {{header|ranges}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_ratio|value=202306L|std=C++26|freestanding {{header|ratio}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_string_view|value=202311L|std=C++26|freestanding {{header|string_view}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_tuple|value=202306L|std=C++26|freestanding {{header|tuple}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_utility|value=202306L|std=C++26|freestanding {{header|utility}}}} | ||
+ | {{ftm|__cpp_lib_freestanding_variant|value=202311L|std=C++26|freestanding {{header|variant}}}} | ||
+ | {{ftm end}} | ||
===References=== | ===References=== | ||
Line 130: | Line 251: | ||
{{dr list begin}} | {{dr list begin}} | ||
{{dr list item|wg=cwg|dr=1938|std=C++98|before=an implementation did not need<br>to document whether it is hosted|after=made the implementation kind implementation-<br>defined (thus requires a documentation)}} | {{dr list item|wg=cwg|dr=1938|std=C++98|before=an implementation did not need<br>to document whether it is hosted|after=made the implementation kind implementation-<br>defined (thus requires a documentation)}} | ||
− | {{dr list item|wg=lwg|dr=3653|std=C++20|before= | + | {{dr list item|wg=lwg|dr=3653|paper=P1642R11|std=C++20|before={{header|coroutine}} is freestanding, but<br>uses {{lc|std::hash}} which was not|after=made {{header|functional}} being<br> partially freestanding}} |
{{dr list end}} | {{dr list end}} | ||
Latest revision as of 23:40, 29 December 2023
There are two kinds of implementations defined by the C++ standard: hosted and freestanding implementations. For hosted implementations, the set of standard library headers required by the C++ standard is much larger than for freestanding ones. In a freestanding implementation, execution may happen without an operating system.
The kind of the implementation is implementation-defined. The macro __STDC_HOSTED__
is predefined to 1
for hosted implementations and 0
for freestanding implementations.(since C++11)
Requirements on multi-threaded executions and data races
|
(since C++11) |
[edit] Requirements on the main function
freestanding | hosted |
---|---|
In a freestanding implementation, it is implementation-defined whether a program is required to define a main function. Start-up and termination is implementation-defined; start-up contains the execution of constructors for objects of namespace scope with static storage duration; termination contains the execution of destructors for objects with static storage duration. | In a hosted implementation, a program must contain a global function called main. Executing a program starts a main thread of execution in which the main function is invoked, and in which variables of static storage duration might be initialized and destroyed.
|
[edit] Requirements on standard library headers
A freestanding implementation has an implementation-defined set of headers. This set includes at least the headers in the following table.
For partially freestanding headers, freestanding implementations only needs to provide part of the entities in the corresponding synopsis:
- If an entity is commented // freestanding, it is guaranteed to be provided.
|
(since C++26) |
Library | Component | Headers | Freestanding |
---|---|---|---|
Language support | Common definitions | <cstddef> | All |
C standard library | <cstdlib> | Partial | |
Implementation properties | <cfloat> <climits> (since C++11) <limits> <version> (since C++20) |
All | |
Integer types | <cstdint> (since C++11) | All | |
Dynamic memory management | <new> | All | |
Type identification | <typeinfo> | All | |
Source location | <source_location> (since C++20) | All | |
Exception handling | <exception> | All | |
Initializer lists | <initializer_list> (since C++11) | All | |
Comparisons | <compare> (since C++20) | All | |
Coroutines support | <coroutine> (since C++20) | All | |
Other runtime support | <cstdarg> | All | |
Debugging support | <debugging> (since C++26) | All | |
Concepts | <concepts> (since C++20) | All | |
Diagnostics | Error numbers | <cerrno> (since C++26) | Partial |
System error support | <system_error> (since C++26) | Partial | |
Memory management | Memory | <memory> (since C++23) | Partial |
Metaprogramming | Type traits | <type_traits> (since C++11) | All |
Compile-time rational arithmetic | <ratio> (since C++23) | All | |
General utilities | Utility components | <utility> (since C++23) | All |
Tuples | <tuple> (since C++23) | All | |
Function objects | <functional> (since C++20) | Partial | |
Primitive numeric conversions | <charconv> (since C++26) | Partial | |
Bit manipulation | <bit> (since C++20) | All | |
Strings | String classes | <string> (since C++26) | Partial |
Null-terminated sequence utilities |
<cstring> (since C++26) <cwchar> (since C++26) |
Partial | |
Iterators | <iterator> (since C++23) | Partial | |
Ranges | <ranges> (since C++23) | Partial | |
Numerics | Mathematical functions for floating-point types |
<cmath> (since C++26) | Partial |
Concurrency support | Atomics | <atomic> (since C++11) | All[1] |
Deprecated headers | <ciso646> (until C++20) <cstdalign> (since C++11)(until C++20) <cstdbool> (since C++11)(until C++20) |
All |
- ↑ Support for always lock-free integral atomic types and presence of type aliases std::atomic_signed_lock_free and std::atomic_unsigned_lock_free are implementation-defined in a freestanding implementation.(since C++20)
[edit] Notes
Some compiler vendors may not fully support freestanding implementation. For example, GCC libstdc++ has had implementation and build issues before version 13, while LLVM libcxx and MSVC STL do not support freestanding.
In C++23, many features are made freestanding with partial headers. However, it is still up for discussion in WG21 whether some headers will be made freestanding in the future standards. Regardless, containers like vector, list, deque, and map will never be freestanding due to their dependencies on exceptions and heap.
GCC 13 provides more headers, such as <optional>, <span>, <array>, and <bitset>, for freestanding, although these headers may not be portable or provide the same capabilities as a hosted implementation. It is better to avoid using them in a freestanding environment, even if the toolchain provides them.
[edit] References
- C++23 standard (ISO/IEC 14882:2024):
- 4.1 Implementation compliance [intro.compliance] (p: 10)
- 6.9.2 Multi-threaded executions and data races [intro.multithread] (p: 84)
- 6.9.3.1 main function [basic.start.main] (p: 89)
- 16.4.2.5 Freestanding implementations [compliance] (p: 483)
- C++20 standard (ISO/IEC 14882:2020):
- 4.1 Implementation compliance [intro.compliance] (p: 7)
- 6.9.2 Multi-threaded executions and data races [intro.multithread] (p: 77)
- 6.9.3.1 main function [basic.start.main] (p: 82)
- 16.5.1.3 Freestanding implementations [compliance] (p: 470)
- C++17 standard (ISO/IEC 14882:2017):
- 4.1 Implementation compliance [intro.compliance] (p: 5)
- 4.7 Multi-threaded executions and data races [intro.multithread] (p: 15)
- 6.6.1 main function [basic.start.main] (p: 66)
- 20.5.1.3 Freestanding implementations [compliance] (p: 458)
- C++14 standard (ISO/IEC 14882:2014):
- 1.4 Implementation compliance [intro.compliance] (p: 5)
- 1.10 Multi-threaded executions and data races [intro.multithread] (p: 11)
- 3.6.1 Main function [basic.start.main] (p: 62)
- 17.6.1.3 Freestanding implementations [compliance] (p: 441)
- C++11 standard (ISO/IEC 14882:2011):
- 1.4 Implementation compliance [intro.compliance] (p: 5)
- 1.10 Multi-threaded executions and data races [intro.multithread] (p: 11)
- 3.6.1 Main function [basic.start.main] (p: 58)
- 17.6.1.3 Freestanding implementations [compliance] (p: 408)
- C++03 standard (ISO/IEC 14882:2003):
- 1.4 Implementation compliance [intro.compliance] (p: 3)
- 3.6.1 Main function [basic.start.main] (p: 43)
- 17.4.1.3 Freestanding implementations [lib.compliance] (p: 326)
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
CWG 1938 | C++98 | an implementation did not need to document whether it is hosted |
made the implementation kind implementation- defined (thus requires a documentation) |
LWG 3653 (P1642R11) |
C++20 | <coroutine> is freestanding, but uses std::hash which was not |
made <functional> being partially freestanding |
[edit] See also
C documentation for Conformance
|