update ceph source to reef 18.1.2

[ceph.git] / ceph / src / jaegertracing / opentelemetry-cpp / tools / vcpkg / docs / examples / overlay-triplets-linux-dynamic.md

# Overlay triplets example\r
\r
## Building dynamic libraries on Linux\r
\r
Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS.\r
\r
This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux.\r
\r
### Step 1: Create the custom triplet files\r
\r
To save time, copy the existing `x64-linux.cmake` triplet file.\r
\r
```sh\r
~/git$ mkdir custom-triplets\r
~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake\r
```\r
\r
And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below:\r
```cmake\r
# ~/git/custom-triplets/x64-linux-dynamic.cmake\r
set(VCPKG_TARGET_ARCHITECTURE x64)\r
set(VCPKG_CRT_LINKAGE dynamic)\r
set(VCPKG_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic\r
\r
set(VCPKG_CMAKE_SYSTEM_NAME Linux)\r
```\r
\r
### Step 2: Use `--overlay-triplets` to build dynamic libraries\r
\r
Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. \r
\r
```\r
~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets\r
The following packages will be built and installed:\r
    sqlite3[core]:x64-linux-dynamic\r
Starting package 1/1: sqlite3:x64-linux-dynamic\r
Building package sqlite3[core]:x64-linux-dynamic...\r
-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux-dynamic.cmake\r
-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...\r
-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip\r
-- Applying patch fix-arm-uwp.patch\r
-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92\r
-- Configuring x64-linux-dynamic-dbg\r
-- Configuring x64-linux-dynamic-rel\r
-- Building x64-linux-dynamic-dbg\r
-- Building x64-linux-dynamic-rel\r
-- Performing post-build validation\r
-- Performing post-build validation done\r
Building package sqlite3[core]:x64-linux-dynamic... done\r
Installing package sqlite3[core]:x64-linux-dynamic...\r
Installing package sqlite3[core]:x64-linux-dynamic... done\r
Elapsed time for package sqlite3:x64-linux-dynamic: 44.82 s\r
\r
Total elapsed time: 44.82 s\r
\r
The package sqlite3:x64-linux-dynamic provides CMake targets:\r
\r
    find_package(unofficial-sqlite3 CONFIG REQUIRED)\r
    target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)\r
```\r
\r
Overlay triplets enables your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.\r
\r
When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used: \r
\r
```\r
-- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake\r
```\r
\r
## Overriding default triplets\r
\r
As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is different with Linux and Mac OS where static libraries are built by `x64-linux` and `x64-osx`.\r
\r
Using `--overlay-triplets` it is possible to override the default triplets to accomplish the same behavior on Linux:\r
\r
* `x64-linux`: Builds dynamic libraries,\r
* `x64-linux-static`: Builds static libraries.\r
\r
### Step 1: Create the overlay triplets\r
\r
Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. Then, copy the default `x64-linux` triplet (which builds static libraries) in your `custom-triplets` folder and rename it to `x64-linux-static.cmake`.\r
\r
```sh\r
~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake\r
~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.cmake\r
```\r
\r
### Step 2: Use `--overlay-triplets` to override default triplets\r
\r
Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.\r
\r
```\r
~/git$ vcpkg/vcpkg install sqlite3:x64-linux --overlay-triplets=custom-triplets\r
The following packages will be built and installed:\r
    sqlite3[core]:x64-linux\r
Starting package 1/1: sqlite3:x64-linux\r
Building package sqlite3[core]:x64-linux...\r
-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake\r
-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...\r
-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip\r
-- Applying patch fix-arm-uwp.patch\r
-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92\r
-- Configuring x64-linux-dbg\r
-- Configuring x64-linux-rel\r
-- Building x64-linux-dbg\r
-- Building x64-linux-rel\r
-- Performing post-build validation\r
-- Performing post-build validation done\r
Building package sqlite3[core]:x64-linux... done\r
Installing package sqlite3[core]:x64-linux...\r
Installing package sqlite3[core]:x64-linux... done\r
Elapsed time for package sqlite3:x64-linux: 44.82 s\r
\r
Total elapsed time: 44.82 s\r
\r
The package sqlite3:x64-linux provides CMake targets:\r
\r
    find_package(unofficial-sqlite3 CONFIG REQUIRED)\r
    target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)\r
```\r
\r
Note that the default triplet is masked by your custom triplet:\r
\r
```\r
-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake\r
```\r