<h1>Per-Compiler Notes</h1>

Notes about setting up cxxomfort, and the support available, on different compilers and setups.

The notes take into consideration following the setup available in [Installation] for the testbed compilers.

<div style="width:100%; margin: 2em auto;"><span style="font-style: sans-serif;">
[#notes-gcc|GNU GCC] -- [#notes-msvc|MSVC] -- [#notes-clang|CLang] -- [#notes-dmc|Digital Mars] -- [#notes-ow|Open Watcom] -- <b>[#general|general notes]</b>


<hr/>

<a id="notes-gcc"></a>
<h2>GNU GCC</h2>

Supported versions:

  *  <tt>-std=c++03</tt>: 4.4-5.5
  *  <tt>-std=c++0x</tt>: 4.6-5.0
  *  <tt>-std=c++11</tt>: 4.8-5.5
  *  <tt>-std=c++14</tt>: ?


<h3>201x versions and TR1 Implementation</h3>

<b>For users of versions <tt>201x</tt> only:</b>

For C++<11, GCC sets up <b>TR1</b> components as files in the include path and the features under the <tt>std::tr1</tt> namespace. Cxxomfort sets up the macro <tt>CXXO_namespace_tr1</tt> to the later value.

Unfortunately the TR1 headers are coded in such a way that it is not possible to add them to the <tt>#include</tt> search path. See for the local  report, bugzilla] for an example bug reported at bugzilla and about stl_list.h] for more general information. The tl;dr of the problem is that adding TR1 to the <code>#include</code> path causes ambiguity errors in declarations that can not be solved without patching the <i>non</i>-TR1 headers themselves, such as <code>stl_list.h</code>.

Since GCC considers Tr1 "not worth fixing", which given its age makes sense, it is instead recommended to use a <b>TR1 forwarder</b> such as  which is the supported and tested-for configuration in GCC C++03 mode; or any other TR1 forwarder set up by the user.

Versions of cxxomfort post <tt>2020-01-01</tt> are not affected by this requirement and users should <b>not</b> set up a TR1 forwarder.

<b>Associated tickets:</b>

  *  [/ticket?s=TR1]
  *  [5a9e81910ede7e3e1f77].


<h3>Short <tt>enum</tt> Types</h3>

GCC supports the <tt>-fshort-enums</tt> flag which allows enumeration types to use as a base types shorter than <tt>signed/unsigned int</tt>. Note that when this flag is enabled, the default implementation of typesafe enumeration types using <tt>library::typesafe_enum</tt> might change.

As a result, some specific types exposed to the public interface <em>may or may not</em> change:

  *  <tt>std::errc</tt>
  *  <tt>std::endian</tt>


<div style="display:none;">User code can check the result of <tt>sizeof(cxxomfort::fix::short_enum)</tt> to determine if short enums are enabled or not.</div>

<h3>GCC >= 7.x</h3>

Cxxomfort is, as of late 2018, not tested with and not intended to be used with more modern versions of GCC, the latest version tested being 5.0. Ideally, at least for C++03 and C++11 mode Cxxomfort should be expected to work in <em>all</em> GCC versions past 5.0.

The ticket [457376c379] will follow efforts to test GCC >= 7.x compatibility.

<hr/>
<a id="notes-msvc"></a>
<h2>Microsoft Visual C++ Compiler</h2>

Supported versions:

  *  C++03 : 2008 SP1, 2010, 2012 (partial)
  *  C++11: none? (as of 2020-01-01)


<h3>TR1 Implementation</h3>

MSVC < 2008 SP1 ships without a TR1, and thus is unsupported.

MSVC 2008 <b>SP1</b> ships with a TR1 implementation that is functional for Cxxomfort's requirements. The implementation uses the same header files as the normal C++ headers, as such MSVC does not require a TR1 forwarder or any other special treatment; also the features live in the <tt>std::tr1</tt> namespace. Cxxofort defines the macro <tt>CXXO_namespace_tr1</tt> to this later value so that features such as <tt>hash</tt> can be pointed to.

MSVC 2012 and later do not have a <tt>std::tr1</tt> namespace.

<h3>MSVC 2010 <tt>std::common_type</tt> </h3>

MSVC 2010 and 2010 SP1 ship with a broken implementation of <tt>std::common_type</tt> that is not variadic, and can only take two types. Because this means that the name <tt>common_type</tt> is used, Cxxomfort can not extend this feature to more template arguments.

Code wanting to transparently use <tt>common_type</tt> can instead use which will forward to the correct implementation (std or cxxomfort) depending on compiler version.

<h3>MSVC >= 2013</h3>

Cxxomfort is largely untested with compiler versions 1800 and above (MSVC 2013). These versions also include a number of variants such as the "November Update".

The ticket [70b70d8017] will track compatibility tests with MSVC 2012 and 2013.

As of early 2020, there is no intention to support MSVC 2015 and beyond.

<h3>No typeof</h3>

MSVC < 2010 lacks any semblance to a <tt>__typeof__</tt> mechanism. As such, code using <tt>CXXO_TYPEOF</tt> or <tt>CXXO_DECLTYPE</tt> will fail to compile. See the general note on <tt>__typeof__</tt>.


<hr/>
<a id="notes-clang"></a>
<h2>Clang</h2>

Supported versions:

  *  default / <tt>-std=c++03</tt>: 2.8; 3.0-3.4
  *  <tt>-std=c++0x</tt>: 3.0-3.2
  *  <tt>-std=c++11</tt>: 3.2
  *  <tt>-std=c++14</tt>: ?


Most of the notes valid for GCC are also valid here.

<h3>clang-libc++</h3>

Cxxomfort has <b>not</b> been tested with Clang using libc++, and has no support for it as of the latest 2019 releases.

<h3>Rvalue-References</h3>

Clang supports C++11 rvalue-references as an extension in C++03. Cxxomfort may or may not pick rvalue-reference constructors in C++03 when using Clang, but no guarantees are provided.


<hr/>
<a id="notes-dmc"></a>
<h2>Digital Mars</h2>

<h3>Lacking C++ Support</h3>

The compiler supports a limited subset of C++, lacking features such as inline struct initialization, template constructors and template conversion operators (see "Template Support" below). Because of this, as of latest 2019 releases of Cxxomfort <b>the library is not guaranteed to compile</b> beyond the Base featureset.


Digital Mars provides minimal support for the <tt>decltype</tt> feature, although it lacks some of the corrections from later revisions such as decltype 1.1. Cxxomfort defines the macros <tt>CXXO_TYPEOF</tt> and <tt>CXXO_DECLTYPE</tt> to use this feature.

<hr/>
<a id="notes-ow"></a>
<h2>Watcom 1.9 / OpenWatcom (beta)</h2>

<h3>Lacking C++ Support</h3>

The compiler supports a limited subset of C++, lacking features such as inline struct initialization, template constructors, lazy initialization and template template parameters. See [#general] below and also at the OpenWatcom wiki for more details. This also means classes such as <tt>istream</tt> and <tt>ostream</tt> families are implemented in a manner different than the Standard and there are entire base class families missing. Because of this, as of latest 2018 releases of Cxxomfort <b>the library is not guaranteed to compile</b> beyond the Base featureset.

As of Oct 2019, an effort is going to be made to provide at least a subset of features of Cxxomfort and other backports for Watcom 1.9 and OpenWatcom 2.0, with [b8ea55b791] being used as the tracking ticket. Features that are intended to land in are ATM limited to:

  *  <tt>std::valarray</tt> in a limited form.
  *  <tt>std::array</tt>
  *  <tt>std::forward_list</tt> in a limited form.
  *  Output operators for <tt>std::string</tt>.
  *  <tt>std::unique_ptr</tt> emulation.
  *  Different-range signatures for equal and mismatch.
  *  <tt>std::byte</tt>
  *  <tt>string_view</tt> in a limited form.

<h3>basic_istream, basic_ostream</h3>

Watcom 1.9 only supports the <tt>istream</tt> and <tt>ostream</tt> classes as sole classes, not templated on char type, and they inherit from <tt>ios</tt> rather than <tt>basic_ios</tt>; hence code that depends on prototypes for <tt>basic_istream</tt> or <tt>basic_ostream</tt> will fail to compile.

As of latest 2018 release Cxxomfort does not make any attempt to provide a

<h3>No TR1 Support</h3>

Watcom 1.9 / 2.0 beta has almost no support for C++ TR1 or its headers. As such <tt><array>, <cstdint>, <tuple></tt> all required by Cxxomfort are missing.


Watcom defines <tt>NULL</tt> as integral zero, and also lacks template conversion operators; as such, <tt>nullptr</tt> can not be implemented as per C++11 official backport. For this compiler, Cxxomfort defines <tt>nullptr</tt> to be integral zero, and <tt>std::nullptr_t</tt> as an empty type with an implicit conversion to null void pointer.

<h3>Template Support</h3>

See [#general] below.


<hr/>

<a id="general"></a>
<h2>General Notes</h2>

<h3>Compiler Lacks Basic C++ Support</h3>

Some old compilers might lack enough support for C++ features, in particular <tt>inline</tt> and <b>templates</b> that implementing a number of Cxxomfort features might be unfeasible. Cxxomfort requires, in order to provide proper support for the <b>base</b> features, compliance with template member operators (used by <tt>nullptr</tt>), zero-argument macros (needed for code generation tools), explicit template argument call (needed to implement <tt>explicit_cast</tt>), two-phase lookup and typenames (all required to implement eg.: iterator accessors, or <tt>move</tt> emulation).

Support for the various C++ backports requires even more extensive use of templates, in particular when it comes to stuff in <tt><functional></tt> or <tt><tuple></tt>.

In theory a compiler that lacks this level of support should declare <tt>__cplusplus</tt> to be a value below <tt>199712UL</tt> and thus lack of features can be caught early in order to either provide a few minimal implementations or terminate early with <tt>#error</tt>; as of latest 2018 release, Cxxomfort takes neither approach.


<h3>Compiler Intrinsics</h3>

In order to work correctly, <b>cxxomfort</b> expects to find, for pre-C++11 compilers, support for a number of compiler intrinsics related to type and memory information. If those intrinsics are not found, the library is not guaranteed to work and might induce hard compilation fails.

  *  <tt>__alignof(T)</tt> is <b>needed</b> by cxxomfort's base feature set.
  *  The type category intrinsics <tt>__is_enum</tt>, <tt>__is_union</tt> and <tt>__is_class</tt> are expected and <b>needed</b> to be found when using per-compiler TR1 support.
  *  The type/memory information intrinsics <tt>__is_pod</tt> and <tt>__is_abstract</tt> are expected when using per-compiler TR1 support.
  *  <tt>__typeof(expr)</tt> is expected by cxxomfort's base feature set in order to set up <tt>CXXO_TYPEOF</tt> in compilers that have it.


When using the macro <tt>CXXOMFORT_NOTICES</tt> to enable compilation logs, Cxxomfort makes use of <tt>#pragma</tt>s in order to emit the messages. It is implementation-defined by each compiler whether those notices are interpreted to be compilation messages or compilation warnings (which show in the build logs). As such, when setting <tt>CXXOMFORT_NOTICES</tt> on a project that uses such options as "treat warnings as errors", <b>compilation should be expected to fail</b>.

<h3>__typeof__</h3>

Compilers such as GCC >= 4.0 and CLang >= 3.1 implement the <tt>__typeof__</tt> extension in all Standard modes, which returns the type corresponding to an expression: it is basically an earlier alternative to <tt>decltype</tt>.

Cxxomfort declares the <tt>CXXO_TYPEOF(expression)</tt> macro to return <tt>__typeof__</tt> of the expression in C++03 mode, or <tt>decltype</tt> of the expression in later Standards.

Compilers without typeof will evaluate <tt>CXXO_TYPEOF</tt> to a non-resolvable type or expression and thus compilation will fail. User code wanting to check before use should check the value of <tt>CXXO_COMPILER_SUPPORT_typeof</tt>.

<h3>type_name</h3>

Using the <tt>library::type_name</tt> and <tt>typeid_demangle</tt> features require support] and thus RTTI to be enabled, and the <tt><typeinfo></tt> header to be included <b>explicitly</b>  (Though an assist using type index] is under study).

<hr/>

→ <b>Proceed with the [Configuration]</b>