Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[vcpkg-docs] Reword and reorganize overlay-triplets-linux-dynamic.md #7502

Merged
merged 1 commit into from
Aug 2, 2019
Merged

[vcpkg-docs] Reword and reorganize overlay-triplets-linux-dynamic.md #7502

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 26 additions & 58 deletions docs/examples/overlay-triplets-linux-dynamic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<div>
<ul style="columns: 3;">
<li> arm-uwp</li>
<li> arm-windows</li>
<li> arm64-uwp</li>
<li> arm64-windows</li>
<li> x86-uwp</li>
<li> x86-windows</li>
<li> x86-windows-static</li>
<li> x64-uwp</li>
<li> x64-linux</li>
<li> x64-osx</li>
<li> x64-windows</li>
<li> x64-windows-static</li>
</ul>
</div>
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
Expand All @@ -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:

Expand All @@ -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

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 1: Create the overlay triplets

### Step 2: Copy and rename the default triplet
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`.

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
```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 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
Expand All @@ -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
```