boost/website-v2-docs
2
0
Fork 0
mirror of https://github.com/boostorg/website-v2-docs.git synced 2026-01-19 04:42:17 +00:00
Code Issues Projects Releases Wiki Activity

Format updates to Library Naming topic (#568)

Browse Source
This commit is contained in:
Peter Turcan
2025-12-19 08:32:35 -08:00
committed by GitHub
parent ac11ba2f2a
commit c4a20981dd
1 changed files with 43 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
user-guide/modules/ROOT/pages/library-naming.adoc
View File

@@ -9,6 +9,15 @@ Official repository: https://github.com/boostorg/website-v2-docs
= Library Names and Organization
:navtitle: Library Names and Organization
* <<Introduction>>
* <<Library Name Elements>>
* <<Installed Library Names>>
* <<The Boost Distribution>>
* <<Footnotes>>
* <<See Also>>
== Introduction
If your compiler supports auto-linking, such as Visual C++, then there is no need to understand the details of library binary naming.
However, if auto-linking is not supported by your compiler, then, in order to choose the right binary for your build configuration you
@@ -16,60 +25,41 @@ need to know how Boost binaries are named.
== Library Name Elements
Each library filename is
composed of a common sequence of elements that describe how it was
built. For example, `libboost_regex-vc71-mt-d-x86-1_34.lib` can
be broken down into the following elements:
Each library filename is composed of a common sequence of elements that describe how it was built. For example, `libboost_regex-vc71-mt-d-x86-1_34.lib` can be broken down into the following elements:
[#footnote1-location]
`lib`::
_Prefix_: except on Microsoft Windows, every Boost library name begins
with this string. On Windows, only ordinary static libraries use the
`lib` prefix; import libraries and DLLs do not. link:#footnote1[(1)]
* `lib`: _Prefix_: except on Microsoft Windows, every Boost library name begins with this string. On Windows, only ordinary static libraries use the `lib` prefix; import libraries and DLLs do not. link:#footnote1[(1)]
`boost_regex`::
_Library name_: all boost library filenames begin with `boost_`.
* `boost_regex`: _Library name_: all boost library filenames begin with `boost_`.
`-vc71`::
_Toolset tag_: identifies the xref:header-organization-compilation.adoc#toolset[toolset] and version used to build the binary.
* `-vc71`: _Toolset tag_: identifies the xref:header-organization-compilation.adoc#toolset[toolset] and version used to build the binary.
`-mt`::
_Threading tag_: indicates that the library was built with
multithreading support enabled. Libraries built without multithreading
support can be identified by the absence of `-mt` .
* `-mt`: _Threading tag_: indicates that the library was built with multithreading support enabled. Libraries built without multithreading support can be identified by the absence of `-mt` .
[#footnote2-location]
`-d`::
_ABI tag_: encodes details that affect the library's interoperability
with other compiled code. For each such feature, a single letter is
added to the tag:
[cols="1,5,2",options="header",stripes=even]
* `-d`: _ABI tag_: encodes details that affect the library's interoperability with other compiled code. For each such feature, a single letter is added to the tag:
+
[cols="1,5,2",options="header",stripes=even,frame=none]
|===
|Key |Use this library when: |B2 option
|`s` |linking statically to the C++ standard library and compiler
|Key |Use Case |B2 Option
|`s` |Linking statically to the C++ standard library and compiler
runtime support libraries. |`runtime-link=static`
|`g` |using debug versions of the standard and runtime support
|`g` |Using debug versions of the standard and runtime support
libraries. |`runtime-debugging=on`
|`y` |using a special https://www.boost.org/doc/libs/1_58_0/libs/python/doc/building.html[debug build of Python]. |`python-debugging=on`
|`d` |building a debug version of your code. link:#footnote2[(2)]
|`y` |Using a special https://www.boost.org/doc/libs/1_58_0/libs/python/doc/building.html[debug build of Python]. |`python-debugging=on`
|`d` |Building a debug version of your code. link:#footnote2[(2)]
|`variant=debug`
|`p` |using the STLPort standard library rather than the default one
|`p` |Using the STLPort standard library rather than the default one
supplied with your compiler. |`stdlib=stlport`
|===
+
For example, if you build a debug version of your code for use with debug versions of the static runtime library and the STLPort standard library, the tag would be: `-sgdp` . If none of the above apply, the ABI tag is omitted.
For example, if you build a debug version of your code for use with
debug versions of the static runtime library and the STLPort standard
library, the tag would be: `-sgdp` . If none of the above
apply, the ABI tag is omitted.
`-x86`::
_Architecture and address model tag_: in the first letter, encodes the
architecture as follows:
[width="100%",cols="1,3,4",options="header",stripes=even]
* `-x86`: _Architecture and address model tag_: in the first letter, encodes the architecture as follows:
+
[width="100%",cols="1,3,4",options="header",stripes=even,frame=none]
|===
|Key |Architecture |B2 option
|Key |Architecture |B2 Option
|`x` |x86-32, x86-64 | `architecture=x86`
|`a` |ARM |`architecture=arm`
|`i` |IA-64 |`architecture=ia64`
@@ -77,30 +67,19 @@ apply, the ABI tag is omitted.
|`m` |MIPS/SGI |`architecture=mips*`
|`p` |RS/6000 & PowerPC |`architecture=power`
|===
The two digits following the letter encode the address model as
follows:
[width="100%",cols="1,3,4",options="header",stripes=even]
+
The two digits following the letter encode the address model as follows:
+
[width="100%",cols="1,3,4",options="header",stripes=even,frame=none]
|===
|Key |Address model |B2 option
|Key |Address Model |B2 Option
|`32` |32 bit |`address-model=32`
|`64` |64 bit |`address-model=64`
|===
`-1_34`::
_Version tag_: the full Boost release number, with periods replaced by
underscores. For example, version 1.31.1 would be tagged as `-1_31_1`.
* `-1_34`: _Version tag_: the full Boost release number, with periods replaced by underscores. For example, version 1.31.1 would be tagged as `-1_31_1`.
`.lib`::
_Extension_: determined according to the operating system's usual
convention. On most unix-style platforms the extensions are `.a` and
`.so` for static libraries (archives) and shared libraries,
respectively. On Windows, `.dll` indicates a shared library and `.lib`
indicates a static or import library. Where supported by toolsets on
unix variants, a full version extension is added (e.g. ".so.1.34") and
a symbolic link to the library file, named without the trailing
version number, will also be created.
* `.lib`: _Extension_: determined according to the operating system's usual convention. On most unix-style platforms the extensions are `.a` and `.so` for static libraries (archives) and shared libraries, respectively. On Windows, `.dll` indicates a shared library and `.lib` indicates a static or import library. Where supported by toolsets on unix variants, a full version extension is added (e.g. ".so.1.34") and a symbolic link to the library file, named without the trailing version number, will also be created.
== Installed Library Names
@@ -108,9 +87,9 @@ When libraries are installed using the B2 app, the actual name can vary from the
The `--layout=<layout>` option determines how the library name is handled, and the appropriate header locations so that multiple versions of Boost, or multiple compilers, can be used on the same system.
[cols="1,3,1",options="header",stripes=even]
[cols="1,3,1",options="header",stripes=even,frame=none]
|===
|Layout |Description | Default on
|Layout |Description | Default On
|`versioned` | The names of Boost binaries include the Boost version number, name and version of the compiler, and encoded build properties. Boost headers are installed in a subdirectory of `<HDRDIR>` whose name contains the Boost version number. | Windows
|`tagged` | Names of boost binaries include the encoded build properties such as variant and threading, but do not including compiler name and version, or Boost version. This option is useful if you build several variants of Boost, using the same compiler. | none
|`system` | Binaries names do not include the Boost version number or the name and version number of the compiler. Boost headers are installed directly into `<HDRDIR>`. This option is intended for system integrators building distribution packages. | Unix
@@ -120,7 +99,7 @@ The `--layout=<layout>` option determines how the library name is handled, and t
After installing Boost, this is the resulting directory structure, in the *boost_1_82_0* root:
[cols="1,1,4",options="header",stripes=even]
[cols="1,1,4",options="header",stripes=even,frame=none]
|===
|Root Level |Lower Level | Description
|*bin.v2*| *libs* | Mainly contains the compiled binaries for those libraries that require compilation.
@@ -131,27 +110,19 @@ After installing Boost, this is the resulting directory structure, in the *boost
|*stage* | *lib* | CMake files for each library
|*status*| | Boost-wide test suite
|*tools* | tool folders |Utilities: B2, quickbook, bcp, etc.
|b2.exe| | Boost install app, and supporting files
|index.htm | | A copy of www.boost.org starts here
|`b2.exe`| | Boost install app, and supporting files
|`index.htm` | | A copy of www.boost.org starts here
|===
== Footnotes
[#footnote1]
link:#footnote1-location[(1)]::
This convention distinguishes the static version of a
Boost library from the import library for an identically-configured
Boost DLL, which would otherwise have the same name.
link:#footnote1-location[(1)] This convention distinguishes the static version of a Boost library from the import library for an identically-configured Boost DLL, which would otherwise have the same name.
[#footnote2]
link:#footnote2-location[(2)]::
These libraries were compiled without optimization or
inlining, with full debug symbols enabled, and without `#define NDEBUG`. Although it's true that sometimes these choices don't affect
binary compatibility with other compiled code, you can't count on that
with Boost libraries.
link:#footnote2-location[(2)] These libraries were compiled without optimization or inlining, with full debug symbols enabled, and without `#define NDEBUG`. Although it's true that sometimes these choices don't affect binary compatibility with other compiled code, you can't count on that with Boost libraries.
== See Also
[square]
* xref:header-organization-compilation.adoc[]