Skip to content

Commit 144651e

Browse files
rouaultrouault
committed
Add RFC 109 text: Split of gdal_priv.h and addition of gdal_cpp.h header
1 parent 51c49a2 commit 144651e

File tree

2 files changed

+154
-0
lines changed

2 files changed

+154
-0
lines changed

‎doc/source/development/rfc/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,3 +115,4 @@ RFC list
115115
rfc106_update_metadata
116116
rfc107_igetextent_isetspatialfilter
117117
rfc108_driver_removal_3_11
118+
rfc109_gdal_cpp_api

‎doc/source/development/rfc/rfc109_gdal_cpp_api.rst‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
.. _rfc-109:
2+
3+
=====================================================================
4+
RFC 109: Split of gdal_priv.h and addition of gdal_cpp.h header
5+
=====================================================================
6+
7+
============== =============================================
8+
Author: Even Rouault
9+
Contact: even.rouault @ spatialys.com
10+
Started: 2025-09-12
11+
Status: Draft
12+
Target: GDAL 3.12
13+
============== =============================================
14+
15+
Summary
16+
-------
17+
18+
This RFC spreads the content of :file:`gdal_priv.h`, the installed header
19+
containing declaration for GDAL (raster) C++ classes, into finer grain exported headers.
20+
It also adds a new :file:`gdal_cpp.h` exported header, which is essentially the
21+
content of current :file:`gdal_priv.h` header, but with a more engaging name.
22+
Those changes are done in a fully backward compatible way: current external
23+
users of :file:`gdal_priv.h` will not have any change to do in their source code.
24+
25+
Motivation
26+
----------
27+
28+
As of today, :file:`gdal_priv.h` is a 5,600+ line long monolith including 35 classes
29+
definitions. There are several disadvantages to that:
30+
31+
- it makes navigating the content of the file difficult for users.
32+
- it may cause longer compilation times when only a subset of the functionality
33+
is needed.
34+
- it causes a number of C++ standard or other GDAL header files to be included
35+
by default to fulfill the requirements of those classes, but that would not be
36+
necessary in third-party code wanting to use the GDAL C++ API.
37+
38+
Another issue is the name itself :file:`gdal_priv.h` which suggests that this is
39+
a private API. While it is true that part of the content of that file is indeed
40+
for GDAL private needs, the majority of it is of legitimate use by external
41+
C++ users, hence it might be appropriate to offer a more engaging :file:`gdal_cpp.h`,
42+
while still acknowledging that what it exposes might be subject to changes:
43+
generally at least ABI changes at each feature release; sometimes API incompatible
44+
changes occur.
45+
46+
Technical solution
47+
------------------
48+
49+
The content of current :file:`gdal_priv.h` is spread over the following new
50+
exported (installed) header files:
51+
52+
- :file:`gdal_multidomainmetadata.h`: ``GDALMultiDomainMetadata`` class definition
53+
- :file:`gdal_majorobject.h`: ``GDALMajorObject`` class definition
54+
- :file:`gdal_defaultoverviews.h`: ``GDALDefaultOverviews`` class definition
55+
- :file:`gdal_openinfo.h`: ``GDALOpenInfo`` class definition
56+
- :file:`gdal_gcp.h`: ``gdal::GCP class`` definition
57+
- :file:`gdal_geotransform`: ``GDALGeoTransform`` class definition
58+
- :file:`gdal_dataset.h`: ``GDALDataset`` class definition
59+
- :file:`gdal_rasterblock.h`: ``GDALRasterBlock`` class definition
60+
- :file:`gdal_colortable.h`: ``GDALColorTable`` class definition
61+
- :file:`gdal_rasterband.h`: ``GDALRasterBand`` class definition
62+
- :file:`gdal_computedrasterband.h`: ``GDALComputedRasterBand`` class definition
63+
- :file:`gdal_maskbands.h`: ``GDALAllValidMaskBand``, ``GDALNoDataMaskBand``, ``GDALNoDataValuesMaskBand``, ``GDALRescaledAlphaBand`` class definitions (only a subset of out-of-tree drivers might need them)
64+
- :file:`gdal_driver.h`: ``GDALDriver`` class definition
65+
- :file:`gdal_drivermanager.h`: ``GDALDriverManager`` class definition
66+
- :file:`gdal_asyncreader.h`: ``GDALAsyncRader`` class definition
67+
- :file:`gdal_multidim.h`: definition all classes related to the multidimensional API: ``GDALGroup``, ``GDALAttribute``, ``GDALMDArray``, etc.
68+
- :file:`gdal_pam_multidim.h`: ``GDALPamMultiDim`` and ``GDALPanMDArray`` class definitions
69+
- :file:`gdal_relationship.h`: ``GDALRelationship`` class definition
70+
- :file:`gdal_cpp_functions.h`: public (exported), driver-public (exported) and private (non-exported) C++ methods
71+
72+
Each of this file aims to include the minimum amount of headers (C++ standard
73+
headers and GDAL specific headers) required to make it compile in a standalone
74+
mode (and this is enforced by a CI check) and use forward class definitions as
75+
much as possible.
76+
77+
A new :file:`gdal_cpp.h` file is added and just includes all the above mentioned
78+
files.
79+
80+
The existing :file:`gdal_priv.h` is modified as following:
81+
82+
- its current inclusion of non-strictly needed GDAL headers, such as CPL ones
83+
(:file:`cpl_vsi.h`, :file:`cpl_minixm.h`, etc.), GDAL ones (:file:`gdal_frmts.h`,
84+
:file:`gdalsubdatasetinfo.h`) and OGR ones (:file:`ogr_feature.h`) are kept
85+
by default. Users may define ``GDAL_PRIV_SKIP_OTHER_GDAL_HEADERS`` or ``GDAL_4_0_COMPAT``
86+
before including :file:`gdal_priv.h` to avoid including those files.
87+
88+
- its current inclusion of a number of C++ standard headers that might not all be
89+
needed is kept by default. Users may define ``GDAL_PRIV_SKIP_STANDARD_HEADERS`` or ``GDAL_4_0_COMPAT``
90+
before including :file:`gdal_priv.h` to avoid including those files.
91+
92+
- and finally it includes the new :file:`gdal_cpp.h`
93+
94+
The end result is that this whole restructuring should not have any visible
95+
effect on current users of :file:`gdal_priv.h`.
96+
97+
New users targeting only GDAL 3.12+ can now include at their convenience either
98+
:file:`gdal_cpp.h` or any of the new finer grain include files.
99+
100+
.. note::
101+
102+
The ``GDALPluginDriverProxy`` class definition is moved to a GDAL private
103+
non-installed :file:`gdalplugindriverproxy.h` header, since it can only be used by deferred
104+
loading plugin drivers, which must thus be in-tree. This class was not
105+
CPL_DLL exported.
106+
107+
The ``GDALAbstractBandBlockCache`` class definition is moved to a GDAL private
108+
non-installed :file:`gdal_abstractbandblockcache.h` header, since this is
109+
an implementation detail, that does not be accessed by users. This class was
110+
not CPL_DLL exported.
111+
112+
113+
Open questions
114+
--------------
115+
116+
- Do we need :file:`gdal_cpp.h` at all, or just keep with :file:`gdal_priv.h` ?
117+
One advantage of :file:`gdal_priv.h` is that the name does not suggest any stability.
118+
119+
- Does the content of :file:`gdal_cpp.h` must target only the GDAL "classic 2D" and
120+
multidimensional C++ API, or also the C++ vector API ?
121+
122+
Backwards compatibility
123+
-----------------------
124+
125+
Changes in this RFC aim at being backward compatible by default.
126+
127+
Documentation
128+
-------------
129+
130+
Pages under https://gdal.org/en/latest/api/index.html#raster-api and https://gdal.org/en/latest/api/index.html#multi-dimensional-array-api will be modified to mention the new finer grain headers.
131+
132+
https://gdal.org/en/latest/tutorials/raster_api_tut.html will be modified to
133+
mention the possibility of using the new headers.
134+
135+
Testing
136+
-------
137+
138+
Existing continuous integration should be sufficient to test the non regression;
139+
140+
Related issues and PRs
141+
----------------------
142+
143+
Candidate implementation: https://github.com/OSGeo/gdal/compare/master...rouault:gdal:gdal_priv_split?expand=1
144+
145+
Funding
146+
-------
147+
148+
Funded by GDAL Sponsorship Program (GSP)
149+
150+
Voting history
151+
--------------
152+
153+
TBD

0 commit comments

Comments
 (0)