forked from mongodb/docs-cpp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapi-abi-versioning.txt
308 lines (215 loc) · 13 KB
/
api-abi-versioning.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
.. _cpp-api-abi-versioning:
======================
API and ABI Versioning
======================
.. meta::
:description: Understand the API and ABI versioning for the C++ driver, including header file structure, library filenames, and the use of CMake package config files.
.. contents:: On this page
:local:
:backlinks: none
:depth: 2
:class: singlecol
.. facet::
:name: genre
:values: reference
.. toctree::
:titlesonly:
:maxdepth: 1
API Versioning </api-abi-versioning/api-versioning>
ABI Versioning </api-abi-versioning/abi-versioning>
For brevity, this page may describe properties and features as-if they only apply to the bsoncxx library.
Unless stated otherwise, one may assume the properties and features described are similarly applicable to the mongocxx library.
API Versioning
--------------
See :ref:`API Versioning <cpp-api-versioning-policy>`.
ABI Versioning
--------------
See :ref:`ABI Versioning <cpp-abi-versioning-policy>`.
Header File Structure
---------------------
The public header files of the bsoncxx library are organized by ABI namespace:
.. code-block:: cpp
${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}/
└── bsoncxx/
├── v_noabi/bsoncxx/
│ └── ...
├── v1/bsoncxx/
│ └── ...
├── v2/bsoncxx/
│ └── ...
└── vN/bsoncxx/
└── ...
For forward compatibility, a public header file in an ABI namespace directory ``vA`` may include a header file in a *newer* ABI namespace directory ``vB``, where ``A < B``.
Such forward compatibility include directives, when supported, will be explicitly documented.
When ABI stability is required, we recommend including headers from the *latest* stable ABI namespace directory.
If ABI stability is not required, we recommend including the appropriate *unstable* ABI header instead.
.. important::
The ``bsoncxx/v_noabi/`` unstable ABI namespace directory is prioritized before the ``bsoncxx/`` root directory in include paths, such that ``#include <bsoncxx/example.hpp>`` is equivalent to ``#include <bsoncxx/v_noabi/bsoncxx/example.hpp>``.
.. note::
The stability of an *undocumented* include directive is not supported.
Package files are installed to subdirectories in ``${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/``.
Users are strongly encouraged to use these package files to obtain bsoncxx library header (as well for linking and the setting of compile flags).
Manual configuration of include paths to obtain bsoncxx header files is not recommended.
Package files are described further below.
In all cases, **CMake package config files are the recommended method for importing C++ driver libraries.**
Library Filenames
-----------------
The filename and presence of symlinks depends on the platform and toolchain used to build the library, as well as the library type (shared vs. static).
Shared Libraries
~~~~~~~~~~~~~~~~
.. important::
Shared libraries on Windows when configured with the MSVC toolchain on
Windows are treated differently due to Windows-specific special
considerations. See :ref:`Shared Libraries (MSVC Only) <cpp-shared-lib-msvc>` below.
The "real name" of shared libraries use the following pattern:
.. code-block:: none
lib<basename>.so.<api-version-number>
where:
- ``<basename>`` corresponds to the ``BSONCXX_OUTPUT_BASENAME`` CMake configuration variable (``MONGOCXX_OUTPUT_BASENAME`` for the mongocxx library). By default, this is set to ``bsoncxx`` and ``mongocxx``. The basename of a static library is suffixed with ``-static``.
- ``<api-version-number>`` is the MAJOR, MINOR, and PATCH version for the given build configuration, corresponding to the ``BUILD_VERSION`` CMake configuration variable. (Note: explicitly setting this configuration variable should not be necessary in regular use of the C++ driver.)
- API version number extensions are *not* included in the real name (e.g. the ``-alpha`` in ``1.2.3-alpha``).
Examples of expected library real names include:
.. code-block:: none
libbsoncxx.so.1.0.0
libbsoncxx.so.2.3.4
CMake's ``SOVERSION`` target property and "namelink" behavior is used to also install symlinks to the library directory consistent with the Linux soname convention.
These symlinks include the ABI version number as part of the library soname.
For example, the following lib directory contains the expected library files for a bsoncxx library with API version ``1.2.3`` and ABI version ``10``, where ``a -> b`` indicates ``a`` is a symlink to ``b``:
.. code-block:: none
${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/
├── libbsoncxx.so.1.2.3
├── libbsoncxx.so.10 -> libbsoncxx.so.1.2.3
├── libbsoncxx.so -> libbsoncxx.so.10
├── cmake/bsoncxx-1.2.3/
│ ├── bsoncxx-config.cmake
│ └── ...
└── pkgconfig/
└── libbsoncxx.pc
The name of the CMake package for bsoncxx libraries is controlled by ``BSONCXX_OUTPUT_BASENAME`` (``MONGOCXX_OUTPUT_BASENAME`` for mongocxx libraries).
They should be imported according to CMake's `Config Mode Search Procedure <https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure>`__.
For example, assuming the C++ driver was installed to a prefix ``$INSTALLDIR``:
.. code-block:: bash
# The CMake package may be imported via CMAKE_PREFIX_PATH (recommended)...
cmake -S example -B example-build -D CMAKE_PREFIX_PATH="$INSTALLDIR"
# Or via <PackageName>_ROOT (assuming BSONCXX_OUTPUT_NAME=bsoncxx)...
cmake -S example -B example-build -D bsoncxx_ROOT="$INSTALLDIR"
# Or via ``PATHS`` in the ``find_package()`` command... or etc.
# find_package(bsoncxx CONFIG REQUIRED PATHS "$INSTALLDIR")
.. note::
The C Driver is a required dependency for the C++ Driver. The CMake package config
files for the C Driver may also need to be imported using the same (or
similar) approach to satisfy this dependency.
Although the C++ Driver also provides pkg-config files, users are strongly
encouraged to use CMake package config files instead.
The name of the pkg-config file for bsoncxx libraries is also controlled by ``BSONCXX_OUTPUT_NAME`` and follow the pattern ``lib<basename>.pc``.
The ``PKG_CONFIG_PATH`` environment variable may need to be used to augment
pkg-config's search path, e.g.:
.. code-block:: bash
bsoncxx_cflags="$(PKG_CONFIG_PATH="$INSTALLDIR" pkg-config --cflags "libbsoncxx >= 1.2.3")"
bsoncxx_ldflags="$(PKG_CONFIG_PATH="$INSTALLDIR" pkg-config --libs "libbsoncxx >= 1.2.3")"
g++ $bsoncxx_cflags -c example-a.cpp
g++ $bsoncxx_cflags -c example-b.cpp
g++ $bsoncxx_ldflags -o example example-a.o example-b.o
.. _cpp-shared-lib-msvc:
Shared Libraries (MSVC Only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Since version 3.10.0, the shared libraries when built with the MSVC toolchain on Windows (even when the CMake generator is not Visual Studio) use a different naming scheme from other platforms.
To restore prior behavior, which is similar to other platforms, set ``ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES=OFF``.
The name of shared libraries (aka the "output name") use the following pattern (file extension excluded):
.. code-block:: none
<basename>-v<abi-version-number>-<abi-tag>
where:
- ``<basename>`` corresponds to the ``BSONCXX_OUTPUT_BASENAME`` CMake configuration variable (``MONGOCXX_OUTPUT_BASENAME`` for the mongocxx library). By default, this is set to ``bsoncxx`` and ``mongocxx``. The basename of a static library is suffixed with ``-static``.
- ``<abi-version-number>`` corresponds to the current ABI version number.
- ``<abi-tag>`` describes known properties that affect the binary compatibility of the shared library.
The ``<abi-tag>`` is a triplet of letters indicating:
- Build Type
- mongoc Link Type
- Polyfill Library
This is followed by a suffix describing the toolset and runtime library used to
build the library. The exact contents of the suffix depend on the build configuration.
Examples of expected library filenames (with a brief description of notable features) include:
- ``bsoncxx-v_noabi-rhs-x64-v142-md.dll`` (release build configuration)
- ``bsoncxx-v_noabi-dhs-x64-v142-mdd.dll`` (debug build configuration)
- ``bsoncxx-v_noabi-rts-x64-v142-md.dll`` (link with mongoc static libraries)
- ``bsoncxx-v_noabi-rhi-x64-v142-md.dll`` (bsoncxx as polyfill library)
- ``bsoncxx-v1-rhs-x64-v142-md.dll`` (ABI version number 1)
- ``bsoncxx-v2-rhs-x64-v142-md.dll`` (ABI version number 2)
.. note::
This example also applies to the companion ``.lib`` file.
This naming scheme allows the bsoncxx library to be built and installed with
different build configurations (e.g. Debug vs. Release) and different runtime
library requirements (e.g. MultiThreadedDLL vs. MultiThreadedDebugDLL) in
parallel and without conflict. See references to
``ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES`` and related code in the CMake
configuration for more details.
For example, the following install prefix directory contains the expected debug *and* release library files for a bsoncxx library with API version ``1.2.3`` and ABI version ``10`` (the bin directory is included to account for ``.dll`` files):
.. code-block:: none
${CMAKE_INSTALL_PREFIX}/
├── ${CMAKE_INSTALL_BINDIR}/
│ ├── bsoncxx-v10-dhs-x64-v142-mdd.dll
│ └── bsoncxx-v10-rhs-x64-v142-md.dll
└── ${CMAKE_INSTALL_LIBDIR}/
├── bsoncxx-v10-dhs-x64-v142-mdd.lib
├── bsoncxx-v10-rhs-x64-v142-md.lib
├── cmake/bsoncxx-1.2.3/
│ ├── bsoncxx-config.cmake
│ └── ...
└── pkgconfig/
├── libbsoncxx-v10-dhs-x64-v142-mdd.pc
└── libbsoncxx-v10-rhs-x64-v142-md.pc
The CMake package config files are the same as the regular (non-MSVC) shared library behavior described above.
.. note::
CMake automatically handles selection of libraries according to build type, but does not enforce build type consistency when only one build type is installed. Installing *both* Debug and Release configurations on Windows is highly recommended for this reason. (This note only applies to the build type configuration parameter).
The name of the pkg-config file for C++ Driver libraries is the same as that for the regular (non-MSVC) shared library behavior described above.
However, when ``ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON``, the library output name is used as-if it were the basename for pkg-config files.
For example, to obtain flags for the shared library ``bsoncxx-v_noabi-rhs-x64-v142-md.dll``, the pkg-config command may look as follows when ``ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=OFF`` (the default):
.. code-block:: bash
pkg-config --cflags "libbsoncxx"
or as follows when ``ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON``:
.. code-block:: bash
pkg-config --cflags "libbsoncxx-v_noabi-rhs-x64-v142-md"
Setting ``ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON`` is recommended when
parallel installation of C++ Driver libraries with different build
configurations (e.g. Debug vs. Release) is expected. However, using CMake
package config files instead is most recommended.
Static Libraries
~~~~~~~~~~~~~~~~
Static libraries use a simple filename pattern:
.. code-block:: none
lib<basename>-static.a
No API or ABI version information is included in the name of static library
files.
Shared vs. static library selection for CMake package config files is handled
via CMake targets.
Shared vs. static library selection for pkg-config files is handled by adding the ``-static`` suffix to the library basename, e.g. ``lib<basename>-static.pc``.
For example, the following library directory contains the expected shared *and* static library files for a bsoncxx library:
.. code-block:: none
${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/
├── libbsoncxx.so.1.2.3
├── libbsoncxx.so.10 -> libbsoncxx.so.1.2.3
├── libbsoncxx.so -> libbsoncxx.so.10
├── libbsoncxx-static.a
├── cmake/bsoncxx-1.2.3/
│ ├── bsoncxx-config.cmake
│ └── ...
└── pkgconfig/
├── libbsoncxx.pc
└── libbsoncxx-static.pc
Static Libraries (MSVC Only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The name of static libraries use the same pattern as MSVC shared library behavior described above, but uses ``static`` as the ``<abi-version-number>`` and the library output name as-if it were the basename.
For example, the following install prefix directory contains the expected shared *and* static library files for a bsoncxx library (the bin directory is included to account for ``.dll`` files):
.. code-block:: none
${CMAKE_INSTALL_PREFIX}/
├── ${CMAKE_INSTALL_BINDIR}/
│ └── bsoncxx-v10-rhs-x64-v142-md.dll
└── ${CMAKE_INSTALL_LIBDIR}/
├── bsoncxx-v10-rhs-x64-v142-md.lib
├── bsoncxx-static-dhs-x64-v142-mdd.lib
├── cmake/bsoncxx-1.2.3/
│ ├── bsoncxx-config.cmake
│ └── ...
└── pkgconfig/
├── libbsoncxx-v10-rhs-x64-v142-md.pc
└── libbsoncxx-static-rhs-x64-v142-md.pc