tdlight-team
/
windows-amd64-prebuilt-libraries
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

edit

This commit is contained in:
Andrea 2020-10-11 02:04:38 +02:00
parent 3e85a43f54
commit bc12a655d1
229 changed files with 40293 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
vcpkg/docs/_config.yml Normal file
View File

@ -0,0 +1 @@
theme: jekyll-theme-cayman

115
vcpkg/docs/about/faq.md Normal file
View File

@ -0,0 +1,115 @@
# Frequently Asked Questions
## Can I contribute a new library?
Yes! Start out by reading our [contribution guidelines](https://github.com/Microsoft/vcpkg/blob/master/CONTRIBUTING.md). If you want to contribute but don't have a particular library in mind then take a look at the list of [new port requests](https://github.com/Microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+port+request+-+consider+making+a+PR%21%22).
## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg?
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\`](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 our examples on packaging [zipfiles](../examples/packaging-zipfiles.md) and [GitHub repos](../examples/packaging-github-repos.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 [our packaging zlib Example](../examples/packaging-zipfiles.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`](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 run on Linux/OSX?
Yes! We continuously test on OSX and Ubuntu 16.04, however we know users have been successful with Arch, Fedora, and FreeBSD. If you have trouble with your favorite Linux distribution, let us know in an issue and we'd be happy to help!
## 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!). 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](../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`.
## How does Vcpkg protect my 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.
## Can I use my own/specific flags for rebuilding libs?
Yes. In the current version, there is not yet a standardized global way to change them, however you can edit individual portfiles and tweak the exact build process however you'd like.
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.
## Can I get Vcpkg integration for custom configurations?
Yes. While Vcpkg will only produce the standard "Release" and "Debug" configurations when building a library, you can get integration support for your projects' custom configurations, in addition to your project's standard configurations.
First of all, Vcpkg will automatically assume any custom configuration starting with "Release" (resp. "Debug") as a configuration that is compatible with the standard "Release" (resp. "Debug") configuration and will act accordingly.
For other configurations, you only need to override the MSBuild `$(VcpkgConfiguration)` macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration. Unfortunately, due to the sequential nature of MSBuild, you'll need to add those settings much higher in your vcxproj so that it is declared before the Vcpk integration is loaded. It is recommend that the `$(VcpkgConfiguration)` macro is added to the "Globals" PropertyGroup.
For example, you can add support for your "MyRelease" configuration by adding in your project file:
```
<PropertyGroup Label="Globals">
...
<VcpkgConfiguration Condition="'$(Configuration)' == 'MyRelease'">Release</VcpkgConfiguration>
</PropertyGroup>
```
Of course, this will only produce viable binaries if your custom configuration is compatible with the target configuration (e.g. they should both link with the same runtime library).
## I can't use user-wide integration. Can I use a per-project integration?
Yes. A NuGet package suitable for per-project use can be generated via either the `vcpkg integrate project` command (lightweight linking) or the `vcpkg export --nuget` command (shrinkwrapped).
A lower level mechanism to achieve the same as the `vcpkg integrate project` NuGet package is via the `<vcpkg_root>\scripts\buildsystems\msbuild\vcpkg.targets` file. All you need is to import it in your .vcxproj file, replacing `<vcpkg_root>` with the path where you installed vcpkg:
```
<Import Project="<vcpkg_root>\scripts\buildsystems\msbuild\vcpkg.targets" />
```
## How can I remove temporary files?
You can save some disk space by completely removing the `packages\`, `buildtrees\`, and `downloads\` folders.
## 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 legible for unfamiliar users.
## Will Vcpkg support downloading compiled binaries from a public or private server?
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. See the [`export`](../users/integration.md#export) command.
## What Visual C++ toolsets are supported?
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.
## 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.
- **Compilation Flavors**. With so many possible combinations of compilation options, the task of providing a truly complete set of options is intrinsically impossible. Furthermore, the download size for reasonably complete binary packages becomes enormous. This makes it a requirement to split the results into multiple packages, but then searching becomes very difficult.
- **Binary vs Source**. Very closely tied to the first point, NuGet is designed from the ground up to provide relatively small, prebuilt binaries. Due to the nature of native code, developers need to have access to the source code to ensure ABI compatibility, performance, integrity, and debuggability.
- **Per-dll vs Per-application**. NuGet is highly project centric. This works well in managed languages with naturally stable ABIs, because base libraries can continue to evolve without breaking those higher up. However, in native languages where the ABI is much more fragile, the only robust strategy is to explicitly build each library against the exact dependencies that will be included in the final application. This is difficult to ensure in NuGet and leads to a highly disconnected and independently versioned ecosystem.
## Why not Conan?
Conan.io is a publicly-federated, project-centric, cross-platform, C++ package manager written in python. Our primary differences are:
- **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 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 programming language just to understand your package manager.
## Why not 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!).

50
vcpkg/docs/about/privacy.md Normal file
View File

@ -0,0 +1,50 @@
# Vcpkg telemetry and privacy
vcpkg collects telemetry data to understand usage issues, such as failing packages, and to guide tool improvements. The collected data is anonymous.
For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-US/privacystatement#mainenterprisedeveloperproductsmodule
## Scope
We explicitly ONLY collect information from invocations of the tool itself; we do NOT add any tracking information into the produced libraries. Telemetry is collected when using any of the `vcpkg` commands.
## How to opt out
The vcpkg telemetry feature is enabled by default. In order to opt-out of data collection, you can re-run the boostrap script with the following flag, for Windows and Linux/OSX, respectively:
```PS> .\bootstrap-vcpkg.bat -disableMetrics```
```~/$ ./bootstrap-vcpkg.sh -disableMetrics```
## Disclosure
vcpkg displays text similar to the following when you build vcpkg. This is how Microsoft notifies you about data collection.
```
Telemetry
---------
vcpkg collects usage data in order to help us improve your experience.
The data collected by Microsoft is anonymous.
You can opt-out of telemetry by re-running the bootstrap-vcpkg script with -disableMetrics,
passing --disable-metrics to vcpkg on the command line,
or by setting the VCPKG_DISABLE_METRICS environment variable.
Read more about vcpkg telemetry at docs/about/privacy.md
```
## Data Collected
The telemetry feature doesn't collect personal data, such as usernames or email addresses. It doesn't scan your code and doesn't extract project-level data, such as name, repository, or author. The data is sent securely to Microsoft servers and held under restricted access.
Protecting your privacy is important to us. If you suspect the telemetry is collecting sensitive data or the data is being insecurely or inappropriately handled, file an issue in the Microsoft/vcpkg repository or send an email to vcpkg@microsoft.com for investigation.
We collect various telemetry events such as the command line used, the time of invocation, and how long execution 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.
You can see the telemetry events any command by appending `--printmetrics` after the vcpkg command line.
In the source code (included in `toolsrc\`), you can search for calls to the functions `track_property()`, `track_feature()`, `track_metric()`, and `track_buildtime()`
to see every specific data point we collect.
## Avoid inadvertent disclosure information
vcpkg contributors and anyone else running a version of vcpkg that they built themselves should consider the path to their source code. If a crash occurs when using vcpkg, the file path from the build machine is collected as part of the stack trace and isn't hashed.
Because of this, builds of vcpkg shouldn't be located in directories whose path names expose personal or sensitive information.

180
vcpkg/docs/examples/installing-and-using-packages.md Normal file
View File

@ -0,0 +1,180 @@
## Installing and Using Packages Example: 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.32.1 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
Computing installation plan...
The following packages will be built and installed:
sqlite3[core]:x86-windows
Starting package 1/1: sqlite3:x86-windows
Building package sqlite3[core]:x86-windows...
-- Downloading https://sqlite.org/2020/sqlite-amalgamation-3320100.zip...
-- Extracting source C:/src/vcpkg/downloads/sqlite-amalgamation-3320100.zip
-- Applying patch fix-arm-uwp.patch
-- Using source at C:/src/vcpkg/buildtrees/sqlite3/src/3320100-15aeda126a.clean
-- Configuring x86-windows
-- Building x86-windows-dbg
-- Building x86-windows-rel
-- Performing post-build validation
-- Performing post-build validation done
Building package sqlite3[core]:x86-windows... done
Installing package sqlite3[core]:x86-windows...
Installing package sqlite3[core]:x86-windows... done
Elapsed time for package sqlite3:x86-windows: 12 s
Total elapsed time: 12.04 s
The package sqlite3:x86-windows provides CMake targets:
find_package(unofficial-sqlite3 CONFIG REQUIRED)
target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3))
```
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.32.1 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 afterwards 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 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 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"
}]
}]
}
```
*Note: It might be necessary to delete the CMake cache folder of each modified configuration, to force a full regeneration. In the `CMake` menu, under `Cache (<configuration name>)` you'll find `Delete Cache Folders`.*
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(unofficial-sqlite3 CONFIG REQUIRED)
add_executable(main main.cpp)
target_link_libraries(main PRIVATE unofficial::sqlite3::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

199
vcpkg/docs/examples/manifest-mode-cmake.md Normal file
View File

@ -0,0 +1,199 @@
# Manifest Mode: CMake Example
We would like to add vcpkg manifest support to an existing cmake project!
Let's create a simple project that prints the fibonacci sequence up to a certain number,
using some common dependencies.
## Initial Layout
Let's create the following file layout:
```no-highlight
fibo/
src/
main.cxx
CMakeLists.txt
```
And we wish to use [fmt](https://github.com/fmtlib/fmt), [range-v3](https://github.com/ericniebler/range-v3),
and [cxxopts](https://github.com/jarro2783/cxxopts).
Let's write our `CMakeLists.txt` first:
```cmake
cmake_minimum_required(VERSION 3.15)
project(fibo CXX)
find_package(fmt REQUIRED)
find_package(range-v3 REQUIRED)
find_package(cxxopts REQUIRED)
add_executable(fibo src/main.cxx)
target_link_libraries(fibo
PRIVATE
fmt::fmt
range-v3::range-v3
cxxopts::cxxopts)
```
And then we should add `main.cxx`:
```cxx
#include <cxxopts.hpp>
#include <fmt/format.h>
#include <range/v3/view.hpp>
namespace view = ranges::view;
int fib(int x) {
int a = 0, b = 1;
for (int it : view::repeat(0) | view::take(x)) {
(void)it;
int tmp = a;
a += b;
b = tmp;
}
return a;
}
int main(int argc, char** argv) {
cxxopts::Options options("fibo", "Print the fibonacci sequence up to a value 'n'");
options.add_options()
("n,value", "The value to print to", cxxopts::value<int>()->default_value("10"));
auto result = options.parse(argc, argv);
auto n = result["value"].as<int>();
for (int x : view::iota(1) | view::take(n)) {
fmt::print("fib({}) = {}\n", x, fib(x));
}
}
```
This is a simple project of course, but it should give us a clean project to start with.
Let's try it out!
Let's assume you have `fmt`, `range-v3`, and `cxxopts` installed with vcpkg classic mode;
then, you can just do a simple:
```cmd
D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake
-- Building for: Visual Studio 16 2019
-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
-- The CXX compiler identification is MSVC 19.27.29111.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: D:/src/fibo/build
D:\src\fibo> cmake --build build
Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.
Checking Build System
Building Custom Rule D:/src/fibo/CMakeLists.txt
main.cxx
The contents of <span> are available only with C++20 or later.
fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe
Building Custom Rule D:/src/fibo/CMakeLists.txt
```
And now we can try out the `fibo` binary!
```cmd
D:\src\fibo> .\build\Debug\fibo.exe -n 7
fib(1) = 1
fib(2) = 1
fib(3) = 2
fib(4) = 3
fib(5) = 5
fib(6) = 8
fib(7) = 13
```
it works!
## Converting to Manifest Mode
We now wish to use manifest mode, so all of our dependencies are managed for us! Let's write a `vcpkg.json`:
```json
{
"name": "fibo",
"version-string": "0.1.0",
"dependencies": [
"cxxopts",
"fmt",
"range-v3"
]
}
```
Let's delete the build directory and rerun the build:
```cmd
D:\src\fibo> rmdir /S /Q build
D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake
-- Running vcpkg install
Detecting compiler hash for triplet x64-windows...
The following packages will be built and installed:
cxxopts[core]:x64-windows
fmt[core]:x64-windows
range-v3[core]:x64-windows
Starting package 1/3: cxxopts:x64-windows
Building package cxxopts[core]:x64-windows...
Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\d2\d2d1e5302cdfefef2fd090d8eda84cc0c1fbe6f1.zip
Building package cxxopts[core]:x64-windows... done
Installing package cxxopts[core]:x64-windows...
Installing package cxxopts[core]:x64-windows... done
Elapsed time for package cxxopts:x64-windows: 50.64 ms
Starting package 2/3: fmt:x64-windows
Building package fmt[core]:x64-windows...
Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\bf\bf00d5214e912d71414b545b241f54ef87fdf6e5.zip
Building package fmt[core]:x64-windows... done
Installing package fmt[core]:x64-windows...
Installing package fmt[core]:x64-windows... done
Elapsed time for package fmt:x64-windows: 225 ms
Starting package 3/3: range-v3:x64-windows
Building package range-v3[core]:x64-windows...
Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\fe\fe2cdedef6953bf954e8ddca471bf3cc8d9b06d7.zip
Building package range-v3[core]:x64-windows... done
Installing package range-v3[core]:x64-windows...
Installing package range-v3[core]:x64-windows... done
Elapsed time for package range-v3:x64-windows: 1.466 s
Total elapsed time: 1.742 s
-- Running vcpkg install - done
-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
-- The CXX compiler identification is MSVC 19.27.29111.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: D:/src/fibo/build
D:\src\fibo> cmake --build build
Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.
Checking Build System
Building Custom Rule D:/src/fibo/CMakeLists.txt
main.cxx
The contents of <span> are available only with C++20 or later.
fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe
Building Custom Rule D:/src/fibo/CMakeLists.txt
```
You can see that with just a _single file_, we've changed over to manifests without _any_ trouble.
The build system doesn't change _at all_! We just add a `vcpkg.json` file, delete the build directory,
and reconfigure. And we're done!

126
vcpkg/docs/examples/overlay-triplets-linux-dynamic.md Normal file
View File

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

58
vcpkg/docs/examples/packaging-github-repos.md Normal file
View File

@ -0,0 +1,58 @@
## Packaging Github Repos Example: libogg
### Create the manifest file
The manifest file (called `vcpkg.json`) is a json file describing the package's metadata.
For libogg, we'll create the file `ports/libogg/vcpkg.json` with the following content:
```json
{
"name": "libogg",
"version-string": "1.3.3",
"description": "Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs."
}
```
You can format the manifest file to our specifications with `vcpkg format-manifest ports/libogg/vcpkg.json`.
### Create the portfile
`portfile.cmake` describes how to build and install the package. First we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md):
```cmake
vcpkg_from_github(
OUT_SOURCE_PATH SOURCE_PATH
REPO xiph/ogg
REF v1.3.3
SHA512 0bd6095d647530d4cb1f509eb5e99965a25cc3dd9b8125b93abd6b248255c890cf20710154bdec40568478eb5c4cde724abfb2eff1f3a04e63acef0fbbc9799b
HEAD_REF master
)
```
The important parts to update are `REPO` for the GitHub repository path, `REF` for a stable tag/commit to use, and `SHA512` with the checksum of the downloaded zipfile (you can get this easily by setting it to `1`, trying to install the package, and copying the checksum).
Finally, we configure the project with CMake, install the package, and copy over the license file:
```cmake
vcpkg_configure_cmake(
SOURCE_PATH ${SOURCE_PATH}
PREFER_NINJA
)
vcpkg_install_cmake()
file(INSTALL ${SOURCE_PATH}/COPYING DESTINATION ${CURRENT_PACKAGES_DIR}/share/libogg RENAME copyright)
```
Check the documentation for [`vcpkg_configure_cmake`](../maintainers/vcpkg_configure_cmake.md) and [`vcpkg_install_cmake`](../maintainers/vcpkg_install_cmake.md) if your package needs additional options.
Now you can run `vcpkg install libogg` to build and install the package.
### 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
- cppunit
- mpg123
- Non-CMake, custom buildsystem
- openssl
- ffmpeg

77
vcpkg/docs/examples/packaging-zipfiles.md Normal file
View File

@ -0,0 +1,77 @@
## Packaging Zipfiles Example: 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/zlib-1.2.11.tar.gz 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`.
*`zlib1211.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/zlib-1.2.11.tar.gz zlib1211.tar.gz
-- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake
```
### Create the manifest file
In addition to the generated `ports/<package>/portfile.cmake`, we also need a `ports/<package>/vcpkg.json` file. This file is a simple set of fields describing the package's metadata.
*For zlib2, we'll create the file `ports/zlib2/vcpkg.json` with the following contents:*
```json
{
"name": "zlib2",
"version-string": "1.2.11",
"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 install zlib2
Computing installation plan...
The following packages will be built and installed:
zlib2[core]:x64-uwp
Starting package 1/1: zlib2:x64-uwp
Building package zlib2[core]:x64-uwp...
-- Using cached C:/src/vcpkg/downloads/zlib1211.tar.gz
-- Cleaning sources at C:/src/vcpkg/buildtrees/zlib2/src/1.2.11-deec42f53b.clean. Pass --editable to vcpkg to reuse sources.
-- Extracting source C:/src/vcpkg/downloads/zlib1211.tar.gz
-- Applying patch cmake_dont_build_more_than_needed.patch
-- Using source at C:/src/vcpkg/buildtrees/zlib2/src/1.2.11-deec42f53b.clean
-- Configuring x64-uwp
-- Building x64-uwp-dbg
-- Building x64-uwp-rel
-- Installing: C:/src/vcpkg/packages/zlib2_x64-uwp/share/zlib2/copyright
-- Performing post-build validation
Include files should not be duplicated into the /debug/include directory. If this cannot be disabled in the project cmake, use
file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)
/debug/share should not exist. Please reorganize any important files, then use
file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share)
The software license must be available at ${CURRENT_PACKAGES_DIR}/share/zlib2/copyright
Found 3 error(s). Please correct the portfile:
D:\src\vcpkg\ports\zlib2\portfile.cmake
```
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
- cppunit
- mpg123
- Non-CMake, custom buildsystem
- openssl
- ffmpeg

220
vcpkg/docs/examples/patching.md Normal file
View File

