1.. _rfc-68:
2
3==============================
4RFC 68: C++11 Compilation Mode
5==============================
6
7======== ======================================
8Author:  Kurt Schwehr
9Contact: schwehr@google.com / schwehr@gmail.com
10Started: 2017-Apr-11
11Passed:  2017-Sep-11
12Status:  Adopted, implemented in GDAL 2.3
13======== ======================================
14
15This RFC is based on `GEOS RFC
165 <http://trac.osgeo.org/geos/wiki/RFC5>`__ by Mateusz Łoskot.
17
18Summary
19-------
20
21The document proposes to switch to
22`C++11 <http://en.wikipedia.org/wiki/C%2B%2B11>`__ compilation mode as
23default throughout the whole C++ source code of GDAL.
24
25The goal of the document is to request and achieve agreement on using
26C++11 as the minimum required version of the C++ programming language
27standard.
28
29Motivation
30----------
31
32C++11 is the first major update of the C++ standard since 1998.
33(`C++03 <https://en.wikipedia.org/wiki/C%2B%2B03>`__ was a bug fix
34release.)
35
36Having fewer versions of C++ to support will reduce the load on
37developers and testing systems.
38
39C++11 features aim to promote writing clean, compact, type-safe and fast
40code. It also delivers better feature-wise compatibility with the C
41language (C99).
42
43The Wikipedia article at
44`http://en.wikipedia.org/wiki/C++11 <http://en.wikipedia.org/wiki/C++11>`__
45does a great job describing all changes in C++11 extensively.
46
47The ``std::auto_ptr`` smart pointer, together with a bunch of other
48features, were deprecated and will be removed from C++17. Features like
49``std::unique_ptr`` provide much stronger replacements.
50
51Enabling C++11 compilation mode will improve the programming environment
52making it much friendlier than C++98.
53
54A social factor: since (many) C++ programmers no longer enjoy C++98,
55allowing C++11 mode may increase potential for new contributions.
56
57Compilers Landscape
58-------------------
59
60Summary of compilers supported by GDAL with their minimal versions
61required to compile source code based on
62
63`http://en.cppreference.com/w/cpp/compiler_support <http://en.cppreference.com/w/cpp/compiler_support>`__
64C++11 features.
65
66C++11
67~~~~~
68
69===== ============ ========================================================================= =================================================================================================
70GCC   4.8.1+       `C++11 status <https://gcc.gnu.org/projects/cxx-status.html#cxx11>`__     Debian 8 (stable), Ubuntu 15.04+, Ubuntu 14.04 ``ppa:ubuntu-toolchain-r/test``, Fedora 19+, RHEL7
71===== ============ ========================================================================= =================================================================================================
72Clang 3.3+         `C++11 status <https://clang.llvm.org/cxx_status.html#cxx11>`__           Debian 8 (stable), Ubuntu 14.04+, Fedora 19+, CentOS 6(?)
73MSVC  14.0+ (2015) `C++11 status <https://msdn.microsoft.com/en-us/library/hh567368.aspx>`__ n/a
74===== ============ ========================================================================= =================================================================================================
75
76C++14
77~~~~~
78
79The C++14 compilers are listed for comparison only:
80
81===== ============
82GCC   4.9+
83===== ============
84Clang 3.4+
85MSVC  14.0+ (2015)
86===== ============
87
88Plan
89----
90
91This proposal only requests agreement for the C++11 compilation mode
92switch in the current ``trunk`` branch only.
93
94This proposal does not suggest any detailed roadmap of large refactoring
95of the GDAL C++ codebase.
96
97The GDAL codebase is > 1.3M LOC and given the available man-power to
98LOCs ratio, such one-step refactoring would not be feasible.
99
100Instead, the task will be tackled with the baby step approach gradually
101transforming the codebase according to priorities set along the way. Any
102disruptive refactoring, changes in interfaces of C++ classes, breaking
103changes in C++ API must be announced and discussed on the mailing list
104or the bug tracker.
105
106*IMPORTANT*: C++11 refactoring must not change the C API or break C API
107compatibility, unless agreed upon based on prior RFC proposed.
108
109However, if the proposal is accepted, any new C++ code written for GDAL
110must be C++11-compliant.
111
112Prior acceptance of this proposal is necessary in order to start any
113source code refactoring using C++11 features.
114
115Once accepted, first step will be to update the build configurations to
116require C++11-compliant compiler.
117
118Issues
119------
120
121This section outlines issues potentially caused by upgrade to C++11
122language.
123
124-  C++11 destructors, by default, have now the new exception
125   specification of ``nothrow(true)``. Destructors of GDAL classes
126   should be reviewed and any that are allowed/expected to throw
127   exceptions must be marked with ``nothrow(false)``. Otherwise, any
128   user of the existing GDAL codebase would find the program terminating
129   whenever GDAL destructor throws an exception. Such review would be
130   beneficial anyway.
131
132Release
133-------
134
135First release of GDAL with C++11 compiler requirement could be 2.3.0.
136
137.. _c14-1:
138
139C++14
140~~~~~
141
142This section clarifies status of C++14 support in GDAL.
143
144-  Once C++11 is adopted as default compilation mode, GDAL developers
145   and maintainers must ensure it also successfully compiles in C++14
146   and C++17 modes.
147
148-  Are contributors allowed to add ``ifdef``'s for C++14 and C++17? No.
149   Not at this time.
150
151-  Is there a plan to upgrade to C++14 or C++17 to allow use of the C++
152   latest features? No, there is no plan. It is, however, recognized,
153   such motion may be put to the vote around 2020.
154
155References
156----------
157
158-  `http://en.cppreference.com/w/cpp/compiler_support <http://en.cppreference.com/w/cpp/compiler_support>`__
159   C++ compiler support
160
161Self-assigned development constraints
162-------------------------------------
163
164The changes should have moderate impact on the existing GDAL/OGR code
165base, and particularly on most of its code, that lies in drivers.
166Existing users of the GDAL/OGR API should also be moderately impacted by
167the changes, if they do not need to use the new offered capabilities.
168
169GDAL has been working well with C++11 builds for a number of years now,
170so there should be no externally visible changes for the initial removal
171of C++03 support.
172
173Core changes: summary
174---------------------
175
1761. Change configure.ac to remove ``with_cpp11`` flag, always use C++11,
177   and fail if ``AX_CXX_COMPILE_STDCXX_11`` does not find C++11
1782. Remove @CXX11_SUPPORT@ in GDALmake.opt.in and anywhere else it occurs
1793. Remove continuous build targets that do not support C++11 from
180   Travis-CI and AppVeyor
1814. Remove #if HAVE_CXX11 and leave only the C++11 code
182
183   -  ``find . -name \*.h -o -name \*.cpp | xargs egrep 'HAVE_CXX11'``
184
1855. CPL_STATIC_ASSERT -> ``static_assert``
1866. ``NULL`` -> ``nullptr`` (Only for C++ code)
1877. CPL_OVERRIDE -> override and remove redundant virtual
1888. -MAX or -max() -> ``std::numeric_limits<T>::lowest()``
189
190Changes in SWIG bindings
191------------------------
192
193The switch does not impact the ``C`` API used by the SWIG bindings.
194However, there may be some code that can be removed.
195
196Potential changes that are *NOT* included in this RFC
197-----------------------------------------------------
198
199There are many C++11 features not address in this RFC. See
200`https://en.wikipedia.org/wiki/C%2B%2B11 <https://en.wikipedia.org/wiki/C%2B%2B11>`__
201
202-  attributes
203-  ``auto``
204-  ``consexpr``
205-  ``cstdint``
206-  ``delete`` and ``default`` for member functions
207-  enum classes
208-  initializer lists and ``std::initializer_list``
209-  lambda
210-  range based for loops
211-  std::regex
212-  rvalue references
213-  smart pointers ``std::unique_ptr`` and ``std::shared_ptr``
214-  New string literals: u8"An UTF-8 string", u"An UTF-16 str", U"An
215   UTF-32 str", R"xml(raw content)xml"
216-  ``std::thread``, ``thread_local`` and related
217-  tuples
218-  And more...
219
220Backward compatibility
221----------------------
222
223Any code using the C++ API must use C++11 or newer.
224
225The C API should not be impacted.
226
227GDAL 2.2.x and older will continue to have C++03 support.
228
229Testing
230-------
231
232The existing autotest suite should continue to pass.
233
234Version numbering
235-----------------
236
237Although the above describes changes should have very few impact on
238existing applications of the C API, some behavior changes, C++ level
239changes and the conceptual changes are thought to deserve a 2.3 version
240number.
241
242Implementation
243--------------
244
245Implementation will be done by Kurt Schwehr. Others are welcome to pitch
246in.
247
248Related RFCs
249------------
250
251Related RFCs:
252
253-  `GEOS RFC 5: C++11 Compilation
254   Mode <http://trac.osgeo.org/geos/wiki/RFC5>`__: GEOS is switching to
255   requiring C++11 to build.
256-  `Move OTB to
257   C++14 <https://wiki.orfeo-toolbox.org/index.php/Request_for_Comments-36:_Move_OTB_to_C%2B%2B14>`__
258
259Voting history
260--------------
261
262`https://lists.osgeo.org/pipermail/gdal-dev/2017-September/047139.html <https://lists.osgeo.org/pipermail/gdal-dev/2017-September/047139.html>`__
263
264-  EvenR +1
265-  JukkaR +1
266-  DanielM +0
267-  HowardB +1
268-  KurtS +1
269