From 30a3e3256f27623a3fce643d8d56170e9d3dc256 Mon Sep 17 00:00:00 2001 From: Victor Romero Date: Wed, 17 Jul 2019 11:34:31 -0700 Subject: Example: Building dynamic libraries on Linux using overlay triplets (#7291) * Example building dynamic libraries on Linux using overlay triplets * Change triplets list to multi-columns * Override default triplets example --- docs/examples/overlay-triplets-linux-dynamic.md | 158 ++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/examples/overlay-triplets-linux-dynamic.md (limited to 'docs/examples') diff --git a/docs/examples/overlay-triplets-linux-dynamic.md b/docs/examples/overlay-triplets-linux-dynamic.md new file mode 100644 index 000000000..6168d85e6 --- /dev/null +++ b/docs/examples/overlay-triplets-linux-dynamic.md @@ -0,0 +1,158 @@ +# Overlay triplets example: build dynamic libraries on Linux + +Using **vcpkg** you can build libraries for the following triplets: + +
+ +
+ + + +By design **vcpkg** builds only static libraries for Linux and Mac OS. +However, 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 to build dynamic libraries on Linux using **vcpkg**. + +### Step 1: Create a folder to contain your custom triplets + +``` +~/vcpkg$ mkdir ../custom-triplets +``` + +### Step 2: Create the custom triplet files + +To save time, copy the existing `x64-linux.cmake` triplet file. + +``` +~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-dynamic.cmake +``` + +And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below: +``` +set(VCPKG_TARGET_ARCHITECTURE x64) +set(VCPKG_CRT_LINKAGE dynamic) +# Change VCPKG_LIBRARY_LINKAGE from static to dynamic +set(VCPKG_LIBRARY_LINKAGE dynamic) + +set(VCPKG_CMAKE_SYSTEM_NAME Linux) +``` + +### Step 3: Use `--overlay-triplets` to build dynamic libraries + +Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. + +``` +./vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=../custom-triplets +The following packages will be built and installed: + sqlite3[core]:x64-linux +Starting package 1/1: sqlite3:x64-linux-dynamic +Building package sqlite3[core]:x64-linux-dynamic... +-- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake +-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip... +-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip +-- Applying patch fix-arm-uwp.patch +-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92 +-- Configuring x64-linux-dynamic-dbg +-- Configuring x64-linux-dynamic-rel +-- Building x64-linux-dynamic-dbg +-- Building x64-linux-dynamic-rel +-- Performing post-build validation +-- Performing post-build validation done +Building package sqlite3[core]:x64-linux-dynamic... done +Installing package sqlite3[core]:x64-linux-dynamic... +Installing package sqlite3[core]:x64-linux-dynamic... done +Elapsed time for package sqlite3:x64-linux-dynamic: 44.82 s + +Total elapsed time: 44.82 s + +The package sqlite3:x64-linux-dynamic provides CMake targets: + + find_package(sqlite3 CONFIG REQUIRED) + target_link_libraries(main PRIVATE sqlite3) +``` + +Overlay triplets will add your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`. + +When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used: + +``` +-- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake +``` + +## Overriding default triplets + +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 inconsistent with Linux and Mac OS where only static libraries are built. + +Using `--overlay-ports` it is possible to override the default triplets to accomplish the same behavior on Linux: + +* `x64-linux`: Builds dynamic libraries, +* `x64-linux-static`: Builds static libraries. + +### Step 1: Create the overriden triplet + +Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. + +``` +~/vcpkg$ mv ../custom-triplets/x64-linux-dynamic.cmake ../custom-triplets/x64-linux.cmake +``` + +### Step 2: Copy and rename the default triplet + +Then, copy the default `x64-linux` triplet (which builds static libraries) in your `/custom-triplets` folder and rename it to `x64-linux-static.cmake`. + +``` +~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-static.cmake +``` + +### Step 3: Use `--overlay-ports` to override default triplets + +Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. + +``` +./vcpkg install sqlite3:x64-linux --overlay-triplets=../custom-triplets +The following packages will be built and installed: + sqlite3[core]:x64-linux +Starting package 1/1: sqlite3:x64-linux +Building package sqlite3[core]:x64-linux... +-- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake +-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip... +-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip +-- Applying patch fix-arm-uwp.patch +-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92 +-- Configuring x64-linux-dbg +-- Configuring x64-linux-rel +-- Building x64-linux-dbg +-- Building x64-linux-rel +-- Performing post-build validation +-- Performing post-build validation done +Building package sqlite3[core]:x64-linux... done +Installing package sqlite3[core]:x64-linux... +Installing package sqlite3[core]:x64-linux... done +Elapsed time for package sqlite3:x64-linux: 44.82 s + +Total elapsed time: 44.82 s + +The package sqlite3:x64-linux provides CMake targets: + + find_package(sqlite3 CONFIG REQUIRED) + target_link_libraries(main PRIVATE sqlite3) +``` + +Note that the default triplet is masked by your custom triplet: + +``` +-- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake +``` -- cgit v1.2.3