@ -0,0 +1,220 @@
## Patching Example: Patching libpng to work for x64-uwp
### Initial error logs
First, try building:
```no-highlight
PS D:\src\vcpkg> vcpkg install libpng:x64-uwp --editable
Computing installation plan...
The following packages will be built and installed:
libpng[core]:x64-uwp
Starting package 1/1: libpng:x64-uwp
Building package libpng[core]:x64-uwp...
-- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
-- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
-- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf
-- Configuring x64-uwp
-- Building x64-uwp-rel
CMake Error at scripts/cmake/execute_required_process.cmake:14 (message):
Command failed: C:/Program Files/CMake/bin/cmake.exe;--build;.;--config;Release
Working Directory: D:/src/vcpkg/buildtrees/libpng/x64-uwp-rel
See logs for more information:
D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-out.log
D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-err.log
Call Stack (most recent call first):
scripts/cmake/vcpkg_build_cmake.cmake:3 (execute_required_process)
ports/libpng/portfile.cmake:22 (vcpkg_build_cmake)
scripts/ports.cmake:84 (include)
Error: build command failed
```
Next, looking at the above logs (build-...-out.log and build-...-err.log).
```no-highlight
// build-x64-uwp-rel-out.log
...
"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) ->
(ClCompile target) ->
D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) ->
(Link target) ->
pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
1 Warning(s)
2 Error(s)
Time Elapsed 00:00:04.19
```
### Identify the problematic code
Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658(v=vs.85).aspx) shows that `ExitProcess` is only available for desktop apps. Additionally, it's useful to see the surrounding context:
```c
/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c:769 */
/* If control reaches this point, png_longjmp() must not return. The only
* choice is to terminate the whole process (or maybe the thread); to do
* this the ANSI-C abort() function is used unless a different method is
* implemented by overriding the default configuration setting for
* PNG_ABORT().
*/
PNG_ABORT();
```
A recursive search for `PNG_ABORT` reveals the definition:
```no-highlight
PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> 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().
libpng-manual.txt:434:You can #define PNG_ABORT() to a function that does something
libpng-manual.txt:2753:errors will result in a call to PNG_ABORT() which defaults to abort().
libpng-manual.txt:2755:You can #define PNG_ABORT() to a function that does something
libpng-manual.txt:4226:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
libpng.3:942:errors will result in a call to PNG_ABORT() which defaults to abort().
libpng.3:944:You can #define PNG_ABORT() to a function that does something
libpng.3:3263:errors will result in a call to PNG_ABORT() which defaults to abort().
libpng.3:3265:You can #define PNG_ABORT() to a function that does something
libpng.3:4736:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
png.h:994: * will use it; otherwise it will call PNG_ABORT(). This function was
pngerror.c:773: * PNG_ABORT().
pngerror.c:775: PNG_ABORT();
pngpriv.h:459:#ifndef PNG_ABORT
pngpriv.h:461:# define PNG_ABORT() ExitProcess(0)
pngpriv.h:463:# define PNG_ABORT() abort()
```
This already gives us some great clues, but the full definition tells the complete story.
```c
/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */
#ifndef PNG_ABORT
# ifdef _WINDOWS_
# define PNG_ABORT() ExitProcess(0)
# else
# define PNG_ABORT() abort()
# endif
#endif
```
`abort()` is a standard CRT call and certainly available in UWP, so we just need to convince libpng to be more platform agnostic. The easiest and most reliable way to achieve this is to patch the code; while in this particular case we could pass in a compiler flag to override `PNG_ABORT` because this is a private header, in general it is more reliable to avoid adding more required compiler switches when possible (especially when it isn't already exposed as a CMake option).
### Patching the code to improve compatibility
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\v1.6.37-c993153cdf> git init .
Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf/.git/
PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git add .
warning: LF will be replaced by CRLF in ANNOUNCE.
The file will have its original line endings in your working directory.
...
PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git commit -m "temp"
[master (root-commit) 68f253f] temp
422 files changed, 167717 insertions(+)
...
```
Now we can modify `pngpriv.h` to use `abort()` everywhere.
```c
/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */
#ifndef PNG_ABORT
# define PNG_ABORT() abort()
#endif
```
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\v1.6.37-c993153cdf> git diff --ignore-space-at-eol | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch
```
Finally, we need to apply the patch after extracting the source.
```cmake
# ports\libpng\portfile.cmake
...
vcpkg_extract_source_archive_ex(
OUT_SOURCE_PATH SOURCE_PATH
ARCHIVE ${ARCHIVE}
PATCHES
"use-abort-on-all-platforms.patch"
)
vcpkg_configure_cmake(
...
```
### Verification
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:x64-uwp
Package libpng:x64-uwp was successfully removed
```
Now we try a fresh, from scratch install.
```no-highlight
PS D:\src\vcpkg> vcpkg install libpng:x64-uwp
Computing installation plan...
The following packages will be built and installed:
libpng[core]:x64-uwp
Starting package 1/1: libpng:x64-uwp
Building package libpng[core]:x64-uwp...
Could not locate cached archive: C:\Users\me\AppData\Local\vcpkg/archives\f4\f44b54f818f78b9a4ccd34b3666f566f94286850.zip
-- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
-- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
-- Applying patch use_abort.patch
-- Applying patch cmake.patch
-- Applying patch pkgconfig.patch
-- Applying patch pkgconfig.2.patch
-- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-10db9f58e4.clean
-- Configuring x64-uwp
-- Building x64-uwp-dbg
-- Building x64-uwp-rel
-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/lib/pkgconfig/libpng.pc
-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/lib/pkgconfig/libpng16.pc
-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/debug/lib/pkgconfig/libpng.pc
-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/debug/lib/pkgconfig/libpng16.pc
-- Installing: D:/src/vcpkg/packages/libpng_x64-uwp/share/libpng/copyright
-- Performing post-build validation
-- Performing post-build validation done
Stored binary cache: C:\Users\me\AppData\Local\vcpkg/archives\f4\f44b54f818f78b9a4ccd34b3666f566f94286850.zip
Building package libpng[core]:x64-uwp... done
Installing package libpng[core]:x64-uwp...
Installing package libpng[core]:x64-uwp... done
Elapsed time for package libpng:x64-uwp: 11.94 s
Total elapsed time: 11.95 s
The package libpng:x64-uwp provides CMake targets:
find_package(libpng CONFIG REQUIRED)
target_link_libraries(main PRIVATE png)
```
Finally, to fully commit and publish the changes, we need to bump the port version in `vcpkg.json`,
and add the patch file to source control, then make a Pull Request!
```json
{
"name": "libpng",
"version": "1.6.37",
"port-version": 1,
"dependencies": [
"zlib"
]
}
```

1
vcpkg/docs/examples/vcpkg_android_example_cmake/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
build

5
vcpkg/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt Normal file
View File

@ -0,0 +1,5 @@
cmake_minimum_required(VERSION 3.0)
project(test)
find_package(jsoncpp CONFIG REQUIRED)
add_library(my_lib my_lib.cpp)
target_link_libraries(my_lib jsoncpp_lib)

54
vcpkg/docs/examples/vcpkg_android_example_cmake/compile.sh Normal file
View File

@ -0,0 +1,54 @@
#
# 1. Check the presence of required environment variables
#
if [ -z ${ANDROID_NDK_HOME+x} ]; then
echo "Please set ANDROID_NDK_HOME"
exit 1
fi
if [ -z ${VCPKG_ROOT+x} ]; then
echo "Please set VCPKG_ROOT"
exit 1
fi
#
# 2. Set the path to the toolchains
#
vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
#
# 3. Select a pair "Android abi" / "vcpkg triplet"
# Uncomment one of the four possibilities below
#
android_abi=armeabi-v7a
vcpkg_target_triplet=arm-android
# android_abi=x86
# vcpkg_target_triplet=x86-android
# android_abi=arm64-v8a
# vcpkg_target_triplet=arm64-android
# android_abi=x86_64
# vcpkg_target_triplet=x64-android
#
# 4. Install the library via vcpkg
#
$VCPKG_ROOT/vcpkg install jsoncpp:$vcpkg_target_triplet
#
# 5. Test the build
#
rm -rf build
mkdir build
cd build
cmake .. \
-DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
-DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
-DANDROID_ABI=$android_abi
make

8
vcpkg/docs/examples/vcpkg_android_example_cmake/my_lib.cpp Normal file
View File

@ -0,0 +1,8 @@
#include <json/json.h>
int answer()
{
Json::Value meaning_of;
meaning_of["everything"] = 42;
return meaning_of["everything"].asInt();
}

1
vcpkg/docs/examples/vcpkg_android_example_cmake_script/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
build

13
vcpkg/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt Normal file
View File

@ -0,0 +1,13 @@
cmake_minimum_required(VERSION 3.0)
# if -DVCPKG_TARGET_ANDROID=ON is specified when invoking cmake, load cmake/vcpkg_android.cmake
# !!! Important: place this line before calling project() !!!
if (VCPKG_TARGET_ANDROID)
include("cmake/vcpkg_android.cmake")
endif()
project(test)
find_package(jsoncpp CONFIG REQUIRED)
add_library(my_lib my_lib.cpp)
target_link_libraries(my_lib jsoncpp_lib)

99
vcpkg/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake Normal file
View File

@ -0,0 +1,99 @@
#
# vcpkg_android.cmake
#
# Helper script when using vcpkg with cmake. It should be triggered via the variable VCPKG_TARGET_ANDROID
#
# For example:
# if (VCPKG_TARGET_ANDROID)
# include("cmake/vcpkg_android.cmake")
# endif()
#
# This script will:
# 1 & 2. check the presence of needed env variables: ANDROID_NDK_HOME and VCPKG_ROOT
# 3. set VCPKG_TARGET_TRIPLET according to ANDROID_ABI
# 4. Combine vcpkg and Android toolchains by setting CMAKE_TOOLCHAIN_FILE
# and VCPKG_CHAINLOAD_TOOLCHAIN_FILE
# Note: VCPKG_TARGET_ANDROID is not an official Vcpkg variable.
# it is introduced for the need of this script
if (VCPKG_TARGET_ANDROID)
#
# 1. Check the presence of environment variable ANDROID_NDK_HOME
#
if (NOT DEFINED ENV{ANDROID_NDK_HOME})
message(FATAL_ERROR "
Please set an environment variable ANDROID_NDK_HOME
For example:
export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
Or:
export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
")
endif()
#
# 2. Check the presence of environment variable VCPKG_ROOT
#
if (NOT DEFINED ENV{VCPKG_ROOT})
message(FATAL_ERROR "
Please set an environment variable VCPKG_ROOT
For example:
export VCPKG_ROOT=/path/to/vcpkg
")
endif()
#
# 3. Set VCPKG_TARGET_TRIPLET according to ANDROID_ABI
#
# There are four different Android ABI, each of which maps to
# a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures
#
# |VCPKG_TARGET_TRIPLET | ANDROID_ABI |
# |---------------------------|----------------------|
# |arm64-android | arm64-v8a |
# |arm-android | armeabi-v7a |
# |x64-android | x86_64 |
# |x86-android | x86 |
#
# The variable must be stored in the cache in order to successfuly the two toolchains.
#
if (ANDROID_ABI MATCHES "arm64-v8a")
set(VCPKG_TARGET_TRIPLET "arm64-android" CACHE STRING "" FORCE)
elseif(ANDROID_ABI MATCHES "armeabi-v7a")
set(VCPKG_TARGET_TRIPLET "arm-android" CACHE STRING "" FORCE)
elseif(ANDROID_ABI MATCHES "x86_64")
set(VCPKG_TARGET_TRIPLET "x64-android" CACHE STRING "" FORCE)
elseif(ANDROID_ABI MATCHES "x86")
set(VCPKG_TARGET_TRIPLET "x86-android" CACHE STRING "" FORCE)
else()
message(FATAL_ERROR "
Please specify ANDROID_ABI
For example
cmake ... -DANDROID_ABI=armeabi-v7a
Possible ABIs are: arm64-v8a, armeabi-v7a, x64-android, x86-android
")
endif()
message("vcpkg_android.cmake: VCPKG_TARGET_TRIPLET was set to ${VCPKG_TARGET_TRIPLET}")
#
# 4. Combine vcpkg and Android toolchains
#
# vcpkg and android both provide dedicated toolchains:
#
# vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
# android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
#
# When using vcpkg, the vcpkg toolchain shall be specified first.
# However, vcpkg provides a way to preload and additional toolchain,
# with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option.
set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE $ENV{ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake)
set(CMAKE_TOOLCHAIN_FILE $ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake)
message("vcpkg_android.cmake: CMAKE_TOOLCHAIN_FILE was set to ${CMAKE_TOOLCHAIN_FILE}")
message("vcpkg_android.cmake: VCPKG_CHAINLOAD_TOOLCHAIN_FILE was set to ${VCPKG_CHAINLOAD_TOOLCHAIN_FILE}")
endif(VCPKG_TARGET_ANDROID)

37
vcpkg/docs/examples/vcpkg_android_example_cmake_script/compile.sh Normal file
View File

@ -0,0 +1,37 @@
# 1. Install the library via vcpkg
# This install jsoncpp for the 4 android target ABIs and for the host computer.
# see the correspondence between ABIs and vcpkg triplets in the table below:
#
# |VCPKG_TARGET_TRIPLET | ANDROID_ABI |
# |---------------------------|----------------------|
# |arm64-android | arm64-v8a |
# |arm-android | armeabi-v7a |
# |x64-android | x86_64 |
# |x86-android | x86 |
$VCPKG_ROOT/vcpkg install \
jsoncpp \
jsoncpp:arm-android \
jsoncpp:arm64-android \
jsoncpp:x86-android \
jsoncpp:x64-android
# 2. Test the build
#
# First, select an android ABI
# Uncomment one of the four possibilities below
#
android_abi=armeabi-v7a
# android_abi=x86
# android_abi=arm64-v8a
# android_abi=x86_64
rm -rf build
mkdir build && cd build
# DVCPKG_TARGET_ANDROID will load vcpkg_android.cmake,
# which will then load the android + vcpkg toolchains.
cmake .. \
-DVCPKG_TARGET_ANDROID=ON \
-DANDROID_ABI=$android_abi
make

8
vcpkg/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp Normal file
View File

@ -0,0 +1,8 @@
#include <json/json.h>
int answer()
{
Json::Value meaning_of;
meaning_of["everything"] = 42;
return meaning_of["everything"].asInt();
}

52
vcpkg/docs/index.md Normal file
View File

@ -0,0 +1,52 @@
### Quick Start
Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement are vital to its success!
### Examples
- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md)
- [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md)
- [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md)
- [Patching Example: Patching libpng to work for x86-uwp](examples/patching.md)
### User Help
- [Integration with build systems](users/integration.md)
- [Triplet files](users/triplets.md)
- [Configuration and Environment](users/config-environment.md)
- [Usage with Android](users/android.md)
- [Using a manifest file to declare your dependencies](users/top-level-manifest.md)
### Maintainer help
- [Control files](maintainers/control-files.md) - in general, one should use manifest files instead
- [Manifest files](maintainers/manifest-files.md)
- [Portfile functions](maintainers/portfile-functions.md)
- [Maintainer Guidelines](maintainers/maintainer-guide.md)
### Tool Maintainer Help
- [Testing](tool-maintainers/testing.md)
- [Benchmarking](tool-maintainers/benchmarking.md)
- [Layout of the vcpkg source tree](tool-maintainers/layout.md)
- [Maintainer Guidelines](maintainers/maintainer-guide.md)
### Specifications
- [Export](specifications/export-command.md)
- [Feature Packages](specifications/feature-packages.md)
### Blog posts
- [Announcing a single C++ library manager for Linux, macOS and Windows: Vcpkg](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/)
- [Vcpkg: Using multiple enlistments to handle multiple versions of a library](https://blogs.msdn.microsoft.com/vcblog/2017/10/23/vcpkg-using-multiple-enlistments/)
- [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)

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

@ -0,0 +1,203 @@
# CONTROL files
CONTROL files are retained for backwards compatibility with earlier versions of vcpkg;
all new features are added only to vcpkg.json, and we recommend using vcpkg.json for any newly authored port.
The `CONTROL` file contains metadata about the port. The syntax is based on [the Debian `control` format][debian] although we only support the subset of fields documented here.
Field names are case-sensitive and start the line without leading whitespace. Paragraphs are separated by one or more empty lines.
[debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html
## Source Paragraph
The first paragraph in a `CONTROL` file is the Source paragraph. It must have a `Source`, `Version`, and `Description` field. The full set of fields is documented below.
### Examples:
```no-highlight
Source: ace
Version: 6.5.5
Description: The ADAPTIVE Communication Environment
```
```no-highlight
Source: vtk
Version: 8.2.0
Port-Version: 2
Description: Software system for 3D computer graphics, image processing, and visualization
Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c
```
### Recognized fields
#### Source
The name of the port.
When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg. For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique. Verify there are no conflicts on a search engine as well as on other package collections.
Package collections to check for conflicts:
+ [Repology](https://repology.org/projects/)
+ [Debian packages](https://www.debian.org/distrib/packages)
+ [Packages search](https://pkgs.org/)
#### Version
The library version.
This field is an alphanumeric string that may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bit strings and are only evaluated for equality.
For tagged-release ports, we follow the following convention:
1. If the port follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
2. If the port includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
For example, given:
1. The latest commit was made on 2019-04-19
2. The current version string is `2019-02-14-1`
3. Today's date is 2019-06-01.
Then if you update the source version today, you should give it version `2019-06-01`.
#### Port-Version
The version of the port.
This field is a non-negative integer. It allows one to version the port file separately from the version of the underlying library; if you make a change to a port, without changing the underlying version of the library, you should increment this field by one (starting at `0`, which is equivalent to no `Port-Version` field). When the version of the underlying library is upgraded, this field should be set back to `0` (i.e., delete the `Port-Version` field).
##### Examples:
```no-highlight
Version: 1.0.5
Port-Version: 2
```
```no-highlight
Version: 2019-03-21
```
#### Description
A description of the library.
By convention the first line of the description is a summary of the library. An optional detailed description follows. The detailed description can be multiple lines, all starting with whitespace.
##### Examples:
```no-highlight
Description: C++ header-only JSON library
```
```no-highlight
Description: Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.
MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model. This makes it suitable for "machine
to machine" messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino.
````
#### Homepage
The URL of the homepage for the library where a user is able to find additional documentation or the original source code.
Example:
```no-highlight
Homepage: https://github.com/Microsoft/vcpkg
```
#### Build-Depends
Comma separated list of vcpkg ports the library has a dependency on.
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*
If the port is dependent on optional features of another library those can be specified using the `portname[featurelist]` syntax. If the port does not require any features from the dependency, this should be specifed as `portname[core]`.
Dependencies can be filtered based on the target triplet to support differing requirements. These filters use the same syntax as the Supports field below and are surrounded in parentheses following the portname and feature list.
##### Example:
```no-highlight
Build-Depends: rapidjson, curl[core,openssl] (!windows), curl[core,winssl] (windows)
```
#### Default-Features
Comma separated list of optional port features to install by default.
This field is optional.
##### Example:
```no-highlight
Default-Features: dynamodb, s3, kinesis
```
<a name="Supports"></a>
#### Supports
Expression that evaluates to true when the port is expected to build successfully for a triplet.
Currently, this field is only used in the CI testing to skip ports. In the future, this mechanism is intended to warn users in advance that a given install tree is not expected to succeed. Therefore, this field should be used optimistically; in cases where a port is expected to succeed 10% of the time, it should still be marked "supported".
The grammar for the supports expression uses standard operators:
- `!expr` - negation
- `expr|expr` - or (`||` is also supported)
- `expr&expr` - and (`&&` is also supported)
- `(expr)` - grouping/precedence
The predefined expressions are computed from standard triplet settings:
- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"`
- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"`
- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"`
- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
These predefined expressions can be overridden in the triplet file via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option.
This field is optional and defaults to true.
> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism.
##### Example:
```no-highlight
Supports: !(uwp|arm)
```
## Feature Paragraphs
Multiple optional features can be specified in the `CONTROL` files. It must have a `Feature` and `Description` field. It can optionally have a `Build-Depends` field. It must be separated from other paragraphs by one or more empty lines.
### Example:
```no-highlight
Source: vtk
Version: 8.2.0-2
Description: Software system for 3D computer graphics, image processing, and visualization
Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c
Feature: openvr
Description: OpenVR functionality for VTK
Build-Depends: sdl2, openvr
Feature: qt
Description: Qt functionality for VTK
Build-Depends: qt5
Feature: mpi
Description: MPI functionality for VTK
Build-Depends: mpi, hdf5[parallel]
Feature: python
Description: Python functionality for VTK
Build-Depends: python3
```
### Recognized fields
#### Feature
The name of the feature.
#### Description
A description of the feature using the same syntax as the port `Description` field.
#### Build-Depends
The list of dependencies required to build and use this feature.
On installation the dependencies from all selected features are combined to produce the full dependency list for the build. This field follows the same syntax as `Build-Depends` in the Source Paragraph.

10
vcpkg/docs/maintainers/execute_process.md Normal file
View File

@ -0,0 +1,10 @@
# execute_process
Intercepts all calls to execute_process() inside portfiles and fails when Download Mode
is enabled.
In order to execute a process in Download Mode call `vcpkg_execute_in_download_mode()` instead.
## Source
[scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)

270
vcpkg/docs/maintainers/maintainer-guide.md Normal file
View File

@ -0,0 +1,270 @@
# Maintainer Guidelines and Policies
This document lists a set of policies that you should apply when adding or updating a port recipe.
It is intended to serve the role of
[Debian's Policy Manual](https://www.debian.org/doc/debian-policy/),
[Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and
[Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).
## PR Structure
### Make separate Pull Requests per port
Whenever possible, separate changes into multiple PRs.
This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.
### Avoid trivial changes in untouched files
For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand.
However, if you need to modify the file for the primary purpose of the PR (updating the library),
then obviously beneficial changes like fixing typos are appreciated!
### Check names against other repositories
A good service to check many at once is [Repology](https://repology.org/).
If the library you are adding could be confused with another one,
consider renaming to make it clear.
### Use GitHub Draft PRs
GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge.
Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.
More information about GitHub Draft PRs:
https://github.blog/2019-02-14-introducing-draft-pull-requests/
## Portfiles
### Avoid deprecated helper functions
At this time, the following helpers are deprecated:
1. `vcpkg_extract_source_archive()` should be replaced by [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md)
2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
4. `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md)
### Avoid excessive comments in portfiles
Ideally, portfiles should be short, simple, and as declarative as possible.
Remove any boiler plate comments introduced by the `create` command before submitting a PR.
## Build Techniques
### Do not use vendored dependencies
Do not use embedded copies of libraries.
All dependencies should be split out and packaged separately so they can be updated and maintained.
### Prefer using CMake
When multiple buildsystems are available, prefer using CMake.
Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.
Examples: [abseil](../../ports/abseil/portfile.cmake)
### Choose either static or shared binaries
By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`,
however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:
```cmake
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)
vcpkg_configure_cmake(
SOURCE_PATH ${SOURCE_PATH}
PREFER_NINJA
OPTIONS
-DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
-DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
)
```
### When defining features, explicitly control dependencies
When defining a feature that captures an optional dependency,
ensure that the dependency will not be used accidentally when the feature is not explicitly enabled.
```cmake
if ("zlib" IN_LIST FEATURES)
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
else()
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
endif()
vcpkg_configure_cmake(
SOURCE_PATH ${SOURCE_PATH}
PREFER_NINJA
OPTIONS
-CMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
)
```
The snippet below using `vcpkg_check_features()` is equivalent, [see the documentation](vcpkg_check_features.md).
```cmake
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
INVERTED_FEATURES
"zlib" CMAKE_DISABLE_FIND_PACKAGE_ZLIB
)
vcpkg_configure_cmake(
SOURCE_PATH ${SOURCE_PATH}
PREFER_NINJA
OPTIONS
${FEATURE_OPTIONS}
)
```
Note that `ZLIB` in the above is case-sensitive. See the [cmake documentation](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) for more details.
### Place conflicting libs in a `manual-link` directory
A lib is considered conflicting if it does any of the following:
+ Define `main`
+ Define malloc
+ Define symbols that are also declared in other libraries
Conflicting libs are typically by design and not considered a defect. Because some build systems link against everything in the lib directory, these should be moved into a subdirectory named `manual-link`.
## Manifests and CONTROL files
When adding a new port, use the new manifest syntax for defining a port;
you may also change over to manifests when modifying an existing port.
You may do so easily by running the `vcpkg format-manifest` command, which will convert existing CONTROL
files into manifest files. Do not convert CONTROL files that have not been modified.
## Versioning
### Follow common conventions for the `"version"` field
See our [manifest files document](manifest-files.md#version-fields) for a full explanation of our conventions.
### Update the `"port-version"` field in the manifest file of any modified ports
Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes.
Our convention is to use the `"port-version"` field for changes to the port that don't change the upstream version, and to reset the `"port-version"` back to zero when an update to the upstream version is made.
For Example:
- Zlib's package version is currently `1.2.1`, with no explicit `"port-version"` (equivalent to a `"port-version"` of `0`).
- You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile.
- You should update the `"port-version"` field in the manifest file to `1`.
See our [manifest files document](manifest-files.md#port-version) for a full explanation of our conventions.
## Patching
### Prefer options over patching
It is preferable to set options in a call to `vcpkg_configure_xyz()` over patching the settings directly.
Common options that allow avoiding patching:
1. [MSBUILD] `<PropertyGroup>` settings inside the project file can be overridden via `/p:` parameters
2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overridden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
### Prefer patching over overriding `VCPKG_<VARIABLE>` values
Some variables prefixed with `VCPKG_<VARIABLE>` have an equivalent `CMAKE_<VARIABLE>`.
However, not all of them are passed to the internal package build [(see implementation: Windows toolchain)](../../scripts/toolchains/windows.cmake).
Consider the following example:
```cmake
set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")
```
Using `vcpkg`'s built-in toolchains this works, because the value of `VCPKG_<LANG>_FLAGS` is forwarded to the appropriate `CMAKE_LANG_FLAGS` variable. But, a custom toolchain that is not aware of `vcpkg`'s variables will not forward them.
Because of this, it is preferable to patch the buildsystem directly when setting `CMAKE_<LANG>_FLAGS`.
### Minimize patches
When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional.
This helps to keep the size of the vcpkg repository down as well as improves the likelihood that the patch will apply to future code versions.
### Do not implement features in patches
The purpose of patching in vcpkg is to enable compatibility with compilers, libraries, and platforms. It is not to implement new features in lieu of following proper Open Source procedure (submitting an Issue/PR/etc).
## Do not build tests/docs/examples by default
When submitting a new port, check for any options like `BUILD_TESTS` or `WITH_TESTS` or `POCO_ENABLE_SAMPLES` and ensure the additional binaries are disabled. This minimizes build times and dependencies for the average user.
Optionally, you can add a `test` feature which enables building the tests, however this should not be in the `Default-Features` list.
## Enable existing users of the library to switch to vcpkg
### Do not add `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`
Unless the author of the library is already using it, we should not use this CMake functionality because it interacts poorly with C++ templates and breaks certain compiler features. Libraries that don't provide a .def file and do not use __declspec() declarations simply do not support shared builds for Windows and should be marked as such with `vcpkg_check_linkage(ONLY_STATIC_LIBRARY)`.
### Do not rename binaries outside the names given by upstream
This means that if the upstream library has different names in release and debug (libx versus libxd), then the debug library should not be renamed to `libx`. Vice versa, if the upstream library has the same name in release and debug, we should not introduce a new name.
Important caveat:
- Static and shared variants often should be renamed to a common scheme. This enables consumers to use a common name and be ignorant of the downstream linkage. This is safe because we only make one at a time available.
Note that if a library generates CMake integration files (`foo-config.cmake`), renaming must be done through patching the CMake build itself instead of simply calling `file(RENAME)` on the output archives/LIBs.
Finally, DLL files on Windows should never be renamed post-build because it breaks the generated LIBs.
## Code format
### Vcpkg internal code
We require the C++ code inside vcpkg to follow the clang-format, if you change them. Please perform the following steps after modification:
- Use Visual Studio:
1. Configure your [clang-format tools](https://devblogs.microsoft.com/cppblog/clangformat-support-in-visual-studio-2017-15-7-preview-1/).
2. Open the modified file.
3. Use shortcut keys Ctrl+K, Ctrl+D to format the current file.
- Use tools:
1. Install [llvm clang-format](https://releases.llvm.org/download.html#10.0.0)
2. Run command:
```cmd
> LLVM_PATH/bin/clang-format.exe -style=file -i changed_file.cpp
```
### Manifests
We require that the manifest file be formatted. Use the following command to format all manifest files:
```cmd
> vcpkg format-manifest --all
```
## Useful implementation notes
### Portfiles are run in Script Mode
While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core CMake language constructs, portfiles run in "Script Mode", whereas `CMakeLists.txt` files run in "Build Mode" (unofficial term). The most important difference between these two modes is that "Script Mode" does not have a concept of "Target" -- any behaviors that depend on the "target" machine (`CMAKE_CXX_COMPILER`, `CMAKE_EXECUTABLE_SUFFIX`, `CMAKE_SYSTEM_NAME`, etc) will not be correct.
Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`).
Portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:
```no-highlight
+----------------------------+ +------------------------------------+
| CMake.exe | | CMake.exe |
+----------------------------+ +------------------------------------+
| Triplet file | ====> | Toolchain file |
| (x64-windows.cmake) | | (scripts/buildsystems/vcpkg.cmake) |
+----------------------------+ +------------------------------------+
| Portfile | ====> | CMakeLists.txt |
| (ports/foo/portfile.cmake) | | (buildtrees/../CMakeLists.txt) |
+----------------------------+ +------------------------------------+
```
To determine the host in a portfile, the standard CMake variables are fine (`CMAKE_HOST_WIN32`).
To determine the target in a portfile, the vcpkg triplet variables should be used (`VCPKG_CMAKE_SYSTEM_NAME`).
See also our [triplet documentation](../users/triplets.md) for a full enumeration of possible settings.

420
vcpkg/docs/maintainers/manifest-files.md Normal file
View File

@ -0,0 +1,420 @@
# Manifest files - `vcpkg.json`
The `vcpkg.json` file contains metadata about the port.
It's a JSON file, and replaces the existing CONTROL file metadata structure.
It must have a top level object, and all fields are case sensitive.
## Examples:
The most important fields in a manifest, the ones which are required for all ports,
are the `"name"` field, and a version field (for now, just `"version-string"`).
There's more information about these fields below.
```json
{
"name": "ace",
"version-string": "6.5.5"
}
```
```json
{
"name": "vtk",
"version-string": "8.2.0",
"port-version": 2,
"description": "Software system for 3D computer graphics, image processing, and visualization",
"dependencies": [
{
"name": "atlmfc",
"platform": "windows"
},
"double-conversion",
"eigen3",
"expat",
"freetype",
"glew",
"hdf5",
"jsoncpp",
"libharu",
"libjpeg-turbo",
"libpng",
"libtheora",
"libxml2",
"lz4",
"netcdf-c",
"proj4",
"pugixml",
"sqlite3",
"tiff",
"zlib"
]
}
```
## Fields
### `"name"`
The name of the port.
When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg. For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique. Verify there are no conflicts on a search engine as well as on other package collections.
Package collections to check for conflicts:
+ [Repology](https://repology.org/projects/)
+ [Debian packages](https://www.debian.org/distrib/packages)
+ [Packages search](https://pkgs.org/)
A name must be an identifier: i.e., it must only consist of lowercase ascii alphabetic characters,
numbers, and hyphens, and it must not begin nor end with a hyphen.
### Version fields
The library version. There is currently only one kind of version, a `"version-string"` -
however, more version kinds will be added later. Additionally,
`"port-version"` is used to differentiate between port changes that don't change the underlying library version.
#### `"version-string"`
This field is an ascii string, and may contain alphanumeric characters, `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as byte strings and are only evaluated for equality.
For tagged-release ports, we follow the following convention:
1. If the library follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
2. If the library includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
3. If the library is versioned by dates, format the resulting version string just like the upstream library;
for example, Abseil formats their dates `lts_2020_02_25`, so the `"version-string"` should be `"lts_2020_02_25"`.
For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
For example, given:
1. The latest commit was made on 2019-04-19
2. The current version string is `2019-02-14`
3. Today's date is 2019-06-01.
Then if you update the source version today, you should give it version `2019-06-01`.
#### `"port-version"`
The version of the port, aside from the library version.
This field is a non-negative integer.
It allows one to version the port file separately from the version of the underlying library;
if you make a change to a port, without changing the underlying version of the library,
you should increment this field by one (starting at `0`, which is equivalent to no `"port-version"` field).
When the version of the underlying library is upgraded,
this field should be set back to `0` (i.e., delete the `"port-version"` field).
#### Examples:
```json
{
"version": "1.0.5",
"port-version": 2
}
```
```json
{
"version": "2019-03-21"
}
```
### `"description"`
A description of the library.
This field can either be a single string, which should be a summary of the library,
or can be an array, with the first line being a summary and the remaining lines being the detailed description -
one string per line.
#### Examples:
```json
{
"description": "C++ header-only JSON library"
}
```
```json
{
"description": [
"Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.",
"MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model."
"This makes it suitable for 'machine to machine' messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino."
]
}
```
### `"homepage"`
The URL of the homepage for the library where a user is able to find additional documentation or the original source code.
### `"documentation"`
The URL where a user would be able to find official documentation for the library. Optional.
### `"maintainers"`
A list of strings that define the set of maintainers of a package.
It's recommended that these take the form of `Givenname Surname <email>`,
but this field is not checked for consistency.
Optional.
#### Example:
```json
{
"homepage": "https://github.com/microsoft/vcpkg"
}
```
### `"dependencies"`
An array of ports the library has a dependency on.
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.
Each dependency may be either an identifier, or an object.
For many dependencies, just listing the name of the library should be fine;
however, if one needs to add extra information to that dependency, one may use the dependency object.
For a dependency object, the `"name"` field is used to designate the library;
for example the dependency object `{ "name": "zlib" }` is equivalent to just writing `"zlib"`.
If the port is dependent on optional features of another library,
those can be specified using the `"features"` field of the dependency object.
If the port does not require any features from the dependency,
this should be specifed with the `"default-features"` fields set to `false`.
Dependencies can also be filtered based on the target triplet to support differing requirements.
These filters use the same syntax as the `"supports"` field below,
and are specified in the `"platform"` field.
#### Example:
```json
{
"dependencies": [
{
"name": "curl",
"default-features": false,
"features": [
"winssl"
],
"platform": "windows"
},
{
"name": "curl",
"default-features": false,
"features": [
"openssl"
],
"platform": "!windows"
},
"rapidjson"
]
}
```
### `"features"`
Multiple optional features can be specified in manifest files, in the `"features"` object field.
This field is a map from the feature name, to the feature's information.
Each one must have a `"description"` field, and may also optionally have a `"dependencies"` field.
A feature's name must be an identifier -
in other words, lowercase alphabetic characters, digits, and hyphens,
neither starting nor ending with a hyphen.
A feature's `"description"` is a description of the feature,
and is the same kind of thing as the port `"description"` field.
A feature's `"dependencies"` field contains the list of extra dependencies required to build and use this feature;
this field isn't required if the feature doesn't require any extra dependencies.
On installation the dependencies from all selected features are combined to produce the full dependency list for the build.
#### Example:
```json
{
"name": "vtk",
"version-string": "8.2.0",
"port-version": 2,
"description": "Software system for 3D computer graphics, image processing, and visualization",
"dependencies": [
{
"name": "atlmfc",
"platform": "windows"
},
"double-conversion",
"eigen3",
"expat",
"freetype",
"glew",
"hdf5",
"jsoncpp",
"libharu",
"libjpeg-turbo",
"libpng",
"libtheora",
"libxml2",
"lz4",
"netcdf-c",
"proj4",
"pugixml",
"sqlite3",
"tiff",
"zlib"
],
"features": {
"mpi": {
"description": "MPI functionality for VTK",
"dependencies": [
{
"name": "hdf5",
"features": [
"parallel"
]
},
"mpi"
]
},
"openvr": {
"description": "OpenVR functionality for VTK",
"dependencies": [
"openvr",
"sdl2"
]
},
"python": {
"description": "Python functionality for VTK",
"dependencies": [
"python3"
]
},
"qt": {
"description": "Qt functionality for VTK",
"dependencies": [
"qt5"
]
}
}
}
```
### `"default-features"`
An array of feature names that the library uses by default, if nothing else is specified.
#### Example:
```json
{
"default-features": [
"kinesis"
],
"features": {
"dynamodb": {
"description": "Build dynamodb support",
"dependencies": [
"dynamodb"
]
},
"kinesis": {
"description": "build kinesis support"
}
}
}
```
### `"supports"`
A string, formatted as a platform expression,
that evaluates to true when the port should build successfully for a triplet.
This field is used in the CI testing to skip ports,
and warns users in advance that a given install tree is not expected to succeed.
Therefore, this field should be used optimistically;
in cases where a port is expected to succeed 10% of the time, it should still be marked "supported".
The grammar for this top-level platform expression, in [EBNF], is as follows:
```ebnf
whitespace-character =
| ? U+0009 "CHARACTER TABULATION" ?
| ? U+000A "LINE FEED" ?
| ? U+000D "CARRIAGE RETURN" ?
| ? U+0020 "SPACE" ? ;
optional-whitespace = { whitespace-character } ;
lowercase-alpha =
| "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m"
| "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
digit =
| "0" | "1" | "2" | "3" | "4"
| "5" | "6" | "7" | "8" | "9" ;
identifier-character =
| lowercase-alpha
| digit ;
platform-expression =
| platform-expression-not
| platform-expression-and
| platform-expression-or ;
platform-expression-identifier =
| identifier-character, { identifier-character }, optional-whitespace ;
platform-expression-simple =
| platform-expression-identifier
| "(", optional-whitespace, platform-expression, ")", optional-whitespace ;
platform-expression-not =
| platform-expression-simple
| "!", optional-whitespace, platform-expression-simple ;
platform-expression-and =
| platform-expression-not, { "&", optional-whitespace, platform-expression-not } ;
platform-expression-or =
| platform-expression-not, { "|", optional-whitespace, platform-expression-not } ;
top-level-platform-expression = optional-whitespace, platform-expression ;
```
Basically, there are four kinds of expressions -- identifiers, negations, ands, and ors.
Negations may only negate an identifier or a grouped expression.
Ands and ors are a list of `&` or `|` separated identifiers, negated expressions, and grouped expressions.
One may not mix `&` and `|` without parentheses for grouping.
These predefined identifier expressions are computed from standard triplet settings:
- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"`
- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"`
- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"`
- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
These predefined identifier expressions can be overridden in the triplet file,
via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option,
and new identifier expressions can be added via the same mechanism.
This field is optional and defaults to true.
> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism.
[EBNF]: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
#### Example:
```json
{
"supports": "!uwp & !(arm & !arm64)"
}
```
This means "doesn't support uwp, nor arm32 (but does support arm64)".

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

@ -0,0 +1,48 @@
<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
# Portfile helper functions
- [execute\_process](execute_process.md)
- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
- [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
- [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
- [vcpkg\_build\_gn](vcpkg_build_gn.md)
- [vcpkg\_build\_make](vcpkg_build_make.md)
- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
- [vcpkg\_build\_ninja](vcpkg_build_ninja.md)
- [vcpkg\_build\_nmake](vcpkg_build_nmake.md)
- [vcpkg\_check\_features](vcpkg_check_features.md)
- [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
- [vcpkg\_clean\_executables\_in\_bin](vcpkg_clean_executables_in_bin.md)
- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
- [vcpkg\_configure\_gn](vcpkg_configure_gn.md)
- [vcpkg\_configure\_make](vcpkg_configure_make.md)
- [vcpkg\_configure\_meson](vcpkg_configure_meson.md)
- [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
- [vcpkg\_copy\_tools](vcpkg_copy_tools.md)
- [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
- [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
- [vcpkg\_execute\_build\_process](vcpkg_execute_build_process.md)
- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
- [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)
- [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)
- [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md)
- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md)
- [vcpkg\_fixup\_pkgconfig](vcpkg_fixup_pkgconfig.md)
- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
- [vcpkg\_from\_git](vcpkg_from_git.md)
- [vcpkg\_from\_github](vcpkg_from_github.md)
- [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)
- [vcpkg\_from\_sourceforge](vcpkg_from_sourceforge.md)
- [vcpkg\_install\_cmake](vcpkg_install_cmake.md)
- [vcpkg\_install\_gn](vcpkg_install_gn.md)
- [vcpkg\_install\_make](vcpkg_install_make.md)
- [vcpkg\_install\_meson](vcpkg_install_meson.md)
- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)
- [vcpkg\_install\_nmake](vcpkg_install_nmake.md)
- [vcpkg\_install\_qmake](vcpkg_install_qmake.md)
- [vcpkg\_prettify\_command](vcpkg_prettify_command.md)
- [vcpkg\_test\_cmake](vcpkg_test_cmake.md)

115
vcpkg/docs/maintainers/pr-review-checklist.md Normal file
View File

@ -0,0 +1,115 @@
Vcpkg PR Checklist
=====================
Revision: 1
## Overview
This document provides an annotated checklist which vcpkg team members use to apply the "reviewed" label on incoming pull requests. If a pull request violates any of these points, we may ask contributors to make necessary changes before we can merge the changeset.
Feel free to create an issue or pull request if you feel that this checklist can be improved. Please increment the revision number when modifying the checklist content.
## Checklist
You can link any of these checklist items in a GitHub comment by copying the link address attached to each item code.
<details id="c000001">
<summary><a href="#c000001">c000001</a>: No deprecated helper functions are used</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#Avoid-deprecated-helper-functions) for more information.
</details>
<details id="c000002">
<summary><a href="#c000002">c000002</a>: `"port-version"` field is updated</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#versioning) for more information.
</details>
<details id="c000003">
<summary><a href="#c000003">c000003</a>: New ports contain a `"description"` field written in English</summary>
A description only one or a few sentences long is helpful. Consider using the library's official description from their `README.md` or similar if possible. Automatic translations are acceptable and we are happy to clean up translations to English for our contributors.
See our [manifest file documentation](manifest-files.md#description) for more information.
</details>
<details id="c000004">
<summary><a href="#c000004">c000004</a>: No unnecessary comments are present in the changeset</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#Avoid-excessive-comments-in-portfiles) for more information.
</details>
<details id="c000005">
<summary><a href="#c000005">c000005</a>: Downloaded archives are versioned if available</summary
To ensure archive content does not change, archives downloaded preferably have an associated version tag that can be incremented alongside the port's `"version"`.
</details>
<details id="c000006">
<summary><a href="#c000006">c000006</a>: New ports pass CI checks for triplets that the library officially supports</summary>
To ensure vcpkg ports are of a high quality, we ask that incoming ports support the official platforms for the library in question.
</details>
<details id="c000007">
<summary><a href="#c000007">c000007</a>: Patches fix issues that are vcpkg-specific only</summary>
If possible, patches to the library source code should be upstreamed to the library's official repository. Opening up a pull request on the library's repository will help to improve the library for everyone, not just vcpkg users.
</details>
<details id="c000008">
<summary><a href="#c000008">c000008</a>: New ports download source code from the official source if available</summary>
To respect library authors and keep code secure, please have ports download source code from the official source. We may make exceptions if the original source code is not available and there is substantial community interest in maintaining the library in question.
</details>
<details id="c000009">
<summary><a href="#c000009">c000009</a>: Ports and port features are named correctly</summary>
For user accessibility, we prefer names of ports and port features to be intuitive and close to their counterparts in official sources and other package managers. If you are unsure about the naming of a port or port feature, we recommend checking repology.org, packages.ubuntu.com, or searching for additional information using a search engine. We can also help our contributors with this, so feel free to ask for naming suggestions if you are unsure.
</details>
<details id="c000010">
<summary><a href="#c000010">c000010</a>: Library targets are exported when appropriate</summary>
To provide users with a seamless build system integration, please be sure to export and provide a means of finding the library targets intended to be used downstream. Targets not meant to be exported should be be marked private and not exported.
</details>
<details id="c000011">
<summary><a href="#c000011">c000011</a>: Ports do not use applications which modify the user's system</summary>
Ports should uphold vcpkg's contract of not modifying the user's system by avoiding applications which do so. Examples of these applications are `sudo`, `apt`, `brew`, or `pip`. Please use an alternative to these types of programs wherever possible.
</details>
<details id="c000012">
<summary><a href="#c000012">c000012</a>: Ports with system dependencies include an information message during installation</summary>
Some ports have library and tool dependencies that do not exist within vcpkg. For these missing dependencies, we ask that contributors add a message to the top of the port's `portfile.cmake` stating the missing dependencies and how to acquire them. We ask that the message is displayed before any major work is done to ensure that users can "early out" of the installation process as soon as possible in case they are missing the dependency.
Example:
```cmake
message(
"${PORT} currently requires the following libraries from the system package manager:
autoconf libtool
These can be installed on Ubuntu systems via sudo apt install autoconf libtool"
)
```
</details>
<details id="c000013">
<summary><a href="#c000013">c000013</a>: Manifest files are used instead of CONTROL files for new ports</summary>
Many existing ports use the CONTROL file syntax; while this syntax will be supported for some time to come,
new ports should not use these. Any newly added port _must_ use the manifest files.
We also recommend, when significant modifications are made to ports, that one switches to manifest files;
however, this is not required. You may find `vcpkg format-manifest` useful.

39
vcpkg/docs/maintainers/vcpkg_acquire_msys.md Normal file
View File

@ -0,0 +1,39 @@
# vcpkg_acquire_msys
Download and prepare an MSYS2 instance.
## Usage
```cmake
vcpkg_acquire_msys(<MSYS_ROOT_VAR> [PACKAGES <package>...])
```
## Parameters
### MSYS_ROOT_VAR
An out-variable that will be set to the path to MSYS2.
### PACKAGES
A list of packages to acquire in msys.
To ensure a package is available: `vcpkg_acquire_msys(MSYS_ROOT PACKAGES make automake1.15)`
## 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
)
```
## 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)

26
vcpkg/docs/maintainers/vcpkg_add_to_path.md Normal file
View File

@ -0,0 +1,26 @@
# vcpkg_add_to_path
Add a directory to the PATH environment variable
## Usage
```cmake
vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)
```
## Parameters
### <positional>
The directory to add
### PREPEND
Prepends the directory.
The default is to append.
## Examples:
* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
## Source
[scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)

34
vcpkg/docs/maintainers/vcpkg_apply_patches.md Normal file
View File

@ -0,0 +1,34 @@
# vcpkg_apply_patches
Apply a set of patches to a source tree. This function is deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
## 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
* [libbson](https://github.com/Microsoft/vcpkg/blob/master/ports/libbson/portfile.cmake)
* [gdal](https://github.com/Microsoft/vcpkg/blob/master/ports/gdal/portfile.cmake)
## Source
[scripts/cmake/vcpkg_apply_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)

34
vcpkg/docs/maintainers/vcpkg_build_cmake.md Normal file
View File

@ -0,0 +1,34 @@
# vcpkg_build_cmake
Build a cmake project.
## Usage:
```cmake
vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>])
```
## Parameters:
### DISABLE_PARALLEL
The underlying buildsystem will be instructed to not parallelize
### TARGET
The target passed to the cmake build command (`cmake --build . --target <target>`). If not specified, no target will
be passed.
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs.
## Notes:
This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
"install" target
## 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_build_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)

17
vcpkg/docs/maintainers/vcpkg_build_gn.md Normal file
View File

@ -0,0 +1,17 @@
# vcpkg_build_gn
Build a GN project
## Usage:
```cmake
vcpkg_build_gn(
[TARGETS <target>...]
)
```
## Parameters:
### TARGETS
Only build the specified targets.
## Source
[scripts/cmake/vcpkg_build_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_gn.cmake)

40
vcpkg/docs/maintainers/vcpkg_build_make.md Normal file
View File

@ -0,0 +1,40 @@
# vcpkg_build_make
Build a linux makefile project.
## Usage:
```cmake
vcpkg_build_make([BUILD_TARGET <target>]
[ADD_BIN_TO_PATH]
[ENABLE_INSTALL])
[LOGFILE_ROOT <logfileroot>])
```
### BUILD_TARGET
The target passed to the make build command (`./make <target>`). If not specified, the 'all' target will
be passed.
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs.
### ENABLE_INSTALL
IF the port supports the install target use vcpkg_install_make() instead of vcpkg_build_make()
### BUILD_TARGET
The target passed to the make build command (`./make <target>`). If not specified, the 'all' target will
be passed.
## Notes:
This command should be preceeded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md).
You can use the alias [`vcpkg_install_make()`](vcpkg_configure_make.md) function if your CMake script supports the
"install" target
## Examples
* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
## Source
[scripts/cmake/vcpkg_build_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)

65
vcpkg/docs/maintainers/vcpkg_build_msbuild.md Normal file
View File

@ -0,0 +1,65 @@
# vcpkg_build_msbuild
Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
## 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>...]
[USE_VCPKG_INTEGRATION]
)
```
## Parameters
### USE_VCPKG_INTEGRATION
Apply the normal `integrate install` integration for building the project.
By default, projects built with this command will not automatically link libraries or have header paths set.
### 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
* [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake)
* [cppunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cppunit/portfile.cmake)
## Source
[scripts/cmake/vcpkg_build_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)

17
vcpkg/docs/maintainers/vcpkg_build_ninja.md Normal file
View File

@ -0,0 +1,17 @@
# vcpkg_build_ninja
Build a ninja project
## Usage:
```cmake
vcpkg_build_ninja(
[TARGETS <target>...]
)
```
## Parameters:
### TARGETS
Only build the specified targets.
## Source
[scripts/cmake/vcpkg_build_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake)

75
vcpkg/docs/maintainers/vcpkg_build_nmake.md Normal file
View File

@ -0,0 +1,75 @@
# vcpkg_build_nmake
Build a msvc makefile project.
## Usage:
```cmake
vcpkg_build_nmake(
SOURCE_PATH <${SOURCE_PATH}>
[NO_DEBUG]
[PROJECT_SUBPATH <${SUBPATH}>]
[PROJECT_NAME <${MAKEFILE_NAME}>]
[PRERUN_SHELL <${SHELL_PATH}>]
[PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
[PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
[TARGET <target>])
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the source files.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PROJECT_SUBPATH
Specifies the sub directory containing the `makefile.vc`/`makefile.mak`/`makefile.msvc` or other msvc makefile.
### PROJECT_NAME
Specifies the name of msvc makefile name.
Default is `makefile.vc`
### NO_DEBUG
This port doesn't support debug mode.
### ENABLE_INSTALL
Install binaries after build.
### PRERUN_SHELL
Script that needs to be called before build
### PRERUN_SHELL_DEBUG
Script that needs to be called before debug build
### PRERUN_SHELL_RELEASE
Script that needs to be called before release build
### OPTIONS
Additional options passed to generate during the generation.
### OPTIONS_RELEASE
Additional options passed to generate during the Release generation. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`.
### TARGET
The target passed to the nmake build command (`nmake/nmake install`). If not specified, no target will
be passed.
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs.
## Notes:
This command should be preceeded by a call to [`vcpkg_configure_nmake()`](vcpkg_configure_nmake.md).
You can use the alias [`vcpkg_install_nmake()`](vcpkg_configure_nmake.md) function if your CMake script supports the
"install" target
## Examples
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
## Source
[scripts/cmake/vcpkg_build_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)

148
vcpkg/docs/maintainers/vcpkg_check_features.md Normal file
View File

@ -0,0 +1,148 @@
# vcpkg_check_features
Check if one or more features are a part of a package installation.
## Usage
```cmake
vcpkg_check_features(
OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>
[FEATURES
<cuda> <WITH_CUDA>
[<opencv> <WITH_OPENCV>]
...]
[INVERTED_FEATURES
<cuda> <IGNORE_PACKAGE_CUDA>
[<opencv> <IGNORE_PACKAGE_OPENCV>]
...]
)
```
`vcpkg_check_features()` accepts these parameters:
* `OUT_FEATURE_OPTIONS`:
An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS`
and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`).
This should be set to `FEATURE_OPTIONS` by convention.
* `FEATURES`:
A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.
For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
* `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
* `-D<OPTION_NAME>=OFF`, otherwise.
* `INVERTED_FEATURES`:
A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.
For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
* `-D<OPTION_NAME>=OFF`, if a feature is specified for installation,
* `-D<OPTION_NAME>=ON`, otherwise.
## Notes
The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used.
At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call.
Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication.
If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists,
two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
## Examples
### Example 1: Regular features
```cmake
$ ./vcpkg install mimalloc[asm,secure]
# ports/mimalloc/portfile.cmake
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
# Keyword FEATURES is optional if INVERTED_FEATURES are not used
asm MI_SEE_ASM
override MI_OVERRIDE
secure MI_SECURE
)
vcpkg_configure_cmake(
SOURCE_PATH ${SOURCE_PATH}
PREFER_NINJA
OPTIONS
# Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
${FEATURE_OPTIONS}
)
```
### Example 2: Inverted features
```cmake
$ ./vcpkg install cpprestsdk[websockets]
# ports/cpprestsdk/portfile.cmake
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
brotli CPPREST_EXCLUDE_BROTLI
websockets CPPREST_EXCLUDE_WEBSOCKETS
)
vcpkg_configure_cmake(
SOURCE_PATH ${SOURCE_PATH}
PREFER_NINJA
OPTIONS
# Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
${FEATURE_OPTIONS}
)
```
### Example 3: Set multiple options for same feature
```cmake
$ ./vcpkg install pcl[cuda]
# ports/pcl/portfile.cmake
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
cuda WITH_CUDA
cuda BUILD_CUDA
cuda BUILD_GPU
)
vcpkg_configure_cmake(
SOURCE_PATH ${SOURCE_PATH}
PREFER_NINJA
OPTIONS
# Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
${FEATURE_OPTIONS}
)
```
### Example 4: Use regular and inverted features
```cmake
$ ./vcpkg install rocksdb[tbb]
# ports/rocksdb/portfile.cmake
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
tbb WITH_TBB
INVERTED_FEATURES
tbb ROCKSDB_IGNORE_PACKAGE_TBB
)
vcpkg_configure_cmake(
SOURCE_PATH ${SOURCE_PATH}
PREFER_NINJA
OPTIONS
# Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
${FEATURE_OPTIONS}
)
```
## Examples in portfiles
* [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
* [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
## Source
[scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)

34
vcpkg/docs/maintainers/vcpkg_check_linkage.md Normal file
View File

@ -0,0 +1,34 @@
# vcpkg_check_linkage
Asserts the available library and CRT linkage options for the port.
## Usage
```cmake
vcpkg_check_linkage(
[ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY]
[ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT]
)
```
## Parameters
### ONLY_STATIC_LIBRARY
Indicates that this port can only be built with static library linkage.
### ONLY_DYNAMIC_LIBRARY
Indicates that this port can only be built with dynamic/shared library linkage.
### ONLY_STATIC_CRT
Indicates that this port can only be built with static CRT linkage.
### ONLY_DYNAMIC_CRT
Indicates that this port can only be built with dynamic/shared CRT linkage.
## Notes
This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail, depending on what was requested by the user versus what the library supports.
## Examples
* [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake)
## Source
[scripts/cmake/vcpkg_check_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake)

23
vcpkg/docs/maintainers/vcpkg_clean_executables_in_bin.md Normal file
View File

@ -0,0 +1,23 @@
# vcpkg_clean_executables_in_bin
Remove specified executables found in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. If, after all specified executables have been removed, and the `bin` and `debug/bin` directories are empty, then also delete `bin` and `debug/bin` directories.
## Usage
```cmake
vcpkg_clean_executables_in_bin(
FILE_NAMES <file1>...
)
```
## Parameters
### FILE_NAMES
A list of executable filenames without extension.
## Notes
Generally, there is no need to call this function manually. Instead, pass an extra `AUTO_CLEAN` argument when calling `vcpkg_copy_tools`.
## Examples
* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
## Source
[scripts/cmake/vcpkg_clean_executables_in_bin.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_executables_in_bin.cmake)

15
vcpkg/docs/maintainers/vcpkg_clean_msbuild.md Normal file
View File

@ -0,0 +1,15 @@
# vcpkg_clean_msbuild
Clean intermediate files generated by `vcpkg_install_msbuild()`.
## Usage
```cmake
vcpkg_clean_msbuild()
```
## Examples
* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
## Source
[scripts/cmake/vcpkg_clean_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)

28
vcpkg/docs/maintainers/vcpkg_common_definitions.md Normal file
View File

@ -0,0 +1,28 @@
# vcpkg_common_definitions
File contains helpful variabls for portfiles which are commonly needed or used.
## The following variables are available:
```cmake
VCPKG_TARGET_IS_<target> with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD. only defined if <target>
VCPKG_HOST_PATH_SEPARATOR Host specific path separator (USAGE: "<something>${VCPKG_HOST_PATH_SEPARATOR}<something>"; only use and pass variables with VCPKG_HOST_PATH_SEPARATOR within "")
VCPKG_HOST_EXECUTABLE_SUFFIX executable suffix of the host
VCPKG_TARGET_EXECUTABLE_SUFFIX executable suffix of the target
VCPKG_TARGET_STATIC_LIBRARY_PREFIX static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX)
VCPKG_TARGET_STATIC_LIBRARY_SUFFIX static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX)
VCPKG_TARGET_SHARED_LIBRARY_PREFIX shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX)
VCPKG_TARGET_SHARED_LIBRARY_SUFFIX shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX)
VCPKG_TARGET_IMPORT_LIBRARY_PREFIX import library prefix for target (same as CMAKE_IMPORT_LIBRARY_PREFIX)
VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX import library suffix for target (same as CMAKE_IMPORT_LIBRARY_SUFFIX)
VCPKG_FIND_LIBRARY_PREFIXES target dependent prefixes used for find_library calls in portfiles
VCPKG_FIND_LIBRARY_SUFFIXES target dependent suffixes used for find_library calls in portfiles
VCPKG_SYSTEM_LIBRARIES list of libraries are provide by the toolchain and are not managed by vcpkg
```
CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and CMAKE_IMPORT_LIBRARY_(PREFIX|SUFFIX) are defined for the target
Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also defined for the target so that
portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
## Source
[scripts/cmake/vcpkg_common_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)

65
vcpkg/docs/maintainers/vcpkg_configure_cmake.md Normal file
View File

@ -0,0 +1,65 @@
# vcpkg_configure_cmake
Configure CMake for Debug and Release builds of a project.
## Usage
```cmake
vcpkg_configure_cmake(
SOURCE_PATH <${SOURCE_PATH}>
[PREFER_NINJA]
[DISABLE_PARALLEL_CONFIGURE]
[NO_CHARSET_FLAG]
[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.
### DISABLE_PARALLEL_CONFIGURE
Disables running the CMake configure step in parallel.
This is needed for libraries which write back into their source directory during configure.
This also disables CMAKE_DISABLE_SOURCE_CHANGES.
### NO_CHARSET_FLAG
Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`.
This is needed for libraries that set their own source code's character set.
### 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)

30
vcpkg/docs/maintainers/vcpkg_configure_gn.md Normal file
View File

@ -0,0 +1,30 @@
# vcpkg_configure_gn
Generate Ninja (GN) targets
## Usage:
```cmake
vcpkg_configure_gn(
SOURCE_PATH <SOURCE_PATH>
[OPTIONS <OPTIONS>]
[OPTIONS_DEBUG <OPTIONS_DEBUG>]
[OPTIONS_RELEASE <OPTIONS_RELEASE>]
)
```
## Parameters:
### SOURCE_PATH (required)
The path to the GN project.
### OPTIONS
Options to be passed to both the debug and release targets.
Note: Must be provided as a space-separated string.
### OPTIONS_DEBUG (space-separated string)
Options to be passed to the debug target.
### OPTIONS_RELEASE (space-separated string)
Options to be passed to the release target.
## Source
[scripts/cmake/vcpkg_configure_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_gn.cmake)

58
vcpkg/docs/maintainers/vcpkg_configure_make.md Normal file
View File

@ -0,0 +1,58 @@
# vcpkg_configure_make
Configure configure for Debug and Release builds of a project.
## Usage
```cmake
vcpkg_configure_make(
SOURCE_PATH <${SOURCE_PATH}>
[AUTOCONFIG]
[NO_DEBUG]
[SKIP_CONFIGURE]
[PROJECT_SUBPATH <${PROJ_SUBPATH}>]
[PRERUN_SHELL <${SHELL_PATH}>]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
)
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the `configure`/`configure.ac`.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PROJECT_SUBPATH
Specifies the directory containing the ``configure`/`configure.ac`.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### SKIP_CONFIGURE
Skip configure process
### AUTOCONFIG
Need to use autoconfig to generate configure file.
### PRERUN_SHELL
Script that needs to be called before configuration (do not use for batch files which simply call autoconf or configure)
### OPTIONS
Additional options passed to configure during the configuration.
### OPTIONS_RELEASE
Additional options passed to configure during the Release configuration. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to configure during the Debug configuration. These are in addition to `OPTIONS`.
## Notes
This command supplies many common arguments to configure. To see the full list, examine the source.
## Examples
* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
## Source
[scripts/cmake/vcpkg_configure_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)

38
vcpkg/docs/maintainers/vcpkg_configure_meson.md Normal file
View File

@ -0,0 +1,38 @@
# vcpkg_configure_meson
Configure Meson for Debug and Release builds of a project.
## Usage
```cmake
vcpkg_configure_meson(
SOURCE_PATH <${SOURCE_PATH}>
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
)
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the `meson.build`.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### OPTIONS
Additional options passed to Meson during the configuration.
### OPTIONS_RELEASE
Additional options passed to Meson during the Release configuration. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to Meson during the Debug configuration. These are in addition to `OPTIONS`.
## Notes
This command supplies many common arguments to Meson. To see the full list, examine the source.
## Examples
* [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
* [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
## Source
[scripts/cmake/vcpkg_configure_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake)

25
vcpkg/docs/maintainers/vcpkg_copy_pdbs.md Normal file
View File

@ -0,0 +1,25 @@
# vcpkg_copy_pdbs
Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
## Usage
```cmake
vcpkg_copy_pdbs([BUILD_PATHS <${CURRENT_PACKAGES_DIR}/bin/*.dll> ...])
```
## Notes
This command should always be called by portfiles after they have finished rearranging the binary output.
## Parameters
### BUILD_PATHS
Path patterns passed to `file(GLOB_RECURSE)` for locating dlls.
Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`.
## 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
vcpkg/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)

30
vcpkg/docs/maintainers/vcpkg_copy_tools.md Normal file
View File

@ -0,0 +1,30 @@
# vcpkg_copy_tools
Copy tools and all their DLL dependencies into the `tools` folder.
## Usage
```cmake
vcpkg_copy_tools(
TOOL_NAMES <tool1>...
[SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>]
[AUTO_CLEAN]
)
```
## Parameters
### TOOL_NAMES
A list of tool filenames without extension.
### SEARCH_DIR
The path to the directory containing the tools. This will be set to `${CURRENT_PACKAGES_DIR}/bin` if ommited.
### AUTO_CLEAN
Auto clean executables in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`.
## Examples
* [cpuinfo](https://github.com/microsoft/vcpkg/blob/master/ports/cpuinfo/portfile.cmake)
* [nanomsg](https://github.com/microsoft/vcpkg/blob/master/ports/nanomsg/portfile.cmake)
* [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake)
## Source
[scripts/cmake/vcpkg_copy_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake)

51
vcpkg/docs/maintainers/vcpkg_download_distfile.md Normal file
View File

@ -0,0 +1,51 @@
# vcpkg_download_distfile
Download and cache a file needed for this port.
This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
## 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.
### SKIP_SHA512
Skip SHA512 hash check for file.
This switch is only valid when building with the `--head` command line flag.
### HEADERS
A list of headers to append to the download request. This can be used for authentication during a download.
Headers should be specified as "<header-name>: <header-value>".
## Notes
The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
## Examples
* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)
* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
## Source
[scripts/cmake/vcpkg_download_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)

36
vcpkg/docs/maintainers/vcpkg_execute_build_process.md Normal file
View File

@ -0,0 +1,36 @@
# vcpkg_execute_build_process
Execute a required build process
## Usage
```cmake
vcpkg_execute_build_process(
COMMAND <cmd> [<args>...]
[NO_PARALLEL_COMMAND <cmd> [<args>...]]
WORKING_DIRECTORY </path/to/dir>
LOGNAME <log_name>)
)
```
## Parameters
### COMMAND
The command to be executed, along with its arguments.
### NO_PARALLEL_COMMAND
Optional parameter which specifies a non-parallel command to attempt if a
failure potentially due to parallelism is detected.
### 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
* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
## Source
[scripts/cmake/vcpkg_execute_build_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)

37
vcpkg/docs/maintainers/vcpkg_execute_required_process.md Normal file
View File

@ -0,0 +1,37 @@
# 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
### ALLOW_IN_DOWNLOAD_MODE
Allows the command to execute in Download Mode.
[See execute_process() override](../../scripts/cmake/execute_process.cmake).
### 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
vcpkg/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. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md).
## 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)

56
vcpkg/docs/maintainers/vcpkg_extract_source_archive_ex.md Normal file
View File

@ -0,0 +1,56 @@
# vcpkg_extract_source_archive_ex
Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md).
## Usage
```cmake
vcpkg_extract_source_archive_ex(
SKIP_PATCH_CHECK
OUT_SOURCE_PATH <SOURCE_PATH>
ARCHIVE <${ARCHIVE}>
[REF <1.0.0>]
[NO_REMOVE_ONE_LEVEL]
[WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/src>]
[PATCHES <a.patch>...]
)
```
## Parameters
### SKIP_PATCH_CHECK
If this option is set the failure to apply a patch is ignored.
### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.
This should be set to `SOURCE_PATH` by convention.
### ARCHIVE
The full path to the archive to be extracted.
This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
### REF
A friendly name that will be used instead of the filename of the archive. If more than 10 characters it will be truncated.
By convention, this is set to the version number or tag fetched
### WORKING_DIRECTORY
If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
### NO_REMOVE_ONE_LEVEL
Specifies that the default removal of the top level folder should not occur.
## Examples
* [bzip2](https://github.com/Microsoft/vcpkg/blob/master/ports/bzip2/portfile.cmake)
* [sqlite3](https://github.com/Microsoft/vcpkg/blob/master/ports/sqlite3/portfile.cmake)
* [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake)
## Source
[scripts/cmake/vcpkg_extract_source_archive_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)

41
vcpkg/docs/maintainers/vcpkg_fail_port_install.md Normal file
View File

@ -0,0 +1,41 @@
# vcpkg_fail_port_install
Checks common requirements and fails the current portfile with a (default) error message
## Usage
```cmake
vcpkg_fail_port_install(
[ALWAYS]
[MESSAGE <"Reason for failure">]
[ON_TARGET <Windows> [<OSX> ...]]
[ON_ARCH <x64> [<arm> ...]]
[ON_CRT_LINKAGE <static> [<dynamic> ...]])
[ON_LIBRARY_LINKAGE <static> [<dynamic> ...]]
)
```
## Parameters
### MESSAGE
Additional failure message. If none is given, a default message will be displayed depending on the failure condition.
### ALWAYS
Will always fail early
### ON_TARGET
Targets for which the build should fail early. Valid targets are `<target>` from `VCPKG_IS_TARGET_<target>` (see `vcpkg_common_definitions.cmake`).
### ON_ARCH
Architecture for which the build should fail early.
### ON_CRT_LINKAGE
CRT linkage for which the build should fail early.
### ON_LIBRARY_LINKAGE
Library linkage for which the build should fail early.
## Examples
* [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
## Source
[scripts/cmake/vcpkg_fail_port_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)

48
vcpkg/docs/maintainers/vcpkg_find_acquire_program.md Normal file
View File

@ -0,0 +1,48 @@
# 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
- ARIA2 (Downloader)
- BISON
- CLANG
- DARK
- DOXYGEN
- FLEX
- GASPREPROCESSOR
- GPERF
- PERL
- PYTHON2
- PYTHON3
- GIT
- GN
- GO
- JOM
- MESON
- NASM
- NINJA
- NUGET
- SCONS
- 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)

47
vcpkg/docs/maintainers/vcpkg_fixup_cmake_targets.md Normal file
View File

@ -0,0 +1,47 @@
# vcpkg_fixup_cmake_targets
Merge release and debug CMake targets and configs to support multiconfig generators.
Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
## Usage
```cmake
vcpkg_fixup_cmake_targets([CONFIG_PATH <share/${PORT}>] [TARGET_PATH <share/${PORT}>] [DO_NOT_DELETE_PARENT_CONFIG_PATH])
```
## Parameters
### CONFIG_PATH
Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`.
Defaults to `share/${PORT}`.
### TARGET_PATH
Subpath to which the above `*.cmake` files should be moved. Should be relative to `${CURRENT_PACKAGES_DIR}`.
This needs to be specified if the port name differs from the `find_package()` name.
Defaults to `share/${PORT}`.
### DO_NOT_DELETE_PARENT_CONFIG_PATH
By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
Passing this option disable such behavior, as it is convenient for ports that install
more than one CMake package configuration file.
## Notes
Transform all `/debug/<CONFIG_PATH>/*targets-debug.cmake` files and move them to `/<TARGET_PATH>`.
Removes all `/debug/<CONFIG_PATH>/*targets.cmake` and `/debug/<CONFIG_PATH>/*config.cmake`.
Transform all references matching `/bin/*.exe` to `/tools/<port>/*.exe` on Windows.
Transform all references matching `/bin/*` to `/tools/<port>/*` on other platforms.
Fix `${_IMPORT_PREFIX}` in auto generated targets to be one folder deeper.
Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets.
## Examples
* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake)
* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
## Source
[scripts/cmake/vcpkg_fixup_cmake_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)

42
vcpkg/docs/maintainers/vcpkg_fixup_pkgconfig.md Normal file
View File

@ -0,0 +1,42 @@
# vcpkg_fixup_pkgconfig
Fix common paths in *.pc files and make everything relativ to $(prefix)
## Usage
```cmake
vcpkg_fixup_pkgconfig(
[RELEASE_FILES <PATHS>...]
[DEBUG_FILES <PATHS>...]
[SYSTEM_LIBRARIES <NAMES>...]
)
```
## Parameters
### RELEASE_FILES
Specifies a list of files to apply the fixes for release paths.
Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR} without ${CURRENT_PACKAGES_DIR}/debug/
### DEBUG_FILES
Specifies a list of files to apply the fixes for debug paths.
Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR}/debug/
### SYSTEM_PACKAGES
If the *.pc file contains system packages outside vcpkg these need to be listed here.
Since vcpkg checks the existence of all required packages within vcpkg.
### SYSTEM_LIBRARIES
If the *.pc file contains system libraries outside vcpkg these need to be listed here.
VCPKG checks every -l flag for the existence of the required library within vcpkg.
### IGNORE_FLAGS
If the *.pc file contains flags in the lib field which are not libraries. These can be listed here
## Notes
Still work in progress. If there are more cases which can be handled here feel free to add them
## Examples
Just call vcpkg_fixup_pkgconfig() after any install step which installs *.pc files.
## Source
[scripts/cmake/vcpkg_fixup_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)

59
vcpkg/docs/maintainers/vcpkg_from_bitbucket.md Normal file
View File

@ -0,0 +1,59 @@
# vcpkg_from_bitbucket
Download and extract a project from Bitbucket.
Enables support for installing HEAD `vcpkg.exe install --head <port>`.
## Usage:
```cmake
vcpkg_from_bitbucket(
OUT_SOURCE_PATH <SOURCE_PATH>
REPO <Microsoft/cpprestsdk>
[REF <v2.0.0>]
[SHA512 <45d0d7f8cc350...>]
[HEAD_REF <master>]
[PATCHES <patch1.patch> <patch2.patch>...]
)
```
## 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. **This should not be a branch.**
For repositories without official releases, this can be set to the full commit id of the current latest master.
If `REF` is specified, `SHA512` must also be specified.
### SHA512
The SHA512 hash that should match the archive (https://bitbucket.com/${REPO}/get/${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.
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
## Notes:
At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
This exports the `VCPKG_HEAD_VERSION` variable during head builds.
## Examples:
* [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
## Source
[scripts/cmake/vcpkg_from_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)

40
vcpkg/docs/maintainers/vcpkg_from_git.md Normal file
View File

@ -0,0 +1,40 @@
# vcpkg_from_git
Download and extract a project from git
## Usage:
```cmake
vcpkg_from_git(
OUT_SOURCE_PATH <SOURCE_PATH>
URL <https://android.googlesource.com/platform/external/fdlibm>
REF <59f7335e4d...>
[PATCHES <patch1.patch> <patch2.patch>...]
)
```
## Parameters:
### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.
This should be set to `SOURCE_PATH` by convention.
### URL
The url of the git repository.
### REF
The git sha of the commit to download.
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
## Notes:
`OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
## Examples:
* [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
## Source
[scripts/cmake/vcpkg_from_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake)

70
vcpkg/docs/maintainers/vcpkg_from_github.md Normal file
View File

@ -0,0 +1,70 @@
# 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>]
[PATCHES <patch1.patch> <patch2.patch>...]
[GITHUB_HOST <https://github.com>]
[AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>]
)
```
## 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 or commit) that will not change contents. **This should not be a branch.**
For repositories without official releases, this can be set to the full commit id of the current latest master.
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.
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
### GITHUB_HOST
A replacement host for enterprise GitHub instances.
This field should contain the scheme, host, and port of the desired URL without a trailing slash.
### AUTHORIZATION_TOKEN
A token to be passed via the Authorization HTTP header as "token ${AUTHORIZATION_TOKEN}".
## Notes:
At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
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)

66
vcpkg/docs/maintainers/vcpkg_from_gitlab.md Normal file
View File

@ -0,0 +1,66 @@
# vcpkg_from_gitlab
Download and extract a project from Gitlab instances. Enables support for `install --head`.
## Usage:
```cmake
vcpkg_from_gitlab(
GITLAB_URL <https://gitlab.com>
OUT_SOURCE_PATH <SOURCE_PATH>
REPO <gitlab-org/gitlab-ce>
[REF <v10.7.3>]
[SHA512 <45d0d7f8cc350...>]
[HEAD_REF <master>]
[PATCHES <patch1.patch> <patch2.patch>...]
)
```
## Parameters:
### GITLAB_URL
The URL of the Gitlab instance to use.
### 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 plus the repository name on the Gitlab instance.
### REF
A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
For repositories without official releases, this can be set to the full commit id of the current latest master.
If `REF` is specified, `SHA512` must also be specified.
### SHA512
The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz).
The REPO_NAME variable is parsed from the value of REPO.
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.
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
## Notes:
At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
This exports the `VCPKG_HEAD_VERSION` variable during head builds.
## Examples:
* [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
## Source
[scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)

68
vcpkg/docs/maintainers/vcpkg_from_sourceforge.md Normal file
View File

@ -0,0 +1,68 @@
# vcpkg_from_sourceforge
Download and extract a project from sourceforge.
## Usage:
```cmake
vcpkg_from_sourceforge(
OUT_SOURCE_PATH SOURCE_PATH
REPO <cunit/CUnit>
[REF <2.1-3>]
SHA512 <547b417109332...>
FILENAME <CUnit-2.1-3.tar.bz2>
[DISABLE_SSL]
[NO_REMOVE_ONE_LEVEL]
[PATCHES <patch1.patch> <patch2.patch>...]
)
```
## 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 (optional) on sourceforge.
### REF
A stable version number that will not change contents.
### 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.
For example, we can get the download link:
https://sourceforge.net/settings/mirror_choices?projectname=mad&filename=libmad/0.15.1b/libmad-0.15.1b.tar.gz&selected=nchc
So the REPO is `mad/libmad`, the REF is `0.15.1b`, and the FILENAME is `libmad-0.15.1b.tar.gz`
For some special links:
https://sourceforge.net/settings/mirror_choices?projectname=soxr&filename=soxr-0.1.3-Source.tar.xz&selected=nchc
The REPO is `soxr`, REF is not exist, and the FILENAME is `soxr-0.1.3-Source.tar.xz`
### SHA512
The SHA512 hash that should match the archive.
### WORKING_DIRECTORY
If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
### DISABLE_SSL
Disable ssl when downloading source.
### NO_REMOVE_ONE_LEVEL
Specifies that the default removal of the top level folder should not occur.
## Examples:
* [cunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cunit/portfile.cmake)
* [polyclipping](https://github.com/Microsoft/vcpkg/blob/master/ports/polyclipping/portfile.cmake)
* [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake)
## Source
[scripts/cmake/vcpkg_from_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake)

25
vcpkg/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(...)
```
## Parameters:
See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md).
## Notes:
This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install`
parameter.
## 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)

23
vcpkg/docs/maintainers/vcpkg_install_gn.md Normal file
View File

@ -0,0 +1,23 @@
# vcpkg_install_gn
Installs a GN project
## Usage:
```cmake
vcpkg_install_gn(
SOURCE_PATH <SOURCE_PATH>
[TARGETS <target>...]
)
```
## Parameters:
### SOURCE_PATH
The path to the source directory
### TARGETS
Only install the specified targets.
Note: includes must be handled separately
## Source
[scripts/cmake/vcpkg_install_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake)

24
vcpkg/docs/maintainers/vcpkg_install_make.md Normal file
View File

@ -0,0 +1,24 @@
# vcpkg_install_make
Build and install a make project.
## Usage:
```cmake
vcpkg_install_make(...)
```
## Parameters:
See [`vcpkg_build_make()`](vcpkg_build_make.md).
## Notes:
This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.md), adding `ENABLE_INSTALL`
## Examples
* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
## Source
[scripts/cmake/vcpkg_install_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)

16
vcpkg/docs/maintainers/vcpkg_install_meson.md Normal file
View File

@ -0,0 +1,16 @@
# vcpkg_install_meson
Builds a meson project previously configured with `vcpkg_configure_meson()`.
## Usage
```cmake
vcpkg_install_meson()
```
## Examples
* [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
* [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
## Source
[scripts/cmake/vcpkg_install_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake)

93
vcpkg/docs/maintainers/vcpkg_install_msbuild.md Normal file
View File

@ -0,0 +1,93 @@
# vcpkg_install_msbuild
Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
## Usage
```cmake
vcpkg_install_msbuild(
SOURCE_PATH <${SOURCE_PATH}>
PROJECT_SUBPATH <port.sln>
[INCLUDES_SUBPATH <include>]
[LICENSE_SUBPATH <LICENSE>]
[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>...]
[USE_VCPKG_INTEGRATION]
[ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES]
)
```
## Parameters
### SOURCE_PATH
The path to the root of the source tree.
Because MSBuild uses in-source builds, the source tree will be copied into a temporary location for the build. This
parameter is the base for that copy and forms the base for all XYZ_SUBPATH options.
### USE_VCPKG_INTEGRATION
Apply the normal `integrate install` integration for building the project.
By default, projects built with this command will not automatically link libraries or have header paths set.
### PROJECT_SUBPATH
The subpath to the solution (`.sln`) or project (`.vcxproj`) file relative to `SOURCE_PATH`.
### LICENSE_SUBPATH
The subpath to the license file relative to `SOURCE_PATH`.
### INCLUDES_SUBPATH
The subpath to the includes directory relative to `SOURCE_PATH`.
This parameter should be a directory and should not end in a trailing slash.
### ALLOW_ROOT_INCLUDES
Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed.
### REMOVE_ROOT_INCLUDES
Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed.
### SKIP_CLEAN
Indicates that the intermediate files should not be removed.
Ports using this option should later call [`vcpkg_clean_msbuild()`](vcpkg_clean_msbuild.md) to manually clean up.
### 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
* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
* [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
## Source
[scripts/cmake/vcpkg_install_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake)

65
vcpkg/docs/maintainers/vcpkg_install_nmake.md Normal file
View File

@ -0,0 +1,65 @@
# vcpkg_install_nmake
Build and install a msvc makefile project.
## Usage:
```cmake
vcpkg_install_nmake(
SOURCE_PATH <${SOURCE_PATH}>
[NO_DEBUG]
PROJECT_SUBPATH <${SUBPATH}>
PROJECT_NAME <${MAKEFILE_NAME}>
[PRERUN_SHELL <${SHELL_PATH}>]
[PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
[PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the source files.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PROJECT_SUBPATH
Specifies the sub directory containing the `makefile.vc`/`makefile.mak`/`makefile.msvc` or other msvc makefile.
### PROJECT_NAME
Specifies the name of msvc makefile name.
Default is makefile.vc
### NO_DEBUG
This port doesn't support debug mode.
### PRERUN_SHELL
Script that needs to be called before build
### PRERUN_SHELL_DEBUG
Script that needs to be called before debug build
### PRERUN_SHELL_RELEASE
Script that needs to be called before release build
### OPTIONS
Additional options passed to generate during the generation.
### OPTIONS_RELEASE
Additional options passed to generate during the Release generation. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`.
## Parameters:
See [`vcpkg_build_nmake()`](vcpkg_build_nmake.md).
## Notes:
This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`
## Examples
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
## Source
[scripts/cmake/vcpkg_install_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)

24
vcpkg/docs/maintainers/vcpkg_install_qmake.md Normal file
View File

@ -0,0 +1,24 @@
# vcpkg_install_qmake
Build and install a qmake project.
## Usage:
```cmake
vcpkg_install_qmake(...)
```
## Parameters:
See [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
## Notes:
This command transparently forwards to [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
Additionally, this command will copy produced .libs/.dlls/.as/.dylibs/.sos to the appropriate
staging directories.
## Examples
* [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake)
## Source
[scripts/cmake/vcpkg_install_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake)

17
vcpkg/docs/maintainers/vcpkg_prettify_command.md Normal file
View File

@ -0,0 +1,17 @@
# vcpkg_prettify_command
Turns list of command arguments into a formatted string.
## Usage
```cmake
vcpkg_prettify_command(<INPUT_VAR> <OUTPUT_VAR>)
```
## Examples
* `scripts/cmake/vcpkg_execute_build_process.cmake`
* `scripts/cmake/vcpkg_execute_required_process.cmake`
* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
## Source
[scripts/cmake/vcpkg_prettify_command.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_prettify_command.cmake)

20
vcpkg/docs/maintainers/vcpkg_test_cmake.md Normal file
View File

@ -0,0 +1,20 @@
# vcpkg_test_cmake
Tests a built package for CMake `find_package()` integration.
## Usage:
```cmake
vcpkg_test_cmake(PACKAGE_NAME <name> [MODULE])
```
## Parameters:
### PACKAGE_NAME
The expected name to find with `find_package()`.
### MODULE
Indicates that the library expects to be found via built-in CMake targets.
## Source
[scripts/cmake/vcpkg_test_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_test_cmake.cmake)

27
vcpkg/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"
}
}

157
vcpkg/docs/specifications/binarycaching.md Normal file
View File

@ -0,0 +1,157 @@
# Binary Caching v1.1 (Jul 14, 2020)
**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
## Motivation
The primary motivation of binary caching is to accelerate two broad scenarios in an easily accessible way
- Continuous Integration
- Developer Environment Changes (first-time or branch change)
We generally believe both of these scenarios are addressed with the same feature set, however when differences arise they will be discussed in the individual scenarios.
It should also be explicitly noted that this specification does not intend to propose a "Microsoft Sanctioned Public Binaries Service" such as nuget.org – we only intend to enable users to leverage services they already have access to, such as GitHub, local file shares, Azure Artifacts, etc.
## Key User Stories
### CI -> CI
In this story, a CI build using either persistent or non-persistent machines wants to potentially reuse binaries built in a previous run of the pipeline. This is partially covered by the Cache tasks in GitHub Actions or Azure DevOps Pipelines, however the Cache task is all-or-nothing: a single package change will prevent restoration and require rebuilding the entire graph which is unacceptable in many scenarios (such as if actively developing one of the packages).
### CI -> Developer
In this story, the developer wants to reuse binaries built during a CI run. Given appropriate CI coverage, most developers will always have any needed dependencies pre-built by the CI system.
Notably, this scenario indicates a need for Read/Write access granularity on the remote storage solution. Developers should not need write access to the output from the CI system for security reasons.
### Single Developer (same machine reuse)
With the introduction of manifest files, each project will have separate instances of Vcpkg. The performance costs of rebuilding binaries across each cloned project can be debilitating for those working in micro-repos or open source; for the monolithic enterprise developer it is simply frustrating.
User-wide binary caching alleviates the pain of this scenario by ensuring the same binaries aren’t built multiple times (as long as the projects truly overlap with respect to versions/packages/etc).
### Developer <-> Developer (multi-machine / team scenario)
In a small team scenario, it's reasonable that multiple developer machines can trust each other enough to share binaries. This also applies to developers that have multiple machines and wish to share binaries between them (given a similar enough environment).
## Solution Aspects
### Tracking Compilers
In order to provide reliable binary caching, vcpkg must determine if the produced binaries are appropriate for the current context. Currently, we consider many factors, including:
- All files in the port directory
- The toolchain file contents
- The triplet contents
- All dependency binaries
- The version of the CMake tool used to build
and a few others.
However, we notably do not currently track the compiler used. This is critical for all cross-machine scenarios, as the environment is likely to change incompatibly from machine to machine. We propose hashing the compiler that will used by CMake. This can be accomplished either by reimplementing the logic of CMake or running some partial project and extracting the results. For performance reasons, we will prefer first using heuristics to approximate the CMake logic with accompanying documentation for users that fall outside those bounds.
Another aspect of the environment we don't currently track is the CRT version on Linux systems. Currently, we believe this will not cause as many problems in most practices (thus not suitable for an MVP), since the compiler will (generally) link against the system CRT and should sufficiently reflect any differences. This can also be easily worked around by the user with documentation – the toolchain file can simply have a comment such as "# this uses muslc", which will cause it to hash differently.
### Better control over source modifications
Currently, vcpkg caches sources inside `buildtrees/$PORT/src/`. The built-in helpers, such as `vcpkg_extract_archive_ex()` assume that if the appropriately named source folder exists, it is true, accurate, and without modification.
However, the basic workflow for working on ports (specifically, developing patches) breaks this assumption by directly editing whatever extracted source directory the tool is currently using until a successful build is achieved. The user then usually builds a patch file from their changes, then checks it in to the port directory (adding the changes to one of the tracked locations above) and everything is restored to normal.
However, this causes serious issues with the current tracking system, because modifications to this cached source are not detected and tracked into the binary package.
Our proposed solution is to force source re-extraction each time during builds that have uploading to any protocol enabled. Uploading/downloading can then be disabled on the command line via the --editable switch to reuse extracted sources and enable the current workflow.
### Protocols
To service different scenarios and user requirements, we need to support multiple backends. Currently, our CI system uses our only implemented backend: file-based archives.
#### Backend #1: File-Based Archives
This backend simply stores .zip files in a hierarchy similar to git objects: `$VCPKG_ROOT/archives/$XX/$YYYY.zip` with `$XX` being the first two characters of the computed package hash, and `$YYYY` being the full expanded hash. It also supports storing failure logs as `$VCPKG_ROOT/archives/fail/$XX/$YYYY.zip`, however we consider this an internal feature that is not relevant to the key User Stories.
Our CI system uses this backend by symlinking this directory to an Azure Files share, enabling built binaries and failure logs to be shared by all machines in the pool. Credentials are handled at the time of mounting the Azure Files share, so this does not require interactive authentication.
This protocol is ideal due to simplicity for same-machine reuse and simple serverless scenarios such as using networked SMB folders across multiple machines for very small teams. However, it has three significant limitations in the current incarnation:
- It uses the hardcoded directory `$VCPKG_ROOT/archives` (redirectable using symlinks, but unwieldy)
- It cannot use multiple directories
- There is no ability to treat directories as "read-only"/immutable
These second two points are required to implement the very useful concept of "fallback" folders (see https://github.com/NuGet/Home/wiki/%5BSpec%5D-Fallback-package-folders for NuGet’s spec on this topic).
#### Backend #2: NuGet (Azure DevOps Artifacts, GitHub Packages, etc)
This backend packages binaries into a "raw" NuGet package (not suitable for direct import by MSBuild projects) and uploads them to supported NuGet servers such as Azure DevOps Artifacts and GitHub Packages. We believe this will best satisfy the CI scenarios – both CI -> CI as well as CI -> Developer by relying on powerful, centralized, managed hosting.
There is a difference in this case between the developer and CI scenarios. The developer generally wants to configure their remotes for the project and then be able to run vcpkg commands as normal, with packages automatically being downloaded and uploaded to optimize the experience. This is similar to File-Based Archives.
While a CI system could use the same workflow as a developer, there are a few key differences. First, a CI system must use a stored secret for authentication, because it cannot interactively authenticate. Second, to enable more complex interactions with systems such as package signing and task-based restores, we must also support a 4-step workflow:
1. Vcpkg computes hashes of any potentially required packages and writes them to a file
2. An unspecified service/task/etc can parse this file and download any appropriate packages
3. vcpkg is then invoked a second time, with any downloaded packages. This consumes the packages, performs any installations and builds, and potentially produces new packages to an output folder.
4. Finally, another unspecified service/task/etc can take these output packages, sign them, and upload them.
This flow enables arbitrarily complex, user-defined authentication and signing schemes, such as the tasks provided by GitHub Actions and Azure DevOps Pipelines or manual signing as documented in the NuGet documentation: https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package.
#### Configuration
Currently, our file-based backend is enabled by passing the undocumented `--binarycaching` flag to any Vcpkg command or setting the undocumented environment variable `VCPKG_FEATURE_FLAGS` to `binarycaching`. We will replace this feature flag with an on-by-default user-wide behavior, plus command line and environment-based configurability.
The on-by-default configuration will specify the file-based archive protocol on either `%LOCALAPPDATA%/vcpkg/archives` (Windows) or `$XDG_CACHE_HOME/vcpkg/archives` (Unix). If `XDG_CACHE_HOME` is not defined on Unix, we will fall back to `$HOME/.cache/vcpkg/archives` based on the [XDG Base Directory Specification][1]. This can be redirected with a symlink, or completely overridden with the command line or environment. In the future we can also consider having a user-wide configuration file, however we do not believe this is important for any of our key scenarios.
On the command line, a backend can be specified via `--binarysource=<config>`. Multiple backends can be specified by passing the option multiple times and the order of evaluation is determined by the order on the command line. Writes will be performed on all upload backends, but only for packages that were built as part of this build (the tool will not repackage/reupload binaries downloaded from other sources).
The environment variable `VCPKG_BINARY_SOURCES` can be set to a semicolon-delimited list of `<config>`. Empty `<config>` strings are valid and ignored, to support appending like `set VCPKG_BINARY_SOURCES=%VCPKG_BINARY_SOURCES%;foo` or `export VCPKG_BINARY_SOURCES="$VCPKG_BINARY_SOURCES;foo"`
`<config>` can be any of:
- `clear` - ignore all lower priority sources (lowest priority is default, then env, then command line)
- `default[,<readwrite>]` - Reintroduce the default ~/.vcpkg/packages (as read-only or with uploading)
- `files,<path>[,<readwrite>]` - Add a file-based archive at `<path>`
- `nuget,<url>[,<readwrite>]` - Add a nuget-based source at `<url>`. This url has a similar semantic as `nuget.exe restore -source <url>` for reads and `nuget.exe push -source <url>` for writes; notably it can also be a local path.
- `nugetconfig,<path>[,<readwrite>]` - Add a nuget-based source using the NuGet.config file at `<path>`. This enables users to fully control NuGet's execution in combination with the documented NuGet environment variables. This has similar semantics to `nuget.exe push -ConfigFile <path>` and `nuget.exe restore -ConfigFile <path>`.
- `interactive` - Enables interactive mode (such as manual credential entry) for all other configured backends.
`<readwrite>` can be any of `read`, `write`, or `readwrite` to control whether packages will be consumed or published.
Backtick (`) can be used as an escape character within config strings, with double backtick (``) inserting a single backtick. All paths must be absolute.
For all backends, noninteractive operation will be the default and the vcpkg tool will take a `--interactive` parameter to enable prompting for user credentials (if needed by the backend).
To enable the 4-step flow, `vcpkg install` will take a command `--write-nuget-packages-config=<path>` which can be used in combination with `--dry-run`. This path can be relative and will resolve with respect to the current working directory.
[1]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
#### Example 4-step flow
```
PS> vcpkg install --dry-run pkg1 pkg2 pkg3 --write-nuget-packages-config=packages.config
```
An unspecified process, such as `nuget.exe restore packages.config -packagedirectory $packages` or the [ADO task][2], restores the packages to `$packages`.
```
PS> vcpkg install pkg1 pkg2 pkg3 --binarysource=clear --binarysource=nuget,$outpkgs,upload --binarysource=nuget,$packages
```
Another unspecified process such as `nuget.exe sign $outpkgs/*.nupkg` and `nuget.exe push $outpkgs/*.nupkg` or the ADO task uploads the packages for use in future CI runs.
[2]: https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/package/nuget?view=azure-devops

172
vcpkg/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 teams 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 need 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.

289
vcpkg/docs/specifications/feature-packages.md Normal file
View File

@ -0,0 +1,289 @@
# Proposal: Features / Feature packages (Feb 23 2017)
**Note: this is the proposal as it was initially accepted and does not necessarily reflect the current behavior.**
## 1. Motivation
### A. OpenCV + CUDA
[OpenCV][] is a computer vision library that can optionally be built with CUDA support to massively accelerate certain tasks when using computers with NVidia GPUs. For users without NVidia GPUs, building with CUDA support provides no benefit. [CUDA][] is provided only via a 1.3 GB installer (at the time of this authoring), which requires administrator access to install and modifies the global system state.
Therefore, there is significant value in enabling users to choose whether they find CUDA support valuable for their particular scenario.
### B. OpenCV + OpenCV\_contrib
The community around [OpenCV][] has built up a library of extensions called [OpenCV_contrib][]. However, these extensions are a source-level patch onto the main OpenCV codebase and therefore must be applied _during_ the core OpenCV build. Further confounding the problem, it is the author's understanding that these community extensions have only been developed with [CUDA][] enabled and cannot be built without that dependency.
Therefore, if CUDA is disabled, OpenCV\_contrib must also be disabled. Likewise, when a user requests OpenCV\_contrib, CUDA must be enabled. It would be convenient, but not a requirement, to enable CUDA without enabling the community extensions.
Finally, these extensions add additional exports and headers which could be depended upon by other libraries. For maintainers, there must be a way to specify this requirement such that `vcpkg install mylib-depends-ocv-contrib` will verify/build/rebuild OpenCV with the community extensions enabled.
### C. C++ REST SDK + SignalR
The [C++ REST SDK][cpprestsdk] is a networking library that provides (among other features) HTTP and Websockets clients. To implement the HTTP client functionality on Windows Desktop, only the core Win32 platform APIs are needed (`zlib` is optional).
However, the websockets client is based on [Websockets++][], which adds mandatory dependencies on `boost`, `openssl`, and `zlib`. Many users of the C++ REST SDK do not use the websockets component, so to minimize their overall dependency footprint it can be disabled at build time. Ideally, these kinds of options would be easily accessible to users in Vcpkg who are concerned about the final size or licensing of their deployment.
[SignalR-Client-Cpp][SignalR] depends on the websockets functionality provided by the C++ REST SDK. Therefore, the maintainers of the `signalrclient` port would ideally like to express this dependency such that `cpprestsdk` will be automatically correctly built for their needs. Note that `signalrclient` does not _inherently_ care about `boost`, `websocketspp` or `openssl` -- it depends only on the public websocket client APIs provided by `cpprestsdk`. It would be much more maintainable to declare dependencies based on the public APIs rather than the dependencies themselves.
[OpenCV]: http://opencv.org/
[CUDA]: http://www.nvidia.com/object/cuda_home_new.html
[OpenCV_contrib]: https://github.com/opencv/opencv_contrib
[cpprestsdk]: https://github.com/Microsoft/cpprestsdk
[Websockets++]: https://www.zaphoyd.com/websocketpp/
[SignalR]: https://github.com/aspnet/SignalR-Client-Cpp
## 2. Other design concerns
- General-purpose Open Source projects must be able to easily and succinctly describe their build dependencies inside Vcpkg. This should be no more verbose than a single `vcpkg install` line and, when that command succeeds, there is a strong expectation that all required functionality/headers/imports are available.
- The internal state of the Vcpkg enlistment must be either extremely transparent OR managed by version control (git). This enables larger projects to efficiently transfer the entire state of their customized Vcpkg system between machines (and onto build servers) by having the destination clone and then run a single `vcpkg install` line for the subset of dependencies required. The results of this operation should be as repeatable as reasonably achievable given the current limits of the underlying toolchain.
## 3. Proposed solution
A key summary of the above motivations is that they are all scenarios surrounding APIs that are not independently buildable from each other. We have an existing solution for APIs that are independently buildable: separate packages. Therefore, we seek to extend the user-facing notion of "packages" to include capabilities and contracts that cannot be made into independent builds.
This document proposes "features" (also called feature packages). These features are intended to model semi-independently toggleable API sets/contracts such that they can be sanely depended upon by other packages. It is not a goal to model exclusive alternatives (such as implementation choices that are not directly user-observable) through this mechanism.
- Individual libraries within `boost` may be reasonably represented as features.
- Whether a graphics library is built on DirectX xor OpenGL (where one but not both must be chosen) is not representable as a feature.
From a user experience perspective (i.e. from `vcpkg install`) feature packages act as much as possible like completely independent packages. However, internally, any change to a package's features will result in a rebuild of the associated "parent" package. This will invoke a package rebuild experience similar to upgrading.
When using `vcpkg install <package>`, some features will be enabled by default. These default features can be avoided by referring to the packages as `<package>[core]` and features can be added by supplying them on the same installation line.
### A. Proposed User experience
#### i. User with no preference about options
Install of a library with default features:
```no-highlight
> vcpkg install cpprestsdk
// -- omitted build information -- //
Package cpprestsdk[core]:x86-windows is installed.
Package cpprestsdk[compression]:x86-windows is installed.
Package cpprestsdk[ws-client]:x86-windows is installed.
```
Removal of that library:
```no-highlight
> vcpkg remove cpprestsdk
The following packages will be removed:
cpprestsdk:x86-windows
Removing package cpprestsdk:x86-windows...
Removing package cpprestsdk:x86-windows... done
Purging package cpprestsdk:x86-windows...
Cleaned up D:\src\vcpkg\packages\cpprestsdk_x64-windows
Purging package cpprestsdk:x86-windows... done
```
Installation of a library with optional features:
```no-highlight
> vcpkg install opencv
// -- omitted build information -- //
Package opencv[core]:x86-windows is installed.
```
#### ii. User desires CUDA support for OpenCV directly, and is unfamiliar with feature packages
Developer Bob knows he wants OpenCV, so he guesses what the package is called
```no-highlight
> vcpkg install opencv
// -- omitted build information -- //
Package opencv[core]:x86-windows is installed.
```
Bob attempts to build his application against OpenCV (assuming CUDA), which fails at runtime or compile time indicating that OpenCV wasn't built with CUDA.
Bob comes back to vcpkg, not knowing about the "feature packages" feature. The primary inquiry tools for Vcpkg are `search` and `list`, so he runs `vcpkg search`:
```no-highlight
> vcpkg search opencv
opencv 3.2.0 computer vision library
opencv[cuda] support for NVidia CUDA
opencv[contrib] community supported extensions for OpenCV
If your library is not listed, please open an issue at:
https://github.com/Microsoft/vcpkg/issues
```
He isn't immediately sure what the lack of a version number means, but anything in `vcpkg search` can be applied to `vcpkg install`, so he runs:
```no-highlight
> vcpkg install opencv[cuda]
The following packages will be rebuilt:
opencv:x86-windows
To rebuild with this feature, use:
vcpkg remove opencv:x86-windows
vcpkg install opencv[core,cuda]:x86-windows
```
Bob follows the instructions...
```no-highlight
> vcpkg remove opencv:x86-windows
// -- omitted results as above -- //
> vcpkg install opencv[core,cuda]:x86-windows
// -- omitted build information -- //
Package opencv[core]:x86-windows is installed.
Package opencv[cuda]:x86-windows is installed.
```
and he can now use OpenCV's CUDA support in his application.
#### iii. User is familiar with feature packages, and wants to opt-out of a feature
Developer Alice has used `cpprestsdk`, built it from source, and she knows about the option to disable websockets. She uses `search` to find the complete list of features:
```
> vcpkg search cpprestsdk
cpprestsdk 2.9.0-2 C++11 JSON, REST, and OAuth library The C++ RES...
cpprestsdk[compression] Gzip compression support in the HTTP client.
cpprestsdk[ws-client] Websocket client support based on websocketspp.
If your library is not listed, please open an issue at:
https://github.com/Microsoft/vcpkg/issues
```
She decided she only wants `cpprestsdk[compression]`, so she installs only that feature:
```no-highlight
> vcpkg install cpprestsdk[compression]
// -- omitted build information -- //
Package cpprestsdk[core]:x86-windows is installed.
Package cpprestsdk[compression]:x86-windows is installed.
```
She receives a quick recursive build that only depends on `zlib`.
She's now interested in some additional libraries built on top of cpprestsdk: `azure-storage-cpp` and `signalrclient`.
```no-highlight
> vcpkg install azure-storage-cpp
// -- omitted build information -- //
Package azure-storage-cpp[core]:x86-windows is installed.
> vcpkg install signalrclient
Package signalrclient:x86-windows depends on cpprestsdk[ws-client]:x86-windows.
The following packages will be rebuilt:
* azure-storage-cpp:x86-windows
* cpprestsdk:x86-windows
To rebuild the current package graph with this feature, use:
vcpkg remove cpprestsdk:x86-windows azure-storage-cpp:x86-windows
vcpkg install cpprestsdk[core,compression,ws-client]:x86-windows
vcpkg install azure-storage-cpp[core]:x86-windows
vcpkg install signalrclient[core]:x86-windows
```
She follows the above script and can use both `azure-storage-cpp` and `signalrclient` in her code.
Some time has passed, she decided not to use `signalrclient`, and she's interested in shipping her application. She wants to minimize her final install size, so she'd like to remove all unneeded packages like `boost` and `openssl`.
```no-highlight
> vcpkg remove boost openssl
The following packages and features will be removed:
* signalrclient[core]:x86-windows
* cpprestsdk[ws-client]:x86-windows
boost[core]:x86-windows
openssl[core]:x86-windows
The following packages will be rebuilt:
* azure-storage-cpp:x86-windows
* cpprestsdk:x86-windows
Removing features requires rebuilding packages.
To rebuild the current package graph without these features, use:
vcpkg remove cpprestsdk:x86-windows azure-storage-cpp:x86-windows signalrclient:x86-windows openssl:x86-windows boost:x86-windows
vcpkg install cpprestsdk[core,compression]:x86-windows
vcpkg install azure-storage-cpp[core]:x86-windows
```
In the end, her final `vcpkg list` outputs:
```no-highlight
> vcpkg list
zlib[core]:x86-windows 1.2.11 A compression library
azure-storage-cpp[core]:x86-windows 2.6.0 Microsoft Azure Storage Client SDK for ...
cpprestsdk[core]:x86-windows 2.9.0-2 C++11 JSON, REST, and OAuth library
cpprestsdk[compression]:x86-windows Gzip compression support in the HTTP client.
```
### B. Technical model
- Each package can have any number "features".
- Features follow the same naming conventions as packages, but when referenced are always "namespaced" by the parent package.
- `cpprestsdk[ws-client]` is a completely orthogonal feature from `poco[ws-client]`.
- Features are valid dependencies.
- `signalrclient` depends on `cpprestsdk[ws-client]`
- Features can have dependencies (including other features).
- `cpprestsdk[ws-client]` depends on `boost`, `openssl`, and `websocketspp`
- `opencv[cuda]` depends on `cuda`
- `opencv[contrib]` depends on `opencv[cuda]`
- `boost[python]` depends on `libpython`
- Every package has an implicit feature called `core`, which covers the core library with a minimum set of features. All features implicitly depend on the `core` feature of their parent package
- `azure-storage-cpp` depends on `cpprestsdk[core]`
- `cpprestsdk[ws-client]` implicitly depends on `cpprestsdk[core]`
- Each package declares a list of default features that are enabled when the package is referred to by its raw name, and `core` is always a default feature.
- `cpprestsdk` declares `ws-client` and `compression` to be default features. Any unqualified reference `cpprestsdk` implicitly means `cpprestsdk[core]` _and_ `cpprestsdk[ws-client]` _and_ `cpprestsdk[compression]`.
- `opencv` does not declare `cuda` nor `contrib` to be default features.
As a conclusion of the above, it is expected that all packages will be buildable with all features disabled (just the `core` feature) and with all features enabled.
### C. Proposed Control File Syntax
#### OpenCV and CUDA
To add the feature CUDA to OpenCV, we will adopt the following syntax in the CONTROL file:
```no-highlight
# opencv/CONTROL
Source: opencv
Version: 3.2.0-1
Build-Depends: zlib, libpng, libjpeg-turbo, tiff
Description: computer vision library
Default-Features:
Feature: cuda
Build-Depends: cuda
Description: parallel computing platform
Feature: contrib
Build-Depends: opencv[cuda]
Description: library of OpenCV Extensions
```
#### Signalrclient
```no-highlight
# signalrclient/CONTROL
Source: signalrclient
Version: 1.0.0-beta1
Build-Depends: cpprestsdk[ws-client]
Description: C++ client for SignalR.
```
```no-highlight
# cpprestsdk/CONTROL
Source: cpprestsdk
Version: 2.9.0-2
Build-Depends:
Description: C++11 JSON, REST, and OAuth library ...
Default-Features: compression, ws-client
Feature: compression
Build-Depends: zlib (windows)
Description: Gzip compression support in the HTTP client.
Feature: ws-client
Build-Depends: boost (windows), openssl (windows), websocketpp (windows)
Description: Websocket client support based on websocketspp
```
### D. Additional Control File Technical Details
- If any feature paragraphs exist, the field `Default-Features` must be present.
## 4. Related Work
### Cargo's Features (from Rust): <http://doc.crates.io/manifest.html#the-features-section>
The proposed feature packages are exceedingly similar to Cargo's Features, with the following changes:
- We avoid any collision problems because features are always namespaced by the owning package
- We do not have a concept of "feature groups", instead we allow dependencies from one feature to another within the same package (Note: This may be how "feature groups" are implemented internally to Cargo -- it was not clear from the documentation).
- Because of the nature of C and C++, it is extremely commonplace that large software packages can have features disabled to remove their dependencies upon other libraries. Changing this configuration requires a rebuild of the package and potentially rippling ABI changes to any downstream dependencies. Therefore, we expect significantly more use of this feature to manage optional API contracts instead of the intended use in Cargo (curation).
- We do not intend feature packages to be used to express the curation relationship, beyond the notion of a "default" set within a package.
### Gentoo's USE flags: <https://wiki.gentoo.org/wiki/Handbook:X86/Working/USE>
Gentoo's USE flags can be shortly summarized as a global set of keywords that is used to make cross-cutting changes to the entire package graph's build configuration. This system standardizes many common settings such that they can be simultaneously toggled for the entire graph.
The most common example of this would be using KDE vs Gnome. A user who knows that, given the choice, they would prefer the KDE/Qt interface can manage the massive space of package configuration efficiently without learning the particular term that each package has decided to call "build using Qt instead of GTK".
USE flags can be customized hierarchically when needed, including at the per-package level. They can be depended upon by other packages, both positively and negatively. USE flags themselves can be used in any boolean expression to determine the complete set of package dependencies, including removing dependencies when flags are enabled.
Problems with USE flags:
- They require coordination from package maintainers to achieve the goal of "portable" flags. This increases the burden of adding a package -- to author a good package, I need to be aware of every uncommon USE flag and evaluate how those could map onto my local configuration space.
- Based on research online, it seems extremely common that users need to tweak flags at a per-package level. This calls into question how valuable the cross-cutting power above is.
- The vast majority of common USE flags are essentially a list of all the common packages and focus on giving the user a view of dependencies (which a package manager is designed to abstract when possible) instead of APIs (which is what users code against).
- Dependency analysis with USE flags becomes a SAT problem with an enormous state space -- P*F bits -- which compounds with any versioning relations. This may work acceptably in practice via heuristics, but it implies that a) there is a looming performance wall which could suddenly create a poor user experience and b) the heuristics may incorrectly model the user's needs, causing a disconnect in desire vs practice, which again leads to a poor user experience.

298
vcpkg/docs/specifications/manifests.md Normal file
View File

@ -0,0 +1,298 @@
# Manifests -- `vcpkg.json`
For many other language package managers, there exists a way of writing one's dependencies in a declarative
manifest format; we want something similar for vcpkg. What follows is the specification of that feature;
this should mean that vcpkg becomes far more user and enterprise-friendly, and is additionally an important
first step for versioning and package federation. Our primary concern, beyond implementability, is ease-of-use;
it is important that using this feature is all of:
* Easy for existing users
* Easy for new users to set up
* Easy to extend later for new features like versioning and federation
* _Declarative_, not _Imperative_.
## Reasoning
### Why JSON?
We choose JSON for five main reasons:
* Everybody knows JSON, and if one doesn't, it's really easy to learn
* Every tool supports JSON in the standard library, or in a commonly used support library
* This means writing tooling should be trivial in any language one is comfortable with
* Most configuration formats don't have a COBOL implementation 😉
* Specified in an international standard
* There is _one_ right way to parse JSON
* There are no ambiguities of what the parse tree _should_ be
* Simple and secure
* Unlike YAML, for example, there's no weird ACE issues
* Easy to write a parser -- important since we can't depend on external libraries
* Schemas are almost a necessity
Some have suggested allowing comments or commas in our parser; we chose to use JSON proper
rather than JSON5 or JSON with comments because JSON is the everywhere-supported international
standard. That is not necessarily true of JSON with comments. Additionally, if one needs
to write a comment, they can do so via `"$reason"` or `"$comment"` fields.
## Specification
A manifest file shall have the name `vcpkg.json`, and shall be in the root directory of a package.
It also replaces CONTROL files, though existing CONTROL files will still be
supported; there will be no difference between ports and packages, except
that packages do not need to supply portfile.cmake (eventually we would like
to remove the requirement of portfile.cmake for ports that already use
CMake).
The specification uses definitions from the [Definitions](#definitions) section in order
to specify the shape of a value. Note that any object may contain any directives, written as
a field key that starts with a `$`; these directive shall be ignored by `vcpkg`. Common
directives may include `"$schema"`, `"$comment"`, `"$reason"`.
A manifest must be a top-level object, and must have at least:
* `"name"`: a `<package-name>`
* One (and only one) of the following version fields:
* `"version-string"`: A `string`. Has no semantic meaning.
Equivalent to `CONTROL`'s `Version:` field.
* Other version fields will be defined by the Versions RFC
The simplest vcpkg.json looks like this:
```json
{
"name": "mypackage",
"version-string": "0.1.0-dev"
}
```
Additionally, it may contain the following properties:
* `"port-version"`: A non-negative integer. If this field doesn't exist, it's assumed to be `0`.
* Note that this is a change from existing CONTROL files, where versions were a part of the version string
* `"maintainers"`: An array of `string`s which contain the authors of a package
* `"maintainers": [ "Nicole Mazzuca <nicole@example.com>", "שלום עליכם <shalom@example.com>" ]`
* `"description"`: A string or array of strings containing the description of a package
* `"description": "mypackage is a package of mine"`
* `"homepage"`: A url which points to the homepage of a package
* `"homepage": "https://github.com/strega-nil/mypackage"`
* `"documentation"`: A url which points to the documentation of a package
* `"documentation": "https://readthedocs.io/strega-nil/mypackage"`
* `"license"`: A `<license-string>`
* `"license": "MIT"`
* `"dependencies"`: An array of `<dependency>`s
* `"dev-dependencies"`: An array of `<dependency>`s which are required only for developers (testing and the like)
* `"features"`: An array of `<feature>`s that the package supports
* `"default-features"`: An array of `<identifier>`s that correspond to features, which will be used by default.
* `"supports"`: A `<platform-expression>`
* `"supports": "windows & !arm"`
Any properties which are not listed, and which do not start with a `$`,
will be warned against and are reserved for future use.
The following is an example of an existing port CONTROL file rewritten as a vcpkg.json file:
```
Source: pango
Version: 1.40.11-6
Homepage: https://ftp.gnome.org/pub/GNOME/sources/pango/
Description: Text and font handling library.
Build-Depends: glib, gettext, cairo, fontconfig, freetype, harfbuzz[glib] (!(windows&static)&!osx)
```
```json
{
"name": "pango",
"version-string": "1.40.11",
"port-version": 6,
"homepage": "https://ftp.gnome.org/pub/GNOME/sources/pango/",
"description": "Text and font handling library.",
"dependencies": [
"glib",
"gettext",
"cairo",
"fontconfig",
"freetype",
{
"name": "harfbuzz",
"features": [ "glib" ],
"platform": "!(windows & static) & !osx"
}
]
}
```
## Behavior of the Tool
There will be two "modes" for vcpkg from this point forward: "classic", and "manifest".
The former will act exactly like the existing vcpkg workflow, so as to avoid breaking
anyone. The latter will be the mode only when the user either:
* Passes `--manifest-root-dir=<directory>` (initially, `x-manifest-root-dir`)
* Runs `vcpkg` in a directory that contains a file named `vcpkg.json`, or in a
child directory of a directory containing `vcpkg.json`.
* For this, initially vcpkg will warn that the behavior will change in the
future, and simply run in classic mode, unless the feature flag `manifests` is
passed via:
* The environment variable `VCPKG_FEATURE_FLAGS`
* The option `--feature-flags`
* (e.g., `--feature-flags=binarycaching,manifests`)
* If someone wants to use classic mode and silence the warning, they can add the
`-manifests` feature flag to disable the mode.
When in "manifest" mode, the `installed` directory will be changed to
`<manifest-root>/vcpkg_installed` (name up for bikeshedding).
The following commands will change behavior:
* `vcpkg install` without any port arguments will install the dependencies listed in
the manifest file, and will remove any dependencies
which are no longer in the dependency tree implied by the manifest file.
* `vcpkg install` with port arguments will give an error.
The following commands will not work in manifest mode, at least initially:
* `vcpkg x-set-installed`: `vcpkg install` serves the same function
* `vcpkg remove`
* `vcpkg export`
We may add these features back for manifest mode once we understand how best to
implement them.
### Behavior of the Toolchain
Mostly, the toolchain file stays the same; however, we shall add
two public options:
```cmake
VCPKG_MANIFEST_MODE:BOOL=<we found a manifest>
VCPKG_MANIFEST_INSTALL:BOOL=ON
```
The first option either explicitly turns on, or off, manifest mode;
otherwise, we default to looking for a manifest file in the directory
tree upwards from the source directory.
The `VCPKG_MANIFEST_INSTALL` option tells the toolchain whether to
install the packages or not -- if you wish to install the manifest
dependencies manually, you can set this to off, and we also turn it
off for packages installed by vcpkg.
Additionally, if `-manifests` is set in the feature flags environment
variable, we turn off manifest mode in the toolchain, and we act like
the classic toolchain.
### Example - CMake Integration
An example of using the new vcpkg manifests feature for a new
project follows:
The filesystem structure should look something like:
```
example/
src/
main.cxx
CMakeLists.txt
vcpkg.json
```
Then, `main.cxx` might look like:
```cpp
#include <fmt/format.h>
int main() {
fmt::print("Hello, {}!", "world");
}
```
Therefore, in `vcpkg.json`, we'll need to depend on `fmt`:
```json
{
"name": "example",
"version-string": "0.0.1",
"dependencies": [
"fmt"
]
}
```
Then, let's write our `CMakeLists.txt`:
```cmake
cmake_minimum_required(VERSION 3.14)
project(example CXX)
add_executable(example src/main.cxx)
find_package(fmt REQUIRED)
target_link_libraries(example
PRIVATE
fmt::fmt)
```
And finally, to configure and build:
```sh
$ cd example
$ cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystem/vcpkg.cmake
... configuring and installing...
$ cmake --build build
```
and we're done! `fmt` will get installed into
`example/build/vcpkg_installed`, and we can run our executable with:
```sh
$ build/example
Hello, world!
```
## Definitions
* `<identifier>`: A `string` which:
* Is entirely ASCII
* Contains only lowercase alphabetic characters, digits, and hyphen-minus
* Does not have multiple consecutive hyphens
* Does not begin nor end with a hyphen
* Is not a Windows filesystem reserved name
* Is not a vcpkg reserved name: "default" or "core".
* In other words, it must follow the regex `[a-z0-9]+(-[a-z0-9]+)*`, and must not be any of:
* `{ prn, aux, nul, con, lpt[1-9], com[1-9], core, default }`
* `<package-name>`: A `string` consisting of a non-zero number of `<identifier>`s, separated by `.`.
* `a.b.c` is valid
* `a` is valid
* `a/b` is not valid
* `Boost.Beast` is not valid, but `boost.beast` is
* `<dependency>`: Either a `<package-name>`, or an object:
* A dependency always contains the following:
* `"name"`: A `<package-name>`
* Optionally, `"features"`: an array of `<identifier>`s corresponding to features in the package.
* Optionally, `"default-features"`: a `boolean`. If this is false, then don't use the default features of the package; equivalent to core in existing CONTROL files. If this is true, do the default thing of including the default features.
* Optionally, `"platform"`: a `<platform-expression>`
* `<dependency.port>`: No extra fields are required.
* `<license-string>`: An SPDX license expression at version 3.9.
* `<platform-expression>`: A specification of a set of platforms; used in platform-specific dependencies and supports fields. A string that is parsed as follows:
* `<platform-expression>`:
* `<platform-expression.not>`
* `<platform-expression.and>`
* `<platform-expression.or>`
* `<platform-expression.simple>`:
* `( <platform-expression> )`
* `<platform-expression.identifier>`
* `<platform-expression.identifier>`:
* regex: `/^[a-z0-9]+$/`
* `<platform-expression.not>`:
* `<platform-expression.simple>`
* `! <platform-expression.simple>`
* `<platform-expression.and>`
* `<platform-expression.not>`
* `<platform-expression.and> & <platform-expression.not>`
* `<platform-expression.or>`
* `<platform-expression.not>`
* `<platform-expression.or> | <platform-expression.not>`
* `<feature>`: An object containing the following:
* `"name"`: An `<identifier>`, the name of the feature
* `"description"`: A `string` or array of `string`s, the description of the feature
* Optionally, `"dependencies"`: An array of `<dependency>`s, the dependencies used by this feature

182
vcpkg/docs/specifications/ports-overlay.md Normal file
View File

@ -0,0 +1,182 @@
# Ports Overlay (Jun 19, 2019)
## 1. Motivation
### A. Allow users to override ports with alternate versions
It's a common scenario for `vcpkg` users to keep specific versions of libraries to use in their own projects. The current recommendation for users is to fork `vcpkg`'s repository and create tags for commits containing the specific versions of the ports they want to use.
This proposal adds an alternative to solve this problem. By allowing `vcpkg` users to specify additional locations in their file system containing ports for:
* older or newer versions of libraries,
* modified libraries, or
* libraries not available in `vcpkg`.
These locations will be searched when resolving port names during package installation, and override ports in `<vcpkg-root>/ports`.
### B. Allow users to keep unmodified upstream ports
Users will be able to keep unmodified versions of the ports shipped with `vcpkg` and update them via `vcpkg update` and `vcpkg upgrade` without having to solve merge conflicts.
## 2. Other design concerns
* Allow a set of `vcpkg` commands to optionally accept additional paths to be used when searching for ports.
* Additional paths must take precedence when resolving names of ports to install.
* Allow users to specify multiple additional paths.
* Provide a simple disambiguation mechanism to resolve ambiguous port names.
* After resolving a port name, the installation process has to work the same as for ports shipped by `vcpkg`.
* This **DOES NOT ENABLE MULTIPLE VERSIONS** of a same library to be **INSTALLED SIDE-BY-SIDE**.
## 3. Proposed solution
This document proposes allowing additional locations to search for ports during package installation that will override and complement the set of ports provided by `vcpkg` (ports under the `<vcpkg_root>/ports` directory).`
A new option `--overlay-ports` will be added to the `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, `vcpkg export`, and `vcpkg depend-info` commands to specify additional paths containing ports.
From a user experience perspective, a user expresses interest in adding additional lookup locations by passing the `--overlay-ports` option followed by a path to:
* an individual port (directory containing a `CONTROL` file),
* `vcpkg install sqlite3 --overlay-ports="C:\custom-ports\sqlite3"`
* a directory containing ports,
* `vcpkg install sqlite3 --overlay-ports=\\share\org\custom-ports`
* a file listing paths to the former two.
> NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
* `vcpkg install sqlite3 --overlay-ports=..\port-repos.txt`
_port-repos.txt_
```
.\experimental-ports\sqlite3
C:\custom-ports
\\share\team\custom-ports
\\share\org\custom-ports
```
*Relative paths inside this file are resolved relatively to the file's location. In this case a `experimental-ports` directory should exist at the same level as the `port-repos.txt` file.*
_NOTE: It is not the goal of this document to discuss library versioning or project dependency management solutions, which require the ability to install multiple versions of a same library side-by-side._
### Multiple additional paths
Users can provide multiple additional paths by repeating the `--overlay-ports` option.
```
vcpkg install sqlite3
--overlay-ports="..\experimental-ports\sqlite3"
--overlay-ports="C:\custom-ports"
--overlay-ports="\\share\team\custom-ports
```
### Overlaying ports
Port name resolution follows the order in which additional paths are specified, with the first match being selected for installation, and falling back to `<vcpkg-root>/ports` if the port is not found in any of the additional paths.
No effort is made to compare version numbers inside the `CONTROL` files, or to determine which port contains newer or older files.
### Examples
Given the following directory structure:
```
team-ports/
|-- sqlite3/
|---- CONTROL
|-- rapidjson/
|---- CONTROL
|-- curl/
|---- CONTROL
my-ports/
|-- sqlite3/
|---- CONTROL
|-- rapidjson/
|---- CONTROL
vcpkg
|-- ports/
|---- <upstream ports>
|-- vcpkg.exe
|-- preferred-ports.txt
```
* #### Example #1:
Running:
```
vcpkg/vcpkg.exe install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports
```
Results in `my-ports/sqlite3` getting installed as that location appears first in the command line arguments.
* #### Example #2:
A specific version of a port can be given priority by adding its path first in the list of arguments:
```
vcpkg/vcpkg.exe install sqlite3 rapidjson curl
--overlay-ports=my-ports/rapidjson
--overlay-ports=vcpkg/ports/curl
--overlay-ports=team-ports
```
Installs:
* `sqlite3` from `team-ports/sqlite3`
* `rapidjson` from `my-ports/rapidjson`
* `curl` from `vcpkg/ports/curl`
* #### Example #3:
> NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
Given the content of `preferred-ports.txt` as:
```
./ports/curl
/my-ports/rapidjson
/team-ports
```
A location can be appended or prepended to those included in `preferred-ports.txt` via the command line, like this:
```
vcpkg/vcpkg.exe install sqlite3 curl --overlay-ports=my-ports --overlay-ports=vcpkg/preferred-ports.txt
```
Which results in `my-ports/sqlite3` and `vcpkg/ports/curl` getting installed.
## 4. Proposed User experience
### i. User wants to preserve an older version of a port
Developer Alice and her team use `vcpkg` to acquire **OpenCV** and some other packages. She has even contributed many patches to add features to the **OpenCV 3** port in `vcpkg`. But, one day, she notices that a PR to update **OpenCV** to the next major version has been merged.
Alice wants to update some packages available in `vcpkg`. Unfortunately, updating her project to use the latest **OpenCV** is not immediately possible.
Alice creates a private GitHub repository and checks in the set of ports that she wants to preserve. Then provides her teammates with the link to clone her private ports repository.
```
mkdir vcpkg-custom-ports
cd vcpkg-custom-ports
git init
cp -r %VCPKG_ROOT%/ports/opencv .
git add .
git commit -m "[opencv] Add OpenCV 3 port"
git remote add origin https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
git push -u origin master
```
Now her team is able to use:
```
git clone https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
vcpkg update --overlay-ports=./vcpkg-custom-ports
vcpkg upgrade --no-dry-run --overlay-ports=./vcpkg-custom-ports
```
to upgrade their packages and preserve the old version of **OpenCV** they require.

158
vcpkg/docs/specifications/prefab.md Normal file
View File

@ -0,0 +1,158 @@
# Vcpkg: export Android prefab Archives (AAR files)
Vcpkg can export android archives ([AAR files](https://developer.android.com/studio/projects/android-library)). Once an archive is created, it can imported in Android Studio as a native dependent. The archive is automatically consumed using [android studio's prefab tool](https://github.com/google/prefab).
For more information on Prefab, refer to:
* The [official prefab documentation](https://google.github.io/prefab).
* a blog post from Android developers blog: [Native Dependencies in Android Studio 4.0](https://android-developers.googleblog.com/2020/02/native-dependencies-in-android-studio-40.html)
_Note for Android Studio users: prefab packages are supported on Android Studio 4+_
## Requirements
1. `ndk <required>`
Set environment variable `ANDROID_NDK_HOME` to your android ndk installation. For example:
````
export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
````
2. `7zip <required on windows>` or `zip <required on linux>`
3. `maven <optional>`
4. Android triplets
See [android.md](../users/android.md) for instructions on how to install the triplets.
*Please note that in order to use "prefab" (see below), the four architectures are required. If any is missing the export will fail*
## Example exporting [jsoncpp]
First "vcpkg install" the 4 android architectures (it is mandatory to export all 4 of them)
````
./vcpkg install jsoncpp:arm-android jsoncpp:arm64-android jsoncpp:x64-android jsoncpp:x86-android
````
Then, export the prefab:
Note:
* The `--prefab-maven` flag is optional. Call it if you maven is installed.
* The `--prefab-debug` flag will output instructions on how to use the prefab archive via gradle.
```
./vcpkg export --triplet x64-android jsoncpp --prefab --prefab-maven --prefab-debug
```
You will see an ouput like this:
```
The following packages are already built and will be exported:
jsoncpp:arm64-android
Exporting package jsoncpp...
[DEBUG] Found 4 triplets
arm64-android
x64-android
x86-android
arm-android
...
... Lots of output...
...
[INFO] Scanning for projects...
Downloading from central: https://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-clean-plugin/2.5/maven-clean-plugin-2.5.pom
...
... Lots of output...
...
[INFO] BUILD SUCCESS
[INFO] Total time: 2.207 s
[INFO] Finished at: 2020-05-10T14:42:28+02:00
...
... Lots of output...
...
[DEBUG] Configuration properties in Android Studio
In app/build.gradle
com.vcpkg.ndk.support:jsoncpp:1.9.2
And cmake flags
externalNativeBuild {
cmake {
arguments '-DANDROID_STL=c++_shared'
cppFlags "-std=c++17"
}
}
In gradle.properties
android.enablePrefab=true
android.enableParallelJsonGen=false
android.prefabVersion=${prefab.version}
Successfuly exported jsoncpp. Checkout .../vcpkg/prefab
```
#### The output directory after export
````
prefab
└── jsoncpp/
├── aar/
│   ├── AndroidManifest.xml
│   ├── META-INF/
│   │   └── LICENSE
│   └── prefab/
│   ├── modules/
│   │   └── jsoncpp/
│   │   ├── libs/
│   │   │   ├── android.arm64-v8a/
│   │   │   │   ├── abi.json
│   │   │   │   ├── include/
│   │   │   │   │   └── json/
│   │   │   │   │   ├── json.h
│   │   │   │   │   └── ....
│   │   │   │   └── libjsoncpp.so
│   │   │   ├── android.armeabi-v7a/
│   │   │   │   ├── abi.json
│   │   │   │   ├── include/
│   │   │   │   │   └── json/
│   │   │   │   │   ├── json.h
│   │   │   │   │   └── ....
│   │   │   │   └── libjsoncpp.so
│   │   │   ├── android.x86/
│   │   │   │   ├── abi.json
│   │   │   │   ├── include/
│   │   │   │   │   └── json/
│   │   │   │   │   ├── json.h
│   │   │   │   │   └── ....
│   │   │   │   └── libjsoncpp.so
│   │   │   └── android.x86_64/
│   │   │   ├── abi.json
│   │   │   ├── include/
│   │   │   │   └── json/
│   │   │   │   │   ├── json.h
│   │   │   │   │   └── ....
│   │   │   └── libjsoncpp.so
│   │   └── module.json
│   └── prefab.json
├── jsoncpp-1.9.2.aar
└── pom.xml
````
## Example consuming [jsoncpp] via vcpkg and prefab
See the example repo here:
https://github.com/atkawa7/prefab-vpkg-integration-sample

285
vcpkg/docs/specifications/registries.md Normal file
View File

@ -0,0 +1,285 @@
# Package Federation: Custom Registries
As it is now, vcpkg has over 1400 ports in the default registry (the `/ports` directory).
For the majority of users, this repository of packages is enough. However, many enterprises
need to more closely control their dependencies for one reason or another, and this document
lays out a method which we will build into vcpkg for exactly that reason.
## Background
A registry is simply a set of packages. In fact, there is already a registry in vcpkg: the default one.
Package federation, implemented via custom registries, allows one to add new packages,
edit existing packages, and have as much or as little control as one likes over the dependencies that one uses.
It gives the control over dependencies that an enterprise requires.
### How Does the Current Default Registry Work?
Of course, the existing vcpkg tool does have packages in the official,
default registry. The way we describe these packages is in the ports tree –
at the base of the vcpkg install directory, there is a directory named ports,
which contains on the order of 1300 directories, one for each package. Then,
in each package directory, there are at least two files: a CONTROL or
vcpkg.json file, which contains the name, version, description, and features
of the package; and a portfile.cmake file which contains the information on
how to download and build the package. There may be other files in this
registry, like patches or usage instructions, but only those two files are
needed.
### Existing vcpkg Registry-like Features
There are some existing features in vcpkg that act somewhat like a custom
registry. The most obvious feature that we have is overlay ports – this
feature allows you to specify any number of directories as "overlays", which
either contain a package definition directly, or which contain some number of
package directories; these overlays will be used instead of the ports tree
for packages that exist in both places, and are specified exclusively on the
command line. Additionally, unfortunately, if one installs a package from
overlay ports that does not exist in the ports tree, one must pass these
overlays to every vcpkg installation command.
There is also the less obvious "feature" which works by virtue of the ports
tree being user-editable: one can always edit the ports tree on their own
machine, and can even fork vcpkg and publish their own ports tree.
Unfortunately, this then means that any updates to the source tree require
merges, as opposed to being able to fast-forward to the newest sources.
### Why Registries?
There are many reasons to want custom registries; however, the most important reasons are:
* Legal requirements – a company like Microsoft or Google
needs the ability to strictly control the code that goes into their products,
making certain that they are following the licenses strictly.
* There have been examples in the past where a library which is licensed under certain terms contains code
which is not legally allowed to be licensed under those terms (see [this example][legal-example],
where a person tried to merge Microsoft-owned, Apache-licensed code into the GPL-licensed libstdc++).
* Technical requirements – a company may wish to run their own tests on the packages they ship,
such as [fuzzing].
* Other requirements – an organization may wish to strictly control its dependencies for a myriad of other reasons.
* Newer versions – vcpkg may not necessarily always be up to date for all libraries in our registry,
and an organization may require a newer version than we ship;
they can very easily update this package and have the version that they want.
* Port modifications – vcpkg has somewhat strict policies on port modifications,
and an organization may wish to make different modifications than we do.
It may allow that organization to make certain that the package works on triplets
that our team does not test as extensively.
* Testing – just like port modifications, if a team wants to do specific testing on triplets they care about,
they can do so via their custom registry.
Then, there is the question of why vcpkg needs a new solution for custom registries,
beyond the existing overlay ports feature. There are two big reasons –
the first is to allow a project to define the registries that they use for their dependencies,
and the second is the clear advantage in the user experience of the vcpkg tool.
If a project requires specific packages to come from specific registries,
they can do so without worrying that a user accidentally misses the overlay ports part of a command.
Additionally, beyond a feature which makes overlay ports easier to use,
custom registries allow for more complex and useful infrastructure around registries.
In the initial custom registry implementation, we will allow overlay ports style paths,
as well as git repositories, which means that people can run and use custom registries
without writing their own infrastructure around getting people that registry.
It is the intention of vcpkg to be the most user-friendly package manager for C++,
and this allows us to fulfill on that intention even further.
As opposed to having to write `--overlay-ports=path/to/overlay` for every command one runs,
or adding an environment variable `VCPKG_OVERLAY_PORTS`,
one can simply write vcpkg install and the registries will be taken care of for you.
As opposed to having to use git submodules, or custom registry code for every project,
one can write and run the infrastructure in one place,
and every project that uses that registry requires only a few lines of JSON.
[legal-example]: https://gcc.gnu.org/legacy-ml/libstdc++/2019-09/msg00054.html
[fuzzing]: https://en.wikipedia.org/wiki/Fuzzing
## Specification
We will be adding a new file that vcpkg understands - `vcpkg-configuration.json`.
The way that vcpkg will find this file is different depending on what mode vcpkg is in:
in classic mode, vcpkg finds this file alongside the vcpkg binary, in the root directory.
In manifest mode, vcpkg finds this file alongside the manifest. For the initial implementation,
this is all vcpkg will look for; however, in the future, vcpkg will walk the tree and include
configuration all along the way: this allows for overriding defaults.
The specific algorithm for applying this is not yet defined, since currently only one
`vcpkg-configuration.json` is allowed.
The only thing allowed in a `vcpkg-configuration.json` is a `<configuration>` object.
A `<configuration>` is an object:
* Optionally, `"default-registry"`: A `<registry-implementation>` or `null`
* Optionally, `"registries"`: An array of `<registry>`s
Since this is the first RFC that adds anything to this field,
as of now the only properties that can live in that object will be
these.
A `<registry-implementation>` is an object matching one of the following:
* `<registry-implementation.builtin>`:
* `"kind"`: The string `"builtin"`
* `<registry-implementation.directory>`:
* `"kind"`: The string `"directory"`
* `"path"`: A path
* `<registry-implementation.git>`:
* `"kind"`: The string `"git"`
* `"repository"`: A URI
* Optionally, `"path"`: An absolute path into the git repository
* Optionally, `"ref"`: A git reference
A `<registry>` is a `<registry-implementation>` object, plus the following properties:
* Optionally, `"scopes"`: An array of `<package-name>`s
* Optionally, `"packages"`: An array of `<package-name>`s
The `"packages"` and `"scopes"` fields of distinct registries must be disjoint,
and each `<registry>` must have at least one of the `"scopes"` and `"packages"` property,
since otherwise there's no point.
As an example, a package which uses a different default registry, and a different registry for boost,
might look like the following:
```json
{
"default-registry": {
"kind": "directory",
"path": "vcpkg-ports"
},
"registries": [
{
"kind": "git",
"repository": "https://github.com/boostorg/vcpkg-ports",
"ref": "v1.73.0",
"scopes": [ "boost" ]
},
{
"kind": "builtin",
"packages": [ "cppitertools" ]
}
]
}
```
This will install `fmt` from `<directory-of-vcpkg.json>/vcpkg-ports`,
`cppitertools` from the registry that ships with vcpkg,
and any `boost` dependencies from `https://github.com/boostorg/vcpkg-ports`.
Notably, this does not replace behavior up the tree -- only the `vcpkg-configuration.json`s
for the current invocation do anything.
### Behavior
When a vcpkg command requires the installation of dependencies,
it will generate the initial list of dependencies from the package,
and then run the following algorithm on each dependency:
1. Figure out which registry the package should come from by doing the following:
1. If there is a registry in the registry set which contains the dependency name in the `"packages"` array,
then use that registry.
2. For every scope, in order from most specific to least,
if there is a registry in the registry set which contains that scope in the `"scopes"` array,
then use that registry.
(For example, for `"cat.meow.cute"`, check first for `"cat.meow.cute"`, then `"cat.meow"`, then `"cat"`).
3. If the default registry is not `null`, use that registry.
4. Else, error.
2. Then, add that package's dependencies to the list of packages to find, and repeat for the next dependency.
vcpkg will also rerun this algorithm whenever an install is run with different configuration.
### How Registries are Layed Out
There are three kinds of registries, but they only differ in how the registry gets onto one's filesystem.
Once the registry is there, package lookup runs the same, with each kind having it's own way of defining its
own root.
In order to find a port `meow` in a registry with root `R`, vcpkg first sees if `R/meow` exists;
if it does, then the port root is `R/meow`. Otherwise, see if `R/m-` exists; if it does,
then the port root is `R/m-/meow`. (note: this algorithm may be extended further in the future).
For example, given the following port root:
```
R/
abseil/...
b-/
boost/...
boost-build/...
banana/...
banana/...
```
The port root for `abseil` is `R/abseil`; the port root for `boost` is `R/b-/boost`;
the port root for `banana` is `R/banana` (although this duplication is not recommended).
The reason we are making this change to allow more levels in the ports tree is that ~1300
ports are hard to look through in a tree view, and this allows us to see only the ports we're
interested in. Additionally, no port name may end in a `-`, so this means that these port subdirectories
will never intersect with actual ports. Additionally, since we use only ASCII for port names,
we don't have to worry about graphemes vs. code units vs. code points -- in ASCII, they are equivalent.
Let's now look at how different registry kinds work:
#### `<registry.builtin>`
For a `<registry.builtin>`, there is no configuration required.
The registry root is simply `<vcpkg-root>/ports`.
#### `<registry.directory>`
For a `<registry.directory>`, it is again fairly simple.
Given `$path` the value of the `"path"` property, the registry root is either:
* If `$path` is absolute, then the registry root is `$path`.
* If `$path` is drive-relative (only important on Windows), the registry root is
`(drive of vcpkg.json)/$path`
* If `$path` is relative, the registry root is `(directory of vcpkg.json)/$path`
Note that the path to vcpkg.json is _not_ canonicalized; it is used exactly as it is seen by vcpkg.
#### `<registry.git>`
This registry is the most complex. We would like to cache existing registries,
but we don't want to ignore new updates to the registry.
It is the opinion of the author that we want to find more updates than not,
so we will update the registry whenever the `vcpkg.json` or `vcpkg-configuration.json`
is modified. We will do so by keeping a sha512 of the `vcpkg.json` and `vcpkg-configuration.json`
inside the `vcpkg-installed` directory.
We will download the specific ref of the repository to a central location (and update as needed),
and the root will be either: `<path to repository>`, if the `"path"` property is not defined,
or else `<path to repository>/<path property>` if it is defined.
The `"path"` property must be absolute, without a drive, and will be treated as relative to
the path to the repository. For example:
```json
{
"kind": "git",
"repository": "https://github.com/microsoft/vcpkg",
"path": "/ports"
}
```
is the correct way to refer to the registry built in to vcpkg, at the latest version.
The following are all incorrect:
```json
{
"$reason": "path can't be drive-absolute",
"kind": "git",
"repository": "https://github.com/microsoft/vcpkg",
"path": "F:/ports"
}
```
```json
{
"$reason": "path can't be relative",
"kind": "git",
"repository": "https://github.com/microsoft/vcpkg",
"path": "ports"
}
```
```json
{
"$reason": "path _really_ can't be relative like that",
"kind": "git",
"repository": "https://github.com/microsoft/vcpkg",
"path": "../../meow/ports"
}
```

195
vcpkg/docs/tool-maintainers/benchmarking.md Normal file
View File

@ -0,0 +1,195 @@
# Benchmarking
Benchmarking new code against old code is extremely important whenever making
large changes to how something works. If you are attempting to make something
faster, and you end up slowing it down, you'll never know if you don't
benchmark! We have benchmarks in the `toolsrc/src/vcpkg-test` directory, just
like the tests -- they're treated as a special kind of test.
## Running Benchmarks
Unlike normal tests, benchmarks are hidden behind a special define -- `CATCH_CONFIG_ENABLE_BENCHMARKING` -- so that you never try to run benchmarks
unless you specifically want to. This is because benchmarks actually take quite
a long time! However, if you want to run benchmarks (and I recommend running
only specific benchmarks at a time), you can do so by passing the
`VCPKG_ENABLE_BENCHMARKING` option at cmake configure time.
```sh
$ cmake -B toolsrc/out -S toolsrc -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DVCPKG_BUILD_BENCHMARKING=On
-- The C compiler identification is MSVC 19.22.27905.0
-- The CXX compiler identification is MSVC 19.22.27905.0
-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe
-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Looking for pthread.h
-- Looking for pthread.h - not found
-- Found Threads: TRUE
-- Configuring done
-- Generating done
-- Build files have been written to: C:/Users/t-nimaz/src/vcpkg/toolsrc/out
$ cmake --build toolsrc/out
[0/2] Re-checking globbed directories...
[80/80] Linking CXX executable vcpkg-test.exe
```
You can then run benchmarks easily with the following command (which run the
files benchmarks):
```sh
$ ./toolsrc/out/vcpkg-test [!benchmark][file]
```
You can switch out `[file]` for a different set -- `[hash]`, for example.
## Writing Benchmarks
First, before anything else, I recommend reading the
[benchmarking documentation] at Catch2's repository.
Now, after that, let's say that you wanted to benchmark, say, our ASCII
case-insensitive string compare against your new implementation. We place
benchmarks for code in the same file as their tests, so open
`vcpkg-test/strings.cpp`, and add the following at the bottom:
```cpp
#if defined(CATCH_CONFIG_ENABLE_BENCHMARKING)
TEST_CASE ("case insensitive ascii equals: benchmark", "[strings][!benchmark]")
{
BENCHMARK("qwertyuiop") {
return vcpkg::Strings::case_insensitive_ascii_equals("qwertyuiop", "QWERTYUIOP");
};
}
#endif
```
Remember the `;` at the end of the benchmark -- it's not required for
`TEST_CASE`s, but is for `BENCHMARK`s.
Now, let's rebuild and run:
```sh
$ cmake --build toolsrc/out
[0/2] Re-checking globbed directories...
[2/2] Linking CXX executable vcpkg-test.exe
$ ./toolsrc/out/vcpkg-test [strings][!benchmark]
Filters: [strings][!benchmark]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
vcpkg-test.exe is a Catch v2.9.1 host application.
Run with -? for options
-------------------------------------------------------------------------------
case insensitive ascii equals: benchmark
-------------------------------------------------------------------------------
C:\Users\t-nimaz\src\vcpkg\toolsrc\src\vcpkg-test\strings.cpp(36)
...............................................................................
benchmark name samples iterations estimated
mean low mean high mean
std dev low std dev high std dev
-------------------------------------------------------------------------------
qwertyuiop 100 2088 3.9672 ms
25 ns 24 ns 26 ns
6 ns 5 ns 8 ns
===============================================================================
test cases: 1 | 1 passed
assertions: - none -
```
You've now written your first benchmark!
But wait. This seems kind of silly. Benchmarking the comparison of literal
strings is great and all, but could we make it a little more realistic?
This is where `BENCHMARK_ADVANCED` comes in. `BENCHMARK_ADVANCED` allows one to
write a benchmark that has a little setup to it without screwing up the numbers.
Let's try it now:
```cpp
TEST_CASE ("case insensitive ascii equals: benchmark", "[strings][!benchmark]")
{
BENCHMARK_ADVANCED("equal strings")(Catch::Benchmark::Chronometer meter)
{
std::vector<std::string> strings;
strings.resize(meter.runs());
std::mt19937_64 urbg;
std::uniform_int_distribution<std::uint64_t> data_generator;
std::generate(strings.begin(), strings.end(), [&] {
std::string result;
for (std::size_t i = 0; i < 1000; ++i)
{
result += vcpkg::Strings::b32_encode(data_generator(urbg));
}
return result;
});
meter.measure(
[&](int run) { return vcpkg::Strings::case_insensitive_ascii_equals(strings[run], strings[run]); });
};
}
```
Then, run it again!
```sh
$ cmake --build toolsrc/out
[0/2] Re-checking globbed directories...
[2/2] Linking CXX executable vcpkg-test.exe
$ toolsrc/out/vcpkg-test [strings][!benchmark]
Filters: [strings][!benchmark]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
vcpkg-test.exe is a Catch v2.9.1 host application.
Run with -? for options
-------------------------------------------------------------------------------
case insensitive ascii equals: benchmark
-------------------------------------------------------------------------------
C:\Users\t-nimaz\src\vcpkg\toolsrc\src\vcpkg-test\strings.cpp(36)
...............................................................................
benchmark name samples iterations estimated
mean low mean high mean
std dev low std dev high std dev
-------------------------------------------------------------------------------
equal strings 100 2 5.4806 ms
22.098 us 21.569 us 23.295 us
3.842 us 2.115 us 7.41 us
===============================================================================
test cases: 1 | 1 passed
assertions: - none -
```
And now you have a working benchmark to test the speed of the existing code, and
of new code!
If you're writing a lot of benchmarks that follow the same sort of pattern, with
some differences in constants, look into `vcpkg-test/files.cpp`'s benchmarks --
there are a lot of things one can do to make writing new benchmarks really easy.
If you wish to add a benchmark for a piece of code that has not yet been tested,
please read the [testing documentation], and please write some unit tests.
The speed of your code isn't very important if it doesn't work at all!
[benchmarking documentation]: https://github.com/catchorg/Catch2/blob/master/docs/benchmarks.md#top
[testing documentation]: ./testing.md#adding-new-test-files

74
vcpkg/docs/tool-maintainers/layout.md Normal file
View File

@ -0,0 +1,74 @@
# Layout of the vcpkg source tree
All vcpkg sources and build systems are in `toolsrc`. If you'd like to
contribute to the vcpkg tool itself, most of your time will be spent in here.
## Build Files
These are the files used to build and configure the project. In order to build
with CMake, the only files you should be interested in are `CMakeLists.txt`, and
`.clang-format`; in order to build with msbuild or the Visual Studio IDE, you
will be interested in `dirs.proj` or `vcpkg.sln`. However, if you add or remove
files, you will need to edit the MSBuild project files in the `vcpkg*`
directories no matter what system you use.
### Top Level
We have six files in this directory -- one `.clang-format` file, one
`CMakeLists.txt` file, three Visual Studio files, and `VERSION.txt`.
- `.clang-format`: This is where we store the formatting settings of the
project. If you want to format the project, you can use the `format` target
with the CMake build system.
- `CMakeLists.txt`: This is where the CMake build system definition lives. If
you want to modify how one builds the project, or add a target, you can do
it here.
- `VERSION.txt`: This is a file which tells `vcpkg` to tell the user to
rebuild. If this version is different from the version when the user built
the binary (for example, after a `git pull` or a `vcpkg update`), then
`vcpkg` will print a message to re-bootstrap. This is updated whenever major
changes are made to the `vcpkg` tool.
- The Visual Studio files:
- `vcpkg.natvis`: NATVIS files allow one to visualize objects of user
defined type in the debugger -- this one contains the definitions for
`vcpkg`'s types.
- `dirs.proj`: This is how one builds with `msbuild` without calling into
the IDE.
- `vcpkg.sln`: The solution file is how one opens the project in the VS IDE.
## Source Files
If you're modifying the project, it's likely that these are the directories that
you're going to deal with.
### `include`
There's one file in here -- `pch.h`. This contains most of the C++ standard
library, and acts as a [precompiled header]. You can read more at the link.
There are three directories:
- `catch2` -- This contains the single-header library [catch2]. We use this
library for both [testing] and [benchmarking].
- `vcpkg` -- This contains the header files for the `vcpkg` project. All of
the interfaces for building, installing, and generally "port stuff" live
here.
- `vcpkg/base` -- This contains the interfaces for the
"vcpkg standard library" -- file handling, hashing, strings,
`Span<T>`, printing, etc.
- `vcpkg-test` -- This contains the interfaces for any common utilities
required by the tests.
### `src`
The source files live here. `pch.cpp` is the source file for the
[precompiled header]; `vcpkg.cpp` is where the `vcpkg` binary lives.
The interesting files live in the `vcpkg` and `vcpkg-test` directories. In
`vcpkg`, you have the implementation for the interfaces that live in
`include/vcpkg`; and in `vcpkg-test`, you have the tests and benchmarks.
[precompiled header]: https://en.wikipedia.org/wiki/Precompiled_header
[catch2]: https://github.com/catchorg/Catch2
[testing]: ./testing.md
[benchmarking]: ./benchmarking.md

152
vcpkg/docs/tool-maintainers/testing.md Normal file
View File

@ -0,0 +1,152 @@
# Testing
Testing vcpkg is important whenever one makes changes to the tool itself, and
writing new tests and keeping them up to date is also very important. If one's
code is subtly broken, we'd rather find it out right away than a few weeks down
the line when someone complains!
## Running Tests
Before anything else, we should know whether you can actually run the tests!
All you should need is a way to build vcpkg -- anything will do! All you have to
do is follow the guide 😄
With `$VCPKG_DIRECTORY` being the directory where you have cloned vcpkg, create
a build directory in `$VCPKG_DIRECTORY/toolsrc` (commonly named `out`), and
`cd` into it. Make sure to clean it out if it already exists!
```sh
$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja
$ cmake --build .
$ ./vcpkg-test # ./vcpkg-test [$SPECIFIC_TEST] for a specific set of tests
$ # i.e., ./vcpkg-test [arguments]
```
If you make any modifications to `vcpkg`, you'll have to do the
`cmake --build .` step again.
## Writing Tests
In your journey to write new tests, and to modify existing tests, reading the
[Catch2 documentation] will be very helpful! Come back after reading those 😀
You'll want to place your tests in one of the existing files, or, if it doesn't
belong in any of those, in a [new file](#adding-new-test-files).
The layout of these tests is as follows:
```cpp
// ... includes
TEST_CASE("Name of test", "[filename without the .cpp]") {
// setup and the like
REQUIRE(some boolean expression);
}
// etc.
```
You want to give these test cases good, descriptive, unique names, like
`SourceParagraph construct minimum` -- it doesn't need to be extremely clear
english, and shorthand is good, but make sure it's clear what the test is from
the name. For the latter parameter, known as "tags", you should at least put the
name of the file which the test case is in -- e.g., in `arguments.cpp`, you'd
tag all of the test cases with `[arguments]`.
If you wish to add helper functions, make sure to place them in an anonymous
namespace -- this will ensure that they don't trample over anybody else's
space. Additionally, there are a few helper functions that live in
`<vcpkg-test/util.h>` and `src/vcpkg-test/util.cpp` -- make sure to look into
them so that you're not rewriting functionality.
That should be all you need to know to start writing your own tests!
Remember to check out the [Catch2 documentation]
if you'd like to get more advanced with your tests,
and good luck on your testing journey!
## Adding New Test Files
Adding new test files should be easy and straightforward. All it requires is
creating a new source file in `toolsrc/src/vcpkg-test`.
### Example
Let's try writing a new test file called `example` (very creative, I know).
First, we should create a file, `example.cpp`, in `toolsrc/src/vcpkg-test`:
```cpp
// vcpkg-test/example.cpp
#include <catch2/catch.hpp>
```
This is the minimum file needed for tests; let's rebuild!
```sh
$ cmake --build .
[80/80] Linking CXX executable vcpkg.exe
```
Okay, now let's make sure this worked; add a test case to `example.cpp`:
```cpp
TEST_CASE("Example 1 - fail", "[example]") {
REQUIRE(false);
}
```
Now build the tests again, and run them:
```sh
$ cmake --build .
[2/2] Linking CXX executable vcpkg-test.exe
$ ./vcpkg-test
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
vcpkg-test.exe is a Catch v2.9.1 host application.
Run with -? for options
-------------------------------------------------------------------------------
Example 1 - fail
-------------------------------------------------------------------------------
$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(3)
...............................................................................
$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(14): FAILED:
REQUIRE( false )
===============================================================================
test cases: 102 | 101 passed | 1 failed
assertions: 3611 | 3610 passed | 1 failed
```
Hopefully, that worked! It should compile correctly, and have one failing test.
Now let's try a more complex test, after deleting the old one;
```cpp
// add #include <vcpkg/base/strings.h> to the top of the file
namespace Strings = vcpkg::Strings;
TEST_CASE("Example 2 - success", "[example]") {
std::string hello = "Hello";
REQUIRE(Strings::case_insensitive_ascii_equals(hello, "hELLo"));
REQUIRE_FALSE(Strings::case_insensitive_ascii_starts_with(hello, "E"));
}
```
Now compile and build the tests, and this time let's only run our example tests:
```sh
$ cmake --build .
[2/2] Linking CXX executable vcpkg-test.exe
$ ./vcpkg-test [example]
Filters: [example]
===============================================================================
All tests passed (2 assertions in 1 test case)
```
Hopefully you have one test running and succeeding! If you have that, you have
succeeded at adding a new file to vcpkg's tests. Congratulations! Have fun on
the rest of your journey 🐱‍👤😁
[Catch2 documentation]: https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md#top

168
vcpkg/docs/users/android.md Normal file
View File

@ -0,0 +1,168 @@
# Vcpkg and Android
Android is not officialy supported, and there are no official android triplets at the moment.
However, some packages can compile to Android, and the situation is improving: see the list of [PR related to Android](https://github.com/Microsoft/vcpkg/pulls?q=+android+).
## Android build requirements
1. Download the [android ndk](https://developer.android.com/ndk/downloads/)
2. Set environment variable `ANDROID_NDK_HOME` to your android ndk installation.
For example:
````bash
export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
````
Or:
````bash
export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
````
3. Install [vcpkg](https://github.com/microsoft/vcpkg)
4. Set environment variable `VCPKG_ROOT` to your vcpkg installation.
````bash
export VCPKG_ROOT=/path/to/vcpkg
````
## Create the android triplets
### Android ABI and corresponding vcpkg triplets
There are four different Android ABI, each of which maps to
a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures
|VCPKG_TARGET_TRIPLET | ANDROID_ABI |
|---------------------------|----------------------|
|arm64-android | arm64-v8a |
|arm-android | armeabi-v7a |
|x64-android | x86_64 |
|x86-android | x86 |
### Create the android triplets
You can copy-paste the script below to populate them, and adjust them to your needs if required.
````bash
cd $VCPKG_ROOT
echo "
set(VCPKG_TARGET_ARCHITECTURE arm)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
" > triplets/community/arm-android.cmake
echo "
set(VCPKG_TARGET_ARCHITECTURE arm64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
" > triplets/community/arm64-android.cmake
echo "
set(VCPKG_TARGET_ARCHITECTURE x86)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
" > triplets/community/x86-android.cmake
echo "
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
" > triplets/community/x64-android.cmake
````
## Install libraries for Android using vcpkg
Example for jsoncpp:
````bash
cd $VCPKG_ROOT
# specify the triplet like this
./vcpkg install jsoncpp --triplet arm-android
# or like this
./vcpkg install jsoncpp:arm64-android
./vcpkg install jsoncpp:x86-android
./vcpkg install jsoncpp:x64-android
````
## Consume libraries using vpckg, cmake and the android toolchain
1. Combine vcpkg and Android toolchains
vcpkg and android both provide dedicated toolchains:
````bash
vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
````
When using vcpkg, the vcpkg toolchain shall be specified first.
However, vcpkg provides a way to preload and additional toolchain, with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option.
````bash
cmake \
-DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
...
````
2. Specifiy the android abi and vcpkg triplet
When compiling for android, you need to select a matching "android abi" / "vcpkg triplet" pair.
For example:
````bash
android_abi=armeabi-v7a
vcpkg_target_triplet=arm-android
cmake
...
-DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
-DANDROID_ABI=$android_abi
````
### Test on an example
The folder [docs/examples/vcpkg_android_example_cmake](../examples/vcpkg_android_example_cmake) provides a working example, with an android library that consumes the jsoncpp library:
*Details*
* The [CMakeLists](../examples/vcpkg_android_example_cmake/CMakeLists.txt) simply uses `find_package` and `target_link_library`
* The [compile.sh](../examples/vcpkg_android_example_cmake/compile.sh) script enables you to select any matching pair of "android abi" / "vcpkg triplet" and to test the compilation
* The dummy [my_lib.cpp](../examples/vcpkg_android_example_cmake/my_lib.cpp) file uses the jsoncpp library
*Note*: this example only compiles an Android library, as the compilation of a full fledged Android App is beyond the scope of this document.
### Test on an example, using [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake)
The folder [docs/examples/vcpkg_android_example_cmake_script](../examples/vcpkg_android_example_cmake_script) provides the same example, and uses a cmake script in order to simplify the usage.
*Details*
* The main [CMakeLists](../examples/vcpkg_android_example_cmake_script/CMakeLists.txt) loads [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake) if the flag `VCPKG_TARGET_ANDROID` is set:
````cmake
if (VCPKG_TARGET_ANDROID)
include("cmake/vcpkg_android.cmake")
endif()
````
*Important: place these lines before calling project() !*
* The [compile.sh](../examples/vcpkg_android_example_cmake_script/compile.sh) script shows that it is then possible to compile for android using a simple cmake invocation, for example:
````bash
cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a
````
## Consume libraries using vpckg, and Android prefab Archives (AAR files)
See [prefab.md](../specifications/prefab.md)

151
vcpkg/docs/users/binarycaching.md Normal file
View File

@ -0,0 +1,151 @@
# Binary Caching
Binary caching is vcpkg's method for reusing package builds between projects and between machines. Think of it as a "package restore accelerator" that gives you the same results as though you built from source. Each build is packaged independently, so changing one library only requires rebuilding consuming libraries.
If your CI provider offers a native "caching" function, we recommend using both methods for the most performant results.
In-tool help is available via `vcpkg help binarycaching` and a [detailed configuration reference is provided below](#Configuration).
## CI Examples
If your CI system of choice is not listed, we welcome PRs to add them!
### GitHub Packages
To use vcpkg with GitHub Packages, we recommend using the `NuGet` backend.
>**NOTE 2020-09-21**: GitHub's hosted agents come with an older, pre-installed copy of vcpkg on the path that does not support the latest binary caching. This means that direct calls to `bootstrap-vcpkg` or `vcpkg` without a path prefix may call an unintended vcpkg instance. We recommend taking the following two steps to avoid issues if you want to use your own copy of vcpkg:
> 1. Run the equivalent of `rm -rf "$VCPKG_INSTALLATION_ROOT"` using `shell: 'bash'`
> 2. Always call `vcpkg` and `bootstrap-vcpkg` with a path prefix, such as `./vcpkg`, `vcpkg/vcpkg`, `.\bootstrap-vcpkg.bat`, etc
```yaml
# actions.yaml
#
# In this example, vcpkg has been added as a submodule (`git submodule add https://github.com/Microsoft/vcpkg`).
env:
VCPKG_BINARY_SOURCES: 'clear;nuget,GitHub,readwrite'
matrix:
os: ['windows-2019', 'ubuntu-20.04']
include:
- os: 'windows-2019'
triplet: 'x86-windows'
mono: ''
- os: 'ubuntu-20.04'
triplet: 'x64-linux'
# To run `nuget.exe` on non-Windows platforms, we must use `mono`.
mono: 'mono'
steps:
# This step assumes `vcpkg` has been bootstrapped (run `./vcpkg/bootstrap-vcpkg`)
- name: 'Setup NuGet Credentials'
shell: 'bash'
# Replace <OWNER> with your organization name
run: >
${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1`
sources add
-source "https://nuget.pkg.github.com/<OWNER>/index.json"
-storepasswordincleartext
-name "GitHub"
-username "<OWNER>"
-password "${{ secrets.GITHUB_TOKEN }}"
# Omit this step if you're using manifests
- name: 'vcpkg package restore'
shell: 'bash'
run: >
./vcpkg/vcpkg install sqlite3 cpprestsdk --triplet ${{ matrix.triplet }}
```
If you're using [manifests](../specifications/manifests.md), you can omit the `vcpkg package restore` step: it will be run automatically as part of your build.
More information about GitHub Packages' NuGet support is available on [GitHub Docs][github-nuget].
[github-nuget]: https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages
### Azure DevOps Artifacts
To use vcpkg with Azure DevOps Artifacts, we recommend using the `NuGet` backend.
First, you need to ensure Artifacts has been enabled on your DevOps instance; this can be done by an Administrator through `Project Settings > General > Overview > Azure DevOps Services > Artifacts`.
Next, you will need to create a feed for your project; see the [Azure DevOps Artifacts Documentation][devops-nuget] for more information. Your feed URL will be an `https://` link ending with `/nuget/v3/index.json`.
```yaml
# azure-pipelines.yaml
variables:
- name: VCPKG_BINARY_SOURCES
value: 'clear;nuget,<FEED_URL>,readwrite'
```
If you are using custom agents with a non-Windows OS, you will need to install Mono to run `nuget.exe` (`apt install mono-complete`, `brew install mono`, etc).
More information about Azure DevOps Artifacts' NuGet support is available in the [Azure DevOps Artifacts Documentation][devops-nuget].
[devops-nuget]: https://docs.microsoft.com/en-us/azure/devops/artifacts/get-started-nuget?view=azure-devops
## Configuration
Binary caching is configured via a combination of defaults, the environment variable `VCPKG_BINARY_SOURCES` (set to `<source>;<source>;...`), and the command line option `--binarysource=<source>`. Source options are evaluated in order of defaults, then environment, then command line.
By default, zip-based archives will be cached at the first valid location of:
**Windows**
1. `%VCPKG_DEFAULT_BINARY_CACHE%`
2. `%LOCALAPPDATA%\vcpkg\archives`
3. `%APPDATA%\vcpkg\archives`
**Non-Windows**
1. `$VCPKG_DEFAULT_BINARY_CACHE`
2. `$XDG_CACHE_HOME/vcpkg/archives`
3. `$HOME/.cache/vcpkg/archives`
### Valid source strings (`<source>`)
| form | description
|-----------------------------|---------------
| `clear` | Removes all previous sources (including the default)
| `default[,<rw>]` | Adds the default file-based location
| `files,<path>[,<rw>]` | Adds a custom file-based location
| `nuget,<uri>[,<rw>]` | Adds a NuGet-based source; equivalent to the `-Source` parameter of the NuGet CLI
| `nugetconfig,<path>[,<rw>]` | Adds a NuGet-config-file-based source; equivalent to the `-Config` parameter <br>of the NuGet CLI. This config should specify `defaultPushSource` for uploads.
| `interactive` | Enables interactive credential management for NuGet (for debugging; requires `--debug` on the command line)
The `<rw>` optional parameter for certain sources controls whether they will be consulted for
downloading binaries (`read`), whether on-demand builds will be uploaded to that remote (`write`), or both (`readwrite`).
The `nuget` and `nugetconfig` source providers additionally respect certain environment variables while generating nuget packages. The `metadata.repository` field of any packages will be generated as:
```
<repository type="git" url="${VCPKG_NUGET_REPOSITORY}"/>
```
or
```
<repository type="git"
url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
branch="${GITHUB_REF}"
commit="${GITHUB_SHA}"/>
```
if the appropriate environment variables are defined and non-empty. This is specifically used to associate packages in GitHub Packages with the _building_ project and not intended to associate with the original package sources.
Finally, binary caching can be completely disabled by passing `--no-binarycaching` on the command line.
## Implementation Notes (internal details subject to change without notice)
Binary caching relies on hashing everything that contributes to a particular package build. This includes:
- Every file in the port directory
- The triplet file and name
- The C++ compiler executable
- The C compiler executable
- The set of features selected
- Every dependency's package hash (note: this is that package's input hash, not contents)
- All helper scripts referenced by `portfile.cmake` (heuristic)
- The version of CMake used
- The contents of any environment variables listed in `VCPKG_ENV_PASSTHROUGH`
- The hash of the toolchain file (builtin or `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`)
Despite this extensive list, it is possible to defeat the cache and introduce nondeterminism. If you have additional details that you'd like to be tracked, the easiest resolution is to generate a triplet file with your additional information in a comment. That additional information will be included in the package's input set and ensure a unique universe of binaries.
The hashes used are stored in the package and in the current installed directory at `/share/<port>/vcpkg_abi_info.txt`.
The original specification for binary caching is available [here](../specifications/binarycaching.md).

64
vcpkg/docs/users/config-environment.md Normal file
View File

@ -0,0 +1,64 @@
## Environment and Configuration
### Environment Variables
#### VCPKG_DOWNLOADS
This environment variable can be set to an existing directory to use for storing downloads instead of the internal
`downloads/` directory. It should always be set to an absolute path.
#### VCPKG_FEATURE_FLAGS
This environment variable can be set to a comma-separated list of off-by-default features in vcpkg. These features are
subject to change without notice and should be considered highly unstable.
Non-exhaustive list of off-by-default features:
- `binarycaching`
- `manifest`
#### EDITOR
This environment variable can be set to the full path of an executable to be used for `vcpkg edit`. Please see
`vcpkg help edit` for command-specific help.
#### VCPKG_ROOT
This environment variable can be set to a directory to use as the root of the vcpkg instance. Note that mixing vcpkg
repo versions and executable versions can cause issues.
#### VCPKG_VISUAL_STUDIO_PATH
This environment variable can be set to the full path to a Visual Studio instance on the machine. This Visual Studio instance
will be used if the triplet does not override it via the [`VCPKG_VISUAL_STUDIO_PATH` triplet setting](triplets.md#VCPKG_VISUAL_STUDIO_PATH).
Example: `D:\2017`
#### VCPKG_DEFAULT_TRIPLET
This environment variable can be set to a triplet name which will be used for unqualified triplet references in command lines.
#### VCPKG_OVERLAY_PORTS
This environment variable allows users to override ports with alternate versions according to the
[ports overlay](../specifications/ports-overlay.md) specification. List paths to overlays using
the platform dependent PATH seperator (Windows `;` | others `:`)
Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3`
#### VCPKG_OVERLAY_TRIPLETS
This environment variable allows users to add directories to search for triplets.
[Example: overlay triplets](../examples/overlay-triplets-linux-dynamic.md).
List paths to overlays using the platform dependent PATH seperator (Windows `;`, others `:`)
#### VCPKG_FORCE_SYSTEM_BINARIES
This environment variable, if set, suppresses the downloading of CMake and Ninja and forces the use of the system binaries.
#### VCPKG_KEEP_ENV_VARS
This environment variable can be set to a list of environment variables, separated by `;`, which will be propagated to
the build environment.
Example: `FOO_SDK_DIR;BAR_SDK_DIR`

153
vcpkg/docs/users/integration.md Normal file
View File

@ -0,0 +1,153 @@
## 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)
Each integration style has heuristics to deduce the correct [triplet][]. This can be overridden using [a common method](#triplet-selection) based on your buildsystem.
<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.
<a name="user-wide-msbuild"></a>
#### 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, VS2017 and VS2019 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 [Installing and Using Packages Example: sqlite](../examples/installing-and-using-packages.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 NAMES catch.hpp PATH_SUFFIXES catch2)
include_directories(${CATCH_INCLUDE_DIR})
```
##### Using an environment variable instead of a command line option
The `CMAKE_TOOLCHAIN_FILE` setting simply must be set before the `project()` directive is first called. This means that you can easily read from an environment variable to avoid passing it on the configure line:
```cmake
if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
CACHE STRING "")
endif()
project(myproject CXX)
```
##### Using multiple toolchain files
To use an external toolchain file with a project using vcpkg, you can set the cmake variable `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` on the configure line:
```no-highlight
cmake ../my/project \
-DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/compiler-settings-toolchain.cmake
```
#### 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.
<a name="triplet-selection"></a>
### Triplet selection
Every integration mechanism besides manually adding the folders will deduce a [triplet][] for your project as one of:
- x86-windows
- x64-windows
- x86-uwp
- x64-uwp
- arm-uwp
#### With MSBuild
You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher:
> *Shortcut: Ctrl+Q "build and run"*
>
> Tools -> Options -> Projects and Solutions -> Build and Run -> MSBuild project build output verbosity
To override the automatically chosen [triplet][], you can specify the MSBuild property `VcpkgTriplet` in your `.vcxproj`. We recommend adding this to the `Globals` PropertyGroup.
```xml
<PropertyGroup Label="Globals">
<!-- .... -->
<VcpkgTriplet Condition="'$(Platform)'=='Win32'">x86-windows-static</VcpkgTriplet>
<VcpkgTriplet Condition="'$(Platform)'=='x64'">x64-windows-static</VcpkgTriplet>
</PropertyGroup>
```
#### With CMake
You can set `VCPKG_TARGET_TRIPLET` on the configure line:
```no-highlight
cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=...
```
If you use `VCPKG_DEFAULT_TRIPLET` [environment variable](config-environment.md) to control the unqualified triplet in vcpkg command lines you can default `VCPKG_TARGET_TRIPLET` in CMake like [Using an environment variable instead of a command line option](#using-an-environment-variable-instead-of-a-command-line-option):
```cmake
if(DEFINED ENV{VCPKG_DEFAULT_TRIPLET} AND NOT DEFINED VCPKG_TARGET_TRIPLET)
set(VCPKG_TARGET_TRIPLET "$ENV{VCPKG_DEFAULT_TRIPLET}" CACHE STRING "")
endif()
```
[triplet]: triplets.md

259
vcpkg/docs/users/manifests.md Normal file
View File

@ -0,0 +1,259 @@
# Manifest Mode
vcpkg has two modes of operation - classic mode and manifest mode.
In classic mode, vcpkg produces an "installed" tree,
whose contents are changed by explicit calls to `vcpkg install` or `vcpkg remove`.
The installed tree is intended for consumption by any number of projects:
for example, installing a bunch of libraries and then using those libraries from Visual Studio,
without additional configuration.
Because the installed tree is not associated with an individual project,
it's similar to tools like `brew` or `apt`,
except that the installed tree is vcpkg-installation-local,
rather than global to a system or user.
In manifest mode, an installed tree is associated with a particular project rather than the vcpkg installation.
The set of installed ports is controlled by editing the project's "manifest file",
and the installed tree is placed in the project directory or build directory.
This mode acts more similarly to language package managers like Cargo, or npm.
We recommend using this manifest mode whenever possible,
because it allows one to encode a project's dependencies explicitly in a project file,
rather than in the documentation, making your project much easier to consume.
Manifest mode is in beta, but one can use it from the CMake integration,
which will be stable when used via things like `find_package`.
This is the recommended way to use manifest mode.
In this document, we have basic information on [Writing a Manifest](#writing-a-manifest),
the [vcpkg Command Line Interface](#command-line-interface),
and a little more information on [CMake](#cmake-integration) integration.
Check out the [manifest cmake example](../examples/manifest-mode-cmake.md) for an example project using CMake and manifest mode.
## Writing a Manifest
A manifest is a JSON-formatted file which lies at the root of your project.
It contains all the information a person needs to know to get dependencies for your project,
as well as all the metadata about your project that a person who depends on you might be interested in.
Every manifest is named `vcpkg.json`, and has a top level object. It is a strict JSON file,
and can't contain things like comments or trailing commas - however,
you can use field names that start with `$` to write your comments.
All of the fields that `vcpkg.json` supports are as follows; the most important ones are [`"name"`](#name),
the [version fields](#version-fields), and [`"dependencies"`](#dependencies):
### `"name"`
This is the name of your project! It must be formatted in a way that vcpkg understands - in other words,
it must be lowercase alphabetic characters, digits, and hyphens, and it must not start nor end with a hyphen.
For example, `Boost.Asio` might be given the name `boost-asio`.
This is a required field.
### Version fields
There is, at this point, only one version field - `"version-string"`. However, more will be added in the future.
You must have one (and only one) version field. There are different reasons to use each version field:
* `"version-string"` - used for packages that don't have orderable versions. This is pretty uncommon,
but since we don't have any versioning constraints yet, this is the only one that you can use.
Additionally, the `"port-version"` field is used by registries of packages,
as a way to version "the package gotten from `vcpkg install`" differently from the upstream package version.
You shouldn't need to worry about this at all.
### `"description"`
This is where you describe your project. Give it a good description to help in searching for it!
This can be a single string, or it can be an array of strings;
in the latter case, the first string is treated as a summary,
while the remaining strings are treated as the full description.
### `"dependencies"`
This field lists all the dependencies you'll need to build your library (as well as any your dependents might need,
if they were to use you). It's an array of strings and objects:
* A string dependency (e.g., `"dependencies": [ "zlib" ]`) is the simplest way one can depend on a library;
it means you don't depend on a single version, and don't need to write down any more information.
* On the other hand, an object dependency (e.g., `"dependencies": [ { "name": "zlib" } ]`)
allows you to add that extra information.
An object dependency can have the following fields:
#### `"name"`
The name of the dependency. This follows the same restrictions as the [`"name"`](#name) property for a project.
#### `"features"` and `"default-features"`
`"features"` is an array of feature names which tell you the set of features that the
dependencies need to have at a minimum,
while `"default-features"` is a boolean that tells vcpkg whether or not to
install the features the package author thinks should be "most common for most people to use".
For example, `ffmpeg` is a library which supports many, many audio and video codecs;
however, for your specific project, you may only need mp3 encoding.
Then, you might just ask for:
```json
{
"name": "ffmpeg",
"default-features": false,
"features": [ "mp3lame" ]
}
```
#### `"platform"`
The `"platform"` field defines the platforms where the dependency should be installed - for example,
you might need to use sha256, and so you use platform primitives on Windows, but `picosha2` on non-Windows platforms.
```json
{
"name": "picosha2",
"platform": "!windows"
}
```
This is a string field which takes boolean expressions of the form `<identifier>`,
`!expression`, `expression { & expression & expression...}`, and `expression { | expression | expression...}`,
along with parentheses to denote precedence.
For example, a dependency that's only installed on the Windows OS, for the ARM64 architecture,
and on Linux on x64, would be written `(windows & arm64) | (linux & x64)`.
The common identifiers are:
- The operating system: `windows`, `uwp`, `linux`, `osx` (includes macOS), `android`, `emscripten`
- The architecture: `x86`, `x64`, `wasm32`, `arm64`, `arm` (includes both arm32 and arm64 due to backwards compatibility)
although one can define their own.
#### Example:
```json
{
"dependencies": [
{
"name": "arrow",
"default-features": false,
"features": [ "json" ]
},
"boost-asio",
"openssl",
{
"name": "picosha2",
"platform": "!windows"
}
]
}
```
### `"supports"`
If your project doesn't support common platforms, you can tell your users this with the `"supports"` field.
It uses the same platform expressions as [`"platform"`](#platform), from dependencies, as well as the
`"supports"` field of features.
For example, if your library doesn't support linux, you might write `{ "supports": "!linux" }`.
### `"features"` and `"default-features"`
The `"features"` field defines _your_ project's optional features, that others may either depend on or not.
It's an object, where the keys are the names of the features, and the values are objects describing the feature.
`"description"` is required,
and acts exactly like the [`"description"`](#description) field on the global package,
and `"dependencies"` are optional,
and again act exactly like the [`"dependencies"`](#dependencies) field on the global package.
There's also the `"supports"` field,
which again acts exactly like the [`"supports"`](#supports) field on the global package.
You also have control over which features are default, if a person doesn't ask for anything specific,
and that's the `"default-features"` field, which is an array of feature names.
#### Example:
```
{
"name": "libdb",
"description": [
"An example database library.",
"Optionally uses one of CBOR, JSON, or CSV as a backend."
],
"default-features": [ "cbor", "csv", "json" ],
"features": {
"cbor": {
"description": "The CBOR backend",
"dependencies": [
{
"$explanation": [
"This is currently how you tell vcpkg that the cbor feature depends on the json feature of this package",
"We're looking into making this easier"
],
"name": "libdb",
"default-features": false,
"features": [ "json" ]
}
]
},
"csv": {
"description": "The CSV backend",
"dependencies": [
"fast-cpp-csv-parser"
]
},
"gui": {
"description": "The GUI libdb database viewer.",
"supports": "windows | osx"
}
"json": {
"description": "The JSON backend",
"dependencies": [
"jsoncons"
]
},
}
}
```
## Command Line Interface
The command line interface around the new manifest mode is pretty simple.
There's only one command that one really needs to worry about, `vcpkg install`,
although `vcpkg search` is still useful.
Since manifest mode is still in beta, you'll need to pass a feature flag: `manifests`.
There are a few ways to pass this feature flag:
* `--feature-flags` option: On any vcpkg command, you can pass `--feature-flags=manifests`
* `VCPKG_FEATURE_FLAGS` environment variable: one can set the environment variable `VCPKG_FEATURE_FLAGS` to
`manifests`.
### `vcpkg install`
Once one has written a manifest file,
they can run `vcpkg install` in any subdirectory of the directory containing `vcpkg.json`.
It will install all of the dependencies for the default triplet into
`<directory containing vcpkg.json>/vcpkg_installed`.
If you want to switch the triplet (for example, this is very common on windows, where the default triplet is x86-windows, not x64-windows),
you can pass it with the `--triplet` option: `vcpkg install --triplet x64-windows` (or whatever).
Then, vcpkg will install all the dependencies, and you're ready to go!
## CMake Integration
The CMake integration acts exactly like the existing CMake integration.
One passes the toolchain file, located at `[vcpkg root]/scripts/buildsystems/vcpkg.cmake`,
to the CMake invocation via the `CMAKE_TOOLCHAIN_FILE` variable.
Then, CMake will install all dependencies into the build directory, and you're good!
It ends up that you only have to run CMake, and vcpkg is called only as part of the build process.
Unlike bare vcpkg, the feature flag is not required,
since the CMake integration won't break as long as you depending on the exact naming of vcpkg's installed directory.
### Example:
```
> cmake -B builddir -S . -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
> cmake --build builddir
```
with a `vcpkg.json` in the same directory as `CMakeLists.txt` should Just Work!

183
vcpkg/docs/users/triplets.md Normal file
View File

@ -0,0 +1,183 @@
# Triplet files
Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name.
In Vcpkg, we use triplets to describe an imaginary "target configuration set" for every library. Within a triplet, libraries are generally built with the same configuration, but it is not a requirement. For example, you could have one triplet that builds `openssl` statically and `zlib` dynamically, one that builds them both statically, and one that builds them both dynamically (all for the same target OS and architecture). A single build will consume files from a single triplet.
We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily add your own by creating a new file in the `triplets\` directory. The new triplet will immediately be available for use in commands, such as `vcpkg install boost:x86-windows-custom`.
To change the triplet used by your project, such as to enable static linking, see our [Integration Document](integration.md#triplet-selection).
## Community triplets
Triplets contained in the `triplets\community` folder are not tested by continuous integration, but are commonly requested by the community.
Because we do not have continuous coverage, port updates may break compatibility with community triplets. Because of this, community involvement is paramount!
We will gladly accept and review contributions that aim to solve issues with these triplets.
### Usage
Community Triplets are enabled by default, when using a community triplet a message like the following one will be printed during a package install:
```no-highlight
-- Using community triplet x86-uwp. This triplet configuration is not guaranteed to succeed.
-- [COMMUNITY] Loading triplet configuration from: D:\src\viromer\vcpkg\triplets\community\x86-uwp.cmake
```
## Variables
### VCPKG_TARGET_ARCHITECTURE
Specifies the target machine architecture.
Valid options are `x86`, `x64`, `arm`, `arm64` and `wasm32`.
### VCPKG_CRT_LINKAGE
Specifies the desired CRT linkage (for MSVC).
Valid options are `dynamic` and `static`.
### VCPKG_LIBRARY_LINKAGE
Specifies the preferred library linkage.
Valid options are `dynamic` and `static`. Note that libraries can ignore this setting if they do not support the preferred linkage type.
### VCPKG_CMAKE_SYSTEM_NAME
Specifies the target platform.
Valid options include any CMake system name, such as:
- Empty (Windows Desktop for legacy reasons)
- `WindowsStore` (Universal Windows Platform)
- `MinGW` (Minimalist GNU for Windows)
- `Darwin` (Mac OSX)
- `iOS` (iOS)
- `Linux` (Linux)
- `Emscripten` (WebAssembly)
### VCPKG_CMAKE_SYSTEM_VERSION
Specifies the target platform system version.
This field is optional and, if present, will be passed into the build as `CMAKE_SYSTEM_VERSION`.
See also the CMake documentation for `CMAKE_SYSTEM_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html.
### VCPKG_CHAINLOAD_TOOLCHAIN_FILE
Specifies an alternate CMake Toolchain file to use.
This (if set) will override all other compiler detection logic. By default, a toolchain file is selected from `scripts/toolchains/` appropriate to the platform.
See also the CMake documentation for toolchain files: https://cmake.org/cmake/help/v3.11/manual/cmake-toolchains.7.html.
### VCPKG_CXX_FLAGS
Sets additional compiler flags to be used when not using `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`.
This option also has forms for configuration-specific and C flags:
- `VCPKG_CXX_FLAGS`
- `VCPKG_CXX_FLAGS_DEBUG`
- `VCPKG_CXX_FLAGS_RELEASE`
- `VCPKG_C_FLAGS`
- `VCPKG_C_FLAGS_DEBUG`
- `VCPKG_C_FLAGS_RELEASE`
### VCPKG_LINKER_FLAGS
Sets additional linker flags to be used while building dynamic libraries and
executables in the absence of `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`.
This option also has forms for configuration-specific flags:
- `VCPKG_LINKER_FLAGS`
- `VCPKG_LINKER_FLAGS_DEBUG`
- `VCPKG_LINKER_FLAGS_RELEASE`
<a name="VCPKG_DEP_INFO_OVERRIDE_VARS"></a>
### VCPKG_DEP_INFO_OVERRIDE_VARS
Replaces the default computed list of triplet "Supports" terms.
This option (if set) will override the default set of terms used for qualified dependency resolution and "Supports" field evaluation.
See the [`"supports"`](../maintainers/manifest-files.md#supports) manifest file field documentation for more details.
> Implementers' Note: this list is extracted via the `vcpkg_get_dep_info` mechanism.
## Windows Variables
### VCPKG_ENV_PASSTHROUGH
Instructs vcpkg to allow additional environment variables into the build process.
On Windows, vcpkg builds packages in a special clean environment that is isolated from the current command prompt to ensure build reliability and consistency.
This triplet option can be set to a list of additional environment variables that will be added to the clean environment.
See also the `vcpkg env` command for how you can inspect the precise environment that will be used.
> Implementers' Note: this list is extracted via the `vcpkg_get_tags` mechanism.
<a name="VCPKG_VISUAL_STUDIO_PATH"></a>
### VCPKG_VISUAL_STUDIO_PATH
Specifies the Visual Studio installation to use.
To select the precise combination of Visual Studio instance and toolset version, we walk through the following algorithm:
1. Determine the setting for `VCPKG_VISUAL_STUDIO_PATH` from the triplet, or the environment variable `VCPKG_VISUAL_STUDIO_PATH`, or consider it unset
2. Determine the setting for `VCPKG_PLATFORM_TOOLSET` from the triplet or consider it unset
3. Gather a list of all pairs of Visual Studio Instances with all toolsets available in those instances
1. This is ordered first by instance type (Stable, Prerelease, Legacy) and then by toolset version (v142, v141, v140)
4. Filter the list based on the settings for `VCPKG_VISUAL_STUDIO_PATH` and `VCPKG_PLATFORM_TOOLSET`.
5. Select the best remaining option
The path should be absolute, formatted with backslashes, and have no trailing slash:
```cmake
set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Community")
```
### VCPKG_PLATFORM_TOOLSET
Specifies the VS-based C/C++ compiler toolchain to use.
See [`VCPKG_VISUAL_STUDIO_PATH`](#VCPKG_VISUAL_STUDIO_PATH) for the full selection algorithm.
Valid settings:
* The Visual Studio 2019 platform toolset is `v142`.
* The Visual Studio 2017 platform toolset is `v141`.
* The Visual Studio 2015 platform toolset is `v140`.
### VCPKG_LOAD_VCVARS_ENV
If `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` is used, VCPKG will not setup the Visual Studio environment.
Setting `VCPKG_LOAD_VCVARS_ENV` to (true|1|on) changes this behavior so that the Visual Studio environment is setup following the same rules as if `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` was not set.
## MacOS Variables
### VCPKG_INSTALL_NAME_DIR
Sets the install name used when building macOS dynamic libraries. Default value is `@rpath`. See the CMake documentation for [CMAKE_INSTALL_NAME_DIR](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_NAME_DIR.html) for more information.
### VCPKG_OSX_DEPLOYMENT_TARGET
Sets the minimum macOS version for compiled binaries. This also changes what versions of the macOS platform SDK that CMake will search for. See the CMake documentation for [CMAKE_OSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) for more information.
### VCPKG_OSX_SYSROOT
Set the name or path of the macOS platform SDK that will be used by CMake. See the CMake documentation for [CMAKE_OSX_SYSROOT](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html) for more information.
### VCPKG_OSX_ARCHITECTURES
Set the macOS / iOS target architecture which will be used by CMake. See the CMake documentation for [CMAKE_OSX_ARCHITECTURES](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html) for more information.
## Per-port customization
The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE`) on a per-port basis.
Example:
```cmake
set(VCPKG_LIBRARY_LINKAGE static)
if(PORT MATCHES "qt5-")
set(VCPKG_LIBRARY_LINKAGE dynamic)
endif()
```
This will build all the `qt5-*` libraries as DLLs, but every other library as a static library.
For an example in a real project, see https://github.com/Intelight/vcpkg/blob/master/triplets/x86-windows-mixed.cmake.
## Additional Remarks
The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or a platform-specific choice if that environment variable is undefined.
- Windows: `x86-windows`
- Linux: `x64-linux`
- OSX: `x64-osx`
We recommend using a systematic naming scheme when creating new triplets. The Android toolchain naming scheme is a good source of inspiration: https://developer.android.com/ndk/guides/standalone_toolchain.html.
## Android triplets
See [android.md](android.md)

125
vcpkg/installed/vcpkg/info/openssl-windows_1.1.1g_x64-windows-static.list Normal file
View File

@ -0,0 +1,125 @@
x64-windows-static/
x64-windows-static/include/
x64-windows-static/include/openssl/
x64-windows-static/include/openssl/__DECC_INCLUDE_EPILOGUE.H
x64-windows-static/include/openssl/__DECC_INCLUDE_PROLOGUE.H
x64-windows-static/include/openssl/aes.h
x64-windows-static/include/openssl/asn1.h
x64-windows-static/include/openssl/asn1_mac.h
x64-windows-static/include/openssl/asn1err.h
x64-windows-static/include/openssl/asn1t.h
x64-windows-static/include/openssl/async.h
x64-windows-static/include/openssl/asyncerr.h
x64-windows-static/include/openssl/bio.h
x64-windows-static/include/openssl/bioerr.h
x64-windows-static/include/openssl/blowfish.h
x64-windows-static/include/openssl/bn.h
x64-windows-static/include/openssl/bnerr.h
x64-windows-static/include/openssl/buffer.h
x64-windows-static/include/openssl/buffererr.h
x64-windows-static/include/openssl/camellia.h
x64-windows-static/include/openssl/cast.h
x64-windows-static/include/openssl/cmac.h
x64-windows-static/include/openssl/cms.h
x64-windows-static/include/openssl/cmserr.h
x64-windows-static/include/openssl/comp.h
x64-windows-static/include/openssl/comperr.h
x64-windows-static/include/openssl/conf.h
x64-windows-static/include/openssl/conf_api.h
x64-windows-static/include/openssl/conferr.h
x64-windows-static/include/openssl/crypto.h
x64-windows-static/include/openssl/cryptoerr.h
x64-windows-static/include/openssl/ct.h
x64-windows-static/include/openssl/cterr.h
x64-windows-static/include/openssl/des.h
x64-windows-static/include/openssl/dh.h
x64-windows-static/include/openssl/dherr.h
x64-windows-static/include/openssl/dsa.h
x64-windows-static/include/openssl/dsaerr.h
x64-windows-static/include/openssl/dtls1.h
x64-windows-static/include/openssl/e_os2.h
x64-windows-static/include/openssl/ebcdic.h
x64-windows-static/include/openssl/ec.h
x64-windows-static/include/openssl/ecdh.h
x64-windows-static/include/openssl/ecdsa.h
x64-windows-static/include/openssl/ecerr.h
x64-windows-static/include/openssl/engine.h
x64-windows-static/include/openssl/engineerr.h
x64-windows-static/include/openssl/err.h
x64-windows-static/include/openssl/evp.h
x64-windows-static/include/openssl/evperr.h
x64-windows-static/include/openssl/hmac.h
x64-windows-static/include/openssl/idea.h
x64-windows-static/include/openssl/kdf.h
x64-windows-static/include/openssl/kdferr.h
x64-windows-static/include/openssl/lhash.h
x64-windows-static/include/openssl/md2.h
x64-windows-static/include/openssl/md4.h
x64-windows-static/include/openssl/md5.h
x64-windows-static/include/openssl/mdc2.h
x64-windows-static/include/openssl/modes.h
x64-windows-static/include/openssl/obj_mac.h
x64-windows-static/include/openssl/objects.h
x64-windows-static/include/openssl/objectserr.h
x64-windows-static/include/openssl/ocsp.h
x64-windows-static/include/openssl/ocsperr.h
x64-windows-static/include/openssl/opensslconf.h
x64-windows-static/include/openssl/opensslv.h
x64-windows-static/include/openssl/ossl_typ.h
x64-windows-static/include/openssl/pem.h
x64-windows-static/include/openssl/pem2.h
x64-windows-static/include/openssl/pemerr.h
x64-windows-static/include/openssl/pkcs12.h
x64-windows-static/include/openssl/pkcs12err.h
x64-windows-static/include/openssl/pkcs7.h
x64-windows-static/include/openssl/pkcs7err.h
x64-windows-static/include/openssl/rand.h
x64-windows-static/include/openssl/rand_drbg.h
x64-windows-static/include/openssl/randerr.h
x64-windows-static/include/openssl/rc2.h
x64-windows-static/include/openssl/rc4.h
x64-windows-static/include/openssl/rc5.h
x64-windows-static/include/openssl/ripemd.h
x64-windows-static/include/openssl/rsa.h
x64-windows-static/include/openssl/rsaerr.h
x64-windows-static/include/openssl/safestack.h
x64-windows-static/include/openssl/seed.h
x64-windows-static/include/openssl/sha.h
x64-windows-static/include/openssl/srp.h
x64-windows-static/include/openssl/srtp.h
x64-windows-static/include/openssl/ssl.h
x64-windows-static/include/openssl/ssl2.h
x64-windows-static/include/openssl/ssl3.h
x64-windows-static/include/openssl/sslerr.h
x64-windows-static/include/openssl/stack.h
x64-windows-static/include/openssl/store.h
x64-windows-static/include/openssl/storeerr.h
x64-windows-static/include/openssl/symhacks.h
x64-windows-static/include/openssl/tls1.h
x64-windows-static/include/openssl/ts.h
x64-windows-static/include/openssl/tserr.h
x64-windows-static/include/openssl/txt_db.h
x64-windows-static/include/openssl/ui.h
x64-windows-static/include/openssl/uierr.h
x64-windows-static/include/openssl/whrlpool.h
x64-windows-static/include/openssl/x509.h
x64-windows-static/include/openssl/x509_vfy.h
x64-windows-static/include/openssl/x509err.h
x64-windows-static/include/openssl/x509v3.h
x64-windows-static/include/openssl/x509v3err.h
x64-windows-static/lib/
x64-windows-static/lib/libcrypto.lib
x64-windows-static/lib/libssl.lib
x64-windows-static/lib/ossl_static.pdb
x64-windows-static/misc/
x64-windows-static/misc/CA.pl
x64-windows-static/misc/tsget.pl
x64-windows-static/share/
x64-windows-static/share/openssl-windows/
x64-windows-static/share/openssl-windows/copyright
x64-windows-static/share/openssl-windows/usage
x64-windows-static/share/openssl-windows/vcpkg_abi_info.txt
x64-windows-static/tools/
x64-windows-static/tools/openssl/
x64-windows-static/tools/openssl/openssl.cnf
x64-windows-static/tools/openssl/openssl.exe

5
vcpkg/installed/vcpkg/info/openssl_1.1.1g_x64-windows-static.list Normal file
View File

@ -0,0 +1,5 @@
x64-windows-static/
x64-windows-static/share/
x64-windows-static/share/openssl/
x64-windows-static/share/openssl/usage
x64-windows-static/share/openssl/vcpkg_abi_info.txt

5
vcpkg/installed/vcpkg/info/openssl_1.1.1g_x64-windows.list
View File

@ -1,5 +0,0 @@
x64-windows/
x64-windows/share/
x64-windows/share/openssl/
x64-windows/share/openssl/usage
x64-windows/share/openssl/vcpkg_abi_info.txt

13
vcpkg/installed/vcpkg/info/zlib_1.2.11_x64-windows-static.list Normal file
View File

@ -0,0 +1,13 @@
x64-windows-static/
x64-windows-static/include/
x64-windows-static/include/zconf.h
x64-windows-static/include/zlib.h
x64-windows-static/lib/
x64-windows-static/lib/pkgconfig/
x64-windows-static/lib/pkgconfig/zlib.pc
x64-windows-static/lib/zlib.lib
x64-windows-static/share/
x64-windows-static/share/zlib/
x64-windows-static/share/zlib/copyright
x64-windows-static/share/zlib/usage
x64-windows-static/share/zlib/vcpkg_abi_info.txt

24
vcpkg/installed/vcpkg/info/zlib_1.2.11_x64-windows.list
View File

@ -1,24 +0,0 @@
x64-windows/
x64-windows/bin/
x64-windows/bin/zlib.pdb
x64-windows/bin/zlib1.dll
x64-windows/debug/
x64-windows/debug/bin/
x64-windows/debug/bin/zlibd.pdb
x64-windows/debug/bin/zlibd1.dll
x64-windows/debug/lib/
x64-windows/debug/lib/pkgconfig/
x64-windows/debug/lib/pkgconfig/zlib.pc
x64-windows/debug/lib/zlibd.lib
x64-windows/include/
x64-windows/include/zconf.h
x64-windows/include/zlib.h
x64-windows/lib/
x64-windows/lib/pkgconfig/
x64-windows/lib/pkgconfig/zlib.pc
x64-windows/lib/zlib.lib
x64-windows/share/
x64-windows/share/zlib/
x64-windows/share/zlib/copyright
x64-windows/share/zlib/usage
x64-windows/share/zlib/vcpkg_abi_info.txt

25
vcpkg/installed/vcpkg/status
View File

@ -14,10 +14,10 @@ Port-Version: 1
Depends: openssl-windows
Architecture: x64-windows
Multi-Arch: same
Abi: ab4def31d371c017ebc8fe541da8c3c4f62ead13
Abi: ce7e9eb80de869a53f6118dd41e878137892b72c
Description: OpenSSL is an open source project that provides a robust, commercial-grade, and full-featured toolkit for the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols. It is also a general-purpose cryptography library.
Type: Port
Status: install ok installed
Status: purge ok not-installed
Package: zlib
Version: 1.2.11
@ -27,5 +27,26 @@ Multi-Arch: same
Abi: 41694068328acdf979d22ece62b0177fffcaa5f3
Description: A compression library
Type: Port
Status: purge ok not-installed
Package: openssl-windows
Version: 1.1.1g
Port-Version: 1
Architecture: x64-windows-static
Multi-Arch: same
Abi: 23f003a7782c602f18e1ac62390cc49d8c08fa53
Description: OpenSSL is an open source project that provides a robust, commercial-grade, and full-featured toolkit for the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols. It is also a general-purpose cryptography library.
Type: Port
Status: install ok installed
Package: openssl
Version: 1.1.1g
Port-Version: 1
Depends: openssl-windows
Architecture: x64-windows-static
Multi-Arch: same
Abi: 31d706216e1952a27f09319f84ecbeb273d3b625
Description: OpenSSL is an open source project that provides a robust, commercial-grade, and full-featured toolkit for the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols. It is also a general-purpose cryptography library.
Type: Port
Status: install ok installed

9
vcpkg/installed/vcpkg/updates/0000000000 Normal file
View File

@ -0,0 +1,9 @@
Package: zlib
Version: 1.2.11
Port-Version: 9
Architecture: x64-windows-static
Multi-Arch: same
Abi: cd74bd6d5a6cf313f04d7e4baf7b640240059b44
Description: A compression library
Type: Port
Status: install ok half-installed

9
vcpkg/installed/vcpkg/updates/0000000001 Normal file
View File

@ -0,0 +1,9 @@
Package: zlib
Version: 1.2.11
Port-Version: 9
Architecture: x64-windows-static
Multi-Arch: same
Abi: cd74bd6d5a6cf313f04d7e4baf7b640240059b44
Description: A compression library
Type: Port
Status: install ok installed

22
vcpkg/installed/x64-windows-static/include/openssl/__DECC_INCLUDE_EPILOGUE.H Normal file
View File

@ -0,0 +1,22 @@
/*
* Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the OpenSSL license (the "License"). You may not use
* this file except in compliance with the License. You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/
/*
* This file is only used by HP C/C++ on VMS, and is included automatically
* after each header file from this directory
*/
/*
* The C++ compiler doesn't understand these pragmas, even though it
* understands the corresponding command line qualifier.
*/
#ifndef __cplusplus
/* restore state. Must correspond to the save in __decc_include_prologue.h */
# pragma names restore
#endif

26
vcpkg/installed/x64-windows-static/include/openssl/__DECC_INCLUDE_PROLOGUE.H Normal file
View File

@ -0,0 +1,26 @@
/*
* Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the OpenSSL license (the "License"). You may not use
* this file except in compliance with the License. You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/
/*
* This file is only used by HP C/C++ on VMS, and is included automatically
* after each header file from this directory
*/
/*
* The C++ compiler doesn't understand these pragmas, even though it
* understands the corresponding command line qualifier.
*/
#ifndef __cplusplus
/* save state */
# pragma names save
/* have the compiler shorten symbols larger than 31 chars to 23 chars
* followed by a 8 hex char CRC
*/
# pragma names as_is,shortened
#endif

92
vcpkg/installed/x64-windows-static/include/openssl/aes.h Normal file
View File

@ -0,0 +1,92 @@
/*
* Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the OpenSSL license (the "License"). You may not use
* this file except in compliance with the License. You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/
#ifndef HEADER_AES_H
# define HEADER_AES_H
# include <openssl/opensslconf.h>
# include <stddef.h>
# ifdef __cplusplus
extern "C" {
# endif
# define AES_ENCRYPT 1
# define AES_DECRYPT 0
/*
* Because array size can't be a const in C, the following two are macros.
* Both sizes are in bytes.
*/
# define AES_MAXNR 14
# define AES_BLOCK_SIZE 16
/* This should be a hidden type, but EVP requires that the size be known */
struct aes_key_st {
# ifdef AES_LONG
unsigned long rd_key[4 * (AES_MAXNR + 1)];
# else
unsigned int rd_key[4 * (AES_MAXNR + 1)];
# endif
int rounds;
};
typedef struct aes_key_st AES_KEY;
const char *AES_options(void);
int AES_set_encrypt_key(const unsigned char *userKey, const int bits,
AES_KEY *key);
int AES_set_decrypt_key(const unsigned char *userKey, const int bits,
AES_KEY *key);
void AES_encrypt(const unsigned char *in, unsigned char *out,
const AES_KEY *key);
void AES_decrypt(const unsigned char *in, unsigned char *out,
const AES_KEY *key);
void AES_ecb_encrypt(const unsigned char *in, unsigned char *out,
const AES_KEY *key, const int enc);
void AES_cbc_encrypt(const unsigned char *in, unsigned char *out,
size_t length, const AES_KEY *key,
unsigned char *ivec, const int enc);
void AES_cfb128_encrypt(const unsigned char *in, unsigned char *out,
size_t length, const AES_KEY *key,
unsigned char *ivec, int *num, const int enc);
void AES_cfb1_encrypt(const unsigned char *in, unsigned char *out,
size_t length, const AES_KEY *key,
unsigned char *ivec, int *num, const int enc);
void AES_cfb8_encrypt(const unsigned char *in, unsigned char *out,
size_t length, const AES_KEY *key,
unsigned char *ivec, int *num, const int enc);
void AES_ofb128_encrypt(const unsigned char *in, unsigned char *out,
size_t length, const AES_KEY *key,
unsigned char *ivec, int *num);
/* NB: the IV is _two_ blocks long */
void AES_ige_encrypt(const unsigned char *in, unsigned char *out,
size_t length, const AES_KEY *key,
unsigned char *ivec, const int enc);
/* NB: the IV is _four_ blocks long */
void AES_bi_ige_encrypt(const unsigned char *in, unsigned char *out,
size_t length, const AES_KEY *key,
const AES_KEY *key2, const unsigned char *ivec,
const int enc);
int AES_wrap_key(AES_KEY *key, const unsigned char *iv,
unsigned char *out,
const unsigned char *in, unsigned int inlen);
int AES_unwrap_key(AES_KEY *key, const unsigned char *iv,
unsigned char *out,
const unsigned char *in, unsigned int inlen);
# ifdef __cplusplus
}
# endif
#endif

886
vcpkg/installed/x64-windows-static/include/openssl/asn1.h Normal file
View File

@ -0,0 +1,886 @@
/*
* Copyright 1995-2017 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the OpenSSL license (the "License"). You may not use
* this file except in compliance with the License. You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/
#ifndef HEADER_ASN1_H
# define HEADER_ASN1_H
# include <time.h>
# include <openssl/e_os2.h>
# include <openssl/opensslconf.h>
# include <openssl/bio.h>
# include <openssl/safestack.h>
# include <openssl/asn1err.h>
# include <openssl/symhacks.h>
# include <openssl/ossl_typ.h>
# if OPENSSL_API_COMPAT < 0x10100000L
# include <openssl/bn.h>
# endif
# ifdef OPENSSL_BUILD_SHLIBCRYPTO
# undef OPENSSL_EXTERN
# define OPENSSL_EXTERN OPENSSL_EXPORT
# endif
#ifdef __cplusplus
extern "C" {
#endif
# define V_ASN1_UNIVERSAL 0x00
# define V_ASN1_APPLICATION 0x40
# define V_ASN1_CONTEXT_SPECIFIC 0x80
# define V_ASN1_PRIVATE 0xc0
# define V_ASN1_CONSTRUCTED 0x20
# define V_ASN1_PRIMITIVE_TAG 0x1f
# define V_ASN1_PRIMATIVE_TAG /*compat*/ V_ASN1_PRIMITIVE_TAG
# define V_ASN1_APP_CHOOSE -2/* let the recipient choose */
# define V_ASN1_OTHER -3/* used in ASN1_TYPE */
# define V_ASN1_ANY -4/* used in ASN1 template code */
# define V_ASN1_UNDEF -1
/* ASN.1 tag values */
# define V_ASN1_EOC 0
# define V_ASN1_BOOLEAN 1 /**/
# define V_ASN1_INTEGER 2
# define V_ASN1_BIT_STRING 3
# define V_ASN1_OCTET_STRING 4
# define V_ASN1_NULL 5
# define V_ASN1_OBJECT 6
# define V_ASN1_OBJECT_DESCRIPTOR 7
# define V_ASN1_EXTERNAL 8
# define V_ASN1_REAL 9
# define V_ASN1_ENUMERATED 10
# define V_ASN1_UTF8STRING 12
# define V_ASN1_SEQUENCE 16
# define V_ASN1_SET 17
# define V_ASN1_NUMERICSTRING 18 /**/
# define V_ASN1_PRINTABLESTRING 19
# define V_ASN1_T61STRING 20
# define V_ASN1_TELETEXSTRING 20/* alias */
# define V_ASN1_VIDEOTEXSTRING 21 /**/
# define V_ASN1_IA5STRING 22
# define V_ASN1_UTCTIME 23
# define V_ASN1_GENERALIZEDTIME 24 /**/
# define V_ASN1_GRAPHICSTRING 25 /**/
# define V_ASN1_ISO64STRING 26 /**/
# define V_ASN1_VISIBLESTRING 26/* alias */
# define V_ASN1_GENERALSTRING 27 /**/
# define V_ASN1_UNIVERSALSTRING 28 /**/
# define V_ASN1_BMPSTRING 30
/*
* NB the constants below are used internally by ASN1_INTEGER
* and ASN1_ENUMERATED to indicate the sign. They are *not* on
* the wire tag values.
*/
# define V_ASN1_NEG 0x100
# define V_ASN1_NEG_INTEGER (2 | V_ASN1_NEG)
# define V_ASN1_NEG_ENUMERATED (10 | V_ASN1_NEG)
/* For use with d2i_ASN1_type_bytes() */
# define B_ASN1_NUMERICSTRING 0x0001
# define B_ASN1_PRINTABLESTRING 0x0002
# define B_ASN1_T61STRING 0x0004
# define B_ASN1_TELETEXSTRING 0x0004
# define B_ASN1_VIDEOTEXSTRING 0x0008
# define B_ASN1_IA5STRING 0x0010
# define B_ASN1_GRAPHICSTRING 0x0020
# define B_ASN1_ISO64STRING 0x0040
# define B_ASN1_VISIBLESTRING 0x0040
# define B_ASN1_GENERALSTRING 0x0080
# define B_ASN1_UNIVERSALSTRING 0x0100
# define B_ASN1_OCTET_STRING 0x0200
# define B_ASN1_BIT_STRING 0x0400
# define B_ASN1_BMPSTRING 0x0800
# define B_ASN1_UNKNOWN 0x1000
# define B_ASN1_UTF8STRING 0x2000
# define B_ASN1_UTCTIME 0x4000
# define B_ASN1_GENERALIZEDTIME 0x8000
# define B_ASN1_SEQUENCE 0x10000
/* For use with ASN1_mbstring_copy() */
# define MBSTRING_FLAG 0x1000
# define MBSTRING_UTF8 (MBSTRING_FLAG)
# define MBSTRING_ASC (MBSTRING_FLAG|1)
# define MBSTRING_BMP (MBSTRING_FLAG|2)
# define MBSTRING_UNIV (MBSTRING_FLAG|4)
# define SMIME_OLDMIME 0x400
# define SMIME_CRLFEOL 0x800
# define SMIME_STREAM 0x1000
struct X509_algor_st;
DEFINE_STACK_OF(X509_ALGOR)
# define ASN1_STRING_FLAG_BITS_LEFT 0x08/* Set if 0x07 has bits left value */
/*
* This indicates that the ASN1_STRING is not a real value but just a place
* holder for the location where indefinite length constructed data should be
* inserted in the memory buffer
*/
# define ASN1_STRING_FLAG_NDEF 0x010
/*
* This flag is used by the CMS code to indicate that a string is not
* complete and is a place holder for content when it had all been accessed.
* The flag will be reset when content has been written to it.
*/
# define ASN1_STRING_FLAG_CONT 0x020
/*
* This flag is used by ASN1 code to indicate an ASN1_STRING is an MSTRING
* type.
*/
# define ASN1_STRING_FLAG_MSTRING 0x040
/* String is embedded and only content should be freed */
# define ASN1_STRING_FLAG_EMBED 0x080
/* String should be parsed in RFC 5280's time format */
# define ASN1_STRING_FLAG_X509_TIME 0x100
/* This is the base type that holds just about everything :-) */
struct asn1_string_st {
int length;
int type;
unsigned char *data;
/*
* The value of the following field depends on the type being held. It
* is mostly being used for BIT_STRING so if the input data has a
* non-zero 'unused bits' value, it will be handled correctly
*/
long flags;
};
/*
* ASN1_ENCODING structure: this is used to save the received encoding of an
* ASN1 type. This is useful to get round problems with invalid encodings
* which can break signatures.
*/
typedef struct ASN1_ENCODING_st {
unsigned char *enc; /* DER encoding */
long len; /* Length of encoding */
int modified; /* set to 1 if 'enc' is invalid */
} ASN1_ENCODING;
/* Used with ASN1 LONG type: if a long is set to this it is omitted */
# define ASN1_LONG_UNDEF 0x7fffffffL
# define STABLE_FLAGS_MALLOC 0x01
/*
* A zero passed to ASN1_STRING_TABLE_new_add for the flags is interpreted
* as "don't change" and STABLE_FLAGS_MALLOC is always set. By setting
* STABLE_FLAGS_MALLOC only we can clear the existing value. Use the alias
* STABLE_FLAGS_CLEAR to reflect this.
*/
# define STABLE_FLAGS_CLEAR STABLE_FLAGS_MALLOC
# define STABLE_NO_MASK 0x02
# define DIRSTRING_TYPE \
(B_ASN1_PRINTABLESTRING|B_ASN1_T61STRING|B_ASN1_BMPSTRING|B_ASN1_UTF8STRING)
# define PKCS9STRING_TYPE (DIRSTRING_TYPE|B_ASN1_IA5STRING)
typedef struct asn1_string_table_st {
int nid;
long minsize;
long maxsize;
unsigned long mask;
unsigned long flags;
} ASN1_STRING_TABLE;
DEFINE_STACK_OF(ASN1_STRING_TABLE)
/* size limits: this stuff is taken straight from RFC2459 */
# define ub_name 32768
# define ub_common_name 64
# define ub_locality_name 128
# define ub_state_name 128
# define ub_organization_name 64
# define ub_organization_unit_name 64
# define ub_title 64
# define ub_email_address 128
/*
* Declarations for template structures: for full definitions see asn1t.h
*/
typedef struct ASN1_TEMPLATE_st ASN1_TEMPLATE;
typedef struct ASN1_TLC_st ASN1_TLC;
/* This is just an opaque pointer */
typedef struct ASN1_VALUE_st ASN1_VALUE;
/* Declare ASN1 functions: the implement macro in in asn1t.h */
# define DECLARE_ASN1_FUNCTIONS(type) DECLARE_ASN1_FUNCTIONS_name(type, type)
# define DECLARE_ASN1_ALLOC_FUNCTIONS(type) \
DECLARE_ASN1_ALLOC_FUNCTIONS_name(type, type)
# define DECLARE_ASN1_FUNCTIONS_name(type, name) \
DECLARE_ASN1_ALLOC_FUNCTIONS_name(type, name) \
DECLARE_ASN1_ENCODE_FUNCTIONS(type, name, name)
# define DECLARE_ASN1_FUNCTIONS_fname(type, itname, name) \
DECLARE_ASN1_ALLOC_FUNCTIONS_name(type, name) \
DECLARE_ASN1_ENCODE_FUNCTIONS(type, itname, name)
# define DECLARE_ASN1_ENCODE_FUNCTIONS(type, itname, name) \
type *d2i_##name(type **a, const unsigned char **in, long len); \
int i2d_##name(type *a, unsigned char **out); \
DECLARE_ASN1_ITEM(itname)
# define DECLARE_ASN1_ENCODE_FUNCTIONS_const(type, name) \
type *d2i_##name(type **a, const unsigned char **in, long len); \
int i2d_##name(const type *a, unsigned char **out); \
DECLARE_ASN1_ITEM(name)
# define DECLARE_ASN1_NDEF_FUNCTION(name) \
int i2d_##name##_NDEF(name *a, unsigned char **out);
# define DECLARE_ASN1_FUNCTIONS_const(name) \
DECLARE_ASN1_ALLOC_FUNCTIONS(name) \
DECLARE_ASN1_ENCODE_FUNCTIONS_const(name, name)
# define DECLARE_ASN1_ALLOC_FUNCTIONS_name(type, name) \
type *name##_new(void); \
void name##_free(type *a);
# define DECLARE_ASN1_PRINT_FUNCTION(stname) \
DECLARE_ASN1_PRINT_FUNCTION_fname(stname, stname)
# define DECLARE_ASN1_PRINT_FUNCTION_fname(stname, fname) \
int fname##_print_ctx(BIO *out, stname *x, int indent, \
const ASN1_PCTX *pctx);
# define D2I_OF(type) type *(*)(type **,const unsigned char **,long)
# define I2D_OF(type) int (*)(type *,unsigned char **)
# define I2D_OF_const(type) int (*)(const type *,unsigned char **)
# define CHECKED_D2I_OF(type, d2i) \
((d2i_of_void*) (1 ? d2i : ((D2I_OF(type))0)))
# define CHECKED_I2D_OF(type, i2d) \
((i2d_of_void*) (1 ? i2d : ((I2D_OF(type))0)))
# define CHECKED_NEW_OF(type, xnew) \
((void *(*)(void)) (1 ? xnew : ((type *(*)(void))0)))
# define CHECKED_PTR_OF(type, p) \
((void*) (1 ? p : (type*)0))
# define CHECKED_PPTR_OF(type, p) \
((void**) (1 ? p : (type**)0))
# define TYPEDEF_D2I_OF(type) typedef type *d2i_of_##type(type **,const unsigned char **,long)
# define TYPEDEF_I2D_OF(type) typedef int i2d_of_##type(type *,unsigned char **)
# define TYPEDEF_D2I2D_OF(type) TYPEDEF_D2I_OF(type); TYPEDEF_I2D_OF(type)
TYPEDEF_D2I2D_OF(void);
/*-
* The following macros and typedefs allow an ASN1_ITEM
* to be embedded in a structure and referenced. Since
* the ASN1_ITEM pointers need to be globally accessible
* (possibly from shared libraries) they may exist in
* different forms. On platforms that support it the
* ASN1_ITEM structure itself will be globally exported.
* Other platforms will export a function that returns
* an ASN1_ITEM pointer.
*
* To handle both cases transparently the macros below
* should be used instead of hard coding an ASN1_ITEM
* pointer in a structure.
*
* The structure will look like this:
*
* typedef struct SOMETHING_st {
* ...
* ASN1_ITEM_EXP *iptr;
* ...
* } SOMETHING;
*
* It would be initialised as e.g.:
*
* SOMETHING somevar = {...,ASN1_ITEM_ref(X509),...};
*
* and the actual pointer extracted with:
*
* const ASN1_ITEM *it = ASN1_ITEM_ptr(somevar.iptr);
*
* Finally an ASN1_ITEM pointer can be extracted from an
* appropriate reference with: ASN1_ITEM_rptr(X509). This
* would be used when a function takes an ASN1_ITEM * argument.
*
*/
# ifndef OPENSSL_EXPORT_VAR_AS_FUNCTION
/* ASN1_ITEM pointer exported type */
typedef const ASN1_ITEM ASN1_ITEM_EXP;
/* Macro to obtain ASN1_ITEM pointer from exported type */
# define ASN1_ITEM_ptr(iptr) (iptr)
/* Macro to include ASN1_ITEM pointer from base type */
# define ASN1_ITEM_ref(iptr) (&(iptr##_it))
# define ASN1_ITEM_rptr(ref) (&(ref##_it))
# define DECLARE_ASN1_ITEM(name) \
OPENSSL_EXTERN const ASN1_ITEM name##_it;
# else
/*
* Platforms that can't easily handle shared global variables are declared as
* functions returning ASN1_ITEM pointers.
*/
/* ASN1_ITEM pointer exported type */
typedef const ASN1_ITEM *ASN1_ITEM_EXP (void);
/* Macro to obtain ASN1_ITEM pointer from exported type */
# define ASN1_ITEM_ptr(iptr) (iptr())
/* Macro to include ASN1_ITEM pointer from base type */
# define ASN1_ITEM_ref(iptr) (iptr##_it)
# define ASN1_ITEM_rptr(ref) (ref##_it())
# define DECLARE_ASN1_ITEM(name) \
const ASN1_ITEM * name##_it(void);
# endif
/* Parameters used by ASN1_STRING_print_ex() */
/*
* These determine which characters to escape: RFC2253 special characters,
* control characters and MSB set characters
*/
# define ASN1_STRFLGS_ESC_2253 1
# define ASN1_STRFLGS_ESC_CTRL 2
# define ASN1_STRFLGS_ESC_MSB 4
/*
* This flag determines how we do escaping: normally RC2253 backslash only,
* set this to use backslash and quote.
*/
# define ASN1_STRFLGS_ESC_QUOTE 8
/* These three flags are internal use only. */
/* Character is a valid PrintableString character */
# define CHARTYPE_PRINTABLESTRING 0x10
/* Character needs escaping if it is the first character */
# define CHARTYPE_FIRST_ESC_2253 0x20
/* Character needs escaping if it is the last character */
# define CHARTYPE_LAST_ESC_2253 0x40
/*
* NB the internal flags are safely reused below by flags handled at the top
* level.
*/
/*
* If this is set we convert all character strings to UTF8 first
*/
# define ASN1_STRFLGS_UTF8_CONVERT 0x10
/*
* If this is set we don't attempt to interpret content: just assume all
* strings are 1 byte per character. This will produce some pretty odd
* looking output!
*/
# define ASN1_STRFLGS_IGNORE_TYPE 0x20
/* If this is set we include the string type in the output */
# define ASN1_STRFLGS_SHOW_TYPE 0x40
/*
* This determines which strings to display and which to 'dump' (hex dump of
* content octets or DER encoding). We can only dump non character strings or
* everything. If we don't dump 'unknown' they are interpreted as character
* strings with 1 octet per character and are subject to the usual escaping
* options.
*/
# define ASN1_STRFLGS_DUMP_ALL 0x80
# define ASN1_STRFLGS_DUMP_UNKNOWN 0x100
/*
* These determine what 'dumping' does, we can dump the content octets or the
* DER encoding: both use the RFC2253 #XXXXX notation.
*/
# define ASN1_STRFLGS_DUMP_DER 0x200
/*
* This flag specifies that RC2254 escaping shall be performed.
*/
#define ASN1_STRFLGS_ESC_2254 0x400
/*
* All the string flags consistent with RFC2253, escaping control characters
* isn't essential in RFC2253 but it is advisable anyway.
*/
# define ASN1_STRFLGS_RFC2253 (ASN1_STRFLGS_ESC_2253 | \
ASN1_STRFLGS_ESC_CTRL | \
ASN1_STRFLGS_ESC_MSB | \
ASN1_STRFLGS_UTF8_CONVERT | \
ASN1_STRFLGS_DUMP_UNKNOWN | \
ASN1_STRFLGS_DUMP_DER)
DEFINE_STACK_OF(ASN1_INTEGER)
DEFINE_STACK_OF(ASN1_GENERALSTRING)
DEFINE_STACK_OF(ASN1_UTF8STRING)
typedef struct asn1_type_st {
int type;
union {
char *ptr;
ASN1_BOOLEAN boolean;
ASN1_STRING *asn1_string;
ASN1_OBJECT *object;
ASN1_INTEGER *integer;
ASN1_ENUMERATED *enumerated;
ASN1_BIT_STRING *bit_string;
ASN1_OCTET_STRING *octet_string;
ASN1_PRINTABLESTRING *printablestring;
ASN1_T61STRING *t61string;
ASN1_IA5STRING *ia5string;
ASN1_GENERALSTRING *generalstring;
ASN1_BMPSTRING *bmpstring;
ASN1_UNIVERSALSTRING *universalstring;
ASN1_UTCTIME *utctime;
ASN1_GENERALIZEDTIME *generalizedtime;
ASN1_VISIBLESTRING *visiblestring;
ASN1_UTF8STRING *utf8string;
/*
* set and sequence are left complete and still contain the set or
* sequence bytes
*/
ASN1_STRING *set;
ASN1_STRING *sequence;
ASN1_VALUE *asn1_value;
} value;
} ASN1_TYPE;
DEFINE_STACK_OF(ASN1_TYPE)
typedef STACK_OF(ASN1_TYPE) ASN1_SEQUENCE_ANY;
DECLARE_ASN1_ENCODE_FUNCTIONS_const(ASN1_SEQUENCE_ANY, ASN1_SEQUENCE_ANY)
DECLARE_ASN1_ENCODE_FUNCTIONS_const(ASN1_SEQUENCE_ANY, ASN1_SET_ANY)
/* This is used to contain a list of bit names */
typedef struct BIT_STRING_BITNAME_st {
int bitnum;
const char *lname;
const char *sname;
} BIT_STRING_BITNAME;
# define B_ASN1_TIME \
B_ASN1_UTCTIME | \
B_ASN1_GENERALIZEDTIME
# define B_ASN1_PRINTABLE \
B_ASN1_NUMERICSTRING| \
B_ASN1_PRINTABLESTRING| \
B_ASN1_T61STRING| \
B_ASN1_IA5STRING| \
B_ASN1_BIT_STRING| \
B_ASN1_UNIVERSALSTRING|\
B_ASN1_BMPSTRING|\
B_ASN1_UTF8STRING|\
B_ASN1_SEQUENCE|\
B_ASN1_UNKNOWN
# define B_ASN1_DIRECTORYSTRING \
B_ASN1_PRINTABLESTRING| \
B_ASN1_TELETEXSTRING|\
B_ASN1_BMPSTRING|\
B_ASN1_UNIVERSALSTRING|\
B_ASN1_UTF8STRING
# define B_ASN1_DISPLAYTEXT \
B_ASN1_IA5STRING| \
B_ASN1_VISIBLESTRING| \
B_ASN1_BMPSTRING|\
B_ASN1_UTF8STRING
DECLARE_ASN1_FUNCTIONS_fname(ASN1_TYPE, ASN1_ANY, ASN1_TYPE)
int ASN1_TYPE_get(const ASN1_TYPE *a);
void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);
int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);
int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);
ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s, ASN1_TYPE **t);
void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t);
ASN1_OBJECT *ASN1_OBJECT_new(void);
void ASN1_OBJECT_free(ASN1_OBJECT *a);
int i2d_ASN1_OBJECT(const ASN1_OBJECT *a, unsigned char **pp);
ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, const unsigned char **pp,
long length);
DECLARE_ASN1_ITEM(ASN1_OBJECT)
DEFINE_STACK_OF(ASN1_OBJECT)
ASN1_STRING *ASN1_STRING_new(void);
void ASN1_STRING_free(ASN1_STRING *a);
void ASN1_STRING_clear_free(ASN1_STRING *a);
int ASN1_STRING_copy(ASN1_STRING *dst, const ASN1_STRING *str);
ASN1_STRING *ASN1_STRING_dup(const ASN1_STRING *a);
ASN1_STRING *ASN1_STRING_type_new(int type);
int ASN1_STRING_cmp(const ASN1_STRING *a, const ASN1_STRING *b);
/*
* Since this is used to store all sorts of things, via macros, for now,
* make its data void *
*/
int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
void ASN1_STRING_set0(ASN1_STRING *str, void *data, int len);
int ASN1_STRING_length(const ASN1_STRING *x);
void ASN1_STRING_length_set(ASN1_STRING *x, int n);
int ASN1_STRING_type(const ASN1_STRING *x);
DEPRECATEDIN_1_1_0(unsigned char *ASN1_STRING_data(ASN1_STRING *x))
const unsigned char *ASN1_STRING_get0_data(const ASN1_STRING *x);
DECLARE_ASN1_FUNCTIONS(ASN1_BIT_STRING)
int ASN1_BIT_STRING_set(ASN1_BIT_STRING *a, unsigned char *d, int length);
int ASN1_BIT_STRING_set_bit(ASN1_BIT_STRING *a, int n, int value);
int ASN1_BIT_STRING_get_bit(const ASN1_BIT_STRING *a, int n);
int ASN1_BIT_STRING_check(const ASN1_BIT_STRING *a,
const unsigned char *flags, int flags_len);
int ASN1_BIT_STRING_name_print(BIO *out, ASN1_BIT_STRING *bs,
BIT_STRING_BITNAME *tbl, int indent);
int ASN1_BIT_STRING_num_asc(const char *name, BIT_STRING_BITNAME *tbl);
int ASN1_BIT_STRING_set_asc(ASN1_BIT_STRING *bs, const char *name, int value,
BIT_STRING_BITNAME *tbl);
DECLARE_ASN1_FUNCTIONS(ASN1_INTEGER)
ASN1_INTEGER *d2i_ASN1_UINTEGER(ASN1_INTEGER **a, const unsigned char **pp,
long length);
ASN1_INTEGER *ASN1_INTEGER_dup(const ASN1_INTEGER *x);
int ASN1_INTEGER_cmp(const ASN1_INTEGER *x, const ASN1_INTEGER *y);
DECLARE_ASN1_FUNCTIONS(ASN1_ENUMERATED)
int ASN1_UTCTIME_check(const ASN1_UTCTIME *a);
ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);
ASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t,
int offset_day, long offset_sec);
int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);
int ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t);
int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *a);
ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,
time_t t);
ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s,
time_t t, int offset_day,
long offset_sec);
int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s, const char *str);
int ASN1_TIME_diff(int *pday, int *psec,
const ASN1_TIME *from, const ASN1_TIME *to);
DECLARE_ASN1_FUNCTIONS(ASN1_OCTET_STRING)
ASN1_OCTET_STRING *ASN1_OCTET_STRING_dup(const ASN1_OCTET_STRING *a);
int ASN1_OCTET_STRING_cmp(const ASN1_OCTET_STRING *a,
const ASN1_OCTET_STRING *b);
int ASN1_OCTET_STRING_set(ASN1_OCTET_STRING *str, const unsigned char *data,
int len);
DECLARE_ASN1_FUNCTIONS(ASN1_VISIBLESTRING)
DECLARE_ASN1_FUNCTIONS(ASN1_UNIVERSALSTRING)
DECLARE_ASN1_FUNCTIONS(ASN1_UTF8STRING)
DECLARE_ASN1_FUNCTIONS(ASN1_NULL)
DECLARE_ASN1_FUNCTIONS(ASN1_BMPSTRING)
int UTF8_getc(const unsigned char *str, int len, unsigned long *val);
int UTF8_putc(unsigned char *str, int len, unsigned long value);
DECLARE_ASN1_FUNCTIONS_name(ASN1_STRING, ASN1_PRINTABLE)
DECLARE_ASN1_FUNCTIONS_name(ASN1_STRING, DIRECTORYSTRING)
DECLARE_ASN1_FUNCTIONS_name(ASN1_STRING, DISPLAYTEXT)
DECLARE_ASN1_FUNCTIONS(ASN1_PRINTABLESTRING)
DECLARE_ASN1_FUNCTIONS(ASN1_T61STRING)
DECLARE_ASN1_FUNCTIONS(ASN1_IA5STRING)
DECLARE_ASN1_FUNCTIONS(ASN1_GENERALSTRING)
DECLARE_ASN1_FUNCTIONS(ASN1_UTCTIME)
DECLARE_ASN1_FUNCTIONS(ASN1_GENERALIZEDTIME)
DECLARE_ASN1_FUNCTIONS(ASN1_TIME)
DECLARE_ASN1_ITEM(ASN1_OCTET_STRING_NDEF)
ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t,
int offset_day, long offset_sec);
int ASN1_TIME_check(const ASN1_TIME *t);
ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(const ASN1_TIME *t,
ASN1_GENERALIZEDTIME **out);
int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);
int ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm);
int ASN1_TIME_normalize(ASN1_TIME *s);
int ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t);
int ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b);
int i2a_ASN1_INTEGER(BIO *bp, const ASN1_INTEGER *a);
int a2i_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *bs, char *buf, int size);
int i2a_ASN1_ENUMERATED(BIO *bp, const ASN1_ENUMERATED *a);
int a2i_ASN1_ENUMERATED(BIO *bp, ASN1_ENUMERATED *bs, char *buf, int size);
int i2a_ASN1_OBJECT(BIO *bp, const ASN1_OBJECT *a);
int a2i_ASN1_STRING(BIO *bp, ASN1_STRING *bs, char *buf, int size);
int i2a_ASN1_STRING(BIO *bp, const ASN1_STRING *a, int type);
int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a);
int a2d_ASN1_OBJECT(unsigned char *out, int olen, const char *buf, int num);
ASN1_OBJECT *ASN1_OBJECT_create(int nid, unsigned char *data, int len,
const char *sn, const char *ln);
int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);
int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);
int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);
int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);
int ASN1_INTEGER_set(ASN1_INTEGER *a, long v);
long ASN1_INTEGER_get(const ASN1_INTEGER *a);
ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_ENUMERATED *a);
int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r);
int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(const BIGNUM *bn, ASN1_ENUMERATED *ai);
BIGNUM *ASN1_ENUMERATED_to_BN(const ASN1_ENUMERATED *ai, BIGNUM *bn);
/* General */
/* given a string, return the correct type, max is the maximum length */
int ASN1_PRINTABLE_type(const unsigned char *s, int max);
unsigned long ASN1_tag2bit(int tag);
/* SPECIALS */
int ASN1_get_object(const unsigned char **pp, long *plength, int *ptag,
int *pclass, long omax);
int ASN1_check_infinite_end(unsigned char **p, long len);
int ASN1_const_check_infinite_end(const unsigned char **p, long len);
void ASN1_put_object(unsigned char **pp, int constructed, int length,
int tag, int xclass);
int ASN1_put_eoc(unsigned char **pp);
int ASN1_object_size(int constructed, int length, int tag);
/* Used to implement other functions */
void *ASN1_dup(i2d_of_void *i2d, d2i_of_void *d2i, void *x);
# define ASN1_dup_of(type,i2d,d2i,x) \
((type*)ASN1_dup(CHECKED_I2D_OF(type, i2d), \
CHECKED_D2I_OF(type, d2i), \
CHECKED_PTR_OF(type, x)))
# define ASN1_dup_of_const(type,i2d,d2i,x) \
((type*)ASN1_dup(CHECKED_I2D_OF(const type, i2d), \
CHECKED_D2I_OF(type, d2i), \
CHECKED_PTR_OF(const type, x)))
void *ASN1_item_dup(const ASN1_ITEM *it, void *x);
/* ASN1 alloc/free macros for when a type is only used internally */
# define M_ASN1_new_of(type) (type *)ASN1_item_new(ASN1_ITEM_rptr(type))
# define M_ASN1_free_of(x, type) \
ASN1_item_free(CHECKED_PTR_OF(type, x), ASN1_ITEM_rptr(type))
# ifndef OPENSSL_NO_STDIO
void *ASN1_d2i_fp(void *(*xnew) (void), d2i_of_void *d2i, FILE *in, void **x);
# define ASN1_d2i_fp_of(type,xnew,d2i,in,x) \
((type*)ASN1_d2i_fp(CHECKED_NEW_OF(type, xnew), \
CHECKED_D2I_OF(type, d2i), \
in, \
CHECKED_PPTR_OF(type, x)))
void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);
int ASN1_i2d_fp(i2d_of_void *i2d, FILE *out, void *x);
# define ASN1_i2d_fp_of(type,i2d,out,x) \
(ASN1_i2d_fp(CHECKED_I2D_OF(type, i2d), \
out, \
CHECKED_PTR_OF(type, x)))
# define ASN1_i2d_fp_of_const(type,i2d,out,x) \
(ASN1_i2d_fp(CHECKED_I2D_OF(const type, i2d), \
out, \
CHECKED_PTR_OF(const type, x)))
int ASN1_item_i2d_fp(const ASN1_ITEM *it, FILE *out, void *x);
int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);
# endif
int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
void *ASN1_d2i_bio(void *(*xnew) (void), d2i_of_void *d2i, BIO *in, void **x);
# define ASN1_d2i_bio_of(type,xnew,d2i,in,x) \
((type*)ASN1_d2i_bio( CHECKED_NEW_OF(type, xnew), \
CHECKED_D2I_OF(type, d2i), \
in, \
CHECKED_PPTR_OF(type, x)))
void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x);
int ASN1_i2d_bio(i2d_of_void *i2d, BIO *out, unsigned char *x);
# define ASN1_i2d_bio_of(type,i2d,out,x) \
(ASN1_i2d_bio(CHECKED_I2D_OF(type, i2d), \
out, \
CHECKED_PTR_OF(type, x)))
# define ASN1_i2d_bio_of_const(type,i2d,out,x) \
(ASN1_i2d_bio(CHECKED_I2D_OF(const type, i2d), \
out, \
CHECKED_PTR_OF(const type, x)))
int ASN1_item_i2d_bio(const ASN1_ITEM *it, BIO *out, void *x);
int ASN1_UTCTIME_print(BIO *fp, const ASN1_UTCTIME *a);
int ASN1_GENERALIZEDTIME_print(BIO *fp, const ASN1_GENERALIZEDTIME *a);
int ASN1_TIME_print(BIO *fp, const ASN1_TIME *a);
int ASN1_STRING_print(BIO *bp, const ASN1_STRING *v);
int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);
int ASN1_buf_print(BIO *bp, const unsigned char *buf, size_t buflen, int off);
int ASN1_bn_print(BIO *bp, const char *number, const BIGNUM *num,
unsigned char *buf, int off);
int ASN1_parse(BIO *bp, const unsigned char *pp, long len, int indent);
int ASN1_parse_dump(BIO *bp, const unsigned char *pp, long len, int indent,
int dump);
const char *ASN1_tag2str(int tag);
/* Used to load and write Netscape format cert */
int ASN1_UNIVERSALSTRING_to_string(ASN1_UNIVERSALSTRING *s);
int ASN1_TYPE_set_octetstring(ASN1_TYPE *a, unsigned char *data, int len);
int ASN1_TYPE_get_octetstring(const ASN1_TYPE *a, unsigned char *data, int max_len);
int ASN1_TYPE_set_int_octetstring(ASN1_TYPE *a, long num,
unsigned char *data, int len);
int ASN1_TYPE_get_int_octetstring(const ASN1_TYPE *a, long *num,
unsigned char *data, int max_len);
void *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it);
ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it,
ASN1_OCTET_STRING **oct);
void ASN1_STRING_set_default_mask(unsigned long mask);
int ASN1_STRING_set_default_mask_asc(const char *p);
unsigned long ASN1_STRING_get_default_mask(void);
int ASN1_mbstring_copy(ASN1_STRING **out, const unsigned char *in, int len,
int inform, unsigned long mask);
int ASN1_mbstring_ncopy(ASN1_STRING **out, const unsigned char *in, int len,
int inform, unsigned long mask,
long minsize, long maxsize);
ASN1_STRING *ASN1_STRING_set_by_NID(ASN1_STRING **out,
const unsigned char *in, int inlen,
int inform, int nid);
ASN1_STRING_TABLE *ASN1_STRING_TABLE_get(int nid);
int ASN1_STRING_TABLE_add(int, long, long, unsigned long, unsigned long);
void ASN1_STRING_TABLE_cleanup(void);
/* ASN1 template functions */
/* Old API compatible functions */
ASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it);
void ASN1_item_free(ASN1_VALUE *val, const ASN1_ITEM *it);
ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **val, const unsigned char **in,
long len, const ASN1_ITEM *it);
int ASN1_item_i2d(ASN1_VALUE *val, unsigned char **out, const ASN1_ITEM *it);
int ASN1_item_ndef_i2d(ASN1_VALUE *val, unsigned char **out,
const ASN1_ITEM *it);
void ASN1_add_oid_module(void);
void ASN1_add_stable_module(void);
ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
int ASN1_str2mask(const char *str, unsigned long *pmask);
/* ASN1 Print flags */
/* Indicate missing OPTIONAL fields */
# define ASN1_PCTX_FLAGS_SHOW_ABSENT 0x001
/* Mark start and end of SEQUENCE */
# define ASN1_PCTX_FLAGS_SHOW_SEQUENCE 0x002
/* Mark start and end of SEQUENCE/SET OF */
# define ASN1_PCTX_FLAGS_SHOW_SSOF 0x004
/* Show the ASN1 type of primitives */
# define ASN1_PCTX_FLAGS_SHOW_TYPE 0x008
/* Don't show ASN1 type of ANY */
# define ASN1_PCTX_FLAGS_NO_ANY_TYPE 0x010
/* Don't show ASN1 type of MSTRINGs */
# define ASN1_PCTX_FLAGS_NO_MSTRING_TYPE 0x020
/* Don't show field names in SEQUENCE */
# define ASN1_PCTX_FLAGS_NO_FIELD_NAME 0x040
/* Show structure names of each SEQUENCE field */
# define ASN1_PCTX_FLAGS_SHOW_FIELD_STRUCT_NAME 0x080
/* Don't show structure name even at top level */
# define ASN1_PCTX_FLAGS_NO_STRUCT_NAME 0x100
int ASN1_item_print(BIO *out, ASN1_VALUE *ifld, int indent,
const ASN1_ITEM *it, const ASN1_PCTX *pctx);
ASN1_PCTX *ASN1_PCTX_new(void);
void ASN1_PCTX_free(ASN1_PCTX *p);
unsigned long ASN1_PCTX_get_flags(const ASN1_PCTX *p);
void ASN1_PCTX_set_flags(ASN1_PCTX *p, unsigned long flags);
unsigned long ASN1_PCTX_get_nm_flags(const ASN1_PCTX *p);
void ASN1_PCTX_set_nm_flags(ASN1_PCTX *p, unsigned long flags);
unsigned long ASN1_PCTX_get_cert_flags(const ASN1_PCTX *p);
void ASN1_PCTX_set_cert_flags(ASN1_PCTX *p, unsigned long flags);
unsigned long ASN1_PCTX_get_oid_flags(const ASN1_PCTX *p);
void ASN1_PCTX_set_oid_flags(ASN1_PCTX *p, unsigned long flags);
unsigned long ASN1_PCTX_get_str_flags(const ASN1_PCTX *p);
void ASN1_PCTX_set_str_flags(ASN1_PCTX *p, unsigned long flags);
ASN1_SCTX *ASN1_SCTX_new(int (*scan_cb) (ASN1_SCTX *ctx));
void ASN1_SCTX_free(ASN1_SCTX *p);
const ASN1_ITEM *ASN1_SCTX_get_item(ASN1_SCTX *p);
const ASN1_TEMPLATE *ASN1_SCTX_get_template(ASN1_SCTX *p);
unsigned long ASN1_SCTX_get_flags(ASN1_SCTX *p);
void ASN1_SCTX_set_app_data(ASN1_SCTX *p, void *data);
void *ASN1_SCTX_get_app_data(ASN1_SCTX *p);
const BIO_METHOD *BIO_f_asn1(void);
BIO *BIO_new_NDEF(BIO *out, ASN1_VALUE *val, const ASN1_ITEM *it);
int i2d_ASN1_bio_stream(BIO *out, ASN1_VALUE *val, BIO *in, int flags,
const ASN1_ITEM *it);
int PEM_write_bio_ASN1_stream(BIO *out, ASN1_VALUE *val, BIO *in, int flags,
const char *hdr, const ASN1_ITEM *it);
int SMIME_write_ASN1(BIO *bio, ASN1_VALUE *val, BIO *data, int flags,
int ctype_nid, int econt_nid,
STACK_OF(X509_ALGOR) *mdalgs, const ASN1_ITEM *it);
ASN1_VALUE *SMIME_read_ASN1(BIO *bio, BIO **bcont, const ASN1_ITEM *it);
int SMIME_crlf_copy(BIO *in, BIO *out, int flags);
int SMIME_text(BIO *in, BIO *out);
const ASN1_ITEM *ASN1_ITEM_lookup(const char *name);
const ASN1_ITEM *ASN1_ITEM_get(size_t i);
# ifdef __cplusplus
}
# endif
#endif

