diff --git a/docs/examples/overlay-triplets-linux-dynamic.md b/docs/examples/overlay-triplets-linux-dynamic.md index 6168d85e6fa..b2868e2fd5b 100644 --- a/docs/examples/overlay-triplets-linux-dynamic.md +++ b/docs/examples/overlay-triplets-linux-dynamic.md @@ -1,66 +1,41 @@ -# Overlay triplets example: build dynamic libraries on Linux +# Overlay triplets example -Using **vcpkg** you can build libraries for the following triplets: +## Building dynamic libraries on Linux -
- -
+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. +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. - -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 +### Step 1: 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 +```sh +~/git$ mkdir custom-triplets +~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake ``` And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below: -``` +```cmake +# ~/git/custom-triplets/x64-linux-dynamic.cmake 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_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic set(VCPKG_CMAKE_SYSTEM_NAME Linux) ``` -### Step 3: Use `--overlay-triplets` to build dynamic libraries +### Step 2: 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 +~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets The following packages will be built and installed: - sqlite3[core]:x64-linux + sqlite3[core]:x64-linux-dynamic 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 +-- Loading triplet configuration from: /home/victor/git/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 @@ -84,7 +59,7 @@ The package sqlite3:x64-linux-dynamic provides CMake targets: 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`. +Overlay triplets enables 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: @@ -94,40 +69,33 @@ When using the `--overlay-triplets` option, a message like the following lets yo ## 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. +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`. 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 +### Step 1: Create the overlay triplets -Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. +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`. -``` -~/vcpkg$ mv ../custom-triplets/x64-linux-dynamic.cmake ../custom-triplets/x64-linux.cmake +```sh +~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake +~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.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 +### Step 2: 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 +~/git$ vcpkg/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 +-- Loading triplet configuration from: /home/victor/git/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 @@ -154,5 +122,5 @@ The package sqlite3:x64-linux provides CMake targets: Note that the default triplet is masked by your custom triplet: ``` --- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake +-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake ```