Skip to content

Commit a44ca5a

Browse files
vossmjpdnmokhov
vossmjp
and
dnmokhov
authored
Added VERSIONING.md (#1640)
* Added Versioning Policies * Update VERSIONING.md Fixed subtitle based on review * Update VERSIONING.md Co-authored-by: Dmitri Mokhov <[email protected]> * Update VERSIONING.md --------- Co-authored-by: Dmitri Mokhov <[email protected]>
1 parent c712c1a commit a44ca5a

File tree

2 files changed

+110
-0
lines changed

2 files changed

+110
-0
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ See [Release Notes](RELEASE_NOTES.md) and [System Requirements](SYSTEM_REQUIREME
3737
* [oneTBB Developer Guide and Reference](https://uxlfoundation.github.io/oneTBB)
3838
* [Migrating from TBB to oneTBB](https://uxlfoundation.github.io/oneTBB/main/tbb_userguide/Migration_Guide.html)
3939
* [README for the CMake build system](cmake/README.md)
40+
* [oneTBB Versioning Policies](VERSIONING.md)
4041
* [oneTBB Testing Approach](https://uxlfoundation.github.io/oneTBB/main/intro/testing_approach.html)
4142
* [Basic support for the Bazel build system](Bazel.md)
4243
* [oneTBB Discussions](https://github.com/uxlfoundation/oneTBB/discussions)

‎VERSIONING.md

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# oneTBB Versioning Policies
2+
3+
There are several types of "versioning" used by the oneTBB project.
4+
5+
1. The *oneTBB specification version*
6+
2. The *official oneTBB library version*
7+
3. The *library interface version*
8+
4. *API versioning* used to maintain backwards compatibility
9+
10+
The oneTBB project uses semantic versioning (https://semver.org/) and as a oneAPI Library,
11+
the oneTBB project makes commitments around compatibility as described
12+
[here](https://www.intel.com/content/www/us/en/docs/oneapi/programming-guide/2024-1/oneapi-library-compatibility.html).
13+
With semantic versioning, a MAJOR version increment generally means an incompatible API change,
14+
while a MINOR version increment means added functionality that is implemented in a backwards compatible manner.
15+
16+
## The oneTBB Specification Version
17+
18+
The oneTBB project is governed by the [UXL foundation](https://uxlfoundation.org/) and has
19+
[an open specification](https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/nested-index).
20+
Each release of the specification has a version number.
21+
22+
[As described in the specification](https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/configuration/version_information),
23+
the value of the `ONETBB_SPEC_VERSION` macro in `oneapi/tbb/version.h` is latest specification of oneTBB fully
24+
supported by the implementation.
25+
26+
## The oneTBB Library Version
27+
28+
The oneTBB library version can be thought of as the name of the release. If you want to find a specific
29+
release in the repository (https://github.com/uxlfoundation/oneTBB), the tag you would look for corresponds
30+
to the oneTBB library version.
31+
32+
[As described in the specification](https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/configuration/version_information),
33+
the macros `TBB_VERSION_MAJOR`, `TBB_VERSION_MINOR`, `TBB_VERSION_STRING` in `oneapi/tbb/version.h`
34+
provide the library version of the implementation that is being compiled against. The function
35+
`const char* TBB_runtime_version();` can be used to query the library version of the oneTBB binary library that is
36+
loaded at runtime.
37+
38+
## The oneTBB Interface Version
39+
40+
The oneTBB interface version is the public contract about the interface to the library including the
41+
functions exported by the binary library and the types defined in the headers. The oneTBB library is designed
42+
for backwards compatibility. It works well in the scenarios where components compile/link against a TBB version
43+
X.Y. And then at runtime, the application loads a library version X.Z, where X.Z >= X.Y.
44+
45+
A minor version may add new functionality in the headers or in the binary library, including new entry points to the
46+
binary library. An application compiled against an older minor version could not have used this new functionality
47+
and therefore can safely use the newer binary library.
48+
49+
[As described in the specification](https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/configuration/version_information),
50+
the macros `TBB_INTERFACE_VERSION_MAJOR`, `TBB_INTERFACE_VERSION_MINOR`, `TBB_INTERFACE_VERSION` in `oneapi/tbb/version.h`
51+
can be used to determine the interface version of the implementation that is being compiled against. The function
52+
`int TBB_runtime_interface_version();` can be used to query the interface version of the oneTBB binary library that is
53+
loaded at runtime.
54+
55+
### Shared Library Practices for Linux
56+
57+
On Linux we use a symlink system for binary libraries in the oneTBB distribution, and also explicitly set a soname.
58+
The actual shared library is libtbb.so.X.Y but it is built with a –soname that uses only the major version number,
59+
libtbb.so.X. In addition, there is a symlink from libtbb.so.X -> libtbb.so.X.Y and a symlink from
60+
libtbb.so -> libtbb.so.X. Therefore, whether you build against libtbb.so, libtbb.so.X or libtbb.so.X.Y, your
61+
application will have a dependency on libtbb.so.X.
62+
63+
A common development process is to compile and link against a library version X.Y. This creates
64+
a dependency on libtbb.so.X. The packaged project then redistributes a TBB shared library that
65+
is X.Z, where X.Z >= X.Y.
66+
67+
In the (unusual) case where the package does not redistribute a TBB library and instead depends on a version already
68+
available on the install platform, it is safest to build against the oldest version you expect to encounter; in the
69+
extreme this would be X.1. Of course, building against X.1 means no additional functionalility added in any later minor
70+
release can be used during the development of the application.
71+
72+
### Shared Library Practices for Windows
73+
74+
On Windows, the TBB binary library has only the major version number, tbb12.dll.
75+
76+
## API versioning used to maintain backwards compatibility
77+
78+
This section is targeted at oneTBB contributors and will likely not be of interest to users of the
79+
oneTBB library.
80+
81+
As mentioned previously, minor release may add new functionality, including modified definitions of classes
82+
in the headers or new entry points into the binary library. To safely add this new functionality in a way
83+
that avoids conflicts, oneTBB has namespaces for class definitions in the headers (that start with the
84+
letter "d") and namespaces for symbols exported by the binary runtime library (that start with the
85+
letter "r").
86+
87+
Below is an example of
88+
[a function exported](https://github.com/uxlfoundation/oneTBB/blob/45c2298727d09556a523d6aeaec84ef23872eccf/src/tbb/parallel_pipeline.cpp#L446)
89+
by the oneTBB runtime library:
90+
91+
namespace tbb {
92+
namespace detail {
93+
namespace r1 {
94+
void __TBB_EXPORTED_FUNC parallel_pipeline(d1::task_group_context& cxt,
95+
std::size_t max_token,
96+
const d1::filter_node& fn);
97+
}
98+
}
99+
}
100+
101+
This function is in the runtime namespace `r1` and takes `d1` versions of `task_group_context` and
102+
`filter_node` classes as arguments. Backward incompatible changes added to the library can be added
103+
to namespaces with incremented version numbers.
104+
105+
Rules for the `d` namespace include:
106+
107+
- If the layout of public class X is changed incompatibly, the “d” namespace number should be incremented.
108+
- If there are existing entry points using the current version of class X, the old version of X should
109+
be kept in the previous “d” namespace.

0 commit comments

Comments
 (0)