10
vcpkg/installed/x64-windows-static/include/openssl/asn1_mac.h Normal file
View File

@ -0,0 +1,10 @@
/*
* Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the OpenSSL license (the "License"). You may not use
* this file except in compliance with the License. You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/
#error "This file is obsolete; please update your software."

256
vcpkg/installed/x64-windows-static/include/openssl/asn1err.h Normal file
View File

@ -0,0 +1,256 @@
/*
* Generated by util/mkerr.pl DO NOT EDIT
* Copyright 1995-2019 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the OpenSSL license (the "License"). You may not use
* this file except in compliance with the License. You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/
#ifndef HEADER_ASN1ERR_H
# define HEADER_ASN1ERR_H
# ifndef HEADER_SYMHACKS_H
# include <openssl/symhacks.h>
# endif
# ifdef __cplusplus
extern "C"
# endif
int ERR_load_ASN1_strings(void);
/*
* ASN1 function codes.
*/
# define ASN1_F_A2D_ASN1_OBJECT 100
# define ASN1_F_A2I_ASN1_INTEGER 102
# define ASN1_F_A2I_ASN1_STRING 103
# define ASN1_F_APPEND_EXP 176
# define ASN1_F_ASN1_BIO_INIT 113
# define ASN1_F_ASN1_BIT_STRING_SET_BIT 183
# define ASN1_F_ASN1_CB 177
# define ASN1_F_ASN1_CHECK_TLEN 104
# define ASN1_F_ASN1_COLLECT 106
# define ASN1_F_ASN1_D2I_EX_PRIMITIVE 108
# define ASN1_F_ASN1_D2I_FP 109
# define ASN1_F_ASN1_D2I_READ_BIO 107
# define ASN1_F_ASN1_DIGEST 184
# define ASN1_F_ASN1_DO_ADB 110
# define ASN1_F_ASN1_DO_LOCK 233
# define ASN1_F_ASN1_DUP 111
# define ASN1_F_ASN1_ENC_SAVE 115
# define ASN1_F_ASN1_EX_C2I 204
# define ASN1_F_ASN1_FIND_END 190
# define ASN1_F_ASN1_GENERALIZEDTIME_ADJ 216
# define ASN1_F_ASN1_GENERATE_V3 178
# define ASN1_F_ASN1_GET_INT64 224
# define ASN1_F_ASN1_GET_OBJECT 114
# define ASN1_F_ASN1_GET_UINT64 225
# define ASN1_F_ASN1_I2D_BIO 116
# define ASN1_F_ASN1_I2D_FP 117
# define ASN1_F_ASN1_ITEM_D2I_FP 206
# define ASN1_F_ASN1_ITEM_DUP 191
# define ASN1_F_ASN1_ITEM_EMBED_D2I 120
# define ASN1_F_ASN1_ITEM_EMBED_NEW 121
# define ASN1_F_ASN1_ITEM_FLAGS_I2D 118
# define ASN1_F_ASN1_ITEM_I2D_BIO 192
# define ASN1_F_ASN1_ITEM_I2D_FP 193
# define ASN1_F_ASN1_ITEM_PACK 198
# define ASN1_F_ASN1_ITEM_SIGN 195
# define ASN1_F_ASN1_ITEM_SIGN_CTX 220
# define ASN1_F_ASN1_ITEM_UNPACK 199
# define ASN1_F_ASN1_ITEM_VERIFY 197
# define ASN1_F_ASN1_MBSTRING_NCOPY 122
# define ASN1_F_ASN1_OBJECT_NEW 123
# define ASN1_F_ASN1_OUTPUT_DATA 214
# define ASN1_F_ASN1_PCTX_NEW 205
# define ASN1_F_ASN1_PRIMITIVE_NEW 119
# define ASN1_F_ASN1_SCTX_NEW 221
# define ASN1_F_ASN1_SIGN 128
# define ASN1_F_ASN1_STR2TYPE 179
# define ASN1_F_ASN1_STRING_GET_INT64 227
# define ASN1_F_ASN1_STRING_GET_UINT64 230
# define ASN1_F_ASN1_STRING_SET 186
# define ASN1_F_ASN1_STRING_TABLE_ADD 129
# define ASN1_F_ASN1_STRING_TO_BN 228
# define ASN1_F_ASN1_STRING_TYPE_NEW 130
# define ASN1_F_ASN1_TEMPLATE_EX_D2I 132
# define ASN1_F_ASN1_TEMPLATE_NEW 133
# define ASN1_F_ASN1_TEMPLATE_NOEXP_D2I 131
# define ASN1_F_ASN1_TIME_ADJ 217
# define ASN1_F_ASN1_TYPE_GET_INT_OCTETSTRING 134
# define ASN1_F_ASN1_TYPE_GET_OCTETSTRING 135
# define ASN1_F_ASN1_UTCTIME_ADJ 218
# define ASN1_F_ASN1_VERIFY 137
# define ASN1_F_B64_READ_ASN1 209
# define ASN1_F_B64_WRITE_ASN1 210
# define ASN1_F_BIO_NEW_NDEF 208
# define ASN1_F_BITSTR_CB 180
# define ASN1_F_BN_TO_ASN1_STRING 229
# define ASN1_F_C2I_ASN1_BIT_STRING 189
# define ASN1_F_C2I_ASN1_INTEGER 194
# define ASN1_F_C2I_ASN1_OBJECT 196
# define ASN1_F_C2I_IBUF 226
# define ASN1_F_C2I_UINT64_INT 101
# define ASN1_F_COLLECT_DATA 140
# define ASN1_F_D2I_ASN1_OBJECT 147
# define ASN1_F_D2I_ASN1_UINTEGER 150
# define ASN1_F_D2I_AUTOPRIVATEKEY 207
# define ASN1_F_D2I_PRIVATEKEY 154
# define ASN1_F_D2I_PUBLICKEY 155
# define ASN1_F_DO_BUF 142
# define ASN1_F_DO_CREATE 124
# define ASN1_F_DO_DUMP 125
# define ASN1_F_DO_TCREATE 222
# define ASN1_F_I2A_ASN1_OBJECT 126
# define ASN1_F_I2D_ASN1_BIO_STREAM 211
# define ASN1_F_I2D_ASN1_OBJECT 143
# define ASN1_F_I2D_DSA_PUBKEY 161
# define ASN1_F_I2D_EC_PUBKEY 181
# define ASN1_F_I2D_PRIVATEKEY 163
# define ASN1_F_I2D_PUBLICKEY 164
# define ASN1_F_I2D_RSA_PUBKEY 165
# define ASN1_F_LONG_C2I 166
# define ASN1_F_NDEF_PREFIX 127
# define ASN1_F_NDEF_SUFFIX 136
# define ASN1_F_OID_MODULE_INIT 174
# define ASN1_F_PARSE_TAGGING 182
# define ASN1_F_PKCS5_PBE2_SET_IV 167
# define ASN1_F_PKCS5_PBE2_SET_SCRYPT 231
# define ASN1_F_PKCS5_PBE_SET 202
# define ASN1_F_PKCS5_PBE_SET0_ALGOR 215
# define ASN1_F_PKCS5_PBKDF2_SET 219
# define ASN1_F_PKCS5_SCRYPT_SET 232
# define ASN1_F_SMIME_READ_ASN1 212
# define ASN1_F_SMIME_TEXT 213
# define ASN1_F_STABLE_GET 138
# define ASN1_F_STBL_MODULE_INIT 223
# define ASN1_F_UINT32_C2I 105
# define ASN1_F_UINT32_NEW 139
# define ASN1_F_UINT64_C2I 112
# define ASN1_F_UINT64_NEW 141
# define ASN1_F_X509_CRL_ADD0_REVOKED 169
# define ASN1_F_X509_INFO_NEW 170
# define ASN1_F_X509_NAME_ENCODE 203
# define ASN1_F_X509_NAME_EX_D2I 158
# define ASN1_F_X509_NAME_EX_NEW 171
# define ASN1_F_X509_PKEY_NEW 173
/*
* ASN1 reason codes.
*/
# define ASN1_R_ADDING_OBJECT 171
# define ASN1_R_ASN1_PARSE_ERROR 203
# define ASN1_R_ASN1_SIG_PARSE_ERROR 204
# define ASN1_R_AUX_ERROR 100
# define ASN1_R_BAD_OBJECT_HEADER 102
# define ASN1_R_BMPSTRING_IS_WRONG_LENGTH 214
# define ASN1_R_BN_LIB 105
# define ASN1_R_BOOLEAN_IS_WRONG_LENGTH 106
# define ASN1_R_BUFFER_TOO_SMALL 107
# define ASN1_R_CIPHER_HAS_NO_OBJECT_IDENTIFIER 108
# define ASN1_R_CONTEXT_NOT_INITIALISED 217
# define ASN1_R_DATA_IS_WRONG 109
# define ASN1_R_DECODE_ERROR 110
# define ASN1_R_DEPTH_EXCEEDED 174
# define ASN1_R_DIGEST_AND_KEY_TYPE_NOT_SUPPORTED 198
# define ASN1_R_ENCODE_ERROR 112
# define ASN1_R_ERROR_GETTING_TIME 173
# define ASN1_R_ERROR_LOADING_SECTION 172
# define ASN1_R_ERROR_SETTING_CIPHER_PARAMS 114
# define ASN1_R_EXPECTING_AN_INTEGER 115
# define ASN1_R_EXPECTING_AN_OBJECT 116
# define ASN1_R_EXPLICIT_LENGTH_MISMATCH 119
# define ASN1_R_EXPLICIT_TAG_NOT_CONSTRUCTED 120
# define ASN1_R_FIELD_MISSING 121
# define ASN1_R_FIRST_NUM_TOO_LARGE 122
# define ASN1_R_HEADER_TOO_LONG 123
# define ASN1_R_ILLEGAL_BITSTRING_FORMAT 175
# define ASN1_R_ILLEGAL_BOOLEAN 176
# define ASN1_R_ILLEGAL_CHARACTERS 124
# define ASN1_R_ILLEGAL_FORMAT 177
# define ASN1_R_ILLEGAL_HEX 178
# define ASN1_R_ILLEGAL_IMPLICIT_TAG 179
# define ASN1_R_ILLEGAL_INTEGER 180
# define ASN1_R_ILLEGAL_NEGATIVE_VALUE 226
# define ASN1_R_ILLEGAL_NESTED_TAGGING 181
# define ASN1_R_ILLEGAL_NULL 125
# define ASN1_R_ILLEGAL_NULL_VALUE 182
# define ASN1_R_ILLEGAL_OBJECT 183
# define ASN1_R_ILLEGAL_OPTIONAL_ANY 126
# define ASN1_R_ILLEGAL_OPTIONS_ON_ITEM_TEMPLATE 170
# define ASN1_R_ILLEGAL_PADDING 221
# define ASN1_R_ILLEGAL_TAGGED_ANY 127
# define ASN1_R_ILLEGAL_TIME_VALUE 184
# define ASN1_R_ILLEGAL_ZERO_CONTENT 222
# define ASN1_R_INTEGER_NOT_ASCII_FORMAT 185
# define ASN1_R_INTEGER_TOO_LARGE_FOR_LONG 128
# define ASN1_R_INVALID_BIT_STRING_BITS_LEFT 220
# define ASN1_R_INVALID_BMPSTRING_LENGTH 129
# define ASN1_R_INVALID_DIGIT 130
# define ASN1_R_INVALID_MIME_TYPE 205
# define ASN1_R_INVALID_MODIFIER 186
# define ASN1_R_INVALID_NUMBER 187
# define ASN1_R_INVALID_OBJECT_ENCODING 216
# define ASN1_R_INVALID_SCRYPT_PARAMETERS 227
# define ASN1_R_INVALID_SEPARATOR 131
# define ASN1_R_INVALID_STRING_TABLE_VALUE 218
# define ASN1_R_INVALID_UNIVERSALSTRING_LENGTH 133
# define ASN1_R_INVALID_UTF8STRING 134
# define ASN1_R_INVALID_VALUE 219
# define ASN1_R_LIST_ERROR 188
# define ASN1_R_MIME_NO_CONTENT_TYPE 206
# define ASN1_R_MIME_PARSE_ERROR 207
# define ASN1_R_MIME_SIG_PARSE_ERROR 208
# define ASN1_R_MISSING_EOC 137
# define ASN1_R_MISSING_SECOND_NUMBER 138
# define ASN1_R_MISSING_VALUE 189
# define ASN1_R_MSTRING_NOT_UNIVERSAL 139
# define ASN1_R_MSTRING_WRONG_TAG 140
# define ASN1_R_NESTED_ASN1_STRING 197
# define ASN1_R_NESTED_TOO_DEEP 201
# define ASN1_R_NON_HEX_CHARACTERS 141
# define ASN1_R_NOT_ASCII_FORMAT 190
# define ASN1_R_NOT_ENOUGH_DATA 142
# define ASN1_R_NO_CONTENT_TYPE 209
# define ASN1_R_NO_MATCHING_CHOICE_TYPE 143
# define ASN1_R_NO_MULTIPART_BODY_FAILURE 210
# define ASN1_R_NO_MULTIPART_BOUNDARY 211
# define ASN1_R_NO_SIG_CONTENT_TYPE 212
# define ASN1_R_NULL_IS_WRONG_LENGTH 144
# define ASN1_R_OBJECT_NOT_ASCII_FORMAT 191
# define ASN1_R_ODD_NUMBER_OF_CHARS 145
# define ASN1_R_SECOND_NUMBER_TOO_LARGE 147
# define ASN1_R_SEQUENCE_LENGTH_MISMATCH 148
# define ASN1_R_SEQUENCE_NOT_CONSTRUCTED 149
# define ASN1_R_SEQUENCE_OR_SET_NEEDS_CONFIG 192
# define ASN1_R_SHORT_LINE 150
# define ASN1_R_SIG_INVALID_MIME_TYPE 213
# define ASN1_R_STREAMING_NOT_SUPPORTED 202
# define ASN1_R_STRING_TOO_LONG 151
# define ASN1_R_STRING_TOO_SHORT 152
# define ASN1_R_THE_ASN1_OBJECT_IDENTIFIER_IS_NOT_KNOWN_FOR_THIS_MD 154
# define ASN1_R_TIME_NOT_ASCII_FORMAT 193
# define ASN1_R_TOO_LARGE 223
# define ASN1_R_TOO_LONG 155
# define ASN1_R_TOO_SMALL 224
# define ASN1_R_TYPE_NOT_CONSTRUCTED 156
# define ASN1_R_TYPE_NOT_PRIMITIVE 195
# define ASN1_R_UNEXPECTED_EOC 159
# define ASN1_R_UNIVERSALSTRING_IS_WRONG_LENGTH 215
# define ASN1_R_UNKNOWN_FORMAT 160
# define ASN1_R_UNKNOWN_MESSAGE_DIGEST_ALGORITHM 161
# define ASN1_R_UNKNOWN_OBJECT_TYPE 162
# define ASN1_R_UNKNOWN_PUBLIC_KEY_TYPE 163
# define ASN1_R_UNKNOWN_SIGNATURE_ALGORITHM 199
# define ASN1_R_UNKNOWN_TAG 194
# define ASN1_R_UNSUPPORTED_ANY_DEFINED_BY_TYPE 164
# define ASN1_R_UNSUPPORTED_CIPHER 228
# define ASN1_R_UNSUPPORTED_PUBLIC_KEY_TYPE 167
# define ASN1_R_UNSUPPORTED_TYPE 196
# define ASN1_R_WRONG_INTEGER_TYPE 225
# define ASN1_R_WRONG_PUBLIC_KEY_TYPE 200
# define ASN1_R_WRONG_TAG 168
#endif

Some files were not shown because too many files have changed in this diff Show More