mirror/vcpkg
1
0
Fork 0
mirror of https://github.com/microsoft/vcpkg.git synced 2025-06-06 06:24:00 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs.

Browse Source
This commit is contained in:
Robert Schumacher 2017-05-24 23:33:16 -07:00
parent e95a098696
commit 49cd399586
39 changed files with 1577 additions and 465 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@ -7,10 +7,10 @@ For short description of available commands, run `vcpkg help`.
## Quick Start
Prerequisites:
- Visual Studio 2015 Update 3 or
- Visual Studio 2017
- CMake 3.8.0 or higher (note: downloaded automatically if not found)
- `git.exe` available in your path
- Windows 10, 8.1, or 7
- Visual Studio 2017 or Visual Studio 2015 Update 3
- Git
- *Optional: CMake 3.8.0*
Clone this repository, then run
```
@ -24,12 +24,14 @@ Install any packages with
```
C:\src\vcpkg> .\vcpkg install sdl2 curl
```
Finally, create a New Project (or open an existing one) in Visual Studio 2015 or Visual Studio 2017. You can now `#include` and use any of the installed libraries.
Finally, create a New Project (or open an existing one) in Visual Studio 2017 or 2015. All installed libraries are immediately ready to be `#include`'d and used in your project.
For CMake projects, simply include our toolchain file. See our [using a package](docs/examples/using-sqlite.md) example for the specifics.
## Examples
See the [`docs\EXAMPLES.md`](docs/EXAMPLES.md) document for specific walkthroughs, including using a package and adding a new package.
See the [documentation](docs/index.md) for specific walkthroughs, including [using a package](docs/examples/using-sqlite.md) and [adding a new package](docs/examples/packaging-zlib.md).
See a 4 minute [demo in video](https://www.youtube.com/watch?v=y41WFKbQFTw).
See a 4 minute [video demo](https://www.youtube.com/watch?v=y41WFKbQFTw).
## Contributing
Vcpkg is built with your contributions. Here are some ways you can contribute:

302
docs/EXAMPLES.md
View File

@ -1,302 +0,0 @@
# Vcpkg
## Overview
Vcpkg helps you get C and C++ libraries on Windows.
For short description of available commands, run `.\vcpkg help`.
## Table of Contents
- <a href="#example-1">Example 1: Using Sqlite</a>
- <a href="#example-1-1">Step 1: Build</a>
- <a href="#example-1-2">Step 2: Use</a>
- <a href="#example-1-2-a">Option A: VS Project (User-wide integration)</a>
- <a href="#example-1-2-b">Option B: CMake (Toolchain file)</a>
- <a href="#example-1-2-c">Option C: Other buildsystems</a>
- <a href="#example-1-2-d">Option D: VS Project (Individual Project integration)</a>
- <a href="#example-2">Example 2: Package a remote project (zlib)</a>
- <a href="example-3-patch-libpng.md">Example 3: Patching libpng to work for uwp-x86</a>
<a name="example-1"></a>
## Example 1: Using Sqlite
<a name="example-1-1"></a>
### Step 1: Build
First, we need to know what name [Sqlite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output:
```
PS D:\src\vcpkg> .\vcpkg search sqlite
libodb-sqlite 2.4.0 Sqlite support for the ODB ORM library
sqlite3 3.15.0 SQLite is a software library that implements a se...
If your library is not listed, please open an issue at:
https://github.com/Microsoft/vcpkg/issues
```
Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages.
Installing is then as simple as using the `install` command.
```
PS D:\src\vcpkg> .\vcpkg install sqlite3
-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows
-- DOWNLOADS=D:/src/vcpkg/downloads
-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/sqlite3_x86-windows
-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/sqlite3
-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/sqlite3/.
-- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip...
-- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip... OK
-- Testing integrity of downloaded file...
-- Testing integrity of downloaded file... OK
-- Extracting source D:/src/vcpkg/downloads/sqlite-amalgamation-3150000.zip
-- Extracting done
-- Configuring x86-windows-rel
-- Configuring x86-windows-rel done
-- Configuring x86-windows-dbg
-- Configuring x86-windows-dbg done
-- Build x86-windows-rel
-- Build x86-windows-rel done
-- Build x86-windows-dbg
-- Build x86-windows-dbg done
-- Package x86-windows-rel
-- Package x86-windows-rel done
-- Package x86-windows-dbg
-- Package x86-windows-dbg done
-- Performing post-build validation
-- Performing post-build validation done
Package sqlite3:x86-windows is installed
```
We can check that sqlite3 was successfully installed for x86 windows desktop by running the `list` command.
```
PS D:\src\vcpkg> .\vcpkg list
sqlite3:x86-windows 3.15.0 SQLite is a software library that implements a se...
```
To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:<target>`.
```
PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows
```
See `.\vcpkg help triplet` for all supported targets.
<a name="example-1-2"></a>
### Step 2: Use
<a name="example-1-2-a"></a>
#### Option A: VS Project (User-wide integration)
The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will require administrator access the first time it is used on a given machine. After the first use, administrator access is no longer required and the integration is on a per-user basis.
```
PS D:\src\vcpkg> .\vcpkg integrate install
Applied user-wide integration for this vcpkg root.
All C++ projects can now #include any installed libraries.
Linking will be handled automatically.
Installing new libraries will make them instantly available.
```
*Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.*
You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 and the library will be automatically available. For Sqlite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html).
To remove the integration for your user, you can use `.\vcpkg integrate remove`.
<a name="example-1-2-b"></a>
#### Option B: CMake (Toolchain File)
The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as `-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`.
Alternatively, if you are using CMake through Open Folder with Visual Studio 2017 you can define `CMAKE_TOOLCHAIN_FILE` by adding a `variables` section to each of your `CMakeSettings.json` configurations:
```json
{
"configurations": [
{
"name": "x86-Debug",
"generator": "Visual Studio 15 2017",
"configurationType" : "Debug",
"buildRoot": "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
"cmakeCommandArgs": "",
"buildCommandArgs": "-m -v:minimal",
"variables": [
{
"name": "CMAKE_TOOLCHAIN_FILE",
"value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
}
]
}
]
}
```
Now let's make a simple CMake project with a main file.
```cmake
# CMakeLists.txt
cmake_minimum_required(VERSION 3.0)
project(test)
find_package(Sqlite3 REQUIRED)
link_libraries(sqlite3)
add_executable(main main.cpp)
```
```cpp
// main.cpp
#include <sqlite3.h>
#include <stdio.h>
int main()
{
printf("%s\n", sqlite3_libversion());
return 0;
}
```
Then, we build our project in the normal CMake way:
```
PS D:\src\cmake-test> mkdir build
PS D:\src\cmake-test> cd build
PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake"
// omitted CMake output here //
-- Build files have been written to: D:/src/cmake-test/build
PS D:\src\cmake-test\build> cmake --build .
// omitted MSBuild output here //
Build succeeded.
0 Warning(s)
0 Error(s)
Time Elapsed 00:00:02.38
PS D:\src\cmake-test\build> .\Debug\main.exe
3.15.0
```
*Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.*
Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2].
```cmake
# To find and use catch
find_path(CATCH_INCLUDE_DIR catch.hpp)
include_directories(${CATCH_INCLUDE_DIR})
# To find and use azure-storage-cpp
find_path(WASTORAGE_INCLUDE_DIR was/blob.h)
find_library(WASTORAGE_LIBRARY wastorage)
include_directories(${WASTORAGE_INCLUDE_DIR})
link_libraries(${WASTORAGE_LIBRARY})
# Note that we recommend using the target-specific directives for a cleaner cmake:
# target_include_directories(main ${LIBRARY})
# target_link_libraries(main PRIVATE ${LIBRARY})
```
[1]: https://cmake.org/cmake/help/latest/command/find_path.html
[2]: https://cmake.org/cmake/help/latest/command/find_library.html
<a name="example-1-2-c"></a>
#### Option C: Other buildsystems
Libraries are installed into the `installed\` subfolder, partitioned by architecture (e.g. x86-windows):
* The header files are installed to `installed\x86-windows\include`
* Release `.lib` files are installed to `installed\x86-windows\lib` or `installed\x86-windows\lib\manual-link`
* Release `.dll` files are installed to `installed\x86-windows\bin`
* Debug `.lib` files are installed to `installed\x86-windows\debug\lib` or `installed\x86-windows\debug\lib\manual-link`
* Debug `.dll` files are installed to `installed\x86-windows\debug\bin`
See your build system specific documentation for how to use prebuilt binaries.
Generally, to run any produced executables you will also need to either copy the needed `dll` files to the same folder as your `exe` or *prepend* the correct `bin` directory to your path.
Example for setting the path for debug mode in powershell:
```
PS D:\src\vcpkg> $env:path = "D:\src\vcpkg\installed\x86-windows\debug\bin;" + $env:path
```
<a name="example-1-2-d"></a>
#### Option D: VS Project (Individual Project integration)
We also provide individual VS project integration through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects.
```
PS D:\src\vcpkg> .\vcpkg integrate project
Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg
With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"
```
*Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.*
<a name="example-2"></a>
## Example 2: Package a remote project (zlib)
### Bootstrap with `create`
First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors.
*Looking at zlib's website, the URL http://zlib.net/zlib128.zip looks appropriate.*
Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name.
*Since zlib is already packaged as zlib, we will use the name zlib2 for this example.*
Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `<packagename>-<version>.zip`.
*`zlib128.zip` is a fine name, so no change needed.*
All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports\<packagename>`.
```
PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib128.zip zlib128.zip
-- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake
```
### Create the CONTROL file
In addition to the generated `ports\<package>\portfile.cmake`, We also need a `ports\<package>\CONTROL` file. This file is a simply formatted set of fields describing the package's metadata.
*For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:*
```
Source: zlib2
Version: 1.2.8
Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library
```
### Tweak the generated portfile
The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build.
```
PS D:\src\vcpkg> .\vcpkg build zlib2
-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows
-- DOWNLOADS=D:/src/vcpkg/downloads
-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/zlib2_x86-windows
-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/zlib2
-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/zlib2
-- Using cached D:/src/vcpkg/downloads/zlib128.zip
-- Extracting source D:/src/vcpkg/downloads/zlib128.zip
-- Extracting done
-- Configuring x86-windows-rel
CMake Error at scripts/cmake/vcpkg_execute_required_process.cmake:13 (message):
Command failed: C:/Program Files
(x86)/CMake/bin/cmake.exe;D:/src/vcpkg/buildtrees/zlib2/src/zlib128;-G;Ninja;-DCMAKE_VERBOSE_MAKEFILE=ON;-DCMAKE_BUILD_TYPE=Release;-DCMAKE_TOOLCHAIN_FILE=D:/src/vcpkg/triplets/x86-windows.cmake;-DCMAKE_PREFIX_PATH=D:/src/vcpkg/installed/x86-windows;-
DCMAKE_INSTALL_PREFIX=D:/src/vcpkg/packages/zlib2_x86-windows
Working Directory: D:/src/vcpkg/buildtrees/zlib2/x86-windows-rel
See logs for more information:
D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-out.log
D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-err.log
Call Stack (most recent call first):
scripts/cmake/vcpkg_configure_cmake.cmake:15 (vcpkg_execute_required_process)
ports/zlib2/portfile.cmake:8 (vcpkg_configure_cmake)
scripts/ports.cmake:105 (include)
scripts/ports.cmake:184 (build)
```
At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed.
### Suggested example portfiles
In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake.
- Header only libraries
- rapidjson
- range-v3
- MSBuild-based
- mpg123
- glew
- Non-CMake, custom buildsystem
- openssl
- boost

3
docs/ROADMAP.md
View File

@ -1,3 +0,0 @@
# Roadmap

2
docs/_config.yml
View File

@ -1 +1 @@
theme: jekyll-theme-minimal
theme: jekyll-theme-cayman

45
docs/FAQ.md → docs/about/faq.md
View File

@ -1,46 +1,42 @@
# Frequently Asked Questions: Vcpkg
Vcpkg is a tool to acquire C++ open source library and rebuild them on Windows.
# Frequently Asked Questions
## Can I contribute a new library?
Yes! Start out by reading our [contribution guidelines](../CONTRIBUTING.md).
Yes! Start out by reading our [contribution guidelines](https://github.com/Microsoft/vcpkg/blob/master/CONTRIBUTING.md).
## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg?
In the preview release, we do not have a supported way to distribute individual binary packages. This avoids the issue of trying to use a specific pre-built package against differently built dependencies. As such, we have also not specified a stable format for the built library packages.
We instead recommend copying the entire system as a whole (which ensures that every package and its dependencies stay in sync with each other).
Yes! See [the `export` command](../users/integration.md#export).
## How do I update libraries?
The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command.
## How do I get more libraries?
The list of libraries is enumerated from the [`ports\`](../ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company (see [Example #2](EXAMPLES.md#example-2)).
The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see [Example #2](../examples/packaging-zlib.md).
We recommend cloning directly from [GitHub](https://github.com/microsoft/vcpkg) and using `git pull` to update the list of portfiles. Once you've updated your portfiles, `vcpkg update` will indicate any installed libraries that are now out of date.
## Can I build a private library with this tool?
Yes. Follow [Example #2](EXAMPLES.md#example-2) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code.
Yes. Follow [our Packaging zlib Example](../examples/packaging-zlib.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code.
## Can I use a prebuilt private library with this tool?
Yes. The `portfile.cmake` for a library is fundamentally a script that places the headers and binaries into the correct arrangement in the `${CURRENT_PACKAGES_DIR}`, so to pull in prebuilt binaries you can write a portfile which directly downloads and arranges the files.
To see an example of this, look at [`ports\opengl\portfile.cmake`](../ports/opengl/portfile.cmake) package which simply copies files out of the Windows SDK.
To see an example of this, look at [`ports\opengl\portfile.cmake`](https://github.com/microsoft/vcpkg/blob/master/ports/opengl/portfile.cmake) which simply copies files out of the Windows SDK.
## Which platforms I can target with Vcpkg?
We currently target Windows Desktop (x86 and x64) as well as the Universal Windows Platform (x86, x64, and ARM). See `vcpkg help triplet` for the current list.
## Does `vcpkg.exe` run on Linux/OSX?
No, for this preview we are focusing on Windows as a host platform. If you'd be interested in having Vcpkg run on Linux or OSX, please let us know in [this issue](https://github.com/microsoft/vcpkg/issues/57).
## Does Vcpkg run on Linux/OSX?
No, for this preview we are focusing on Windows as a host platform. If you'd be interested in having Vcpkg run on Linux or OSX, please let us know in [this issue](https://github.com/microsoft/vcpkg/issues/57)!
## How do I use different versions of a library on one machine?
Within a single instance of Vcpkg (e.g. one set of `installed\`, `packages\`, `ports\` and so forth), you can only have one version of a library installed (otherwise, the headers would conflict with each other!). This is because a package in Vcpkg corresponds to the `X-dev` or `X-devel` packages in other system package managers.
Within a single instance of Vcpkg (e.g. one set of `installed\`, `packages\`, `ports\` and so forth), you can only have one version of a library installed (otherwise, the headers would conflict with each other!). For those with experience with system-wide package managers, packages in Vcpkg correspond to the `X-dev` or `X-devel` packages.
To use different versions of a library (for different projects), we recommend making separate instances of Vcpkg and using the [per-project integration mechanisms](EXAMPLES.md#example-1-2-d). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard VCS techniques. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\package\`.
To use different versions of a library for different projects, we recommend making separate instances of Vcpkg and using the [per-project integration mechanisms](../users/integration.md). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard `git` commands. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\<package>\`.
If your application is very sensitive to the versions of libraries, we recommend checking in the specific set of portfiles you need into your source control along with your project sources and using the `--vcpkg-root` option to redirect the working directory of `vcpkg.exe`.
If your application is very sensitive to the versions of libraries, we recommend checking in the specific set of portfiles you need into your source control along with your project sources and using the `--vcpkg-root` option to redirect the working directory of `vcpkg.exe`.
## How does Vcpkg protect my Privacy?
See the [Privacy document](PRIVACY.md) for all information regarding privacy.
See the [Privacy document](privacy.md) for all information regarding privacy.
## Can I use my own CMake toolchain file with Vcpkg's toolchain file?
Yes. If you already have a CMake toolchain file, you will need to include our toolchain file at the end of yours. This should be as simple as an `include(<vcpkg_root>\scripts\buildsystems\vcpkg.cmake)` directive. Alternatively, you could copy the contents of our `scripts\buildsystems\vcpkg.cmake` into the end of your existing toolchain file.
@ -51,24 +47,19 @@ Yes. In the current preview, there is not yet a standardized global way to chang
By saving the changes to the portfile (and checking them in), you'll get the same results even if you're rebuilding from scratch in the future and forgot what exact settings you used.
## How is CMake used internally by Vcpkg?
Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows (does not require system-wide installation) and reasonably legible for unfamiliar users.
Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows, does not require system-wide installation, and legible for unfamiliar users.
## Will Vcpkg support downloading compiled binaries from a public or private server?
We do plan to eventually support downloading precompiled binaries, similar to other system package managers.
We would like to eventually support downloading precompiled binaries, similar to other system package managers.
In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host.
In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See [the `export` command](../users/integration.md#export).
## What Visual C++ toolsets are supported?
We plan to only support Visual Studio 2015 and above.
We support Visual Studio 2015 Update 3 and above.
## Why does Visual Studio not use my libraries with user-wide integration enabled?
Enabling user-wide integration (`vcpkg integrate install`) changes the default for some project properties. In particular, "C/C++/General/Additional Include Directories" and "Linker/General/Additional Library Directories" are normally blank *without* user-wide integration. *With* integration, a blank value means that the augmented default supplied by vcpkg is overridden, and headers/libraries will not be found. To reinstate the default, set the properties to inherit from parent.
## Can I acquire my package's sources by Git url+tag?
Yes, however we prefer compressed archives of the specific release/commit since the internal downloads and build trees are meant to be read only. Github provides archives for every commit, tag, and branch, so it's always possible to perform this substitution for repositories hosted there.
See [`ports\cpprestsdk\portfile.cmake`](../ports/cpprestsdk/portfile.cmake) for an example of using git directly.
## Why not NuGet?
NuGet is a package manager for .NET libraries with a strong dependency on MSBuild. It does not meet the specific needs of Native C++ customers in at least three ways.
@ -83,11 +74,11 @@ Conan.io is a publicly-federated, project-centric, cross-platform, C++ package m
- **Public federation vs private federation**. Conan relies on individuals publishing independent copies of each package. We believe this approach encourages a large number of packages that are all broken in different ways. We believe it is a waste of user's time to pick through the list of 20+ public packages for Boost 1.56 to determine the handful that will work for their particular situation. In contrast, we believe there should be a single, collaboratively maintained version which works for the vast majority of cases and allow users to hack freely on their private versions. We believe this will result in a set of high quality packages that are heavily tested with each other and form a fantastic base for any private modifications you need.
- **Per-dll vs Per-application**. When dependencies are independently versioned on a library level, it encourages every build environment to be a completely unique, unable to take advantage of or contribute to a solid, well tested ecosystem. In contrast, by versioning all libraries together as a platform (similar to a system package manager), we hope to congregate testing and effort on very common sets of library versions to maximize the quality and stability of the ecosystem. This also completely designs out the ability for a library to ask for versions that conflict with the application's choices (I want openssl Z and boost X but X only works with openssl Y).
- **Per-dll vs Per-application**. When dependencies are independently versioned on a library level, it encourages every build environment to be a completely unique, unable to take advantage of or contribute to a solid, well tested ecosystem. In contrast, by versioning all libraries together as a platform (similar to a system package manager), we hope to congregate testing and effort on very common sets of library versions to maximize the quality and stability of the ecosystem. This also completely designs out the ability for a library to ask for versions that conflict with the application's choices (I want openssl Z and boost X but X only claims to work with openssl Y).
- **Cross-platform vs single-platform**. While being hosted on many platforms is an excellent north star, we believe the level of system integration and stability provided by apt-get, yum, and homebrew is well worth needing to exchange `apt-get install libboost-all-dev` with `brew install boost` in automated scripts. We chose to make our system as easy as possible to integrate into a world with these very successful system managers -- one more line for `vcpkg install boost` -- instead of attempting to replace them where they are already so successful and well-loved.
- **C++/CMake vs python**. While Python is an excellent language loved by many, we believe that transparency and familiarity are the most important factors when choosing a tool as important to your workflow as a package manager. Consequently, we chose to make the implementation languages be as universally accepted as possible: C++ should be used in a C++ package manager for C++ programmers. You should not be required to learn another language just to understand your package manager.
## Why not Chocolatey?
Chocolatey is an excellent system for managing software. However, it is not currently designed to acquire redistributable developer assets and help you with debugging. Vcpkg, in comparison, is designed to get you the libraries you need to build your application and help you deliver through any platform you'd like (including Chocolatey!).
Chocolatey is an excellent system for managing applications. However, it is not currently designed to acquire redistributable developer assets and help you with debugging. Vcpkg, in comparison, is designed to get you the libraries you need to build your application and help you deliver through any platform you'd like (including Chocolatey!).

66
docs/PRIVACY.md → docs/about/privacy.md
View File

@ -1,48 +1,44 @@
# Privacy document for vcpkg
# Privacy and Vcpkg
## Do you collect telemetry data? What is it used for?
## Do you collect telemetry data? What is it used for?
We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY collect information from invocations of the tool itself; we do NOT add any tracking information into the produced libraries. We use this information to understand usage issues, such as failing packages, and to guide tool improvements.
We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY collect information from invocations of the tool itself; we do NOT add any tracking information into the produced libraries.
We use this information to understand usage issues and to guide tool improvements.
## What telemetry is collected?
## What telemetry is collected?
We collect the command line used, the time of invocation, and how long the command took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event. For this preview, we do not offer a mechanism to disable this data collection since it is critical for improving the product. In the full release, you will be able to opt-out with a simple configuration. For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-us/privacy.
Here is an example of an event for the command line `vcpkg install zlib`:
```
```json
[{
"ver": 1,
"name": "Microsoft.ApplicationInsights.Event",
"time": "2016-09-01T00:19:10.949Z",
"sampleRate": 100.000000,
"seq": "0:0",
"iKey": "aaaaaaaa-4393-4dd9-ab8e-97e8fe6d7603",
"flags": 0.000000,
"tags": {
"ai.device.os": "Windows",
"ai.device.osVersion": "10.0.14912",
"ai.session.id": "aaaaaaaa-7c69-4b83-7d82-8a4198d7e88d",
"ai.user.id": "aaaaaaaa-c9ab-4bf5-0847-a3455f539754",
"ai.user.accountAcquisitionDate": "2016-08-20T00:38:09.860Z"
},
"data": {
"baseType": "EventData",
"baseData": {
"ver": 2,
"name": "commandline_test7",
"properties": { "version":"0.0.30-9b4e44a693459c0a618f370681f837de6dd95a30","cmdline":"install zlib","command":"install","installplan":"zlib:x86-windows" },
"measurements": { "elapsed_us":68064.355736 }
}
}
}]
"ver": 1,
"name": "Microsoft.ApplicationInsights.Event",
"time": "2016-09-01T00:19:10.949Z",
"sampleRate": 100.000000,
"seq": "0:0",
"iKey": "aaaaaaaa-4393-4dd9-ab8e-97e8fe6d7603",
"flags": 0.000000,
"tags": {
"ai.device.os": "Windows",
"ai.device.osVersion": "10.0.14912",
"ai.session.id": "aaaaaaaa-7c69-4b83-7d82-8a4198d7e88d",
"ai.user.id": "aaaaaaaa-c9ab-4bf5-0847-a3455f539754",
"ai.user.accountAcquisitionDate": "2016-08-20T00:38:09.860Z"
},
"data": {
"baseType": "EventData",
"baseData": {
"ver": 2,
"name": "commandline_test7",
"properties": { "version":"0.0.30-9b4e44a693459c0a618f370681f837de6dd95a30","cmdline":"install zlib","command":"install","installplan":"zlib:x86-windows" },
"measurements": { "elapsed_us":68064.355736 }
}
}
}]
```
In the source code (included in `toolsrc\`), you can search for calls to the functions `TrackProperty()` and `TrackMetric()` to see every specific data point we collect.
## Is the data stored on my system?
## Is the data stored on my system?
We store each event document in your temporary files directory. These will be cleaned out whenever you clear your temporary files.
We store each event document in your temporary files directory. These will be cleaned out whenever you clear your temporary files.

80
docs/examples/packaging-zlib.md Normal file
View File

@ -0,0 +1,80 @@
## Example 2: Packaging zlib
### Bootstrap with `create`
First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors.
*Looking at zlib's website, the URL http://zlib.net/zlib128.zip looks appropriate.*
Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name.
*Since zlib is already packaged as zlib, we will use the name zlib2 for this example.*
Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `<packagename>-<version>.zip`.
*`zlib128.zip` is a fine name, so no change needed.*
All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports\<packagename>`.
```no-highlight
PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib128.zip zlib128.zip
-- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake
```
### Create the CONTROL file
In addition to the generated `ports\<package>\portfile.cmake`, we also need a `ports\<package>\CONTROL` file. This file is a simply formatted set of fields describing the package's metadata.
*For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:*
```no-highlight
Source: zlib2
Version: 1.2.8
Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library
```
### Tweak the generated portfile
The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build.
```no-highlight
PS D:\src\vcpkg> .\vcpkg build zlib2
-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows
-- DOWNLOADS=D:/src/vcpkg/downloads
-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/zlib2_x86-windows
-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/zlib2
-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/zlib2
-- Using cached D:/src/vcpkg/downloads/zlib128.zip
-- Extracting source D:/src/vcpkg/downloads/zlib128.zip
-- Extracting done
-- Configuring x86-windows-rel
CMake Error at scripts/cmake/vcpkg_execute_required_process.cmake:13 (message):
Command failed: C:/Program Files
(x86)/CMake/bin/cmake.exe;D:/src/vcpkg/buildtrees/zlib2/src/zlib128;-G;Ninja;-DCMAKE_VERBOSE_MAKEFILE=ON;-DCMAKE_BUILD_TYPE=Release;-DCMAKE_TOOLCHAIN_FILE=D:/src/vcpkg/triplets/x86-windows.cmake;-DCMAKE_PREFIX_PATH=D:/src/vcpkg/installed/x86-windows;-
DCMAKE_INSTALL_PREFIX=D:/src/vcpkg/packages/zlib2_x86-windows
Working Directory: D:/src/vcpkg/buildtrees/zlib2/x86-windows-rel
See logs for more information:
D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-out.log
D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-err.log
Call Stack (most recent call first):
scripts/cmake/vcpkg_configure_cmake.cmake:15 (vcpkg_execute_required_process)
ports/zlib2/portfile.cmake:8 (vcpkg_configure_cmake)
scripts/ports.cmake:105 (include)
scripts/ports.cmake:184 (build)
```
At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed.
### Suggested example portfiles
In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake.
- Header only libraries
- rapidjson
- range-v3
- MSBuild-based
- mpg123
- glew
- Non-CMake, custom buildsystem
- openssl
- boost

24
docs/example-3-patch-libpng.md → docs/examples/patching-libpng.md
View File

@ -1,9 +1,9 @@
## Example 3: Patching libpng to work for uwp-x86
## Example 3: Patching libpng to work for x86-uwp
### Initial error logs
First, try building:
```
```no-highlight
PS D:\src\vcpkg> vcpkg install libpng:x86-uwp
-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp
-- DOWNLOADS=D:/src/vcpkg/downloads
@ -39,7 +39,7 @@ Error: build command failed
Next, looking at the above logs (build-...-out.log and build-...-err.log).
```
```no-highlight
// build-x86-uwp-rel-out.log
...
"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
@ -76,7 +76,7 @@ Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop
```
A recursive search for `PNG_ABORT` reveals the definition:
```
```no-highlight
PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> findstr /snipl "PNG_ABORT" *
CHANGES:701: Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros
libpng-manual.txt:432:errors will result in a call to PNG_ABORT() which defaults to abort().
@ -114,8 +114,8 @@ This already gives us some great clues, but the full definition tells the comple
### Patching the code to improve compatibility
I recommend using git to create the patch file, since you'll already have it installed.
```
We recommend using git to create the patch file, since you'll already have it installed.
```no-highlight
PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git init .
Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/libpng-1.6.24/.git/
@ -139,7 +139,7 @@ Now we can modify `pngpriv.h` to use `abort()` everywhere.
```
The output of `git diff` is already in patch format, so we just need to save the patch into the `ports/libpng` directory.
```
```no-highlight
PS buildtrees\libpng\src\libpng-1.6.24> git diff | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch
```
@ -162,14 +162,14 @@ vcpkg_configure_cmake(
To be completely sure this works from scratch, we need to remove the package and rebuild it:
```
```no-highlight
PS D:\src\vcpkg> vcpkg remove libpng:x86-uwp
Package libpng:x86-uwp was successfully removed
```
and delete the building directory: D:\src\vcpkg\buildtrees\libpng
and complete delete the building directory: D:\src\vcpkg\buildtrees\libpng
Now we try a fresh, from scratch install.
```
```no-highlight
PS D:\src\vcpkg> vcpkg install libpng:x86-uwp
-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp
-- DOWNLOADS=D:/src/vcpkg/downloads
@ -194,9 +194,9 @@ PS D:\src\vcpkg> vcpkg install libpng:x86-uwp
Package libpng:x86-uwp is installed
```
Finally, to fully commit and publish the changes, we need to bump the internal release number and add the patch file to source control.
Finally, to fully commit and publish the changes, we need to bump the internal release number and add the patch file to source control, then make a Pull Request!
```
```no-highlight
# ports\libpng\CONTROL
Source: libpng
Version: 1.6.24-1

177
docs/examples/using-sqlite.md Normal file
View File

@ -0,0 +1,177 @@
# Example: Using Sqlite
- [Step 1: Install](#install)
- [Step 2: Use](#use)
- [VS/MSBuild Project (User-wide integration)](#msbuild)
- [CMake (Toolchain file)](#cmake)
- [Other integration options](../users/integration.md)
---
<a name="install"></a>
## Step 1: Install
First, we need to know what name [Sqlite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output:
```no-highlight
PS D:\src\vcpkg> .\vcpkg search sqlite
libodb-sqlite 2.4.0 Sqlite support for the ODB ORM library
sqlite3 3.15.0 SQLite is a software library that implements a se...
If your library is not listed, please open an issue at:
https://github.com/Microsoft/vcpkg/issues
```
Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages.
Installing is then as simple as using the `install` command.
```no-highlight
PS D:\src\vcpkg> .\vcpkg install sqlite3
-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows
-- DOWNLOADS=D:/src/vcpkg/downloads
-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/sqlite3_x86-windows
-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/sqlite3
-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/sqlite3/.
-- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip...
-- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip... OK
-- Testing integrity of downloaded file...
-- Testing integrity of downloaded file... OK
-- Extracting source D:/src/vcpkg/downloads/sqlite-amalgamation-3150000.zip
-- Extracting done
-- Configuring x86-windows-rel
-- Configuring x86-windows-rel done
-- Configuring x86-windows-dbg
-- Configuring x86-windows-dbg done
-- Build x86-windows-rel
-- Build x86-windows-rel done
-- Build x86-windows-dbg
-- Build x86-windows-dbg done
-- Package x86-windows-rel
-- Package x86-windows-rel done
-- Package x86-windows-dbg
-- Package x86-windows-dbg done
-- Performing post-build validation
-- Performing post-build validation done
Package sqlite3:x86-windows is installed
```
We can check that sqlite3 was successfully installed for x86 windows desktop by running the `list` command.
```no-highlight
PS D:\src\vcpkg> .\vcpkg list
sqlite3:x86-windows 3.15.0 SQLite is a software library that implements a se...
```
To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:<target>`.
```no-highlight
PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows
```
See `.\vcpkg help triplet` for all supported targets.
---
<a name="use"></a>
## Step 2: Use
<a name="msbuild"></a>
#### VS/MSBuild Project (User-wide integration)
The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwords is no longer required and the integration is configured on a per-user basis.
```no-highlight
PS D:\src\vcpkg> .\vcpkg integrate install
Applied user-wide integration for this vcpkg root.
All C++ projects can now #include any installed libraries.
Linking will be handled automatically.
Installing new libraries will make them instantly available.
```
*Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.*
You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 and the library will be automatically available. For Sqlite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html).
To remove the integration for your user, you can use `.\vcpkg integrate remove`.
<a name="cmake"></a>
#### CMake (Toolchain File)
The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as `-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`.
If you are using CMake through Open Folder with Visual Studio 2017 you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations:
```json
{
"configurations": [{
"name": "x86-Debug",
"generator": "Visual Studio 15 2017",
"configurationType" : "Debug",
"buildRoot": "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
"cmakeCommandArgs": "",
"buildCommandArgs": "-m -v:minimal",
"variables": [{
"name": "CMAKE_TOOLCHAIN_FILE",
"value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
}]
}]
}
```
Now let's make a simple CMake project with a main file.
```cmake
# CMakeLists.txt
cmake_minimum_required(VERSION 3.0)
project(test)
find_package(Sqlite3 REQUIRED)
add_executable(main main.cpp)
target_link_libraries(main sqlite3)
```
```cpp
// main.cpp
#include <sqlite3.h>
#include <stdio.h>
int main()
{
printf("%s\n", sqlite3_libversion());
return 0;
}
```
Then, we build our project in the normal CMake way:
```no-highlight
PS D:\src\cmake-test> mkdir build
PS D:\src\cmake-test> cd build
PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake"
// omitted CMake output here //
-- Build files have been written to: D:/src/cmake-test/build
PS D:\src\cmake-test\build> cmake --build .
// omitted MSBuild output here //
Build succeeded.
0 Warning(s)
0 Error(s)
Time Elapsed 00:00:02.38
PS D:\src\cmake-test\build> .\Debug\main.exe
3.15.0
```
*Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.*
##### Handling libraries without native cmake support
Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2].
```cmake
# To find and use catch
find_path(CATCH_INCLUDE_DIR catch.hpp)
include_directories(${CATCH_INCLUDE_DIR})
# To find and use azure-storage-cpp
find_path(WASTORAGE_INCLUDE_DIR was/blob.h)
find_library(WASTORAGE_LIBRARY wastorage)
include_directories(${WASTORAGE_INCLUDE_DIR})
link_libraries(${WASTORAGE_LIBRARY})
# Note that we recommend using the target-specific directives for a cleaner cmake:
# target_include_directories(main ${LIBRARY})
# target_link_libraries(main PRIVATE ${LIBRARY})
```
[1]: https://cmake.org/cmake/help/latest/command/find_path.html
[2]: https://cmake.org/cmake/help/latest/command/find_library.html

38
docs/index.md Normal file
View File

@ -0,0 +1,38 @@
### Quick Start
Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are currently in a preview state; your involvement is vital to its success.
- [How to use Sqlite in your application](examples/using-sqlite.md)
### Examples
- [Example 1: Using Sqlite](examples/using-sqlite.md)
- [Example 2: Packaging zlib](examples/packaging-zlib.md)
- [Example 3: Patching libpng for x86-uwp](examples/patching-libpng.md)
### User Help
- [Integration with build systems](users/integration.md)
### Maintainer help
- [Control files](maintainers/control-files.md)
- [Portfile functions](maintainers/portfile-functions.md)
### Specifications
- [Export](specifications/export-command.md)
### Blog posts
- [Vcpkg: introducing the export command](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/)
- [Binary Compatibility and Pain-free Upgrade Why Moving to Visual Studio 2017 is almost "too easy"](https://blogs.msdn.microsoft.com/vcblog/2017/03/07/binary-compatibility-and-pain-free-upgrade-why-moving-to-visual-studio-2017-is-almost-too-easy/)
- [Vcpkg recent enhancements](https://blogs.msdn.microsoft.com/vcblog/2017/02/14/vcpkg-recent-enhancements/)
- [Vcpkg 3 Months Anniversary, Survey](https://blogs.msdn.microsoft.com/vcblog/2017/01/11/vcpkg-3-months-anniversary-survey/)
- [Vcpkg updates: Static linking is now available](https://blogs.msdn.microsoft.com/vcblog/2016/11/01/vcpkg-updates-static-linking-is-now-available/)
- [Vcpkg: a tool to acquire and build C++ open source libraries on Windows](https://blogs.msdn.microsoft.com/vcblog/2016/09/19/vcpkg-a-tool-to-acquire-and-build-c-open-source-libraries-on-windows/)
### Other
- [FAQ](about/faq.md)
- [Privacy](about/privacy.md)

51
docs/maintainers/control-files.md Normal file
View File

@ -0,0 +1,51 @@
## `CONTROL` files
Each port has some static metadata in the form of a `CONTROL` file. This file uses the same rough syntax as and a subset of the fields from [the Debian `control` format][debian].
Fields are case-sensitive.
[debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html
### Recognized fields
#### Source
The name of the port.
#### Version
The port version.
This field should be an alphanumeric string which may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bitstrings and are only evaluated for equality.
By convention, if a portfile is modified without incrementing the "upstream" version, a `-#` is appended to create a unique version string.
Example:
```no-highlight
Version: 1.0.5-2
```
#### Description
A description of the library
The first sentence of the description should concisely describe the purpose and contents of the library. Then, a larger description including the library's "proper name" should follow.
#### Maintainer
Reserved for future use.
#### Build-Depends
The list of dependencies required to build and use this library.
Example:
```no-highlight
Build-Depends: zlib, libpng, libjpeg-turbo, tiff
```
Unlike dpkg, Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified.
*For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies*
Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside brackets is substring-compared against the triplet name. __This will change in a future version to not depend on the triplet name.__
Example:
```no-highlight
Build-Depends: zlib [windows], openssl [windows], boost [windows], websocketpp [windows]
```

15
docs/maintainers/portfile-functions.md Normal file
View File

@ -0,0 +1,15 @@
<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
# Portfile helper functions
- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
- [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
- [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
- [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
- [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
- [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)
- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
- [vcpkg\_from\_github](vcpkg_from_github.md)
- [vcpkg\_install\_cmake](vcpkg_install_cmake.md)

47
docs/maintainers/vcpkg_acquire_msys.md Normal file
View File

@ -0,0 +1,47 @@
# vcpkg_acquire_msys
Download and prepare an MSYS2 instance.
## Usage
```cmake
vcpkg_acquire_msys(<MSYS_ROOT_VAR>)
```
## Parameters
### MSYS_ROOT_VAR
An out-variable that will be set to the path to MSYS2.
## Notes
A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`:
```cmake
vcpkg_acquire_msys(MSYS_ROOT)
set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
vcpkg_execute_required_process(
COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh"
WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
LOGNAME build-${TARGET_TRIPLET}-rel
)
```
To ensure a package is available:
```cmake
vcpkg_acquire_msys(MSYS_ROOT)
set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
message(STATUS "Installing MSYS Packages")
vcpkg_execute_required_process(
COMMAND
${BASH} --noprofile --norc -c
"pacman -Sy --noconfirm --needed make"
WORKING_DIRECTORY ${MSYS_ROOT}
LOGNAME pacman-${TARGET_TRIPLET})
```
## Examples
* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
* [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake)
## Source
[scripts/cmake/vcpkg_acquire_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)

35
docs/maintainers/vcpkg_apply_patches.md Normal file
View File

@ -0,0 +1,35 @@
# vcpkg_apply_patches
Apply a set of patches to a source tree.
## Usage
```cmake
vcpkg_apply_patches(
SOURCE_PATH <${SOURCE_PATH}>
[QUIET]
PATCHES <patch1.patch>...
)
```
## Parameters
### SOURCE_PATH
The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PATCHES
A list of patches that are applied to the source tree.
Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
### QUIET
Disables the warning message upon failure.
This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
## Examples
* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
* [libpng](https://github.com/Microsoft/vcpkg/blob/master/ports/libpng/portfile.cmake)
## Source
[scripts/cmake/vcpkg_apply_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)

59
docs/maintainers/vcpkg_build_msbuild.md Normal file
View File

@ -0,0 +1,59 @@
# vcpkg_build_msbuild
Build an msbuild-based project.
## Usage
```cmake
vcpkg_build_msbuild(
PROJECT_PATH <${SOURCE_PATH}/port.sln>
[RELEASE_CONFIGURATION <Release>]
[DEBUG_CONFIGURATION <Debug>]
[TARGET <Build>]
[TARGET_PLATFORM_VERSION <10.0.15063.0>]
[PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
[PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
[OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
[OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
[OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
)
```
## Parameters
### PROJECT_PATH
The path to the solution (`.sln`) or project (`.vcxproj`) file.
### RELEASE_CONFIGURATION
The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
### DEBUG_CONFIGURATION
The configuration (``/p:Configuration`` msbuild parameter)
used for Debug builds.
### TARGET_PLATFORM_VERSION
The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
### TARGET
The MSBuild target to build. (``/t:<TARGET>``)
### PLATFORM
The platform (``/p:Platform`` msbuild parameter) used for the build.
### PLATFORM_TOOLSET
The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
### OPTIONS
Additional options passed to msbuild for all builds.
### OPTIONS_RELEASE
Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
## Examples
* [libuv](https://github.com/Microsoft/vcpkg/blob/master/ports/libuv/portfile.cmake)
* [zeromq](https://github.com/Microsoft/vcpkg/blob/master/ports/zeromq/portfile.cmake)
## Source
[scripts/cmake/vcpkg_build_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)

49
docs/maintainers/vcpkg_configure_cmake.md Normal file
View File

@ -0,0 +1,49 @@
# vcpkg_configure_cmake
Configure CMake for Debug and Release builds of a project.
## Usage
```cmake
vcpkg_configure_cmake(
SOURCE_PATH <${SOURCE_PATH}>
[PREFER_NINJA]
[GENERATOR <"NMake Makefiles">]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
)
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PREFER_NINJA
Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja.
### GENERATOR
Specifies the precise generator to use.
This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. If used for this purpose, it should be set to "NMake Makefiles".
### OPTIONS
Additional options passed to CMake during the configuration.
### OPTIONS_RELEASE
Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
## Notes
This command supplies many common arguments to CMake. To see the full list, examine the source.
## Examples
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
## Source
[scripts/cmake/vcpkg_configure_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake)

19
docs/maintainers/vcpkg_copy_pdbs.md Normal file
View File

@ -0,0 +1,19 @@
# vcpkg_copy_pdbs
Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
## Usage
```cmake
vcpkg_copy_pdbs()
```
## Notes
This command should always be called by portfiles after they have finished rearranging the binary output.
## Examples
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
## Source
[scripts/cmake/vcpkg_copy_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)

21
docs/maintainers/vcpkg_copy_tool_dependencies.md Normal file
View File

@ -0,0 +1,21 @@
# vcpkg_copy_tool_dependencies
Copy all DLL dependencies of built tools into the tool folder.
## Usage
```cmake
vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
```
## Parameters
The path to the directory containing the tools.
## Notes
This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools.
## Examples
* [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake)
* [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
## Source
[scripts/cmake/vcpkg_copy_tool_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)

39
docs/maintainers/vcpkg_download_distfile.md Normal file
View File

@ -0,0 +1,39 @@
# vcpkg_download_distfile
Download and cache a file needed for this port.
## Usage
```cmake
vcpkg_download_distfile(
<OUT_VARIABLE>
URLS <http://mainUrl> <http://mirror1>...
FILENAME <output.zip>
SHA512 <5981de...>
)
```
## Parameters
### OUT_VARIABLE
This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.
### URLS
A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.
### FILENAME
The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
### SHA512
The expected hash for the file.
If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
## Notes
The command [`vcpkg_from_github`](vcpkg_from_github.md) should be used instead of this for downloading the main archive for GitHub projects.
## Examples
* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
## Source
[scripts/cmake/vcpkg_download_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)

33
docs/maintainers/vcpkg_execute_required_process.md Normal file
View File

@ -0,0 +1,33 @@
# vcpkg_execute_required_process
Execute a process with logging and fail the build if the command fails.
## Usage
```cmake
vcpkg_execute_required_process(
COMMAND <${PERL}> [<arguments>...]
WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
LOGNAME <build-${TARGET_TRIPLET}-dbg>
)
```
## Parameters
### COMMAND
The command to be executed, along with its arguments.
### WORKING_DIRECTORY
The directory to execute the command in.
### LOGNAME
The prefix to use for the log files.
This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
## Examples
* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
## Source
[scripts/cmake/vcpkg_execute_required_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)

32
docs/maintainers/vcpkg_extract_source_archive.md Normal file
View File

@ -0,0 +1,32 @@
# vcpkg_extract_source_archive
Extract an archive into the source directory.
## Usage
```cmake
vcpkg_extract_source_archive(
<${ARCHIVE}> [<${TARGET_DIRECTORY}>]
)
```
## Parameters
### ARCHIVE
The full path to the archive to be extracted.
This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
### TARGET_DIRECTORY
If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}\src\`.
This can be used to mimic git submodules, by extracting into a subdirectory of another archive.
## Notes
This command will also create a tracking file named <FILENAME>.extracted in the TARGET_DIRECTORY. This file, when present, will suppress the extraction of the archive.
## Examples
* [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
* [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
* [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
## Source
[scripts/cmake/vcpkg_extract_source_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)

37
docs/maintainers/vcpkg_find_acquire_program.md Normal file
View File

@ -0,0 +1,37 @@
# vcpkg_find_acquire_program
Download or find a well-known tool.
## Usage
```cmake
vcpkg_find_acquire_program(<VAR>)
```
## Parameters
### VAR
This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable.
## Notes
The current list of programs includes:
- 7Z
- BISON
- FLEX
- PERL
- PYTHON2
- PYTHON3
- JOM
- MESON
- NASM
- NINJA
- YASM
Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
## Examples
* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
## Source
[scripts/cmake/vcpkg_find_acquire_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)

52
docs/maintainers/vcpkg_from_github.md Normal file
View File

@ -0,0 +1,52 @@
# vcpkg_from_github
Download and extract a project from GitHub. Enables support for `install --head`.
## Usage:
```cmake
vcpkg_from_github(
OUT_SOURCE_PATH <SOURCE_PATH>
REPO <Microsoft/cpprestsdk>
[REF <v2.0.0>]
[SHA512 <45d0d7f8cc350...>]
[HEAD_REF <master>]
)
```
## Parameters:
### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.
This should be set to `SOURCE_PATH` by convention.
### REPO
The organization or user and repository on GitHub.
### REF
A stable git commit-ish (ideally a tag) that will not change contents.
If `REF` is specified, `SHA512` must also be specified.
### SHA512
The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz).
This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
### HEAD_REF
The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
## Notes:
At least one of `REF` and `HEAD_REF` must be specified.
This exports the `VCPKG_HEAD_VERSION` variable during head builds.
## Examples:
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake)
* [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
## Source
[scripts/cmake/vcpkg_from_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)

25
docs/maintainers/vcpkg_install_cmake.md Normal file
View File

@ -0,0 +1,25 @@
# vcpkg_install_cmake
Build and install a cmake project.
## Usage:
```cmake
vcpkg_install_cmake([MSVC_64_TOOLSET])
```
## Parameters:
### MSVC_64_TOOLSET
This adds the `/p:PreferredToolArchitecture=x64` switch if the underlying buildsystem is MSBuild. Some large projects can run out of memory when linking if they use the 32-bit hosted tools.
## Notes:
This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
## Examples:
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
## Source
[scripts/cmake/vcpkg_install_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)

27
docs/regenerate.ps1 Normal file
View File

@ -0,0 +1,27 @@
Param([string]$VcpkgRoot = "")
$ErrorActionPreference = "Stop"
if (!$VcpkgRoot) {
$VcpkgRoot = ".."
}
$VcpkgRoot = Resolve-Path $VcpkgRoot
if (!(Test-Path "$VcpkgRoot\.vcpkg-root")) {
throw "Invalid vcpkg instance, did you forget -VcpkgRoot?"
}
Set-Content -Path "$PSScriptRoot\maintainers\portfile-functions.md" -Value "<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->`n`n# Portfile helper functions"
ls "$VcpkgRoot\scripts\cmake\*.cmake" | % {
$contents = Get-Content $_ `
| ? { $_ -match "^## |^##`$" } `
| % { $_ -replace "^## ?","" }
if ($contents) {
Set-Content -Path "$PSScriptRoot\maintainers\$($_.BaseName).md" -Value "$($contents -join "`n")`n`n## Source`n[scripts/cmake/$($_.Name)](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/$($_.Name))"
"- [$($_.BaseName -replace "_","\_")]($($_.BaseName).md)" `
| Out-File -Enc Ascii -Append -FilePath "$PSScriptRoot\maintainers\portfile-functions.md"
}
}

172
docs/specifications/export-command.md Normal file
View File

@ -0,0 +1,172 @@
# Binary Export (Apr 28, 2017)
## 1. Motivation
### A. Build once and share
Customers want to be able to build their set of required libraries once, and then distribute the resulting binaries to all members of the "group". This has been brought up in
- Enterprise environments, in which there are dedicated teams to acquire libraries and then share them with other team to consume them
- Academic environments, in which the professor/teacher wants to build the required libraries and then provide them to all the students
- CI Systems, in which developers want to quickly distribute their exact set of dependencies to a cloud-based farm of build machines
Building once and sharing ensures that everyone gets exactly the same binaries, isolates the building effort to a small number of people and minimizes friction to obtain them. Therefore, there is value in enabling users to easily export ready-to-share binaries from `vcpkg`.
### B. Very large libraries
Libraries like [Qt][] can take a very long time to build (5+ hours). Therefore, having the ability to build them and then distribute the binaries can save a lot of time.
### C. Flexibility and uses without `vcpkg`
`vcpkg` currently handles cases where you have a `vcpkg` enlistment on your machine and use it for acquiring libraries and integrating into Visual Studio, CMake etc. However, users need the ability to build the libraries and then use them outside of and independently of `vcpkg`. For example:
- Use `vcpkg` for the build, then host the binaries in a website (similarly to nuget)
- Use `vcpkg` for the build, then put the binaries in an installer and distribute the installer
Consuming the libraries outside of `vcpkg` forfeits the ability to install new libraries or update existing ones, but this can be:
- not a concern, like in a short term project or assignment
- explicitly desired, like in the development of a game where libraries and their versions are sealed for a particular release, never to be modified
### D. Easy consumption in Visual Studio for NuGet users
Customers have requested C++ NuGet packages to integrate into their project. This has come from:
- Customers than have used NuGet (e.g. in C#) and find it very convenient
- Customers who are working on a C# project that has a few dependencies on C++ and just want those dependencies to be satisfied in the most automatic way possible
Providing a way to create NuGet packages provides great value to those customers. In an enterprise environment which focuses on C#, the dedicated acquisition team can create the NuGet packages with `vcpkg` and provide them to the other developers. For the "end-developer", this makes the consumption of C++ libraries the same as C# ones.
[Qt]: https://www.qt.io/
## 2. Other design concerns
- The `vcpkg` root may have a variety of packages built and many of them might be unrelated to the current task. Providing an easy way to export a subset of them will enhance user experience.
- Since binary compatibility is not guaranteed, it is not safe to individually export packages. Therefore, when exporting a particular package, all of the dependencies that it was built against must also be present in the export format (e.g. zip file). When a `vcpkg export` command succeeds, there is a guarantee that all required headers/binaries are available in the target bundle.
## 3. Proposed solution
This document proposes the `vcpkg export` command to pack the desired binaries in a convenient format. It is not the goal of this document to discuss binary distribution for C++ in a similar way that NuGet does for C#. It proposes exporting "library sets" instead of individual libraries as a solution to the C++ binary incompatibility problem.
From a user experience perspective, the user expresses interest in exporting a particular library (e.g. `vcpkg export cpprestsdk`). `vcpkg export` should then make sure that the output contains `cpprestsdk` along with all dependencies it was actually built against.
## 4. Proposed User experience
### i. User knows what libraries he needs and wants to export them to an archive format (zip)
Developer Bob needs gtest and cpprestsdk and has been manually building them and their dependencies, then using the binaries in his project via applocal deployment. Bob has been experimenting with `vcpkg` and wants to use `vcpkg` for the building part only.
Bob tries to export the libraries:
```no-highlight
> vcpkg export gtest cpprestsdk --zip
The following packages are already built and will be exported:
* boost:x86-windows
* bzip2:x86-windows
cpprestsdk:x86-windows
* openssl:x86-windows
* websocketpp:x86-windows
* zlib:x86-windows
The following packages need to be built:
gtest:x86-windows
Additional packages (*) need to be exported to complete this operation.
There are packages that have not been built.
To build them, run:
vcpkg install gtest:x86-windows
```
Bob proceeds to install the missing libraries:
```no-highlight
> vcpkg install gtest:x86-windows
// -- omitted build information -- //
Package gtest:x86-windows is installed.
```
Bob then returns to export the libraries:
```no-highlight
> vcpkg export gtest cpprestsdk --zip
The following packages are already built and will be exported:
* boost:x86-windows
* bzip2:x86-windows
cpprestsdk:x86-windows
gtest:x86-windows
* openssl:x86-windows
* websocketpp:x86-windows
* zlib:x86-windows
Additional packages (*) need to be exported to complete this operation.
Exporting package zlib:x86-windows...
Exporting package zlib:x86-windows... done
Exporting package openssl:x86-windows...
Exporting package openssl:x86-windows... done
Exporting package bzip2:x86-windows...
Exporting package bzip2:x86-windows... done
Exporting package boost:x86-windows...
Exporting package boost:x86-windows... done
Exporting package websocketpp:x86-windows...
Exporting package websocketpp:x86-windows... done
Exporting package cpprestsdk:x86-windows...
Exporting package cpprestsdk:x86-windows... done
Exporting package gtest:x86-windows...
Exporting package gtest:x86-windows... done
Creating zip archive...
Creating zip archive... done
zip archive exported at: C:/vcpkg/vcpkg-export-20170428-155351.zip
```
Bob takes the zip file and extracts the contents next to his other dependencies. Bob can now proceed with building his own project as before.
### ii. User has a vcpkg root that works and wants to share it
Developer Alice has been using `vcpkg` and has a Visual Studio project that consumes libraries from it (via `vcpkg integrate`). The project is built for both 32-bit and 64-bit architectures. Alice wants to quickly share the dependencies with Bob so he can test the project.
```no-highlight
> vcpkg export gtest zlib gtest:x64-windows zlib:x64-windows --nuget
The following packages are already built and will be exported:
gtest:x86-windows
gtest:x64-windows
zlib:x86-windows
zlib:x64-windows
Exporting package zlib:x86-windows...
Exporting package zlib:x86-windows... done
Exporting package zlib:x64-windows...
Exporting package zlib:x64-windows... done
Exporting package gtest:x86-windows...
Exporting package gtest:x86-windows... done
Exporting package gtest:x64-windows...
Exporting package gtest:x64-windows... done
Creating nuget package...
Creating nuget package... done
Nuget package exported at: C:/vcpkg/scripts/buildsystems/tmp/vcpkg-export-20170428-164312.nupkg
```
Alice gives to Bob: a) The link to her project and b) The NuGet package "vcpkg-export-20170428-164312.nupkg". Bob clones the project and then installs the NuGet package. Bob is now ready to build Alice's project.
### iii. User has a vcpkg root that works and wants to share it #2
Developer Alice has been using `vcpkg` and has a CMake project that consumes libraries from it (via CMake toolchain file). Alice wants to quickly share the dependencies with Bob so he can test the project.
```no-highlight
> vcpkg export cpprestsdk zlib --zip
The following packages are already built and will be exported:
* boost:x86-windows
* bzip2:x86-windows
cpprestsdk:x86-windows
* openssl:x86-windows
* websocketpp:x86-windows
zlib:x86-windows
Additional packages (*) need to be exported to complete this operation.
Exporting package zlib:x86-windows...
Exporting package zlib:x86-windows... done
Exporting package openssl:x86-windows...
Exporting package openssl:x86-windows... done
Exporting package bzip2:x86-windows...
Exporting package bzip2:x86-windows... done
Exporting package boost:x86-windows...
Exporting package boost:x86-windows... done
Exporting package websocketpp:x86-windows...
Exporting package websocketpp:x86-windows... done
Exporting package cpprestsdk:x86-windows...
Exporting package cpprestsdk:x86-windows... done
Creating zip archive...
Creating zip archive... done
zip archive exported at: C:/vcpkg/vcpkg-export-20170428-155351.zip
```
Alice gives to Bob: a) The links to her project and b) The zip file "vcpkg-export-20170428-155351.zip". Bob clones the project, extracts the zip file and uses the provided (in the zip) CMake toolchain file to make the dependencies available to CMake. Bob is now ready to build Alice's project.
## 5. Technical model
- Each exported library, must be accompanied with all of its dependencies, even if they are not explicitly specified in the `vcpkg export` command.
- When exporting a library, a dependency graph will be built, similarly to install, to figure out which packages needs to be exported.
- It is allowed to have packages from different triplets, so users can include 32/64-bit and dynamic/static binaries in the same export.
- The exported archives also include the files needed to integrate with MSBuild and/or CMake.

85
docs/users/integration.md Normal file
View File

@ -0,0 +1,85 @@
## Buildsystem Integration
Vcpkg offers many ways to integrate into your build so you can do what's right for your project. There are two main categories of integration:
- [`integrate` command](#integrate)
- [`export` command](#export)
<a name="integrate"></a>
### Integrate Command
These link your project(s) to a specific copy of Vcpkg on your machine so any updates or new package installations will be instantly available for the next build of your project.
#### User-wide for MSBuild (Recommended for Open Source MSBuild projects)
```no-highlight
vcpkg integrate install
```
This will implicitly add Include Directories, Link Directories, and Link Libraries for all packages installed with Vcpkg to all VS2015 and VS2017 MSBuild projects. We also add a post-build action for executable projects that will analyze and copy any DLLs you need to the output folder, enabling a seamless F5 experience.
For the vast majority of libraries, this is all you need to do -- just File -> New Project and write code! However, some libraries perform conflicting behaviors such as redefining `main()`. Since you need to choose per-project which of these conflicting options you want, you will need to add those libraries to your linker inputs manually.
Here are some examples, though this is not an exhaustive list:
- Gtest provides `gtest`, `gmock`, `gtest_main`, and `gmock_main`
- SDL2 provides `SDL2main`
- SFML provides `sfml-main`
- Boost.Test provides `boost_test_exec_monitor`
To get a full list for all your installed packages, run `vcpkg owns manual-link`.
#### CMake toolchain file (Recommended for Open Source CMake projects)
```no-highlight
cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake
```
Projects configured with the Vcpkg toolchain file will have the appropriate Vcpkg folders added to the cmake search paths. This makes all libraries available to be found through `find_package()`, `find_path()`, and `find_library()`.
See [Example: Using Sqlite](../examples/using-sqlite.md) for a fully worked example using our CMake toolchain.
Note that we do not automatically add ourselves to your compiler include paths. To use a header-only library, simply use `find_path()`, which will correctly work on all platforms:
```cmake
# To find and use catch
find_path(CATCH_INCLUDE_DIR catch.hpp)
include_directories(${CATCH_INCLUDE_DIR})
```
#### Linking NuGet file
We also provide individual VS project integration through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects.
```no-highlight
PS D:\src\vcpkg> .\vcpkg integrate project
Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg
With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"
```
*Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.*
#### Manual compiler settings
Libraries are installed into the `installed\` subfolder, partitioned by architecture (e.g. x86-windows):
* The header files are installed to `installed\x86-windows\include`
* Release `.lib` files are installed to `installed\x86-windows\lib` or `installed\x86-windows\lib\manual-link`
* Release `.dll` files are installed to `installed\x86-windows\bin`
* Debug `.lib` files are installed to `installed\x86-windows\debug\lib` or `installed\x86-windows\debug\lib\manual-link`
* Debug `.dll` files are installed to `installed\x86-windows\debug\bin`
See your build system specific documentation for how to use prebuilt binaries.
Generally, to run any produced executables you will also need to either copy the needed DLL files to the same folder as your executable or *prepend* the correct `bin\` directory to your path.
<a name="export"></a>
### Export Command
This command creates a shrinkwrapped archive containing a specific set of libraries (and their dependencies) that can be quickly and reliably shared with build servers or other users in your organization.
- `--nuget`: NuGet package (Recommended for MSBuild projects)
- `--zip`: Zip archive
- `--7zip`: 7Zip archive (Recommended for CMake projects)
- `--raw`: Raw, uncompressed folder
Each of these have the same layout, which mimics the layout of a full vcpkg:
- `installed\` contains the installed package files
- `scripts\buildsystems\vcpkg.cmake` is a toolchain file suitable for use with CMake
Additionally, NuGet packages will contain a `build\native\vcpkg.targets` that integrates with MSBuild projects.
Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples.

45
scripts/cmake/vcpkg_acquire_msys.cmake
View File

@ -1,3 +1,48 @@
## # vcpkg_acquire_msys
##
## Download and prepare an MSYS2 instance.
##
## ## Usage
## ```cmake
## vcpkg_acquire_msys(<MSYS_ROOT_VAR>)
## ```
##
## ## Parameters
## ### MSYS_ROOT_VAR
## An out-variable that will be set to the path to MSYS2.
##
## ## Notes
## A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`:
## ```cmake
## vcpkg_acquire_msys(MSYS_ROOT)
## set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
##
## vcpkg_execute_required_process(
## COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh"
## WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
## LOGNAME build-${TARGET_TRIPLET}-rel
## )
## ```
## To ensure a package is available:
## ```cmake
## vcpkg_acquire_msys(MSYS_ROOT)
## set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
##
## message(STATUS "Installing MSYS Packages")
## vcpkg_execute_required_process(
## COMMAND
## ${BASH} --noprofile --norc -c
## "pacman -Sy --noconfirm --needed make"
## WORKING_DIRECTORY ${MSYS_ROOT}
## LOGNAME pacman-${TARGET_TRIPLET})
## ```
##
## ## Examples
##
## * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
## * [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
## * [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake)
function(vcpkg_acquire_msys PATH_TO_ROOT_OUT)
set(TOOLPATH ${DOWNLOADS}/tools/msys2)

52
scripts/cmake/vcpkg_apply_patches.cmake
View File

@ -1,23 +1,35 @@
#.rst:
# .. command:: vcpkg_apply_patches
#
# Apply a set of patches to a source tree.
#
# ::
# vcpkg_apply_patches(SOURCE_PATH <source_path>
# PATCHES patch1 [patch ...]
# )
#
# ``SOURCE_PATH``
# The source path in which apply the patches.
# ``PATCHES``
# A list of patches that are applied to the source tree
# ``QUIET``
# If this option is passed, the warning message when applyng
# a patch fails is not printed. This is convenient for patches
# that are known to fail even on a clean source tree, and for
# which the standard warning message would be confusing for the user.
#
## # vcpkg_apply_patches
##
## Apply a set of patches to a source tree.
##
## ## Usage
## ```cmake
## vcpkg_apply_patches(
## SOURCE_PATH <${SOURCE_PATH}>
## [QUIET]
## PATCHES <patch1.patch>...
## )
## ```
##
## ## Parameters
## ### SOURCE_PATH
## The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
##
## ### PATCHES
## A list of patches that are applied to the source tree.
##
## Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
##
## ### QUIET
## Disables the warning message upon failure.
##
## This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
##
## ## Examples
##
## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
## * [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
## * [libpng](https://github.com/Microsoft/vcpkg/blob/master/ports/libpng/portfile.cmake)
function(vcpkg_apply_patches)
cmake_parse_arguments(_ap "QUIET" "SOURCE_PATH" "PATCHES" ${ARGN})

99
scripts/cmake/vcpkg_build_msbuild.cmake
View File

@ -1,46 +1,59 @@
#.rst:
# .. command:: vcpkg_build_msbuild
#
# Build a msbuild-based project.
#
# ::
# vcpkg_build_msbuild(PROJECT_PATH <sln_project_path>
# [RELEASE_CONFIGURATION <release_configuration>] # (default = "Release")
# [DEBUG_CONFIGURATION <debug_configuration>] @ (default = "Debug")
# [TARGET_PLATFORM_VERSION <windows_target_platform_version>]
# [PLATFORM <platform>] # (default = "${TRIPLET_SYSTEM_ARCH}")
# [PLATFORM_TOOLSET <platform_toolset>] # (default = "${VCPKG_PLATFORM_TOOLSET}")
# [OPTIONS arg1 [arg2 ...]]
# [OPTIONS_RELEASE arg1 [arg2 ...]]
# [OPTIONS_DEBUG arg1 [arg2 ...]]
# )
#
# ``PROJECT_PATH``
# The path to the *.sln msbuild project file.
# ``RELEASE_CONFIGURATION``
# The configuration (``/p:Configuration`` msbuild parameter)
# used for Release builds.
# ``DEBUG_CONFIGURATION``
# The configuration (``/p:Configuration`` msbuild parameter)
# used for Debug builds.
# ``TARGET_PLATFORM_VERSION``
# The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
# ``TARGET``
# The MSBuild target to build. (``/t:<TARGET>``)
# ``PLATFORM``
# The platform (``/p:Platform`` msbuild parameter)
# used for the build.
# ``PLATFORM_TOOLSET``
# The platform toolset (``/p:PlatformToolset`` msbuild parameter)
# used for the build.
# ``OPTIONS``
# The options passed to msbuild for all builds.
# ``OPTIONS_RELEASE``
# The options passed to msbuild for Release builds.
# ``OPTIONS_DEBUG``
# The options passed to msbuild for Debug builds.
#
## # vcpkg_build_msbuild
##
## Build an msbuild-based project.
##
## ## Usage
## ```cmake
## vcpkg_build_msbuild(
## PROJECT_PATH <${SOURCE_PATH}/port.sln>
## [RELEASE_CONFIGURATION <Release>]
## [DEBUG_CONFIGURATION <Debug>]
## [TARGET <Build>]
## [TARGET_PLATFORM_VERSION <10.0.15063.0>]
## [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
## [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
## [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
## [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
## [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
## )
## ```
##
## ## Parameters
## ### PROJECT_PATH
## The path to the solution (`.sln`) or project (`.vcxproj`) file.
##
## ### RELEASE_CONFIGURATION
## The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
##
## ### DEBUG_CONFIGURATION
## The configuration (``/p:Configuration`` msbuild parameter)
## used for Debug builds.
##
## ### TARGET_PLATFORM_VERSION
## The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
##
## ### TARGET
## The MSBuild target to build. (``/t:<TARGET>``)
##
## ### PLATFORM
## The platform (``/p:Platform`` msbuild parameter) used for the build.
##
## ### PLATFORM_TOOLSET
## The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
##
## ### OPTIONS
## Additional options passed to msbuild for all builds.
##
## ### OPTIONS_RELEASE
## Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
##
## ### OPTIONS_DEBUG
## Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
##
## ## Examples
##
## * [libuv](https://github.com/Microsoft/vcpkg/blob/master/ports/libuv/portfile.cmake)
## * [zeromq](https://github.com/Microsoft/vcpkg/blob/master/ports/zeromq/portfile.cmake)
function(vcpkg_build_msbuild)
cmake_parse_arguments(_csc "" "PROJECT_PATH;RELEASE_CONFIGURATION;DEBUG_CONFIGURATION;PLATFORM;PLATFORM_TOOLSET;TARGET_PLATFORM_VERSION;TARGET" "OPTIONS;OPTIONS_RELEASE;OPTIONS_DEBUG" ${ARGN})

46
scripts/cmake/vcpkg_configure_cmake.cmake
View File

@ -1,3 +1,49 @@
## # vcpkg_configure_cmake
##
## Configure CMake for Debug and Release builds of a project.
##
## ## Usage
## ```cmake
## vcpkg_configure_cmake(
## SOURCE_PATH <${SOURCE_PATH}>
## [PREFER_NINJA]
## [GENERATOR <"NMake Makefiles">]
## [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
## [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
## [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
## )
## ```
##
## ## Parameters
## ### SOURCE_PATH
## Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
##
## ### PREFER_NINJA
## Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja.
##
## ### GENERATOR
## Specifies the precise generator to use.
##
## This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. If used for this purpose, it should be set to "NMake Makefiles".
##
## ### OPTIONS
## Additional options passed to CMake during the configuration.
##
## ### OPTIONS_RELEASE
## Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
##
## ### OPTIONS_DEBUG
## Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
##
## ## Notes
## This command supplies many common arguments to CMake. To see the full list, examine the source.
##
## ## Examples
##
## * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
function(vcpkg_configure_cmake)
cmake_parse_arguments(_csc "PREFER_NINJA" "SOURCE_PATH;GENERATOR" "OPTIONS;OPTIONS_DEBUG;OPTIONS_RELEASE" ${ARGN})

16
scripts/cmake/vcpkg_copy_pdbs.cmake
View File

@ -1,3 +1,19 @@
## # vcpkg_copy_pdbs
##
## Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
##
## ## Usage
## ```cmake
## vcpkg_copy_pdbs()
## ```
##
## ## Notes
## This command should always be called by portfiles after they have finished rearranging the binary output.
##
## ## Examples
##
## * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
function(vcpkg_copy_pdbs)
function(merge_filelist OUTVAR INVAR)

20
scripts/cmake/vcpkg_copy_tool_dependencies.cmake
View File

@ -1,5 +1,21 @@
# Copy dlls for all tools in TOOL_DIR
## # vcpkg_copy_tool_dependencies
##
## Copy all DLL dependencies of built tools into the tool folder.
##
## ## Usage
## ```cmake
## vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
## ```
## ## Parameters
## The path to the directory containing the tools.
##
## ## Notes
## This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools.
##
## ## Examples
##
## * [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake)
## * [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
function(vcpkg_copy_tool_dependencies TOOL_DIR)
macro(search_for_dependencies PATH_TO_SEARCH)
file(GLOB TOOLS ${TOOL_DIR}/*.exe ${TOOL_DIR}/*.dll)

37
scripts/cmake/vcpkg_download_distfile.cmake
View File

@ -1,4 +1,39 @@
# Usage: vcpkg_download_distfile(<VAR> URLS <http://mainUrl> <http://mirror1> <http://mirror2> FILENAME <output.zip> SHA512 <5981de...>)
## # vcpkg_download_distfile
##
## Download and cache a file needed for this port.
##
## ## Usage
## ```cmake
## vcpkg_download_distfile(
## <OUT_VARIABLE>
## URLS <http://mainUrl> <http://mirror1>...
## FILENAME <output.zip>
## SHA512 <5981de...>
## )
## ```
## ## Parameters
## ### OUT_VARIABLE
## This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.
##
## ### URLS
## A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.
##
## ### FILENAME
## The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
##
## ### SHA512
## The expected hash for the file.
##
## If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
##
## ## Notes
## The command [`vcpkg_from_github`](vcpkg_from_github.md) should be used instead of this for downloading the main archive for GitHub projects.
##
## ## Examples
##
## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
## * [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
function(vcpkg_download_distfile VAR)
set(oneValueArgs FILENAME SHA512)
set(multipleValuesArgs URLS)

31
scripts/cmake/vcpkg_execute_required_process.cmake
View File

@ -1,4 +1,33 @@
# Usage: vcpkg_execute_required_process(COMMAND <cmd> [<args>...] WORKING_DIRECTORY </path/to/dir> LOGNAME <my_log_name>)
## # vcpkg_execute_required_process
##
## Execute a process with logging and fail the build if the command fails.
##
## ## Usage
## ```cmake
## vcpkg_execute_required_process(
## COMMAND <${PERL}> [<arguments>...]
## WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
## LOGNAME <build-${TARGET_TRIPLET}-dbg>
## )
## ```
## ## Parameters
## ### COMMAND
## The command to be executed, along with its arguments.
##
## ### WORKING_DIRECTORY
## The directory to execute the command in.
##
## ### LOGNAME
## The prefix to use for the log files.
##
## This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
##
## ## Examples
##
## * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
function(vcpkg_execute_required_process)
cmake_parse_arguments(vcpkg_execute_required_process "" "WORKING_DIRECTORY;LOGNAME" "COMMAND" ${ARGN})
#debug_message("vcpkg_execute_required_process(${vcpkg_execute_required_process_COMMAND})")

29
scripts/cmake/vcpkg_extract_source_archive.cmake
View File

@ -1,3 +1,32 @@
## # vcpkg_extract_source_archive
##
## Extract an archive into the source directory.
##
## ## Usage
## ```cmake
## vcpkg_extract_source_archive(
## <${ARCHIVE}> [<${TARGET_DIRECTORY}>]
## )
## ```
## ## Parameters
## ### ARCHIVE
## The full path to the archive to be extracted.
##
## This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
##
## ### TARGET_DIRECTORY
## If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}\src\`.
##
## This can be used to mimic git submodules, by extracting into a subdirectory of another archive.
##
## ## Notes
## This command will also create a tracking file named <FILENAME>.extracted in the TARGET_DIRECTORY. This file, when present, will suppress the extraction of the archive.
##
## ## Examples
##
## * [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
## * [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
## * [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
include(vcpkg_execute_required_process)
function(vcpkg_extract_source_archive_ex)

34
scripts/cmake/vcpkg_find_acquire_program.cmake
View File

@ -1,3 +1,37 @@
## # vcpkg_find_acquire_program
##
## Download or find a well-known tool.
##
## ## Usage
## ```cmake
## vcpkg_find_acquire_program(<VAR>)
## ```
## ## Parameters
## ### VAR
## This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable.
##
## ## Notes
## The current list of programs includes:
##
## - 7Z
## - BISON
## - FLEX
## - PERL
## - PYTHON2
## - PYTHON3
## - JOM
## - MESON
## - NASM
## - NINJA
## - YASM
##
## Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
##
## ## Examples
##
## * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
function(vcpkg_find_acquire_program VAR)
if(${VAR} AND NOT ${VAR} MATCHES "-NOTFOUND")
return()

60
scripts/cmake/vcpkg_from_github.cmake
View File

@ -1,14 +1,52 @@
# Usage:
# vcpkg_from_github(
# OUT_SOURCE_PATH <OutVar for SOURCE_PATH (SOURCE_PATH)>
# REPO <Repository (Microsoft/cpprestsdk)>
# REF <stable ref (v2.0.0)>
# SHA512 <SHA for REF (45d0d7f8cc350...)>
# HEAD_REF <unstable branch (master)>
# )
#
# Notes:
# This will export VCPKG_HEAD_VERSION variable during head builds.
## # vcpkg_from_github
##
## Download and extract a project from GitHub. Enables support for `install --head`.
##
## ## Usage:
## ```cmake
## vcpkg_from_github(
## OUT_SOURCE_PATH <SOURCE_PATH>
## REPO <Microsoft/cpprestsdk>
## [REF <v2.0.0>]
## [SHA512 <45d0d7f8cc350...>]
## [HEAD_REF <master>]
## )
## ```
##
## ## Parameters:
## ### OUT_SOURCE_PATH
## Specifies the out-variable that will contain the extracted location.
##
## This should be set to `SOURCE_PATH` by convention.
##
## ### REPO
## The organization or user and repository on GitHub.
##
## ### REF
## A stable git commit-ish (ideally a tag) that will not change contents.
##
## If `REF` is specified, `SHA512` must also be specified.
##
## ### SHA512
## The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz).
##
## This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
##
## ### HEAD_REF
## The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
##
## For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
##
## ## Notes:
## At least one of `REF` and `HEAD_REF` must be specified.
##
## This exports the `VCPKG_HEAD_VERSION` variable during head builds.
##
## ## Examples:
##
## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
## * [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake)
## * [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
function(vcpkg_from_github)
set(oneValueArgs OUT_SOURCE_PATH REPO REF SHA512 HEAD_REF)
set(multipleValuesArgs)

22
scripts/cmake/vcpkg_install_cmake.cmake
View File

@ -1,3 +1,25 @@
## # vcpkg_install_cmake
##
## Build and install a cmake project.
##
## ## Usage:
## ```cmake
## vcpkg_install_cmake([MSVC_64_TOOLSET])
## ```
##
## ## Parameters:
## ### MSVC_64_TOOLSET
## This adds the `/p:PreferredToolArchitecture=x64` switch if the underlying buildsystem is MSBuild. Some large projects can run out of memory when linking if they use the 32-bit hosted tools.
##
## ## Notes:
## This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
##
## ## Examples:
##
## * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
function(vcpkg_install_cmake)
cmake_parse_arguments(_bc "MSVC_64_TOOLSET;DISABLE_PARALLEL" "" "" ${ARGN})