mirror of
https://github.com/microsoft/vcpkg.git
synced 2024-12-26 17:41:09 +08:00
[vcpkg docs] Remove docs migrated to https://learn.microsoft.com/vcpkg and Microsoft/vcpkg-docs (#28350)
* [docs] Remove embedded documentation in favor of learn.microsoft.com * [docs] Remove validation workflow
This commit is contained in:
Robert Schumacher
GitHub
parent
43aabb4f9b
commit
547c030e68
54
.github/workflows/validateDocs.yml
vendored
54
.github/workflows/validateDocs.yml
vendored
@ -1,54 +0,0 @@
|
||||
name: Doc Validation
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'docs/**'
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: ubuntu-22.04
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
path: vcpkg
|
||||
|
||||
- name: Checkout Website
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
repository: vcpkg/vcpkg.github.io
|
||||
ref: '8ee5cacc91b6e017b5e4236940d9f385c1563598'
|
||||
path: vcpkg.github.io
|
||||
|
||||
- uses: actions/cache@v3
|
||||
with:
|
||||
path: ~/.npm
|
||||
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
|
||||
restore-keys: |
|
||||
${{ runner.os }}-node-
|
||||
|
||||
- run: npm ci
|
||||
working-directory: vcpkg.github.io
|
||||
|
||||
- name: Purge existing html files
|
||||
run: rm -rf en
|
||||
working-directory: vcpkg.github.io
|
||||
|
||||
# The current navbar embeds a link to integration.md which no longer exists
|
||||
- name: Ignore navbar
|
||||
run: echo "" > templates/navbar.html
|
||||
working-directory: vcpkg.github.io
|
||||
|
||||
- name: Generate Core Pages
|
||||
run: node scripts/generatePages.js
|
||||
working-directory: vcpkg.github.io
|
||||
|
||||
- name: Generate Docs Pages
|
||||
run: node scripts/generateDocs.js ../vcpkg/docs
|
||||
working-directory: vcpkg.github.io
|
||||
|
||||
- name: Check Links
|
||||
run: VCPKG_VALIDATE_LINKS_ONLY_DOCS=1 node scripts/validateLinks.js
|
||||
working-directory: vcpkg.github.io
|
||||
28
README.md
28
README.md
@ -17,7 +17,7 @@ you can run `vcpkg help`, or `vcpkg help [command]` for command-specific help.
|
||||
* GitHub: ports at [https://github.com/microsoft/vcpkg](https://github.com/microsoft/vcpkg), program at [https://github.com/microsoft/vcpkg-tool](https://github.com/microsoft/vcpkg-tool)
|
||||
* Slack: [https://cppalliance.org/slack/](https://cppalliance.org/slack/), the #vcpkg channel
|
||||
* Discord: [\#include \<C++\>](https://www.includecpp.org), the #🌏vcpkg channel
|
||||
* Docs: [Documentation](docs/README.md)
|
||||
* Docs: [Documentation](https://learn.microsoft.com/vcpkg)
|
||||
|
||||
# Table of Contents
|
||||
|
||||
@ -55,11 +55,6 @@ and potentially add the port to vcpkg.
|
||||
After you've gotten vcpkg installed and working,
|
||||
you may wish to add [tab completion](#tab-completionauto-completion) to your shell.
|
||||
|
||||
Finally, if you're interested in the future of vcpkg,
|
||||
check out the [manifest][getting-started:manifest-spec] guide!
|
||||
This is an experimental feature and will likely have bugs,
|
||||
so try it out and [open all the issues][contributing:submit-issue]!
|
||||
|
||||
## Quick Start: Windows
|
||||
|
||||
Prerequisites:
|
||||
@ -128,9 +123,6 @@ With CMake, you will still need to `find_package` and the like to use the librar
|
||||
Check out the [CMake section](#using-vcpkg-with-cmake) for more information,
|
||||
including on using CMake with an IDE.
|
||||
|
||||
For any other tools, including Visual Studio Code,
|
||||
check out the [integration guide][getting-started:integration].
|
||||
|
||||
## Quick Start: Unix
|
||||
|
||||
Prerequisites for Linux:
|
||||
@ -172,8 +164,6 @@ Check out the [CMake section](#using-vcpkg-with-cmake)
|
||||
for more information on how best to use vcpkg with CMake,
|
||||
and CMake Tools for VSCode.
|
||||
|
||||
For any other tools, check out the [integration guide][getting-started:integration].
|
||||
|
||||
## Installing Linux Developer Tools
|
||||
|
||||
Across the different distros of Linux, there are different packages you'll
|
||||
@ -262,8 +252,7 @@ This will still allow people to not use vcpkg,
|
||||
by passing the `CMAKE_TOOLCHAIN_FILE` directly,
|
||||
but it will make the configure-build step slightly easier.
|
||||
|
||||
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
|
||||
[getting-started:integration]: docs/users/buildsystems/integration.md
|
||||
[getting-started:using-a-package]: https://learn.microsoft.com/vcpkg/examples/installing-and-using-packages.md
|
||||
[getting-started:git]: https://git-scm.com/downloads
|
||||
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
|
||||
[getting-started:linux-gcc]: #installing-linux-developer-tools
|
||||
@ -271,7 +260,6 @@ but it will make the configure-build step slightly easier.
|
||||
[getting-started:macos-brew]: #installing-gcc-on-macos
|
||||
[getting-started:macos-gcc]: #installing-gcc-on-macos
|
||||
[getting-started:visual-studio]: https://visualstudio.microsoft.com/
|
||||
[getting-started:manifest-spec]: docs/specifications/manifests.md
|
||||
|
||||
# Tab-Completion/Auto-Completion
|
||||
|
||||
@ -293,10 +281,10 @@ depending on the shell you use, then restart your console.
|
||||
|
||||
# Examples
|
||||
|
||||
See the [documentation](docs/README.md) for specific walkthroughs,
|
||||
including [installing and using a package](docs/examples/installing-and-using-packages.md),
|
||||
[adding a new package from a zipfile](docs/examples/packaging-zipfiles.md),
|
||||
and [adding a new package from a GitHub repo](docs/examples/packaging-github-repos.md).
|
||||
See the [documentation](https://learn.microsoft.com/vcpkg) for specific walkthroughs,
|
||||
including [installing and using a package](https://learn.microsoft.com/vcpkg/examples/installing-and-using-packages.md),
|
||||
[adding a new package from a zipfile](https://learn.microsoft.com/vcpkg/examples/packaging-zipfiles.md),
|
||||
and [adding a new package from a GitHub repo](https://learn.microsoft.com/vcpkg/examples/packaging-github-repos.md).
|
||||
|
||||
Our docs are now also available online at our website https://vcpkg.io/. We really appreciate any and all feedback! You can submit an issue in https://github.com/vcpkg/vcpkg.github.io/issues.
|
||||
|
||||
@ -335,7 +323,7 @@ by the original developers of those libraries, and download source code and buil
|
||||
official distribution locations. For use behind a firewall, the specific access needed will depend
|
||||
on which ports are being installed. If you must install in in an "air gapped" environment, consider
|
||||
installing once in a non-"air gapped" environment, populating an
|
||||
[asset cache](docs/users/assetcaching.md) shared with the otherwise "air gapped" environment.
|
||||
[asset cache](https://learn.microsoft.com/vcpkg/users/assetcaching.md) shared with the otherwise "air gapped" environment.
|
||||
|
||||
# Telemetry
|
||||
|
||||
@ -346,4 +334,4 @@ You can opt-out of telemetry by
|
||||
- passing --disable-metrics to vcpkg on the command line
|
||||
- setting the VCPKG_DISABLE_METRICS environment variable
|
||||
|
||||
Read more about vcpkg telemetry at docs/about/privacy.md
|
||||
[Read more about vcpkg telemetry](https://learn.microsoft.com/vcpkg/about/privacy.html)
|
||||
|
||||
@ -1,86 +0,0 @@
|
||||
### Quick Start
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/README.md).**
|
||||
|
||||
Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement is 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 x64-uwp](examples/patching.md)
|
||||
- [Getting Started with Versioning](examples/versioning.getting-started.md)
|
||||
- [Manifest Mode: CMake Example](examples/manifest-mode-cmake.md)
|
||||
- [Pin old Boost Versions](examples/modify-baseline-to-pin-old-boost.md)
|
||||
- [Using Overlay Triplets](examples/overlay-triplets-linux-dynamic.md)
|
||||
|
||||
### Command Line Reference
|
||||
|
||||
- [Common Options](commands/common-options.md)
|
||||
- Commands
|
||||
- [vcpkg install](commands/install.md)
|
||||
- [vcpkg integrate](commands/integrate.md)
|
||||
- [vcpkg list](commands/list.md)
|
||||
- [vcpkg remove](commands/remove.md)
|
||||
- [vcpkg search](commands/search.md)
|
||||
- [vcpkg update-baseline](commands/update-baseline.md)
|
||||
- [vcpkg version](commands/version.md)
|
||||
|
||||
### User Help
|
||||
|
||||
- [Buildsystem Integration](users/buildsystems/integration.md)
|
||||
- [Triplet files](users/triplets.md)
|
||||
- [Configuration and Environment](users/config-environment.md)
|
||||
- [Authentication](users/authentication.md)
|
||||
- [Manifest Mode](users/manifests.md)
|
||||
- [Binary Caching](users/binarycaching.md)
|
||||
- [Asset Caching](users/assetcaching.md)
|
||||
- [Versioning](users/versioning.md)
|
||||
- [Usage with Android](users/android.md)
|
||||
- [Usage with Mingw-w64](users/mingw.md)
|
||||
- [Host Dependencies](users/host-dependencies.md)
|
||||
- [Using Registries](users/registries.md)
|
||||
|
||||
### Maintainer Help
|
||||
|
||||
- [Manifest Files - vcpkg.json](maintainers/manifest-files.md)
|
||||
- [Control Files](maintainers/control-files.md)
|
||||
- [Portfile Functions](maintainers/portfile-functions.md)
|
||||
- [Authoring Script Ports](maintainers/authoring-script-ports.md)
|
||||
- [Common CMake Definitions](maintainers/vcpkg_common_definitions.md)
|
||||
- [Maintainer Guidelines](maintainers/maintainer-guide.md)
|
||||
- [Creating Registries](maintainers/registries.md)
|
||||
- [CMake Guidelines](maintainers/cmake-guidelines.md)
|
||||
|
||||
### [Vcpkg-Tool](https://github.com/microsoft/vcpkg-tool) Maintainer Help
|
||||
|
||||
- [Testing](https://github.com/microsoft/vcpkg-tool/tree/main/docs/testing.md)
|
||||
- [Benchmarking](https://github.com/microsoft/vcpkg-tool/tree/main/docs/benchmarking.md)
|
||||
- [Layout of the vcpkg source tree](https://github.com/microsoft/vcpkg-tool/tree/main/docs/layout.md)
|
||||
|
||||
### Community Resources (not directly affiliated with vcpkg)
|
||||
|
||||
- [vcpkgx.com](https://vcpkgx.com/) - Package index + search
|
||||
- [vcpkg.dev](https://vcpkg.dev/) - Package index + search
|
||||
- [vcpkg.link](https://vcpkg.link/) - Package index + search
|
||||
|
||||
### Blog posts
|
||||
|
||||
- [Vcpkg Host Dependencies for Cross-Compilation](https://devblogs.microsoft.com/cppblog/vcpkg-host-dependencies/)
|
||||
- [Registries: Bring your own libraries to vcpkg](https://devblogs.microsoft.com/cppblog/registries-bring-your-own-libraries-to-vcpkg/)
|
||||
- [Vcpkg: Accelerate your team development environment with binary caching and manifests](https://devblogs.microsoft.com/cppblog/vcpkg-accelerate-your-team-development-environment-with-binary-caching-and-manifests/)
|
||||
- [Vcpkg: 2019.06 Update (overlay ports, overlay triplets, `vcpkg_check_features`)](https://devblogs.microsoft.com/cppblog/vcpkg-2019-06-update/)
|
||||
- [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)
|
||||
@ -1 +0,0 @@
|
||||
theme: jekyll-theme-cayman
|
||||
@ -1,134 +0,0 @@
|
||||
# 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%3Acategory%3Anew-port).
|
||||
|
||||
## Can vcpkg create pre-built binary packages? What is the binary format used by vcpkg?
|
||||
Yes! See the [`export` command](../users/buildsystems/export-command.md) if you wish to produce binaries for exporting into other environments.
|
||||
|
||||
Alternatively, if your goal is to preserve binaries produced by `vcpkg install` operations for later re-use, see the [Binary Caching feature](../users/binarycaching.md)
|
||||
|
||||
## 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.
|
||||
|
||||
You can take this further by publishing your private libraries into a registry. See the article on [Creating Registries](../maintainers/registries.md). A registry is a catalog of ports, similar to the one provided with vcpkg that contains open source libraries.
|
||||
|
||||
## 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 can I target with vcpkg?
|
||||
Our built-in, CI-tested triplets are:
|
||||
* Windows Desktop (x86, x64, x64-static, arm64)
|
||||
* Universal Windows Platform (x64, and ARM)
|
||||
* Mac OS X (x64-static)
|
||||
* Linux (x64-static)
|
||||
|
||||
However, there is an even larger number of community triplets available with more platforms and architectures, including for iOS, Android, MinGW, WebAssembly, freeBSD, and openBSD.
|
||||
|
||||
You can also define your own triplets depending on your needs.
|
||||
|
||||
See `vcpkg help triplet` for the current list.
|
||||
|
||||
## Does vcpkg run on Linux/OS X?
|
||||
Yes! We continuously test on OS X 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 update vcpkg?
|
||||
Execute `git pull` to get the latest sources, then run `bootstrap-vcpkg.bat` (Windows) or `./bootstrap-vcpkg.sh` (Unix) to update vcpkg.
|
||||
|
||||
## 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/buildsystems/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 using the [Binary Caching](../users/binarycaching.md) feature to re-use binaries across different machines and for local development vs. CI scenarios.
|
||||
|
||||
## 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!).
|
||||
@ -1,50 +0,0 @@
|
||||
# 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 bootstrap 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 at https://github.com/microsoft/vcpkg-tool/ ), 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.
|
||||
@ -1,121 +0,0 @@
|
||||
# Common Command Options
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/common-options.md).**
|
||||
|
||||
Most vcpkg commands accept a group of common options that control cross-cutting aspects of the tool. Not all options affect every command. For example, a command that does not download any files will be unaffected by changing the downloads directory.
|
||||
|
||||
<a name="asset-sources"></a>
|
||||
|
||||
## `--x-asset-sources=<config>`
|
||||
|
||||
**Experimental: will change or be removed at any time**
|
||||
|
||||
Specify the cache configuration for [Asset Caching](../users/assetcaching.md).
|
||||
|
||||
<a name="binarysource"></a>
|
||||
|
||||
## `--binarysource=<config>`
|
||||
|
||||
Add a source for [Binary Caching](../users/binarycaching.md).
|
||||
|
||||
This option can be specified multiple times; see the Binary Caching documentation for how multiple binary sources interact.
|
||||
|
||||
<a name="buildtrees-root"></a>
|
||||
|
||||
## `--x-buildtrees-root=<path>`
|
||||
|
||||
**Experimental: will change or be removed at any time**
|
||||
|
||||
Specifies the temporary path to store intermediate build files, such as objects or unpacked source code.
|
||||
|
||||
Defaults to `buildtrees/` under the vcpkg root folder.
|
||||
|
||||
<a name="downloads-root"></a>
|
||||
|
||||
## `--downloads-root=<path>`
|
||||
|
||||
Specify where downloaded tools and source code archives should be kept.
|
||||
|
||||
Defaults to the `VCPKG_DOWNLOADS` environment variable. If that is unset, defaults to `downloads/` under the vcpkg root folder.
|
||||
|
||||
<a name="host-triplet"></a>
|
||||
|
||||
## `--host-triplet=<triplet>`
|
||||
|
||||
Specify the host [architecture triplet][triplets].
|
||||
|
||||
Defaults to the `VCPKG_DEFAULT_HOST_TRIPLET` environment variable. If that is unset, deduced based on the host architecture and operating system.
|
||||
|
||||
<a name="install-root"></a>
|
||||
|
||||
## `--x-install-root=<path>`
|
||||
|
||||
**Experimental: will change or be removed at any time**
|
||||
|
||||
Specifies the path to lay out installed packages.
|
||||
|
||||
In Classic Mode, defaults to `installed/` under the vcpkg root folder.
|
||||
|
||||
In [Manifest Mode](../users/manifests.md), defaults to `vcpkg_installed/` under the manifest folder.
|
||||
|
||||
<a name="manifest-root"></a>
|
||||
|
||||
## `--x-manifest-root=<path>`
|
||||
|
||||
**Experimental: will change or be removed at any time**
|
||||
|
||||
Specifies the directory containing [`vcpkg.json`](../users/manifests.md).
|
||||
|
||||
Defaults to searching upwards from the current working directory for the nearest `vcpkg.json`.
|
||||
|
||||
<a name="overlay-ports"></a>
|
||||
|
||||
## `--overlay-ports=<path>`
|
||||
|
||||
Specifies a directory containing [overlay ports](../specifications/ports-overlay.md).
|
||||
|
||||
This option can be specified multiple times; ports will resolve to the first match.
|
||||
|
||||
<a name="overlay-triplets"></a>
|
||||
|
||||
## `--overlay-triplets=<path>`
|
||||
|
||||
Specifies a directory containing [overlay triplets](../examples/overlay-triplets-linux-dynamic.md).
|
||||
|
||||
This option can be specified multiple times; [triplets][] will resolve to the first match.
|
||||
|
||||
<a name="packages-root"></a>
|
||||
|
||||
## `--x-packages-root=<path>`
|
||||
|
||||
**Experimental: will change or be removed at any time**
|
||||
|
||||
Specifies the temporary path to stage intermediate package files before final install.
|
||||
|
||||
Defaults to `packages/` under the vcpkg root folder.
|
||||
|
||||
<a name="triplet"></a>
|
||||
|
||||
## `--triplet=<triplet>`
|
||||
|
||||
Specify the target [architecture triplet][triplets].
|
||||
|
||||
Defaults to the `VCPKG_DEFAULT_TRIPLET` environment variable. If that is unset, deduced based on the host architecture and operating system.
|
||||
|
||||
Note that on Windows operating systems, the architecture is always deduced as x86 for legacy reasons.
|
||||
|
||||
<a name="vcpkg-root"></a>
|
||||
|
||||
## `--vcpkg-root=<path>`
|
||||
|
||||
Specifies the vcpkg root folder.
|
||||
|
||||
Defaults to the directory containing the vcpkg program. The directory must be a valid vcpkg instance, such as a `git clone` of `https://github.com/microsoft/vcpkg`. This option can be used to run a custom-built copy of the tool directly from the build folder.
|
||||
|
||||
## Response Files (`@<file>`)
|
||||
|
||||
The vcpkg command line accepts text files containing newline-separated command line parameters.
|
||||
|
||||
The tool will act as though the items in the file were spliced into the command line in place of the `@` reference. Response files cannot contain additional response files.
|
||||
|
||||
[triplets]: ../users/triplets.md
|
||||
@ -1,193 +0,0 @@
|
||||
# vcpkg install
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/install.md).**
|
||||
|
||||
## Synopsis
|
||||
|
||||
**Classic Mode**
|
||||
```no-highlight
|
||||
vcpkg install [options] <package>...
|
||||
```
|
||||
|
||||
**Manifest Mode**
|
||||
```no-highlight
|
||||
vcpkg install [options]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Build and install port packages.
|
||||
|
||||
### Classic Mode
|
||||
|
||||
In Classic Mode, this verb adds port packages to the existing set in the [installed directory][] (defaults to `installed/` under the vcpkg root). This can require removing and rebuilding existing packages, which can fail.
|
||||
|
||||
<a id="package-syntax"></a>
|
||||
|
||||
**Package Syntax**
|
||||
```
|
||||
portname[feature1,feature2]:triplet
|
||||
```
|
||||
|
||||
Package references without a triplet are automatically qualified by the [default target triplet](common-options.md#triplet). Package references that do not explicitly list `core` are considered to imply all default features.
|
||||
|
||||
### Manifest Mode
|
||||
|
||||
In [Manifest Mode][], this verb sets the [installed directory][] to the state specified by the `vcpkg.json` manifest file, adding, removing, or rebuilding packages as needed.
|
||||
|
||||
[installed directory]: common-options.md#install-root
|
||||
|
||||
## Options
|
||||
|
||||
All vcpkg commands support a set of [common options](common-options.md).
|
||||
|
||||
### `--allow-unsupported`
|
||||
|
||||
Instead of stopping on an unsupported port, continue with a warning.
|
||||
|
||||
By default, vcpkg refuses to execute an install plan containing a port installation for a triplet outside its [`"supports"`][supports] clause. The [`"supports"`][supports] clause of a package describes the full set of platforms a package is expected to be buildable on. This flag instructs vcpkg to warn that the build is expected to fail instead of stopping.
|
||||
|
||||
### `--clean-after-build`
|
||||
|
||||
Clean buildtrees, packages, and downloads after building each package.
|
||||
|
||||
This option has the same effect as passing [`--clean-buildtrees-after-build`](#clean-buildtrees-after-build), [`--clean-downloads-after-build`](#clean-downloads-after-build), and [`--clean-packages-after-build`](#clean-packages-after-build).
|
||||
|
||||
<a id="clean-buildtrees-after-build"></a>
|
||||
|
||||
### `--clean-buildtrees-after-build`
|
||||
|
||||
Clean all subdirectories from the buildtrees temporary subfolder after building each package.
|
||||
|
||||
All top-level files in the buildtrees subfolder (e.g. `buildtrees/zlib/config-x64-windows-out.log`) will be kept. All subdirectories will be deleted.
|
||||
|
||||
<a id="clean-downloads-after-build"></a>
|
||||
|
||||
### `--clean-downloads-after-build`
|
||||
|
||||
Clean all unextracted assets from the `downloads/` folder after building each package.
|
||||
|
||||
All top level files in the `downloads/` folder will be deleted. Extracted tools will be kept.
|
||||
|
||||
<a id="clean-packages-after-build"></a>
|
||||
|
||||
### `--clean-packages-after-build`
|
||||
|
||||
Clean the packages temporary subfolder after building each package.
|
||||
|
||||
The packages subfolder for the built package (for example, `packages/zlib_x64-windows`) will be deleted after installation.
|
||||
|
||||
### `--dry-run`
|
||||
|
||||
Print the install plan, but do not remove or install any packages.
|
||||
|
||||
The install plan lists all packages and features that will be installed, as well as any other packages that need to be removed and rebuilt.
|
||||
|
||||
<a id="editable"></a>
|
||||
|
||||
### `--editable`
|
||||
|
||||
**Classic Mode Only**
|
||||
|
||||
Perform editable builds for all directly referenced packages on the command line.
|
||||
|
||||
When vcpkg builds ports, it purges and re-extracts the source code each time to ensure inputs are accurately. This is necessary for [Manifest Mode][] to accurately update what is installed and [Binary Caching][] to ensure cached content is correct.
|
||||
|
||||
Passing the `--editable` flag disables this behavior, preserving edits to the extracted sources in the `buildtrees/` folder. This helps develop patches quickly by avoiding the need to write a file on each change.
|
||||
|
||||
Sources extracted during an editable build do not have a `.clean/` suffix on the directory name and will not be cleared by subsequent non-editable builds.
|
||||
|
||||
### `--enforce-port-checks`
|
||||
|
||||
Fail install if a port has detected problems or attempts to use a deprecated feature.
|
||||
|
||||
By default, vcpkg will run several checks on built packages and emit warnings if any issues are detected. This flag upgrades those warnings to an error.
|
||||
|
||||
<a name="feature"></a>
|
||||
|
||||
### `--x-feature=<feature>`
|
||||
|
||||
**Experimental and may change or be removed at any time**
|
||||
|
||||
**[Manifest Mode][] Only**
|
||||
|
||||
Specify an additional [feature](../users/manifests.md#features) from the `vcpkg.json` to install dependencies for.
|
||||
|
||||
By default, only [`"dependencies"`][dependencies] and the dependencies of the [`"default-features"`][default-features] will be installed.
|
||||
|
||||
### `--head`
|
||||
|
||||
**Classic Mode Only**
|
||||
|
||||
Request all packages explicitly referenced on the command line to fetch the latest sources available when building.
|
||||
|
||||
This flag is only intended for temporary testing and is not intended for production or long-term use. This disables [Binary Caching][] for all explicitly referenced packages and their dependents because vcpkg cannot accurately track all inputs.
|
||||
|
||||
### `--keep-going`
|
||||
|
||||
Continue the install plan after the first failure.
|
||||
|
||||
By default, vcpkg will stop at the first package build failure. This flag instructs vcpkg to continue building and installing other parts of the install plan that don't depend upon the failed package.
|
||||
|
||||
### `--x-no-default-features`
|
||||
|
||||
**Experimental and may change or be removed at any time**
|
||||
|
||||
**[Manifest Mode][] Only**
|
||||
|
||||
Don't install the default features from the top-level manifest.
|
||||
|
||||
When using `install` in Manifest Mode, by default all dependencies of the features listed in [`"default-features"`][default-features] will be installed. This flag disables that behavior so only features explicitly enabled by [`--x-feature`](#feature) will be installed.
|
||||
|
||||
### `--no-downloads`
|
||||
|
||||
When building a package, prevent ports from downloading new assets during the build.
|
||||
|
||||
By default, ports will acquire source code and tools on demand from the internet (subject to [Asset Caching][]). This parameter blocks downloads and restricts ports to only the assets that were previously downloaded and cached on the machine.
|
||||
|
||||
### `--only-downloads`
|
||||
|
||||
Attempt to download all assets required for an install plan without performing any builds.
|
||||
|
||||
When passed this option, vcpkg will run each build in the plan until it makes its first non-downloading external process call. Most ports perform all downloads before the first external process call (usually to their buildsystem), so this procedure will download all required assets. Ports that do not follow this procedure will not have their assets predownloaded.
|
||||
|
||||
### `--only-binarycaching`
|
||||
|
||||
Refuse to perform any builds. Only restore packages from [Binary Caches][Binary Caching].
|
||||
|
||||
This flag blocks vcpkg from performing builds on demand and will fail if a package cannot be found in any binary caches.
|
||||
|
||||
### `--recurse`
|
||||
|
||||
**Classic Mode Only**
|
||||
|
||||
Approve an install plan that requires rebuilding packages.
|
||||
|
||||
In order to modify the set of features of an installed package, vcpkg must remove and rebuild that package. Because this has the potential of failing and leaving the install tree with fewer packages than the user started with, the user must approve plans that rebuild packages by passing this flag.
|
||||
|
||||
### `--x-use-aria2`
|
||||
|
||||
**Experimental and may change or be removed at any time**
|
||||
|
||||
Use aria2 to perform download tasks.
|
||||
|
||||
<a id="write-nuget-packages-config"></a>
|
||||
|
||||
### `--x-write-nuget-packages-config`
|
||||
|
||||
**Experimental and may change or be removed at any time**
|
||||
|
||||
Writes out a NuGet `packages.config`-formatted file for use with [Binary Caching][].
|
||||
|
||||
This option can be used in conjunction with `--dry-run` to obtain the list of NuGet packages required from [Binary Caching][] without building or installing any packages. This enables the NuGet command line to be invoked separately for advanced scenarios, such as using alternate protocols to acquire the `.nupkg` files.
|
||||
|
||||
### `--no-print-usage`
|
||||
|
||||
Suppress generation of usage text printed at the end of installation.
|
||||
|
||||
[Asset Caching]: ../users/assetcaching.md
|
||||
[Binary Caching]: ../users/binarycaching.md
|
||||
[Manifest Mode]: ../users/manifests.md
|
||||
[supports]: ../users/manifests.md#supports
|
||||
[default-features]: ../users/manifests.md#default-features
|
||||
[dependencies]: ../users/manifests.md#dependencies
|
||||
@ -1,84 +0,0 @@
|
||||
# vcpkg integrate
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/integrate.md).**
|
||||
|
||||
## Synopsis
|
||||
|
||||
**Buildsystem Integration**
|
||||
```no-highlight
|
||||
vcpkg integrate [options] install
|
||||
vcpkg integrate [options] remove
|
||||
vcpkg integrate [options] project
|
||||
```
|
||||
**Shell Integration**
|
||||
```no-highlight
|
||||
vcpkg integrate [options] powershell
|
||||
vcpkg integrate [options] bash
|
||||
vcpkg integrate [options] zsh
|
||||
vcpkg integrate [options] x-fish
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Integrate vcpkg with shells and buildsystems.
|
||||
|
||||
### `vcpkg integrate install`
|
||||
|
||||
Integrates with [Visual Studio](../users/buildsystems/msbuild-integration.md#user-wide-integration) (Windows-only), sets the user-wide vcpkg instance, and displays CMake integration help.
|
||||
|
||||
On Windows with Visual Studio 2015, this subcommand will add redirecting logic into the MSBuild installation which will automatically pick up each user's user-wide vcpkg instance. Visual Studio 2017 and newer have this logic in the box.
|
||||
|
||||
To set the user-wide vcpkg instance, vcpkg creates a few short files containing the absolute path to the vcpkg instance inside the user's user-wide configuration location:
|
||||
|
||||
- `%LOCALAPPDATA%\vcpkg` or `%APPDATA%\Local\vcpkg` on Windows
|
||||
- `$HOME/.vcpkg` or `/var/.vcpkg` on non-Windows
|
||||
|
||||
Displays the full path to the [CMake toolchain file](../users/buildsystems/cmake-integration.md). Running this command is not required to use the toolchain file.
|
||||
|
||||
### `vcpkg integrate remove`
|
||||
|
||||
Removes the user-wide vcpkg instance setting.
|
||||
|
||||
This command deletes the linking files from the user-wide configuration location created by `vcpkg integrate install`.
|
||||
|
||||
### `vcpkg integrate project`
|
||||
|
||||
Creates a linked NuGet package for MSBuild integration.
|
||||
|
||||
See [MSBuild Per-Project Integration](../users/buildsystems/msbuild-integration.md#linked-nuget-package) for more information.
|
||||
|
||||
### `vcpkg integrate powershell`
|
||||
|
||||
**Windows Only**
|
||||
|
||||
Adds vcpkg tab-completion support to the current user's Powershell profile.
|
||||
|
||||
### `vcpkg integrate bash`
|
||||
|
||||
**Non-Windows Only**
|
||||
|
||||
Adds vcpkg tab-completion support to the current user's `.bashrc` (`.bash_profile` on MacOS).
|
||||
|
||||
### `vcpkg integrate zsh`
|
||||
|
||||
**Non-Windows Only**
|
||||
|
||||
Adds vcpkg tab-completion support to the current user's `.zshrc`.
|
||||
|
||||
### `vcpkg integrate x-fish`
|
||||
|
||||
**Non-Windows Only**
|
||||
|
||||
Adds vcpkg tab-completion support to the current user's fish shell completions directory.
|
||||
|
||||
## Example
|
||||
```no-highlight
|
||||
$ vcpkg integrate install
|
||||
Applied user-wide integration for this vcpkg root.
|
||||
|
||||
CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=/workspaces/vcpkg/scripts/buildsystems/vcpkg.cmake"
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
All vcpkg commands support a set of [common options](common-options.md).
|
||||
@ -1,31 +0,0 @@
|
||||
# vcpkg list
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/list.md).**
|
||||
|
||||
## Synopsis
|
||||
|
||||
```no-highlight
|
||||
vcpkg list [options]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Shows a list of the packages in the installed tree, along with the version and description of each.
|
||||
|
||||
## Example
|
||||
```no-highlight
|
||||
$ vcpkg list
|
||||
|
||||
cxxopts:x64-windows 3.0.0 This is a lightweight C++ option parser library...
|
||||
fmt:x64-windows 9.0.0 Formatting library for C++. It can be used as a...
|
||||
range-v3:x64-windows 0.12.0 Range library for C++11/14/17/20.
|
||||
vcpkg-cmake-config:x64-windows 2022-02-06#1
|
||||
vcpkg-cmake:x64-windows 2022-08-18
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
All vcpkg commands support a set of [common options](https://github.com/microsoft/vcpkg/blob/5fac018507e67a8b98141b9d4cebeb07c9bd5cba/docs/commands/common-options.md).
|
||||
|
||||
### `--x-full-desc`
|
||||
Print the full, untruncated description of each package.
|
||||
@ -1,43 +0,0 @@
|
||||
# vcpkg remove
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/remove.md).**
|
||||
|
||||
## Synopsis
|
||||
|
||||
```no-highlight
|
||||
vcpkg remove [options] <package>...
|
||||
```
|
||||
|
||||
```no-highlight
|
||||
vcpkg remove --outdated [options]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Remove port packages from Classic Mode.
|
||||
|
||||
`remove` removes listed packages and any packages that require them from the Classic Mode [installed directory](common-options.md#install-root). See the [install command documentation](install.md#package-syntax) for detailed syntax of the `<package>` parameter.
|
||||
|
||||
This command is not currently supported in [Manifest Mode][].
|
||||
|
||||
## Options
|
||||
|
||||
All vcpkg commands support a set of [common options](common-options.md).
|
||||
|
||||
### `--recurse`
|
||||
|
||||
Allow removing packages not specified on the command line.
|
||||
|
||||
By default, vcpkg refuses to execute a removal plan that would remove packages not listed on the command line.
|
||||
|
||||
### `--dry-run`
|
||||
|
||||
Print the packages to be removed, but do not remove them.
|
||||
|
||||
### `--outdated`
|
||||
|
||||
Remove all packages that do not match the available port versions.
|
||||
|
||||
For each installed package, vcpkg will compare the installed version string to the version string of the current recipe. If those versions differ, the package will be selected for removal. If `--outdated` is passed, no packages should be listed on the command line.
|
||||
|
||||
[Manifest Mode]: ../users/manifests.md
|
||||
@ -1,37 +0,0 @@
|
||||
# vcpkg search
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/search.md).**
|
||||
|
||||
## Synopsis
|
||||
|
||||
```no-highlight
|
||||
vcpkg search [options] [query]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Searches for available packages by name and description.
|
||||
|
||||
Search performs a case-insensitive search through all available package names and descriptions. The results are displayed in a tabular format.
|
||||
|
||||
## Example
|
||||
```no-highlight
|
||||
$ vcpkg search zlib
|
||||
miniz 2.2.0#1 Single C source file zlib-replacement library
|
||||
zlib 1.2.12#1 A compression library
|
||||
zlib-ng 2.0.6 zlib replacement with optimizations for 'next generation' systems
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
All vcpkg commands support a set of [common options](common-options.md).
|
||||
|
||||
### `--x-full-desc`
|
||||
|
||||
**Experimental and may change or be removed at any time**
|
||||
|
||||
Do not truncate long descriptions.
|
||||
|
||||
By default, long descriptions will be truncated to keep the tabular output browsable.
|
||||
|
||||
[Registries]: ../users/registries.md
|
||||
@ -1,42 +0,0 @@
|
||||
# vcpkg x-update-baseline
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/update-baseline.md).**
|
||||
|
||||
**This command is experimental and may change or be removed at any time**
|
||||
|
||||
## Synopsis
|
||||
|
||||
```no-highlight
|
||||
vcpkg x-update-baseline [options] [--add-initial-baseline] [--dry-run]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Update baselines for all configured [registries][].
|
||||
|
||||
In [Manifest Mode][], this command operates on all [registries][] in the `vcpkg.json` and the [`vcpkg-configuration.json`][vcj]. In Classic Mode, this command operates on the [`vcpkg-configuration.json`][vcj] in the vcpkg instance (`$VCPKG_ROOT`).
|
||||
|
||||
See the [versioning documentation](../users/versioning.md#baselines) for more information about baselines.
|
||||
|
||||
## Options
|
||||
|
||||
All vcpkg commands support a set of [common options](common-options.md).
|
||||
|
||||
### `--dry-run`
|
||||
|
||||
Print the planned baseline upgrades, but do not modify the files on disk.
|
||||
|
||||
<a id="add-initial-baseline"></a>
|
||||
|
||||
### `--add-initial-baseline`
|
||||
|
||||
**[Manifest Mode][] Only**
|
||||
|
||||
Add a [`"builtin-baseline"`][builtin-baseline] field to the `vcpkg.json` if it does not already have one.
|
||||
|
||||
Without this flag, it is an error to run this command on a manifest that does not have any [registries][] configured.
|
||||
|
||||
[Manifest Mode]: ../users/manifests.md
|
||||
[builtin-baseline]: ../users/manifests.md#builtin-baseline
|
||||
[vcj]: ../users/registries.md#vcpkg-configurationjson
|
||||
[registries]: ../users/registries.md
|
||||
@ -1,25 +0,0 @@
|
||||
# vcpkg version
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/version.md).**
|
||||
|
||||
## Synopsis
|
||||
|
||||
```no-highlight
|
||||
vcpkg version
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Displays the version of the vcpkg executable.
|
||||
|
||||
## Example
|
||||
```no-highlight
|
||||
$ vcpkg version
|
||||
vcpkg package management program version 2022-09-01-dfb82802c8cc562ce3b665a904a65b22314de724
|
||||
|
||||
See LICENSE.txt for license information.
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
All vcpkg commands support a set of [common options](common-options.md).
|
||||
@ -1,36 +0,0 @@
|
||||
## How to: Add an explicit usage file to a port.
|
||||
|
||||
`vcpkg` generates usage text for customers who install particular ports, if the customer names that
|
||||
specific port. For example:
|
||||
|
||||
```
|
||||
$> vcpkg install zlib:x64-windows
|
||||
Computing installation plan...
|
||||
The following packages will be built and installed:
|
||||
* vcpkg-cmake[core]:x64-windows -> 2022-09-26
|
||||
zlib[core]:x64-windows -> 1.2.12#2
|
||||
Additional packages (*) will be modified to complete this operation.
|
||||
Detecting compiler hash for triplet x64-windows...
|
||||
Restored 2 package(s) from C:\Users\bion\AppData\Local\vcpkg\archives in 77.46 ms. Use --debug to see more details.
|
||||
Installing 1/2 vcpkg-cmake:x64-windows...
|
||||
Elapsed time to handle vcpkg-cmake:x64-windows: 10.32 ms
|
||||
Installing 2/2 zlib:x64-windows...
|
||||
Elapsed time to handle zlib:x64-windows: 20.89 ms
|
||||
Total elapsed time: 2.747 s
|
||||
|
||||
The package zlib is compatible with built-in CMake targets:
|
||||
|
||||
find_package(ZLIB REQUIRED)
|
||||
target_link_libraries(main PRIVATE ZLIB::ZLIB)
|
||||
```
|
||||
|
||||
If there is no explicit usage installed by the port, vcpkg will generate default usage text by
|
||||
inspecting with the port installs. If the default usage text is suboptimal, it can be overridden by
|
||||
a port installing a file named "usage" in its "share" directory.
|
||||
|
||||
1. Create a file named `usage` in the port directory, with the content you want displayed.
|
||||
2. To `portfile.cmake`, add
|
||||
```
|
||||
file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
|
||||
```
|
||||
3. Update the port-version and rerun `vcpkg x-add-version` if necessary.
|
||||
@ -1,182 +0,0 @@
|
||||
## Installing and Using Packages Example: SQLite
|
||||
|
||||
_Note: this old example uses Classic Mode, but most developers will be happier with Manifest Mode. See [Manifest Mode: CMake Example](manifest-mode-cmake.md) for an example of converting to Manifest Mode._
|
||||
|
||||
- [Step 1: Install](#install)
|
||||
- [Step 2: Use](#use)
|
||||
- [VS/MSBuild Project (User-wide integration)](#msbuild)
|
||||
- [CMake (Toolchain file)](#cmake)
|
||||
- [Other integration options](../users/buildsystems/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
|
||||
@ -1,200 +0,0 @@
|
||||
# Manifest Mode: CMake Example
|
||||
|
||||
We would like to add [vcpkg manifest support](../users/manifests.md) 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_compile_features(fibo PRIVATE cxx_std_17)
|
||||
|
||||
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::views;
|
||||
|
||||
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!
|
||||
@ -1,191 +0,0 @@
|
||||
# Pin old Boost versions
|
||||
This document will teach you how to set versions of meta-packages like `boost` or `qt5`.
|
||||
|
||||
**What is a meta-package?**
|
||||
In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform or to conveniently install/uninstall a catalog of related packages (Boost and Qt).
|
||||
|
||||
In the case of Boost, it is unlikely that a user requires all of the 140+ Boost libraries in their project. For the sake of convenience, vcpkg splits Boost into multiple sub-packages broken down to individual libraries. By doing so, users can limit the subset of Boost libraries that they depend on.
|
||||
|
||||
If a user wants to install all of the Boost libraries available in vcpkg, they can do so by installing the `boost` meta-package.
|
||||
|
||||
Due to the nature of meta-packages, some unexpected issues arise when trying to use them with versioning. If a user writes the following manifest file:
|
||||
|
||||
`vcpkg.json`
|
||||
```json
|
||||
{
|
||||
"name": "demo",
|
||||
"version": "1.0.0",
|
||||
"builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4",
|
||||
"dependencies": [ "boost-tuple" ],
|
||||
"overrides": [
|
||||
{ "name": "boost", "version": "1.72.0" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The resulting installation plan is:
|
||||
```
|
||||
The following packages will be built and installed:
|
||||
boost-assert[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-assert\3393715b4ebe30fe1c3b68acf7f84363e611f156
|
||||
boost-compatibility[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-compatibility\cda5675366367789659c59aca65fc57d03c51deb
|
||||
boost-config[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-config\ca82ca1b9c1739c91f3cf42c68cee56c896ae6bd
|
||||
boost-container-hash[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-container-hash\bf472c23d29c3d80b562c43471eb92cea998f372
|
||||
boost-core[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-core\20a19f6ece37686a02eed33e1f58add8b7a2582a
|
||||
boost-detail[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-detail\96744251f025f9b3c856a275dfc338031876777b
|
||||
boost-integer[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-integer\de70ce0d1500df1eda3496c4f98f42f5db256b4a
|
||||
boost-io[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-io\7bf3407372f8fc2a99321d24a0e952d44fe25bf3
|
||||
boost-preprocessor[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-preprocessor\8d78b8ba2e9f54cb00137115ddd2ffec1c63c149
|
||||
boost-static-assert[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-static-assert\2a41c4703c7122de25b1c60510c43edc9371f63d
|
||||
boost-throw-exception[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-throw-exception\b13bdf32a20786a0165cc20205ef63765cac0627
|
||||
boost-tuple[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-tuple\22e3d000a178a88992c430d8ae8a0244c7dea674
|
||||
boost-type-traits[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-type-traits\8829793f6c6c913257314caa317599f8d253a5ca
|
||||
boost-uninstall[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-uninstall\08933bad27b6d41caef0940c31e2069ecb6a079c
|
||||
boost-utility[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-utility\47572946bf6a63c731b9c4142eecb8bef3d3b270
|
||||
boost-vcpkg-helpers[core]:x64-windows -> 7#2 -- D:\vcpkg\buildtrees\versioning\versions\boost-vcpkg-helpers\2a21e5ab45d1ce41c185faf85dff0670ea6def1d
|
||||
```
|
||||
|
||||
It is reasonable to expect that overriding `boost` to version 1.72.0 results in all Boost packages being pinned to version 1.72.0. **However, vcpkg does not treat the `boost` meta-package any differently that any other port.** In other words, vcpkg has no notion that `boost` is related to all the other `boost-*` libraries, other than it depends on all of them. For this reason, all the other boost packages are installed at version 1.75.0, which is the baseline version.
|
||||
|
||||
Below, we describe two methods to pin down Boost versions effectively.
|
||||
|
||||
## Method 1: Pin specific packages
|
||||
Use `"overrides"` to force specific versions in a package-by-package basis.
|
||||
|
||||
`vcpkg.json`
|
||||
```json
|
||||
{
|
||||
"name": "demo",
|
||||
"version": "1.0.0",
|
||||
"builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4",
|
||||
"dependencies": [ "boost-tuple" ],
|
||||
"overrides": [
|
||||
{ "name": "boost-core", "version": "1.72" },
|
||||
{ "name": "boost-integer", "version": "1.72" },
|
||||
{ "name": "boost-io", "version": "1.72" },
|
||||
{ "name": "boost-tuple", "version": "1.72" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This method allows you to quickly set the specific versions you want, but you will need to write an override for each package. Boost libraries are also heavily interdependent, which means that you may end up writing a lot of override lines.
|
||||
|
||||
The second method makes it easy to pin the entire Boost collection and end up with a very simple manifest file.
|
||||
|
||||
## Method 2: Modify baseline
|
||||
An easy way to set the version for the entirety of boost is to use the `"builtin-baseline"` property.
|
||||
|
||||
As of right now, it is only possible to go back to Boost version `1.75.0` using a baseline, since that was the contemporary Boost version when the versioning feature was merged. **But, it is possible to modify the baseline to whatever you like and use that instead.**
|
||||
|
||||
### Step 1: Create a new branch
|
||||
As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a git commit in the microsoft/vcpkg repository's history. If you want to customize the baseline and have control over the vcpkg instance, you can create a new commit with said custom baseline.
|
||||
|
||||
Let's start by creating a new branch to hold our modified baseline.
|
||||
|
||||
In the directory containing your clone of the vcpkg Git repository run:
|
||||
|
||||
```
|
||||
git checkout -b custom-boost-baseline
|
||||
```
|
||||
|
||||
This will create a new branch named `custom-boost-baseline` and check it out immediately.
|
||||
|
||||
### Step 2: Modify the baseline
|
||||
The next step is to modify the baseline file, open the file in your editor of choice and modify the entries for the Boost libraries.
|
||||
|
||||
Change the `"baseline"` version to your desired version.
|
||||
_NOTE: Remember to also set the port versions to 0 (or your desired version)._
|
||||
|
||||
`${vcpkg-root}/versions/baseline.json`
|
||||
```diff
|
||||
...
|
||||
"boost": {
|
||||
- "baseline": "1.75.0",
|
||||
+ "baseline": "1.72.0",
|
||||
"port-version": 0
|
||||
},
|
||||
"boost-accumulators": {
|
||||
- "baseline": "1.75.0",
|
||||
- "port-version": 1
|
||||
+ "baseline": "1.72.0",
|
||||
+ "port-version": 0
|
||||
},
|
||||
"boost-algorithm": {
|
||||
- "baseline": "1.75.0",
|
||||
+ "baseline": "1.72.0",
|
||||
"port-version": 0
|
||||
},
|
||||
"boost-align": {
|
||||
- "baseline": "1.75.0",
|
||||
+ "baseline": "1.72.0",
|
||||
"port-version": 0
|
||||
},
|
||||
...
|
||||
"boost-uninstall: {
|
||||
"baseline": "1.75.0",
|
||||
"port-version": 0
|
||||
},
|
||||
...
|
||||
```
|
||||
|
||||
Some `boost-` packages are helpers used by vcpkg and are not part of Boost. For example, `"boost-uninstall"` is a vcpkg helper to conveniently uninstall all Boost libraries, but it didn't exist for Boost version `1.72.0`, in this case it is fine to leave it at `1.75.0` to avoid baseline errors (since all versions in `baseline.json` must have existed).
|
||||
|
||||
### Step 3: Commit your changes
|
||||
After saving your modified file, run these commands to commit your changes:
|
||||
|
||||
```
|
||||
git add versions/baseline.json
|
||||
git commit -m "Baseline Boost 1.72.0"
|
||||
```
|
||||
|
||||
You can set the commit message to whatever you want, just make it useful for you.
|
||||
|
||||
### Step 4: Get your baseline commit SHA
|
||||
Once all your changes are ready, you can get the commit SHA by running:
|
||||
```
|
||||
git rev-parse HEAD
|
||||
```
|
||||
|
||||
The output of that command will be the commit SHA you need to put as the `"builtin-baseline"` in your project's manifest file. Copy the 40-hex digits and save them to use later in your manifest file.
|
||||
|
||||
### Step 5: (Optional) Go back to the main repository branch
|
||||
Once your changes have been committed locally, you can refer to the commit SHA regardless of the repository branch you're working on. So, let's go back to the main vcpkg repository branch.
|
||||
|
||||
```
|
||||
git checkout master
|
||||
```
|
||||
|
||||
### Step 6: Create your manifest file with your custom baseline
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "demo",
|
||||
"version": "1.0.0",
|
||||
"builtin-baseline": "9b5cf7c3d9376ddf43429671282972ec4f99aa85",
|
||||
"dependencies": [ "boost-tuple" ]
|
||||
}
|
||||
```
|
||||
|
||||
In this example, commit SHA `9b5cf7c3d9376ddf43429671282972ec4f99aa85` is the commit ID with the modified baseline. Even when a different branch (`master` in this case) is checked out, Git is able to find the commit as long as the branch with the modified baseline exists (the `custom-boost-baseline` branch we created in step 1).
|
||||
|
||||
We run `vcpkg install` in the directory containing our manifest file and the output looks like this:
|
||||
|
||||
```
|
||||
The following packages will be built and installed:
|
||||
boost-assert[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-assert\6754398591f48435b28014ca0d60e5375a4c04d1
|
||||
boost-compatibility[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-compatibility\9893ff3c554575bc712df4108a949e07b269f401
|
||||
boost-config[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-config\de2784767046b06ec31eb718f10df512e51f2aad
|
||||
boost-container-hash[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-container-hash\cc19fb0154bbef188f309f49b2664ec7623b96b6
|
||||
boost-core[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-core\0eb5e20df9e267e9eca325be946f52ceb8a60229
|
||||
boost-detail[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-detail\759d7c6a3f9dbaed0b0c69fa0bb764f7606bb02d
|
||||
boost-integer[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-integer\173956c61a26e83b0f8b58b0baf60f06aeee637c
|
||||
boost-preprocessor[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-preprocessor\86eb3938b7875f124feb845331dbe84cbab5d1c6
|
||||
boost-static-assert[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-static-assert\e82d8f7f3ee07e927dc374f5a08ed6d6f4ef81f4
|
||||
boost-throw-exception[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-throw-exception\64df295f7df41de4fcb219834889b126b5020def
|
||||
boost-tuple[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-tuple\b3e1b01ffce6e367e4fed0a5538a8546abacb6b2
|
||||
boost-type-traits[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-type-traits\5e44ec657660eccf4d3b2710b092dd238e1e7a2d
|
||||
boost-uninstall[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-uninstall\08933bad27b6d41caef0940c31e2069ecb6a079c
|
||||
boost-utility[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-utility\7d721b2458d5d595ac341eb54883274f38a4b8c2
|
||||
boost-vcpkg-helpers[core]:x64-windows -> 7#2 -- D:\vcpkg\buildtrees\versioning\versions\boost-vcpkg-helpers\2a21e5ab45d1ce41c185faf85dff0670ea6def1d
|
||||
```
|
||||
|
||||
Notice how simple our manifest file has become, instead of having a multitude of `"overrides"` you can pin down all Boost packages just by setting the `"builtin-baseline"` to be your modified baseline commit SHA.
|
||||
@ -1,126 +0,0 @@
|
||||
# Using Overlay Triplets
|
||||
|
||||
## Building dynamic libraries on Linux
|
||||
|
||||
Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS.
|
||||
|
||||
This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux.
|
||||
|
||||
### 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
|
||||
```
|
||||
@ -1,54 +0,0 @@
|
||||
## 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 file (you can get this easily by setting it to `0`, 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_cmake_configure(SOURCE_PATH ${SOURCE_PATH})
|
||||
vcpkg_cmake_install()
|
||||
file(INSTALL "${SOURCE_PATH}/COPYING" DESTINATION "${CURRENT_PACKAGES_DIR}/share/libogg" RENAME copyright)
|
||||
```
|
||||
|
||||
Check the documentation for [`vcpkg_cmake_configure`](../maintainers/vcpkg_cmake_configure.md) and [`vcpkg_cmake_install`](../maintainers/vcpkg_cmake_install.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
|
||||
- mpg123
|
||||
- Non-CMake, custom buildsystem
|
||||
- openssl
|
||||
- ffmpeg
|
||||
@ -1,76 +0,0 @@
|
||||
## Packaging `.zip` Files 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.12.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`.
|
||||
|
||||
*`zlib1212.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.12.tar.gz zlib1212.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.12",
|
||||
"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/zlib1212.tar.gz
|
||||
-- Cleaning sources at C:/src/vcpkg/buildtrees/zlib2/src/1.2.12-deec42f53b.clean. Pass --editable to vcpkg to reuse sources.
|
||||
-- Extracting source C:/src/vcpkg/downloads/zlib1212.tar.gz
|
||||
-- Applying patch cmake_dont_build_more_than_needed.patch
|
||||
-- Using source at C:/src/vcpkg/buildtrees/zlib2/src/1.2.12-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
|
||||
- mpg123
|
||||
- Non-CMake, custom buildsystem
|
||||
- openssl
|
||||
- ffmpeg
|
||||
@ -1,220 +0,0 @@
|
||||
## 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-xxx-out.log and build-xxx-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_cmake_configure(
|
||||
...
|
||||
```
|
||||
|
||||
### 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 +0,0 @@
|
||||
build
|
||||
@ -1,5 +0,0 @@
|
||||
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)
|
||||
@ -1,54 +0,0 @@
|
||||
#
|
||||
# 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
|
||||
@ -1,8 +0,0 @@
|
||||
#include <json/json.h>
|
||||
|
||||
int answer()
|
||||
{
|
||||
Json::Value meaning_of;
|
||||
meaning_of["everything"] = 42;
|
||||
return meaning_of["everything"].asInt();
|
||||
}
|
||||
@ -1 +0,0 @@
|
||||
build
|
||||
@ -1,13 +0,0 @@
|
||||
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::JsonCpp)
|
||||
@ -1,99 +0,0 @@
|
||||
#
|
||||
# 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 successfully 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)
|
||||
@ -1,37 +0,0 @@
|
||||
# 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
|
||||
@ -1,8 +0,0 @@
|
||||
#include <json/json.h>
|
||||
|
||||
int answer()
|
||||
{
|
||||
Json::Value meaning_of;
|
||||
meaning_of["everything"] = 42;
|
||||
return meaning_of["everything"].asInt();
|
||||
}
|
||||
@ -1,249 +0,0 @@
|
||||
# Getting started with versioning
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/examples/versioning.getting-started.md).**
|
||||
|
||||
Vcpkg lets you take control of which version of packages to install in your projects using manifests.
|
||||
|
||||
## Using versions with manifests
|
||||
|
||||
Let's start with creating a simple CMake project that depends on `fmt` and `zlib`.
|
||||
|
||||
Create a folder with the following files:
|
||||
|
||||
**vcpkg.json**
|
||||
```json
|
||||
{
|
||||
"name": "versions-test",
|
||||
"version": "1.0.0",
|
||||
"dependencies": [
|
||||
{
|
||||
"name": "fmt",
|
||||
"version>=": "7.1.3#1"
|
||||
},
|
||||
"zlib"
|
||||
],
|
||||
"builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc"
|
||||
}
|
||||
```
|
||||
|
||||
**main.cpp**
|
||||
```c++
|
||||
#include <fmt/core.h>
|
||||
#include <zlib.h>
|
||||
|
||||
int main()
|
||||
{
|
||||
fmt::print("fmt version is {}\n"
|
||||
"zlib version is {}\n",
|
||||
FMT_VERSION, ZLIB_VERSION);
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
**CMakeLists.txt**
|
||||
```CMake
|
||||
cmake_minimum_required(VERSION 3.18)
|
||||
|
||||
project(versionstest CXX)
|
||||
|
||||
add_executable(main main.cpp)
|
||||
|
||||
find_package(ZLIB REQUIRED)
|
||||
find_package(fmt CONFIG REQUIRED)
|
||||
target_link_libraries(main PRIVATE ZLIB::ZLIB fmt::fmt)
|
||||
```
|
||||
|
||||
And now we build and run our project with CMake:
|
||||
|
||||
1. Create the build directory for the project.
|
||||
```
|
||||
PS D:\versions-test> mkdir build
|
||||
PS D:\versions-test> cd build
|
||||
```
|
||||
|
||||
2. Configure CMake.
|
||||
```
|
||||
PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
|
||||
-- Running vcpkg install
|
||||
Detecting compiler hash for triplet x86-windows...
|
||||
The following packages will be built and installed:
|
||||
fmt[core]:x64-windows -> 7.1.3#1 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
|
||||
vcpkg-cmake[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake\51896aa8073adb5c8450daa423d03eedf0dfc61f
|
||||
vcpkg-cmake-config[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake-config\d255b3d566a8861dcc99a958240463e678528066
|
||||
zlib[core]:x64-windows -> 1.2.11#9 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
|
||||
...
|
||||
```
|
||||
|
||||
3. Build the project.
|
||||
```
|
||||
PS D:\versions-test\build> cmake --build .
|
||||
[2/2] Linking CXX executable main.exe
|
||||
```
|
||||
|
||||
4. Run it!
|
||||
```
|
||||
PS D:\versions-test\build> ./main.exe
|
||||
fmt version is 70103
|
||||
zlib version is 1.2.11
|
||||
```
|
||||
|
||||
Take a look at the output:
|
||||
|
||||
```
|
||||
fmt[core]:x86-windows -> 7.1.3#1 -- D:\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
|
||||
...
|
||||
zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
|
||||
```
|
||||
|
||||
Instead of using the portfiles in `ports/`, vcpkg is checking out the files for each version in `buildtrees/versioning/versions/`. The files in `ports/` are still used when running vcpkg in classic mode.
|
||||
|
||||
_NOTE: Output from vcpkg while configuring CMake is only available when using CMake version `3.18` or newer. If you're using an older CMake you can check the `vcpkg-manifest-install.log` file in your build directory instead._
|
||||
|
||||
Read our [manifests announcement blog post](https://devblogs.microsoft.com/cppblog/vcpkg-accelerate-your-team-development-environment-with-binary-caching-and-manifests/#using-manifests-with-msbuild-projects) to learn how to use manifests with MSBuild.
|
||||
|
||||
### Manifest changes
|
||||
If you have used manifests before you will notice that there are some new JSON properties. Let's review these changes:
|
||||
|
||||
#### **`version`**
|
||||
```json
|
||||
{
|
||||
"name": "versions-test",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
This is your project's version declaration. Previously, you could only declare versions for your projects using the `version-string` property. Now that versioning has come around, vcpkg is aware of some new versioning schemes.
|
||||
|
||||
Version scheme | Description
|
||||
---------------- | ---------------
|
||||
`version` | Dot-separated numerics: `1.0.0.5`.
|
||||
`version-semver` | Compliant [semantic versions](https://semver.org): `1.2.0` and `1.2.0-rc`.
|
||||
`version-date` | Dates in `YYYY-MM-DD` format: `2021-01-01`
|
||||
`version-string` | Arbitrary strings: `vista`, `candy`.
|
||||
|
||||
#### **`version>=`**
|
||||
```json
|
||||
{
|
||||
"dependencies": [
|
||||
{ "name": "fmt", "version>=": "7.1.3" },
|
||||
"zlib"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3#1` of `fmt`.
|
||||
|
||||
Vcpkg is allowed to upgrade this constraint if a transitive dependency requires a newer version. For example, if `zlib` were to declare a dependency on `fmt` version `7.1.4` then vcpkg would install `7.1.4` instead.
|
||||
|
||||
Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3#1` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest.
|
||||
|
||||
If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline.
|
||||
|
||||
#### **`builtin-baseline`**
|
||||
|
||||
```json
|
||||
{ "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" }
|
||||
```
|
||||
|
||||
This field declares the versioning baseline for all ports. Setting a baseline is required to enable versioning, otherwise you will get the current versions on the ports directory. You can run 'git rev-parse HEAD' to get the current commit of vcpkg and set it as the builtin-baseline. See the [`builtin-baseline` documentation](../users/manifests.md#builtin-baseline) for more information.
|
||||
|
||||
In our example, you can notice that we do not declare a version constraint for `zlib`; instead, the version is taken from the baseline. Internally, vcpkg will look in commit `3426db05b996481ca31e95fff3734cf23e0f51bc` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`).
|
||||
|
||||
During version resolution, baseline versions are treated as minimum version constraints. If you declare an explicit constraint that is lower than a baseline version, the explicit constraint will be upgraded to the baseline version.
|
||||
|
||||
For example, if we modified our dependencies like this:
|
||||
```json
|
||||
{ "dependencies": [
|
||||
{
|
||||
"name": "fmt",
|
||||
"version>=": "7.1.3#1"
|
||||
},
|
||||
{
|
||||
"name": "zlib",
|
||||
"version>=": "1.2.11#7"
|
||||
}
|
||||
] }
|
||||
```
|
||||
|
||||
_NOTE: The value `1.2.11#7` represents version `1.2.11`, port version `7`._
|
||||
|
||||
Since the baseline introduces a minimum version constraint for `zlib` at `1.2.11#9` and a higher version does satisfy the minimum version constraint for `1.2.11#7`, vcpkg is allowed to upgrade it.
|
||||
|
||||
Baselines are also a convenient mechanism to upgrade multiple versions at a time, for example, if you wanted to depend on multiple `boost` libraries, it is more convenient to set the `baseline` once than declaring a version constraint on each package.
|
||||
|
||||
But what if you want to pin a version older than the baseline?
|
||||
|
||||
#### **`overrides`**
|
||||
|
||||
Since baselines establish a version floor for all packages and explicit constraints get upgraded when they are lower than the baseline, we need another mechanism to downgrade versions past the baseline.
|
||||
|
||||
The mechanism vcpkg provides for that scenario is `overrides`. When an override is declared on a package, vcpkg will ignore all other version constraints either directly declared in the manifest or from transitive dependencies. In short, `overrides` will force vcpkg to use the exact version declared, period.
|
||||
|
||||
Let's modify our example once more, this time to force vcpkg to use version `6.0.0` of `fmt`.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "versions-test",
|
||||
"version": "1.0.0",
|
||||
"dependencies": [
|
||||
{
|
||||
"name": "fmt",
|
||||
"version>=": "7.1.3#1"
|
||||
},
|
||||
{
|
||||
"name": "zlib",
|
||||
"version>=": "1.2.11#7"
|
||||
}
|
||||
],
|
||||
"builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
|
||||
"overrides": [
|
||||
{
|
||||
"name": "fmt",
|
||||
"version": "6.0.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Rebuild our project:
|
||||
|
||||
```
|
||||
PS D:\versions-test\build> rm ./CMakeCache.txt
|
||||
PS D:\versions-test\build> rm -r ./vcpkg_installed
|
||||
PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
|
||||
-- Running vcpkg install
|
||||
Detecting compiler hash for triplet x86-windows...
|
||||
The following packages will be built and installed:
|
||||
fmt[core]:x86-windows -> 6.0.0 -- D:\vcpkg\buildtrees\versioning\versions\fmt\d99b6a35e1406ba6b6e09d719bebd086f83ed5f3
|
||||
zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
|
||||
...
|
||||
PS D:\versions-test\build> cmake --build .
|
||||
[2/2] Linking CXX executable main.exe
|
||||
```
|
||||
|
||||
And run it!
|
||||
```
|
||||
PS D:\versions-test\build> .\main.exe
|
||||
fmt version is 60000
|
||||
zlib version is 1.2.11
|
||||
```
|
||||
|
||||
Notice how the `fmt` is now at version `6.0.0` just like we wanted.
|
||||
|
||||
## Versions and custom ports
|
||||
|
||||
The last thing to discuss is how overlay ports interact with versioning resolution. The answer is: they don't.
|
||||
|
||||
Going into more detail, when you provide an overlay for a port, vcpkg will always use the overlay port without caring what version is contained in it. The reasons are two-fold: (1) it is consistent with the existing behavior of overlay ports of completely masking the existing port, and (2) overlay ports do not (and are not expected to) provide enough information to power vcpkg's versioning feature.
|
||||
|
||||
If you want to have flexible port customization along with versioning, you should consider making your own custom registry. See our [registries specification for more details](../specifications/registries.md).
|
||||
|
||||
## Further reading
|
||||
|
||||
If you're interested in delving deeper into the details of how versioning works we recommended that you read the [original versioning specification](../specifications/versioning.md) and the [implementation details](../users/versioning.implementation-details.md).
|
||||
|
||||
See also:
|
||||
|
||||
* [Versioning docs](../users/versioning.md)
|
||||
* [Original specification](../specifications/versioning.md)
|
||||
* [Versioning implementation details](../users/versioning.implementation-details.md)
|
||||
@ -1,45 +0,0 @@
|
||||
# Authoring Script Ports
|
||||
|
||||
Ports can expose functions for other ports to consume during their build. For
|
||||
example, the `vcpkg-cmake` helper port exposes the `vcpkg_cmake_configure()`
|
||||
helper function. Packaging common scripts into a shared helper port makes
|
||||
maintenance easier because all consumers can be updated from a single place.
|
||||
Because the scripts come from a port, they can be versioned and depended upon
|
||||
via all the same mechanisms as any other port.
|
||||
|
||||
Script ports are implemented via the `vcpkg-port-config.cmake` extension
|
||||
mechanism. Before invoking the `portfile.cmake` of a port, vcpkg will first
|
||||
import `share/<port>/vcpkg-port-config.cmake` from each direct dependency. If
|
||||
the direct dependency is a host dependency, the import will be performed in the
|
||||
host installed tree (e.g.
|
||||
`${HOST_INSTALLED_DIR}/share/<port>/vcpkg-port-config.cmake`).
|
||||
|
||||
Only direct dependencies are considered for `vcpkg-port-config.cmake` inclusion.
|
||||
This means that if a script port relies on another script port, it must
|
||||
explicitly import the `vcpkg-port-config.cmake` of its dependency.
|
||||
|
||||
Script-to-script dependencies should not be marked as host. The dependency from
|
||||
a target port to a script should be marked host, which means that scripts should
|
||||
always already be natively compiling. By making script-to-script dependencies
|
||||
`"host": false`, it ensures that one script can depend upon the other being in
|
||||
its same install directory.
|
||||
|
||||
Ports should never provide a `vcpkg-port-config.cmake` file under a different
|
||||
`share/` subdirectory than the current port (`${PORT}`).
|
||||
|
||||
## Example
|
||||
|
||||
```cmake
|
||||
# ${CURRENT_PACKAGES_DIR}/share/my-helper/vcpkg-port-config.cmake
|
||||
|
||||
# This include guard ensures the file will be loaded only once
|
||||
include_guard(GLOBAL)
|
||||
|
||||
# This is how you could pull in a transitive dependency
|
||||
include("${CMAKE_CURRENT_LIST_DIR}/../my-other-helper/vcpkg-port-config.cmake")
|
||||
|
||||
# Finally, it is convention to put each public function into a separate file with a matching name
|
||||
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_01.cmake")
|
||||
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_02.cmake")
|
||||
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_03.cmake")
|
||||
```
|
||||
@ -1,166 +0,0 @@
|
||||
# CMake Guidelines
|
||||
|
||||
We expect that all CMake scripts that are either:
|
||||
|
||||
- In the `scripts/` directory, or
|
||||
- In a `vcpkg-*` port
|
||||
|
||||
should follow the guidelines laid out in this document.
|
||||
Existing scripts may not follow these guidelines yet;
|
||||
it is expected that we will continue to update old scripts
|
||||
to fall in line with these guidelines.
|
||||
|
||||
These guidelines are intended to create stability in our scripts.
|
||||
We hope that they will make both forwards and backwards compatibility easier.
|
||||
|
||||
## The Guidelines
|
||||
|
||||
- Except for out-parameters, we always use `cmake_parse_arguments()`
|
||||
rather than function parameters or referring to `${ARG<N>}`.
|
||||
- This doesn't necessarily need to be followed for "script-local helper functions"
|
||||
- In this case, positional parameters should be put in the function
|
||||
declaration (rather than using `${ARG<N>}`),
|
||||
and should be named according to local rules (i.e. `snake_case`).
|
||||
- Exception: positional parameters that are optional should be
|
||||
given a name via `set(argument_name "${ARG<N>}")`, after checking `ARGC`.
|
||||
- Out-parameters should be the first parameter to a function. Example:
|
||||
```cmake
|
||||
function(format out_var)
|
||||
cmake_parse_arguments(PARSE_ARGV 1 "arg" ...)
|
||||
# ... set(buffer "output")
|
||||
set("${out_var}" "${buffer}" PARENT_SCOPE)
|
||||
endfunction()
|
||||
```
|
||||
- There are no unparsed or unused arguments.
|
||||
Always check for `ARGN` or `arg_UNPARSED_ARGUMENTS`.
|
||||
`FATAL_ERROR` when possible, `WARNING` if necessary for backwards compatibility.
|
||||
- All `cmake_parse_arguments` must use `PARSE_ARGV`.
|
||||
- All `foreach` loops must use `IN LISTS`, `IN ITEMS`, or `RANGE`.
|
||||
- The variables `${ARGV}` and `${ARGN}` are unreferenced,
|
||||
except in helpful messages to the user.
|
||||
- (i.e., `message(FATAL_ERROR "blah was passed extra arguments: ${ARGN}")`)
|
||||
- We always use functions, not macros or top level code.
|
||||
- Exception: "script-local helper macros". It is sometimes helpful to define a small macro.
|
||||
This should be done sparingly, and functions should be preferred.
|
||||
- Exception: `vcpkg.cmake`'s `find_package`.
|
||||
- Scripts in the scripts tree should not be expected to need observable changes
|
||||
as part of normal operation.
|
||||
- Example violation: `vcpkg_acquire_msys()` has hard-coded packages and versions
|
||||
that need updating over time due to the MSYS project dropping old packages.
|
||||
- Example exception: `vcpkg_from_sourceforge()` has a list of mirrors which
|
||||
needs maintenance, but does not have an observable behavior impact on the callers.
|
||||
- Rules for quoting: there are three kinds of arguments in CMake -
|
||||
unquoted (`foo(BAR)`), quoted (`foo("BAR")`), and bracketed (`foo([[BAR]])`).
|
||||
Follow these rules to quote correctly:
|
||||
- If an argument contains a variable expansion `${...}`,
|
||||
it must be quoted.
|
||||
- Exception: a "splat" variable expansion, when one variable will be
|
||||
passed to a function as multiple arguments. In this case, the argument
|
||||
should simply be `${foo}`:
|
||||
```cmake
|
||||
vcpkg_list(SET working_directory)
|
||||
if(DEFINED "arg_WORKING_DIRECTORY")
|
||||
vcpkg_list(SET working_directory WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")
|
||||
endif()
|
||||
# calls do_the_thing() if NOT DEFINED arg_WORKING_DIRECTORY,
|
||||
# else calls do_the_thing(WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")
|
||||
do_the_thing(${working_directory})
|
||||
```
|
||||
- Otherwise, if the argument contains any escape sequences that are not
|
||||
`\\`, `\"`, or `\$`, that argument must be a quoted argument.
|
||||
- For example: `"foo\nbar"` must be quoted.
|
||||
- Otherwise, if the argument contains a `\`, a `"`, or a `$`,
|
||||
that argument should be bracketed.
|
||||
- Example:
|
||||
```cmake
|
||||
set(x [[foo\bar]])
|
||||
set(y [=[foo([[bar\baz]])]=])
|
||||
```
|
||||
- Otherwise, if the argument contains characters that are
|
||||
not alphanumeric or `_`, that argument should be quoted.
|
||||
- Otherwise, the argument should be unquoted.
|
||||
- Exception: arguments to `if()` of type `<variable|string>` should always be quoted:
|
||||
- Both arguments to the comparison operators -
|
||||
`EQUAL`, `STREQUAL`, `VERSION_LESS`, etc.
|
||||
- The first argument to `MATCHES` and `IN_LIST`
|
||||
- Example:
|
||||
```cmake
|
||||
if("${FOO}" STREQUAL "BAR") # ...
|
||||
if("${BAZ}" EQUAL "0") # ...
|
||||
if("FOO" IN_LIST list_variable) # ...
|
||||
if("${bar}" MATCHES [[a[bcd]+\.[bcd]+]]) # ...
|
||||
```
|
||||
- For single expressions and for other types of predicates that do not
|
||||
take `<variable|string>`, use the normal rules.
|
||||
- There are no "pointer" or "in-out" parameters
|
||||
(where a user passes a variable name rather than the contents),
|
||||
except for simple out-parameters.
|
||||
- Variables are not assumed to be empty.
|
||||
If the variable is intended to be used locally,
|
||||
it must be explicitly initialized to empty with `set(foo "")` if it is a string variable,
|
||||
and `vcpkg_list(SET foo)` if it is a list variable.
|
||||
- `set(var)` should not be used. Use `unset(var)` to unset a variable,
|
||||
`set(var "")` to set it to the empty string,
|
||||
and `vcpkg_list(SET var)` to set it to the empty list.
|
||||
_Note: the empty string and the empty list are the same value;_
|
||||
_this is a notational difference rather than a difference in result_
|
||||
- All variables expected to be inherited from the parent scope across an API boundary
|
||||
(i.e. not a file-local function) should be documented.
|
||||
Note that all variables mentioned in triplets.md are considered documented.
|
||||
- Out parameters are only set in `PARENT_SCOPE` and are never read.
|
||||
See also the helper `z_vcpkg_forward_output_variable()` to forward out parameters through a function scope.
|
||||
- `CACHE` variables are used only for global variables which are shared internally among strongly coupled
|
||||
functions and for internal state within a single function to avoid duplicating work.
|
||||
These should be used extremely sparingly and should use the `Z_VCPKG_` prefix to avoid
|
||||
colliding with any local variables that would be defined by any other code.
|
||||
- Examples:
|
||||
- `vcpkg_cmake_configure`'s `Z_VCPKG_CMAKE_GENERATOR`
|
||||
- `z_vcpkg_get_cmake_vars`'s `Z_VCPKG_GET_CMAKE_VARS_FILE`
|
||||
- `include()`s are only allowed in `ports.cmake` or `vcpkg-port-config.cmake`.
|
||||
- `foreach(RANGE)`'s arguments _must always be_ natural numbers,
|
||||
and `<start>` _must always be_ less than or equal to `<stop>`.
|
||||
- This must be checked by something like:
|
||||
```cmake
|
||||
if("${start}" LESS_EQUAL "${end}")
|
||||
foreach(RANGE "${start}" "${end}")
|
||||
...
|
||||
endforeach()
|
||||
endif()
|
||||
```
|
||||
- All port-based scripts must use `include_guard(GLOBAL)`
|
||||
to avoid being included multiple times.
|
||||
|
||||
### CMake Versions to Require
|
||||
|
||||
- All CMake scripts, except for `vcpkg.cmake`,
|
||||
may assume the version of CMake that is present in the
|
||||
`cmake_minimum_required` of `ports.cmake`.
|
||||
- This `cmake_minimum_required` should be bumped every time a new version
|
||||
of CMake is added to `vcpkgTools.xml`, as should the
|
||||
`cmake_minimum_required` in all of the helper `CMakeLists.txt` files.
|
||||
- `vcpkg.cmake` must assume a version of CMake back to 3.7.2 in general
|
||||
- Specific functions and options may assume a greater CMake version;
|
||||
if they do, make sure to comment that function or option
|
||||
with the required CMake version.
|
||||
|
||||
|
||||
### Changing Existing Functions
|
||||
|
||||
- Never remove arguments in non-internal functions;
|
||||
if they should no longer do anything, just take them as normal and warn on use.
|
||||
- Never add a new mandatory argument.
|
||||
|
||||
### Naming Variables
|
||||
|
||||
- `cmake_parse_arguments`: set prefix to `"arg"`
|
||||
- Local variables are named with `snake_case`
|
||||
- Internal global variable names are prefixed with `Z_VCPKG_`.
|
||||
- External experimental global variable names are prefixed with `X_VCPKG_`.
|
||||
|
||||
- Internal functions are prefixed with `z_vcpkg_`
|
||||
- Functions which are internal to a single function (i.e., helper functions)
|
||||
are named `[z_]<func>_<name>`, where `<func>` is the name of the function they are
|
||||
a helper to, and `<name>` is what the helper function does.
|
||||
- `z_` should be added to the front if `<func>` doesn't have a `z_`,
|
||||
but don't name a helper function `z_z_foo_bar`.
|
||||
- Public global variables are named `VCPKG_`.
|
||||
@ -1,205 +0,0 @@
|
||||
# CONTROL files
|
||||
|
||||
**CONTROL files are retained for backwards compatibility with earlier versions of vcpkg;
|
||||
all new features are added only to [vcpkg.json manifest files](manifest-files.md), and we recommend using vcpkg.json for any newly authored port.
|
||||
Use `./vcpkg format-manifest ports/<portname>/CONTROL` to convert an existing CONTROL file to a vcpkg.json file.**
|
||||
|
||||
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 specified 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:
|
||||
- `native` - `TARGET_TRIPLET` == `HOST_TRIPLET`
|
||||
- `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.
|
||||
@ -1,11 +0,0 @@
|
||||
# execute_process
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/execute_process.md).
|
||||
|
||||
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)
|
||||
@ -1,14 +0,0 @@
|
||||
# vcpkg_catalog_release_process
|
||||
|
||||
This document describes the acceptance criteria / process we use when doing a vcpkg release.
|
||||
|
||||
1. Generate a new GitHub Personal Access Token with repo permissions.
|
||||
2. Using the PAT, invoke $/scripts/Get-Changelog.ps1 `-StartDate (previous release date) -EndDate (Get-Date) -OutFile path/to/results.md`
|
||||
3. Create a new GitHub release in this repo.
|
||||
4. Submit a vcpkg.ci (full tree rebuild) run with the same SHA as that release.
|
||||
5. Use the "auto-generate release notes". Copy the "new contributors" and "full changelog" parts to the end of `path/to/results.md`.
|
||||
6. Change `## New Contributors` to `#### New Contributors`
|
||||
7. In `path/to/results.md`, update `LINK TO BUILD` with the most recent link to vcpkg.ci run.
|
||||
8. In `path/to/results.md`, fill out the tables for number of existing ports and successful ports.
|
||||
9. Replace the contents of the release notes with the contents of `path/to/results.md`
|
||||
10. After the full rebuild submission completes, update the link to the one for the exact SHA, the counts, and remove "(tentative)".
|
||||
@ -1,48 +0,0 @@
|
||||
# vcpkg_tool_release_process
|
||||
|
||||
This document describes the acceptance criteria / process we use when doing a vcpkg-tool update,
|
||||
such as https://github.com/microsoft/vcpkg/pull/23757
|
||||
|
||||
1. Verify that all tests etc. are passing in the vcpkg-tool repo's `main` branch, and that the
|
||||
contents therein are acceptable for release. (Steps after this will sign code there, so this
|
||||
review is responsible gating what has access to code signing.)
|
||||
2. Check that the changes there are in fact the changes that we want in that release. (Be aware,
|
||||
you are responsible for what is about to be signed with a Microsoft code signing certificate by
|
||||
proceeding)
|
||||
3. Submit a new full tree rebuild by microsoft.vcpkg.ci (
|
||||
https://dev.azure.com/vcpkg/public/_build?definitionId=29 as of this writing) and queue a new
|
||||
build with the vcpkg-tool SHA overridden to the one you wish to use. Example:
|
||||
https://dev.azure.com/vcpkg/public/_build/results?buildId=73664&view=results
|
||||
4. (Probably the next day) Check over the failures and ensure any differences with the most recent
|
||||
full rebuild using the previous tool version are understood.
|
||||
5. Submit a signed build from "vcpkg Signed Binaries (from GitHub)" (
|
||||
https://devdiv.visualstudio.com/DevDiv/_build?definitionId=17772&_a=summary as of this writing)
|
||||
6. The signed build will automatically create a draft GitHub release at
|
||||
https://github.com/microsoft/vcpkg-tool/releases . Erase the contents filled in there and press
|
||||
the "auto generate release notes" button. Manually remove any entries created by the automated
|
||||
localization tools which will start with `* LEGO: Pull request from juno/`.
|
||||
7. Publish that draft release as "pre-release".
|
||||
8. Clean up a machine for the following tests:
|
||||
* Delete `VCPKG_DOWNLOADS/artifacts` (which forces artifacts to be reacquired)
|
||||
* Delete `LOCALAPPDATA/vcpkg` (which forces registries to be reacquired)
|
||||
9. Smoke test the 'one liner' installer: (Where 2022-06-15 is replaced with the right release name)
|
||||
* Powershell:
|
||||
`iex (iwr https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init.ps1)`
|
||||
* Batch:
|
||||
`curl -L -o vcpkg-init.cmd https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init.ps1 && .\vcpkg-init.cmd`
|
||||
* Bash:
|
||||
`. <(curl https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init -L)`
|
||||
10. Test that embedded scenarios work for vcpkg-artifacts:
|
||||
Ensure that none of the following report errors:
|
||||
1. git clone https://github.com/some-example/blink/
|
||||
2. cd blink
|
||||
3. vcpkg activate
|
||||
4. idf.py set-target ESP32
|
||||
5. cd build
|
||||
6. ninja
|
||||
11. In the vcpkg repo, draft a PR which updates `bootstrap-vcpkg.sh` and `boostrap-vcpkg.ps1`
|
||||
with the new release date, and update SHAs as appropriate in the .sh script. (For example, see
|
||||
https://github.com/microsoft/vcpkg/pull/23757)
|
||||
12. Merge the tool update PR.
|
||||
13. Change the github release in vcpkg-tool from "prerelease" to "release". (This automatically
|
||||
updates the aka.ms links)
|
||||
@ -1,32 +0,0 @@
|
||||
# z_vcpkg_apply_patches
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
|
||||
|
||||
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
|
||||
|
||||
Apply a set of patches to a source tree.
|
||||
|
||||
```cmake
|
||||
z_vcpkg_apply_patches(
|
||||
SOURCE_PATH <path-to-source>
|
||||
[QUIET]
|
||||
PATCHES <patch>...
|
||||
)
|
||||
```
|
||||
|
||||
The `<path-to-source>` should be set to `${SOURCE_PATH}` by convention,
|
||||
and is the path to apply the patches in.
|
||||
|
||||
`z_vcpkg_apply_patches` will take the list of `<patch>`es,
|
||||
which are by default relative to the port directory,
|
||||
and apply them in order using `git apply`.
|
||||
Generally, these `<patch>`es take the form of `some.patch`
|
||||
to select patches in the port directory.
|
||||
One may also download patches and use `${VCPKG_DOWNLOADS}/path/to/some.patch`.
|
||||
|
||||
If `QUIET` is not passed, it is a fatal error for a patch to fail to apply;
|
||||
otherwise, if `QUIET` is passed, no message is printed.
|
||||
This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
|
||||
|
||||
## Source
|
||||
[scripts/cmake/z\_vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_apply_patches.cmake)
|
||||
@ -1,38 +0,0 @@
|
||||
# z_vcpkg_forward_output_variable
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
|
||||
|
||||
This macro helps with forwarding values from inner function calls,
|
||||
through a local function scope, into pointer out parameters.
|
||||
|
||||
```cmake
|
||||
z_vcpkg_forward_output_variable(ptr_to_parent_var var_to_forward)
|
||||
```
|
||||
|
||||
is equivalent to
|
||||
|
||||
```cmake
|
||||
if(DEFINED ptr_to_parent_var)
|
||||
if(DEFINED value_var)
|
||||
set("${ptr_to_parent_var}" "${value_var}" PARENT_SCOPE)
|
||||
else()
|
||||
unset("${ptr_to_parent_var}" PARENT_SCOPE)
|
||||
endif()
|
||||
endif()
|
||||
```
|
||||
|
||||
Take note that the first argument should be a local variable that has a value of the parent variable name.
|
||||
Most commonly, this local is the result of a pointer-out parameter to a function.
|
||||
If the variable in the first parameter is not defined, this function does nothing,
|
||||
simplifying functions with optional out parameters.
|
||||
Most commonly, this should be used in cases like:
|
||||
|
||||
```cmake
|
||||
function(my_function out_var)
|
||||
file(SHA512 "somefile.txt" local_var)
|
||||
z_vcpkg_forward_output_variable(out_var local_var)
|
||||
endfunction()
|
||||
```
|
||||
|
||||
## Source
|
||||
[scripts/cmake/z\_vcpkg\_forward\_output\_variable.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_forward_output_variable.cmake)
|
||||
@ -1,29 +0,0 @@
|
||||
# z_vcpkg_function_arguments
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
|
||||
|
||||
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
|
||||
Get a list of the arguments which were passed in.
|
||||
Unlike `ARGV`, which is simply the arguments joined with `;`,
|
||||
so that `(A B)` is not distinguishable from `("A;B")`,
|
||||
this macro gives `"A;B"` for the first argument list,
|
||||
and `"A\;B"` for the second.
|
||||
|
||||
```cmake
|
||||
z_vcpkg_function_arguments(<out-var> [<N>])
|
||||
```
|
||||
|
||||
`z_vcpkg_function_arguments` gets the arguments between `ARGV<N>` and the last argument.
|
||||
`<N>` defaults to `0`, so that all arguments are taken.
|
||||
|
||||
## Example:
|
||||
```cmake
|
||||
function(foo_replacement)
|
||||
z_vcpkg_function_arguments(ARGS)
|
||||
foo(${ARGS})
|
||||
...
|
||||
endfunction()
|
||||
```
|
||||
|
||||
## Source
|
||||
[scripts/cmake/z\_vcpkg\_function\_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)
|
||||
@ -1,36 +0,0 @@
|
||||
# z_vcpkg_get_cmake_vars
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
|
||||
|
||||
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
|
||||
Runs a cmake configure with a dummy project to extract certain cmake variables
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
z_vcpkg_get_cmake_vars(<out-var>)
|
||||
```
|
||||
|
||||
`z_vcpkg_get_cmake_vars(cmake_vars_file)` sets `<out-var>` to
|
||||
a path to a generated CMake file, with the detected `CMAKE_*` variables
|
||||
re-exported as `VCPKG_DETECTED_*`.
|
||||
|
||||
## Notes
|
||||
Avoid usage in portfiles.
|
||||
|
||||
All calls to `z_vcpkg_get_cmake_vars` will result in the same output file;
|
||||
the output file is not generated multiple times.
|
||||
|
||||
## Examples
|
||||
|
||||
* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```cmake
|
||||
z_vcpkg_get_cmake_vars(cmake_vars_file)
|
||||
include("${cmake_vars_file}")
|
||||
message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CXX_FLAGS}")
|
||||
```
|
||||
|
||||
## Source
|
||||
[scripts/cmake/z\_vcpkg\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_get_cmake_vars.cmake)
|
||||
@ -1,21 +0,0 @@
|
||||
# z_vcpkg_prettify_command_line
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
|
||||
|
||||
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
|
||||
Turn a command line into a formatted string.
|
||||
|
||||
```cmake
|
||||
z_vcpkg_prettify_command_line(<out-var> <argument>...)
|
||||
```
|
||||
|
||||
This command is for internal use, when printing out to a message.
|
||||
|
||||
## 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/z\_vcpkg\_prettify\_command\_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake)
|
||||
@ -1,16 +0,0 @@
|
||||
# z_vcpkg_setup_pkgconfig_path
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
|
||||
|
||||
`z_vcpkg_setup_pkgconfig_path` sets up environment variables to use `pkgconfig`, such as `PKG_CONFIG` and `PKG_CONFIG_PATH`.
|
||||
The original values are restored with `z_vcpkg_restore_pkgconfig_path`. `BASE_DIRS` indicates the base directories to find `.pc` files; typically `${CURRENT_INSTALLED_DIR}`, or `${CURRENT_INSTALLED_DIR}/debug`.
|
||||
|
||||
```cmake
|
||||
z_vcpkg_setup_pkgconfig_path(BASE_DIRS <"${CURRENT_INSTALLED_DIR}" ...>)
|
||||
# Build process that may transitively invoke pkgconfig
|
||||
z_vcpkg_restore_pkgconfig_path()
|
||||
```
|
||||
|
||||
|
||||
## Source
|
||||
[scripts/cmake/z\_vcpkg\_setup\_pkgconfig\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_setup_pkgconfig_path.cmake)
|
||||
@ -1,435 +0,0 @@
|
||||
# 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. We prefer when names are longer and/or
|
||||
unlikely to conflict with any future use of the same name. If the port refers
|
||||
to a library on GitHub, a good practice is to prefix the name with the organization
|
||||
if there is any chance of confusion.
|
||||
|
||||
### 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:
|
||||
|
||||
- [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md) should be replaced by the supported overload of [`vcpkg_extract_source_archive()`] (with `ARCHIVE`)
|
||||
- The deprecated overload of [`vcpkg_extract_source_archive()`] without `ARCHIVE` should be replaced by the supported overload with `ARCHIVE`.
|
||||
- `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
|
||||
- `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
|
||||
- `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md)
|
||||
- `vcpkg_configure_cmake` should be replaced by [`vcpkg_cmake_configure()`](vcpkg_cmake_configure.md) after removing `PREFER_NINJA` (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md))
|
||||
- `vcpkg_build_cmake` should be replaced by [`vcpkg_cmake_build()`](vcpkg_cmake_build.md) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md))
|
||||
- `vcpkg_install_cmake` should be replaced by [`vcpkg_cmake_install()`](vcpkg_cmake_install.md) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md))
|
||||
- `vcpkg_fixup_cmake_targets` should be replaced by [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md#vcpkg_cmake_config_fixup) (from port [`vcpkg-cmake-config`](ports/vcpkg-cmake-config.md#vcpkg-cmake-config))
|
||||
|
||||
Some of the replacement helper functions are in "tools ports" to allow consumers to pin their
|
||||
behavior at specific versions, to allow locking the behavior of the helpers at a particular
|
||||
version. Tools ports need to be added to your port's `"dependencies"`, like so:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "vcpkg-cmake",
|
||||
"host": true
|
||||
},
|
||||
{
|
||||
"name": "vcpkg-cmake-config",
|
||||
"host": true
|
||||
}
|
||||
```
|
||||
|
||||
[`vcpkg_extract_source_archive()`]: vcpkg_extract_source_archive.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.
|
||||
|
||||
### Ports must not be path dependent
|
||||
|
||||
Ports must not change their behavior based on which ports are already installed in a form that would change which contents that port installs. For example, given:
|
||||
|
||||
```
|
||||
> vcpkg install a
|
||||
> vcpkg install b
|
||||
> vcpkg remove a
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```
|
||||
> vcpkg install b
|
||||
```
|
||||
|
||||
the files installed by `b` must be the same, regardless of influence by the previous installation of `a`. This means that ports must not try to detect whether something is provided in the installed tree by another port before taking some action. A specific and common cause of such "path dependent" behavior is described below in "When defining features, explicitly control dependencies."
|
||||
|
||||
### Unique port attribution rule
|
||||
|
||||
In the entire vcpkg system, no two ports a user is expected to use concurrently may provide the same file. If a port tries to install a file already provided by another file, installation will fail. If a port wants to use an extremely common name for a header, for example, it should place those headers in a subdirectory rather than in `include`.
|
||||
|
||||
### Add CMake exports in an unofficial- namespace
|
||||
|
||||
A core design ideal of vcpkg is to not create "lock-in" for customers. In the build system, there should be no difference between depending on a library from the system, and depending on a library from vcpkg. To that end, we avoid adding CMake exports or targets to existing libraries with "the obvious name", to allow upstreams to add their own official CMake exports without conflicting with vcpkg.
|
||||
|
||||
To that end, any CMake configs that the port exports, which are not in the upstream library, should have `unofficial-` as a prefix. Any additional targets should be in the `unofficial::<port>::` namespace.
|
||||
|
||||
This means that the user should see:
|
||||
* `find_package(unofficial-<port> CONFIG)` as the way to get at the unique-to-vcpkg package
|
||||
* `unofficial::<port>::<target>` as an exported target from that port.
|
||||
|
||||
Examples:
|
||||
* [`brotli`](https://github.com/microsoft/vcpkg/blob/4f0a640e4c5b74166b759a862d7527c930eff32e/ports/brotli/install.patch) creates the `unofficial-brotli` package, producing target `unofficial::brotli::brotli`.
|
||||
|
||||
### Install copyright file
|
||||
|
||||
Each port has to provide a file named `copyright` in the folder `${CURRENT_PACKAGES_DIR}/share/${PORT}`.
|
||||
|
||||
Many ports are using this code to install a copyright file:
|
||||
|
||||
```cmake
|
||||
file(INSTALL "${SOURCE_PATH}LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
|
||||
```
|
||||
|
||||
This is discouraged in favour of [`vcpkg_install_copyright()`](vcpkg_install_copyright.md). New ports should use `vcpkg_install_copyright()` instead. However, it is still valid for existing ports to use something like the code above. You may replace this with `vcpkg_install_copyright` but you don't have to.
|
||||
|
||||
`vcpkg_install_copyright` also includes the functionallity to handle multiple copyright files. See its [documentation](vcpkg_install_copyright.md) for more info.
|
||||
|
||||
## Features
|
||||
|
||||
### Do not use features to implement alternatives
|
||||
|
||||
Features must be treated as additive functionality. If port[featureA] installs and port[featureB] installs, then port[featureA,featureB] must install. Moreover, if a second port depends on [featureA] and a third port depends on [featureB], installing both the second and third ports should have their dependencies satisfied.
|
||||
|
||||
Libraries in this situation must choose one of the available options as expressed in vcpkg, and users who want a different setting must use overlay ports at this time.
|
||||
|
||||
Existing examples we would not accept today retained for backwards compatibility:
|
||||
* `libgit2`, `libzip`, `open62541` all have features for selecting a TLS or crypto backend. Note that `curl` has different crypto backend options but allows selecting between them at runtime, meaning the above tenet is maintained.
|
||||
* `darknet` has `opencv2`, `opencv3`, features to control which version of opencv to use for its dependencies.
|
||||
|
||||
### A feature may engage preview or beta functionality
|
||||
|
||||
Notwithstanding the above, if there is a preview branch or similar where the preview functionality has a high probability of not disrupting the non-preview functionality (for example, no API removals), a feature is acceptable to model this setting.
|
||||
|
||||
Examples:
|
||||
* The Azure SDKs (of the form `azure-Xxx`) have a `public-preview` feature.
|
||||
* `imgui` has an `experimental-docking` feature which engages their preview docking branch which uses a merge commit attached to each of their public numbered releases.
|
||||
|
||||
### Default features should enable behaviors, not APIs
|
||||
|
||||
If a consumer is depending directly upon a library, they can list out any desired features easily (`library[feature1,feature2]`). However, if a consumer _does not know_ they are using a library, they cannot list out those features. If that hidden library is like `libarchive` where features are adding additional compression algorithms (and thus behaviors) to an existing generic interface, default features offer a way to ensure a reasonably functional transitive library is built even if the final consumer doesn't name it directly.
|
||||
|
||||
If the feature adds additional APIs (or executables, or library binaries) and doesn't modify the behavior of existing APIs, it should be left off by default. This is because any consumer which might want to use those APIs can easily require it via their direct reference.
|
||||
|
||||
If in doubt, do not mark a feature as default.
|
||||
|
||||
### Do not use features to control alternatives in published interfaces
|
||||
|
||||
If a consumer of a port depends on only the core functionality of that port, with high probability they must not be broken by turning on the feature. This is even more important when the alternative is not directly controlled by the consumer, but by compiler settings like `/std:c++17` / `-std=c++17`.
|
||||
|
||||
Existing examples we would not accept today retained for backwards compatibility:
|
||||
* `redis-plus-plus[cxx17]` controls a polyfill but does not bake the setting into the installed tree.
|
||||
* `ace[wchar]` changes all APIs to accept `const wchar_t*` rather than `const char*`.
|
||||
|
||||
### A feature may replace polyfills with aliases provided that replacement is baked into the installed tree
|
||||
|
||||
Notwithstanding the above, ports may remove polyfills with a feature, as long as:
|
||||
1. Turning on the feature changes the polyfills to aliases of the polyfilled entity
|
||||
2. The state of the polyfill is baked into the installed headers, such that ABI mismatch "impossible" runtime errors are unlikely
|
||||
3. It is possible for a consumer of the port to write code which works in both modes, for example by using a typedef which is either polyfilled or not
|
||||
|
||||
Example:
|
||||
* `abseil[cxx17]` changes `absl::string_view` to a replacement or `std::string_view`; the patch
|
||||
https://github.com/microsoft/vcpkg/blob/981e65ce0ac1f6c86e5a5ded7824db8780173c76/ports/abseil/fix-cxx-standard.patch implements the baking requirement
|
||||
|
||||
### Recommended solutions
|
||||
|
||||
If it's critical to expose the underlying alternatives, we recommend providing messages at build time to instruct the user on how to copy the port into a private overlay:
|
||||
```cmake
|
||||
set(USING_DOG 0)
|
||||
message(STATUS "This version of LibContosoFrobnicate uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")
|
||||
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")
|
||||
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")
|
||||
```
|
||||
|
||||
## 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_cmake_configure()` 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_cmake_configure(
|
||||
SOURCE_PATH ${SOURCE_PATH}
|
||||
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
|
||||
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
|
||||
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF)
|
||||
if ("zlib" IN_LIST FEATURES)
|
||||
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
|
||||
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON)
|
||||
endif()
|
||||
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH ${SOURCE_PATH}
|
||||
OPTIONS
|
||||
-DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
|
||||
-DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_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
|
||||
FEATURES
|
||||
"zlib" CMAKE_REQUIRE_FIND_PACKAGE_ZLIB
|
||||
INVERTED_FEATURES
|
||||
"zlib" CMAKE_DISABLE_FIND_PACKAGE_ZLIB
|
||||
)
|
||||
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH ${SOURCE_PATH}
|
||||
OPTIONS
|
||||
${FEATURE_OPTIONS}
|
||||
)
|
||||
```
|
||||
|
||||
Note that `ZLIB` in the above is case-sensitive. See the [CMAKE_DISABLE_FIND_PACKAGE_PackageName](https://cmake.org/cmake/help/v3.22/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) and [CMAKE_REQUIRE_FIND_PACKAGE_PackageName](https://cmake.org/cmake/help/v3.22/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.html) documnetation 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 [versioning documentation](../users/versioning.md#version-schemes) 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.
|
||||
|
||||
### Update the version files in `versions/` of any modified ports
|
||||
|
||||
Vcpkg uses a set of metadata files to power its versioning feature.
|
||||
These files are located in the following locations:
|
||||
* `${VCPKG_ROOT}/versions/baseline.json`, (this file is common to all ports) and
|
||||
* `${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json` (one per port).
|
||||
|
||||
For example, for `zlib` the relevant files are:
|
||||
* `${VCPKG_ROOT}/versions/baseline.json`
|
||||
* `${VCPKG_ROOT}/versions/z-/zlib.json`
|
||||
|
||||
We expect that each time you update a port, you also update its version files.
|
||||
|
||||
**The recommended method to update these files is to run the `x-add-version` command, e.g.:**
|
||||
|
||||
```
|
||||
vcpkg x-add-version zlib
|
||||
```
|
||||
|
||||
If you're updating multiple ports at the same time, instead you can run:
|
||||
|
||||
```
|
||||
vcpkg x-add-version --all
|
||||
```
|
||||
|
||||
To update the files for all modified ports at once.
|
||||
|
||||
_NOTE: These commands require you to have committed your changes to the ports before running them. The reason is that the Git SHA of the port directory is required in these version files. But don't worry, the `x-add-version` command will warn you if you have local changes that haven't been committed._
|
||||
|
||||
See our [versioning specification](../specifications/versioning.md) and [registries specification](../specifications/registries-2.md) to learn how vcpkg interacts with these files.
|
||||
|
||||
## 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.
|
||||
|
||||
Don't add patches if the port is outdated and updating the port to a newer released version would solve the same issue. vcpkg prefers updating ports over patching outdated versions unless the version bump breaks a considerable amount of dependent ports.
|
||||
|
||||
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 (aka "Scripting Commands"), portfiles run in "Script Mode", whereas `CMakeLists.txt` files run in "Project Mode". The most important difference between these two modes is that "Script Mode" does not have the concepts of "Toolchain", "Language" and "Target". Any behaviors, including scripting commands, which depend on these constructs (e.g. `CMAKE_CXX_COMPILER`, `CMAKE_EXECUTABLE_SUFFIX`, `CMAKE_SYSTEM_NAME`) 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 Project 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.
|
||||
@ -1,551 +0,0 @@
|
||||
# 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
|
||||
|
||||
Currently there are different fields for special versioning. Namely:
|
||||
|
||||
Manifest property | Versioning scheme
|
||||
------------------|------------------------------------
|
||||
`version` | For dot-separated numeric versions
|
||||
`version-semver` | For SemVer compliant versions
|
||||
`version-date` | For dates in the format YYYY-MM-DD
|
||||
`version-string` | For arbitrary strings
|
||||
|
||||
See https://github.com/microsoft/vcpkg/blob/master/docs/specifications/versioning.md#22-package-versions for more details.
|
||||
|
||||
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.
|
||||
|
||||
#### Example:
|
||||
```json
|
||||
{
|
||||
"homepage": "https://github.com/microsoft/vcpkg"
|
||||
}
|
||||
```
|
||||
|
||||
### `"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.
|
||||
|
||||
### `"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 specified 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 } ;
|
||||
required-whitespace = whitespace-character, { optional-whitespace } ;
|
||||
|
||||
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-list =
|
||||
| platform-expression { ",", optional-whitespace, platform-expression } ;
|
||||
|
||||
platform-expression =
|
||||
| platform-expression-not
|
||||
| platform-expression-and
|
||||
| platform-expression-or ;
|
||||
|
||||
platform-expression-identifier =
|
||||
| identifier-character, { identifier-character }, optional-whitespace ;
|
||||
|
||||
platform-expression-grouped =
|
||||
| "(", optional-whitespace, platform-expression, ")", optional-whitespace ;
|
||||
|
||||
platform-expression-simple =
|
||||
| platform-expression-identifier
|
||||
| platform-expression-grouped ;
|
||||
|
||||
platform-expression-unary-keyword-operand =
|
||||
| required-whitespace, platform-expression-simple
|
||||
| optional-whitespace, platform-expression-grouped ;
|
||||
|
||||
platform-expression-not =
|
||||
| platform-expression-simple
|
||||
| "!", optional-whitespace, platform-expression-simple
|
||||
| "not", platform-expression-unary-keyword-operand ;
|
||||
|
||||
platform-expression-binary-keyword-first-operand =
|
||||
| platform-expression-not, required-whitespace
|
||||
| platform-expression-grouped ;
|
||||
|
||||
platform-expression-binary-keyword-second-operand =
|
||||
| required-whitespace, platform-expression-not
|
||||
| platform-expression-grouped ;
|
||||
|
||||
platform-expression-and =
|
||||
| platform-expression-not, { "&", optional-whitespace, platform-expression-not }
|
||||
| platform-expression-binary-keyword-first-operand, { "and", platform-expression-binary-keyword-second-operand } ;
|
||||
|
||||
platform-expression-or =
|
||||
| platform-expression-not, { "|", optional-whitespace, platform-expression-not }
|
||||
| platform-expression-binary-keyword-first-operand, { "or", platform-expression-binary-keyword-second-operand } (* to allow for future extension *) ;
|
||||
|
||||
top-level-platform-expression = optional-whitespace, platform-expression-list ;
|
||||
```
|
||||
|
||||
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:
|
||||
- `native` - `TARGET_TRIPLET` == `HOST_TRIPLET`;
|
||||
useful for ports which depend on their own built binaries in their build.
|
||||
- `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"`
|
||||
- `mingw` - `VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
|
||||
- `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"`
|
||||
- `staticcrt` - `VCPKG_CRT_LINKAGE` == `"static"`
|
||||
|
||||
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)".
|
||||
|
||||
### `"license"`
|
||||
|
||||
The license of the port. This is an [SPDX license expression],
|
||||
or `null` for proprietary licenses and other licenses for which
|
||||
one should "just read the `copyright` file" (e.g., Qt).
|
||||
|
||||
[SPDX license expression]: https://spdx.dev/ids/#how
|
||||
|
||||
Additionally, you can find the list of [recognized license IDs]
|
||||
and [recognized license exception IDs] in Annex A of the SPDX specification.
|
||||
|
||||
[recognized license IDs]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-list/#a1-licenses-with-short-identifiers
|
||||
[recognized license exception IDs]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-list/#a2-exceptions-list
|
||||
|
||||
The following is an EBNF conversion of the ABNF located at
|
||||
<https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/>,
|
||||
and this is what we actually parse in vcpkg.
|
||||
Note that vcpkg does not support DocumentRefs.
|
||||
|
||||
```ebnf
|
||||
idchar = ? regex /[-.a-zA-Z0-9]/ ?
|
||||
idstring = ( idchar ), { idchar } ;
|
||||
|
||||
(* note that unrecognized license and license exception IDs will be warned against *)
|
||||
license-id = idstring ;
|
||||
license-exception-id = idstring ;
|
||||
(* note that DocumentRefs are unsupported by this implementation *)
|
||||
license-ref = "LicenseRef-", idstring ;
|
||||
|
||||
with = [ whitespace ], "WITH", [ whitespace ] ;
|
||||
and = [ whitespace ], "AND", [ whitespace ] ;
|
||||
or = [ whitespace ], "OR", [ whitespace ] ;
|
||||
|
||||
simple-expression = [ whitespace ], (
|
||||
| license-id
|
||||
| license-id, "+"
|
||||
| license-ref
|
||||
), [ whitespace ] ;
|
||||
|
||||
(* the following are split up from compound-expression to make precedence obvious *)
|
||||
parenthesized-expression =
|
||||
| simple-expression
|
||||
| [ whitespace ], "(", or-expression, ")", [ whitespace ] ;
|
||||
|
||||
with-expression =
|
||||
| parenthesized-expression
|
||||
| simple-expression, with, license-exception-id, [ whitespace ] ;
|
||||
|
||||
(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
|
||||
and-expression = with-expression, { and, with-expression } ;
|
||||
or-expression = and-expression, { or, and-exression } ;
|
||||
|
||||
license-expression = or-expression ;
|
||||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
For libraries with simple licensing,
|
||||
only one license identifier may be needed;
|
||||
|
||||
vcpkg, for example, would use this since it uses the MIT license:
|
||||
|
||||
```json
|
||||
{
|
||||
"license": "MIT"
|
||||
}
|
||||
```
|
||||
|
||||
Many GPL'd projects allow either the GPL 2 or any later versions:
|
||||
|
||||
```json
|
||||
{
|
||||
"license": "GPL-2.0-or-later"
|
||||
}
|
||||
```
|
||||
|
||||
Many Rust projects, in order to make certain they're useable with GPL,
|
||||
but also desiring the MIT license, will allow licensing under either
|
||||
the MIT license or Apache 2.0:
|
||||
|
||||
```json
|
||||
{
|
||||
"license": "Apache-2.0 OR MIT"
|
||||
}
|
||||
```
|
||||
|
||||
Some major projects include exceptions;
|
||||
the Microsoft C++ standard library, and the LLVM project,
|
||||
are licensed under Apache 2.0 with the LLVM exception:
|
||||
|
||||
```json
|
||||
{
|
||||
"license": "Apache-2.0 WITH LLVM-exception"
|
||||
}
|
||||
```
|
||||
@ -1,99 +0,0 @@
|
||||
# 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) (deprecated)
|
||||
- [vcpkg\_backup\_restore\_env\_vars](vcpkg_backup_restore_env_vars.md)
|
||||
- [vcpkg\_build\_cmake](vcpkg_build_cmake.md) (deprecated, use [vcpkg\_cmake\_build](vcpkg_cmake_build.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\_build\_qmake](vcpkg_build_qmake.md)
|
||||
- [vcpkg\_buildpath\_length\_warning](vcpkg_buildpath_length_warning.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) (deprecated, use [vcpkg\_cmake\_configure](vcpkg_cmake_configure.md))
|
||||
- [vcpkg\_configure\_gn](vcpkg_configure_gn.md) (deprecated, use [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md))
|
||||
- [vcpkg\_configure\_make](vcpkg_configure_make.md)
|
||||
- [vcpkg\_configure\_meson](vcpkg_configure_meson.md)
|
||||
- [vcpkg\_configure\_qmake](vcpkg_configure_qmake.md)
|
||||
- [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
|
||||
- [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
|
||||
- [vcpkg\_copy\_tools](vcpkg_copy_tools.md)
|
||||
- [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
|
||||
- [vcpkg\_execute\_build\_process](vcpkg_execute_build_process.md)
|
||||
- [vcpkg\_execute\_in\_download\_mode](vcpkg_execute_in_download_mode.md)
|
||||
- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
|
||||
- [vcpkg\_execute\_required\_process\_repeat](vcpkg_execute_required_process_repeat.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) (deprecated)
|
||||
- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
|
||||
- [vcpkg\_find\_fortran](vcpkg_find_fortran.md)
|
||||
- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md) (deprecated, use [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.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\_get\_program\_files\_platform\_bitness](vcpkg_get_program_files_platform_bitness.md)
|
||||
- [vcpkg\_get\_windows\_sdk](vcpkg_get_windows_sdk.md)
|
||||
- [vcpkg\_host\_path\_list](vcpkg_host_path_list.md)
|
||||
- [vcpkg\_install\_cmake](vcpkg_install_cmake.md) (deprecated, use [vcpkg\_cmake\_install](vcpkg_cmake_install.md))
|
||||
- [vcpkg\_install\_gn](vcpkg_install_gn.md) (deprecated, use [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md))
|
||||
- [vcpkg\_install\_copyright](vcpkg_install_copyright.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\_list](vcpkg_list.md)
|
||||
- [vcpkg\_minimum\_required](vcpkg_minimum_required.md)
|
||||
- [vcpkg\_replace\_string](vcpkg_replace_string.md)
|
||||
|
||||
## Internal Functions
|
||||
|
||||
- [z\_vcpkg\_apply\_patches](internal/z_vcpkg_apply_patches.md)
|
||||
- [z\_vcpkg\_forward\_output\_variable](internal/z_vcpkg_forward_output_variable.md)
|
||||
- [z\_vcpkg\_function\_arguments](internal/z_vcpkg_function_arguments.md)
|
||||
- [z\_vcpkg\_get\_cmake\_vars](internal/z_vcpkg_get_cmake_vars.md)
|
||||
- [z\_vcpkg\_prettify\_command\_line](internal/z_vcpkg_prettify_command_line.md)
|
||||
- [z\_vcpkg\_setup\_pkgconfig\_path](internal/z_vcpkg_setup_pkgconfig_path.md)
|
||||
|
||||
## Scripts from Ports
|
||||
|
||||
### [vcpkg-cmake](ports/vcpkg-cmake.md)
|
||||
|
||||
- [vcpkg\_cmake\_build](vcpkg_cmake_build.md)
|
||||
- [vcpkg\_cmake\_configure](vcpkg_cmake_configure.md)
|
||||
- [vcpkg\_cmake\_install](vcpkg_cmake_install.md)
|
||||
|
||||
### [vcpkg-gn](ports/vcpkg-gn.md)
|
||||
|
||||
- [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md)
|
||||
- [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md)
|
||||
|
||||
### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md)
|
||||
|
||||
- [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md)
|
||||
|
||||
### [vcpkg-cmake-get-vars](ports/vcpkg-cmake-get-vars.md)
|
||||
|
||||
- [vcpkg\_cmake\_get\_vars](ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md)
|
||||
|
||||
### [vcpkg-pkgconfig-get-modules](ports/vcpkg-pkgconfig-get-modules.md)
|
||||
|
||||
- [x\_vcpkg\_pkgconfig\_get\_modules](ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md)
|
||||
|
||||
### [vcpkg-get-python-packages](ports/vcpkg-get-python-packages.md)
|
||||
|
||||
- [x\_vcpkg\_get\_python\_packages](ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md)
|
||||
|
||||
### [vcpkg-qmake](ports/vcpkg-qmake.md)
|
||||
|
||||
- [vcpkg\_qmake\_configure](ports/vcpkg-qmake/vcpkg_qmake_configure.md)
|
||||
@ -1,10 +0,0 @@
|
||||
# vcpkg-cmake-config
|
||||
|
||||
`vcpkg-cmake-config` provides `vcpkg_cmake_config_fixup()`,
|
||||
a function which both:
|
||||
|
||||
- Fixes common mistakes in port build systems, like using absolute paths
|
||||
- Merges the debug and release config files.
|
||||
|
||||
This function should almost always be used when a port has `*config.cmake` files,
|
||||
even when the buildsystem of the project is not CMake.
|
||||
@ -1,54 +0,0 @@
|
||||
# vcpkg_cmake_config_fixup
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md).
|
||||
|
||||
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.
|
||||
|
||||
```cmake
|
||||
vcpkg_cmake_config_fixup(
|
||||
[PACKAGE_NAME <name>]
|
||||
[CONFIG_PATH <config-directory>]
|
||||
[TOOLS_PATH <tools/${PORT}>]
|
||||
[DO_NOT_DELETE_PARENT_CONFIG_PATH]
|
||||
[NO_PREFIX_CORRECTION]
|
||||
)
|
||||
```
|
||||
|
||||
For many ports, `vcpkg_cmake_config_fixup()` on its own should work,
|
||||
as `PACKAGE_NAME` defaults to `${PORT}` and `CONFIG_PATH` defaults to `share/${PACKAGE_NAME}`.
|
||||
For ports where the package name passed to `find_package` is distinct from the port name,
|
||||
`PACKAGE_NAME` should be changed to be that name instead.
|
||||
For ports where the directory of the `*config.cmake` files cannot be set,
|
||||
use the `CONFIG_PATH` to change the directory where the files come from.
|
||||
|
||||
By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
|
||||
Passing the `DO_NOT_DELETE_PARENT_CONFIG_PATH` option disable such behavior,
|
||||
as it is convenient for ports that install
|
||||
more than one CMake package configuration file.
|
||||
|
||||
The `NO_PREFIX_CORRECTION` option disables the correction of `_IMPORT_PREFIX`
|
||||
done by vcpkg due to moving the config files.
|
||||
Currently the correction does not take into account how the files are moved,
|
||||
and applies a rather simply correction which in some cases will yield the wrong results.
|
||||
|
||||
## How it Works
|
||||
|
||||
1. Moves `/debug/<CONFIG_PATH>/*targets-debug.cmake` to `/share/${PACKAGE_NAME}`.
|
||||
2. Transforms all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows.
|
||||
3. Transforms all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms.
|
||||
4. Fixes `${_IMPORT_PREFIX}` in auto generated targets.
|
||||
5. Replaces `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs.
|
||||
6. Merges INTERFACE_LINK_LIBRARIES of release and debug configurations.
|
||||
7. Replaces `${CURRENT_INSTALLED_DIR}` with `${VCPKG_IMPORT_PREFIX}` in targets.
|
||||
8. Removes `/debug/<CONFIG_PATH>/*config.cmake`.
|
||||
|
||||
## 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
|
||||
[ports/vcpkg-cmake-config/vcpkg\_cmake\_config\_fixup.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.cmake)
|
||||
@ -1,3 +0,0 @@
|
||||
# vcpkg-cmake-get-vars
|
||||
|
||||
This port contains a helper function to extract CMake variables into the scope of the portfile or other scripts
|
||||
@ -1,41 +0,0 @@
|
||||
# vcpkg_cmake_get_vars
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md).
|
||||
|
||||
Runs a cmake configure with a dummy project to extract certain cmake variables
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_cmake_get_vars(<out-var>)
|
||||
```
|
||||
|
||||
`vcpkg_cmake_get_vars(<out-var>)` sets `<out-var>` to
|
||||
a path to a generated CMake file, with the detected `CMAKE_*` variables
|
||||
re-exported as `VCPKG_DETECTED_CMAKE_*`.
|
||||
|
||||
Additionally sets, for `RELEASE` and `DEBUG`:
|
||||
- VCPKG_COMBINED_CXX_FLAGS_<config>
|
||||
- VCPKG_COMBINED_C_FLAGS_<config>
|
||||
- VCPKG_COMBINED_SHARED_LINKER_FLAGS_<config>
|
||||
- VCPKG_COMBINED_STATIC_LINKER_FLAGS_<config>
|
||||
- VCPKG_COMBINED_EXE_LINKER_FLAGS_<config>
|
||||
|
||||
Most users should use these pre-combined flags instead of attempting
|
||||
to read the `VCPKG_DETECTED_*` flags directly.
|
||||
|
||||
## Notes
|
||||
Avoid usage in portfiles.
|
||||
|
||||
All calls to `vcpkg_cmake_get_vars` will result in the same output file;
|
||||
the output file is not generated multiple times.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```cmake
|
||||
vcpkg_cmake_get_vars(cmake_vars_file)
|
||||
include("${cmake_vars_file}")
|
||||
message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CMAKE_CXX_FLAGS}")
|
||||
```
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-cmake-get-vars/vcpkg\_cmake\_get\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.cmake)
|
||||
@ -1,7 +0,0 @@
|
||||
# vcpkg-cmake
|
||||
|
||||
This port contains portfile helper functions for dealing with a CMake buildsystem.
|
||||
|
||||
- [`vcpkg_cmake_configure()`](../vcpkg_cmake_configure.md)
|
||||
- [`vcpkg_cmake_install()`](../vcpkg_cmake_install.md)
|
||||
- [`vcpkg_cmake_build()`](../vcpkg_cmake_build.md)
|
||||
@ -1,6 +0,0 @@
|
||||
# vcpkg-get-python-packages
|
||||
|
||||
**Experimental: will change or be removed at any time**
|
||||
|
||||
`vcpkg-get-python-packages` provides `x_vcpkg_get_python_packages()`, a function which simplifies getting
|
||||
python packages.
|
||||
@ -1,38 +0,0 @@
|
||||
# x_vcpkg_get_python_packages
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md).
|
||||
|
||||
Experimental
|
||||
Retrieve needed python packages
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
x_vcpkg_get_python_packages(
|
||||
[PYTHON_VERSION (2|3)]
|
||||
PYTHON_EXECUTABLE <path to python binary>
|
||||
REQUIREMENTS_FILE <file-path>
|
||||
PACKAGES <packages to aqcuire>...
|
||||
[OUT_PYTHON_VAR somevar]
|
||||
)
|
||||
```
|
||||
## Parameters
|
||||
|
||||
### PYTHON_VERSION
|
||||
Python version to be used. Either 2 or 3
|
||||
|
||||
### PYTHON_EXECUTABLE
|
||||
Full path to the python executable
|
||||
|
||||
### REQUIREMENTS_FILE
|
||||
Requirement file with the list of python packages
|
||||
|
||||
### PACKAGES
|
||||
List of python packages to acquire
|
||||
|
||||
### OUT_PYTHON_VAR
|
||||
Variable to store the path to the python binary inside the virtual environment
|
||||
|
||||
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-get-python-packages/x\_vcpkg\_get\_python\_packages.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.cmake)
|
||||
@ -1,12 +0,0 @@
|
||||
# vcpkg-gn
|
||||
|
||||
This port contains cmake functions for dealing with a GN buildsystem.
|
||||
|
||||
## Example
|
||||
|
||||
```cmake
|
||||
vcpkg_gn_configure(
|
||||
SOURCE_PATH "${SOURCE_PATH}"
|
||||
)
|
||||
vcpkg_gn_install()
|
||||
```
|
||||
@ -1,32 +0,0 @@
|
||||
# vcpkg_gn_configure
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md).
|
||||
|
||||
Generate Ninja (GN) targets
|
||||
|
||||
## Usage:
|
||||
```cmake
|
||||
vcpkg_gn_configure(
|
||||
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
|
||||
[ports/vcpkg-gn/vcpkg\_gn\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_configure.cmake)
|
||||
@ -1,29 +0,0 @@
|
||||
# vcpkg_gn_install
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md).
|
||||
|
||||
Installs a GN project.
|
||||
|
||||
In order to build a GN project without installing, use [`vcpkg_build_ninja()`].
|
||||
|
||||
## Usage:
|
||||
```cmake
|
||||
vcpkg_gn_install(
|
||||
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
|
||||
|
||||
[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-gn/vcpkg\_gn\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_install.cmake)
|
||||
@ -1,6 +0,0 @@
|
||||
# vcpkg-pkgconfig-get-modules
|
||||
|
||||
**Experimental: will change or be removed at any time**
|
||||
|
||||
`vcpkg-pkgconfig-get-modules` provides `x_vcpkg_pkgconfig_get_modules()`, a function which simplifies calling
|
||||
`pkg-config` in portfiles in order to gather dependencies for exotic buildsystems.
|
||||
@ -1,45 +0,0 @@
|
||||
# x_vcpkg_pkgconfig_get_modules
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md).
|
||||
|
||||
Experimental
|
||||
Retrieve required module information from pkgconfig modules
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
x_vcpkg_pkgconfig_get_modules(
|
||||
PREFIX <prefix>
|
||||
MODULES <pkgconfig_modules>...
|
||||
[CFLAGS]
|
||||
[LIBS]
|
||||
[LIBRARIES]
|
||||
[LIBRARIES_DIRS]
|
||||
[INCLUDE_DIRS]
|
||||
)
|
||||
```
|
||||
## Parameters
|
||||
|
||||
### PREFIX
|
||||
Used variable prefix to use
|
||||
|
||||
### MODULES
|
||||
List of pkgconfig modules to retrieve information for.
|
||||
|
||||
### LIBS
|
||||
Returns `"${PKGCONFIG}" --libs` in <prefix>_LIBS_(DEBUG|RELEASE)
|
||||
|
||||
### LIBRARIES
|
||||
Returns `"${PKGCONFIG}" --libs-only-l` in <prefix>_LIBRARIES_(DEBUG|RELEASE)
|
||||
|
||||
### LIBRARIES_DIRS
|
||||
Returns `"${PKGCONFIG}" --libs-only-L` in <prefix>_LIBRARIES_DIRS_(DEBUG|RELEASE)
|
||||
|
||||
### INCLUDE_DIRS
|
||||
Returns `"${PKGCONFIG}" --cflags-only-I` in <prefix>_INCLUDE_DIRS_(DEBUG|RELEASE)
|
||||
|
||||
## Examples
|
||||
|
||||
* [qt5-base](https://github.com/microsoft/vcpkg/blob/master/ports/qt5-base/portfile.cmake)
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-pkgconfig-get-modules/x\_vcpkg\_pkgconfig\_get\_modules.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.cmake)
|
||||
@ -1,7 +0,0 @@
|
||||
# vcpkg-qmake
|
||||
|
||||
This port contains qmake functions for dealing with a QMake buildsystem.
|
||||
|
||||
In the common case, `vcpkg_qmake_configure()` (with appropriate arguments)
|
||||
followed by `vcpkg_install_qmake()` will be enough to build and install a port.
|
||||
|
||||
@ -1,27 +0,0 @@
|
||||
# vcpkg_qmake_build
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_build.md).
|
||||
|
||||
Build a qmake-based project, previously configured using vcpkg_qmake_configure.
|
||||
|
||||
```cmake
|
||||
vcpkg_qmake_configure(
|
||||
[SKIP_MAKEFILES]
|
||||
[BUILD_LOGNAME arg1]
|
||||
[TARGETS arg1 [arg2 ...]]
|
||||
[RELEASE_TARGETS arg1 [arg2 ...]]
|
||||
[DEBUG_TARGETS arg1 [arg2 ...]]
|
||||
)
|
||||
```
|
||||
|
||||
### SKIP_MAKEFILES
|
||||
Skip the generation of makefiles
|
||||
|
||||
### BUILD_LOGNAME
|
||||
Configuration independent prefix for the build log files (default:'build')
|
||||
|
||||
### TARGETS, RELEASE\_TARGETS, DEBUG\_TARGETS
|
||||
Targets to build for a certain configuration.
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_build.cmake)
|
||||
@ -1,37 +0,0 @@
|
||||
# vcpkg_qmake_configure
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md).
|
||||
|
||||
Configure a qmake-based project.
|
||||
|
||||
###User setable triplet variables:
|
||||
VCPKG_OSX_DEPLOYMENT_TARGET: Determines QMAKE_MACOSX_DEPLOYMENT_TARGET
|
||||
VCPKG_QMAKE_COMMAND: Path to qmake. (default: "${CURRENT_HOST_INSTALLED_DIR}/tools/Qt6/bin/qmake${VCPKG_HOST_EXECUTABLE_SUFFIX}")
|
||||
VCPKG_QT_CONF_(RELEASE|DEBUG): Path to qt.config being used for RELEASE/DEBUG. (default: "${CURRENT_INSTALLED_DIR}/tools/Qt6/qt_(release|debug).conf")
|
||||
VCPKG_QT_TARGET_MKSPEC: Qt mkspec to use
|
||||
VCPKG_QMAKE_OPTIONS(_RELEASE|_DEBUG)?: Extra options to pass to QMake
|
||||
|
||||
```cmake
|
||||
vcpkg_qmake_configure(
|
||||
SOURCE_PATH <pro_file_path>
|
||||
[QMAKE_OPTIONS arg1 [arg2 ...]]
|
||||
[QMAKE_OPTIONS_RELEASE arg1 [arg2 ...]]
|
||||
[QMAKE_OPTIONS_DEBUG arg1 [arg2 ...]]
|
||||
[OPTIONS arg1 [arg2 ...]]
|
||||
[OPTIONS_RELEASE arg1 [arg2 ...]]
|
||||
[OPTIONS_DEBUG arg1 [arg2 ...]]
|
||||
)
|
||||
```
|
||||
|
||||
### SOURCE_PATH
|
||||
The path to the *.pro qmake project file.
|
||||
|
||||
### QMAKE_OPTIONS, QMAKE_OPTIONS\_RELEASE, QMAKE_OPTIONS\_DEBUG
|
||||
options directly passed to qmake with the form QMAKE_X=something or CONFIG=something
|
||||
|
||||
### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
|
||||
The options passed after -- to qmake.
|
||||
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_configure.cmake)
|
||||
@ -1,20 +0,0 @@
|
||||
# vcpkg_qmake_install
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_install.md).
|
||||
|
||||
Build and install a qmake project.
|
||||
|
||||
|
||||
```cmake
|
||||
vcpkg_qmake_install(...)
|
||||
```
|
||||
|
||||
### Parameters:
|
||||
See [`vcpkg_qmake_build()`](vcpkg_qmake_build.md).
|
||||
|
||||
### Notes:
|
||||
This command transparently forwards to [`vcpkg_qmake_build()`](vcpkg_qmake_build.md)
|
||||
and appends the 'install' target
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_install.cmake)
|
||||
@ -1,115 +0,0 @@
|
||||
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.
|
||||
@ -1,360 +0,0 @@
|
||||
# Creating Registries
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/maintainers/registries.md).**
|
||||
|
||||
There are two parts to using registries; this documents the creation side of
|
||||
the relationship. In order to learn more about using registries that others
|
||||
have created, please read [this documentation](../users/registries.md).
|
||||
## Table of Contents
|
||||
|
||||
- [Creating Registries](#creating-registries)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Overview](#overview)
|
||||
- [Git Registries](#git-registries)
|
||||
- [Adding a New Version](#adding-a-new-version)
|
||||
- [Filesystem Registries](#filesystem-registries)
|
||||
- [Adding a New Version](#adding-a-new-version-1)
|
||||
- [Builtin Registries](#builtin-registries)
|
||||
|
||||
## Overview
|
||||
|
||||
Registries are collections of ports and their versions. There are two major
|
||||
choices of implementation for registries, if you want to create your own -
|
||||
git registries, and filesystem registries.
|
||||
|
||||
Git registries are simple git repositories, and can be shared publicly or
|
||||
privately via normal mechanisms for git repositories. The vcpkg repository at
|
||||
<https://github.com/microsoft/vcpkg>, for example, is a git registry.
|
||||
|
||||
Filesystem registries are designed as more of a testing ground. Given that they
|
||||
literally live on your filesystem, the only way to share them is via shared
|
||||
directories. However, filesystem registries can be useful as a way to represent
|
||||
registries held in non-git version control systems, assuming one has some way
|
||||
to get the registry onto the disk.
|
||||
|
||||
Note that we expect the set of registry types to grow over time; if you would
|
||||
like support for registries built in your favorite public version control
|
||||
system, don't hesitate to open a PR.
|
||||
|
||||
The basic structure of a registry is:
|
||||
|
||||
- The set of versions that are considered "latest" at certain times in history,
|
||||
known as the "baseline".
|
||||
- The set of all the versions of all the ports, and where to find each of
|
||||
these in the registry.
|
||||
|
||||
### Git Registries
|
||||
|
||||
As you're following along with this documentation, it may be helpful to have
|
||||
a working example to refer to. We've written one and put it here:
|
||||
<https://github.com/northwindtraders/vcpkg-registry>.
|
||||
|
||||
All git registries must have a `versions/baseline.json` file. This file
|
||||
contains the set of "latest versions" at a certain commit. It is laid out as
|
||||
a top-level object containing only the `"default"` field. This field should
|
||||
contain an object mapping port names to the version which is currently the
|
||||
latest.
|
||||
|
||||
Here's an example of a valid baseline.json:
|
||||
|
||||
```json
|
||||
{
|
||||
"default": {
|
||||
"kitten": {
|
||||
"baseline": "2.6.2",
|
||||
"port-version": 0
|
||||
},
|
||||
"port-b": {
|
||||
"baseline": "19.00",
|
||||
"port-version": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `versions` directory contains all the information about which versions of
|
||||
which packages are contained in the registry, along with where those versions
|
||||
are stored. The rest of the registry just acts as a backing store, as far as
|
||||
vcpkg is concerned: only things inside the `versions` directory will be used
|
||||
to direct how your registry is seen by vcpkg.
|
||||
|
||||
Each port in a registry should exist in the versions directory as
|
||||
`<first letter of port>-/<name of port>.json`; in other words, the
|
||||
information about the `kitten` port would be located in
|
||||
`versions/k-/kitten.json`. This should be a top-level object with only a
|
||||
single field: `"versions"`. This field should contain an array of version
|
||||
objects:
|
||||
|
||||
- The version of the port in question; should be exactly the same as the
|
||||
`vcpkg.json` file, including the version fields and `"port-version"`.
|
||||
- The `"git-tree"` field, which is a git tree; in other words, what you get
|
||||
when you write `git rev-parse COMMIT-ID:path/to/port`.
|
||||
|
||||
Note that the version fields for ports with `CONTROL` files, is
|
||||
`"version-string"`; we do not recommend using `CONTROL` files in new
|
||||
registries, however.
|
||||
|
||||
_WARNING_: One very important part of registries is that versions should
|
||||
_never_ be changed. Updating to a later ref should never remove or change an
|
||||
existing version. It must always be safe to update a registry.
|
||||
|
||||
Here's an example of a valid version database for a `kitten` port with one
|
||||
version:
|
||||
|
||||
```json
|
||||
{
|
||||
"versions": [
|
||||
{
|
||||
"version": "2.6.2",
|
||||
"port-version": 0,
|
||||
"git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
In general, it's not important where you place port directories. However, the
|
||||
idiom in vcpkg is to follow what the built in vcpkg registry does: your
|
||||
`kitten` port should be placed in `ports/kitten`.
|
||||
|
||||
_WARNING_: One other thing to keep in mind is that when you update a registry,
|
||||
all previous versions should also be accessible. Since your user will set their
|
||||
baseline to a commit ID, that commit ID must always exist, and be accessible
|
||||
from your HEAD commit, which is what is actually fetched. This means that your
|
||||
HEAD commit should be a child of all previous HEAD commits.
|
||||
|
||||
### Builtin Registries
|
||||
|
||||
Builtin registries are treated as special [Git registries](#git-registries). Instead of fetching from a remote url, builtin registries consult the `$VCPKG_ROOT/.git` directory of the vcpkg clone. They use the currently checked out `$VCPKG_ROOT/versions` directory as the source for versioning information.
|
||||
|
||||
#### Adding a New Version
|
||||
|
||||
There is some git trickery involved in creating a new version of a port. The
|
||||
first thing to do is make some changes, update the `"port-version"` and regular
|
||||
version field as you need to, and then test with `overlay-ports`:
|
||||
`vcpkg install kitten --overlay-ports=ports/kitten`.
|
||||
|
||||
Once you've finished your testing, you'll need to make sure that the directory
|
||||
as it is is under git's purview. You'll do this by creating a temporary commit:
|
||||
|
||||
```pwsh
|
||||
> git add ports/kitten
|
||||
> git commit -m 'temporary commit'
|
||||
```
|
||||
|
||||
Then, get the git tree ID of the directory:
|
||||
|
||||
```pwsh
|
||||
> git rev-parse HEAD:ports/kitten
|
||||
73ad3c823ef701c37421b450a34271d6beaf7b07
|
||||
```
|
||||
|
||||
Then, you can add this version to the versions database. At the top of your
|
||||
`versions/k-/kitten.json`, you can add (assuming you're adding version
|
||||
`2.6.3#0`):
|
||||
|
||||
```json
|
||||
{
|
||||
"versions": [
|
||||
{
|
||||
"version": "2.6.3",
|
||||
"port-version": 0,
|
||||
"git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
|
||||
},
|
||||
{
|
||||
"version": "2.6.2",
|
||||
"port-version": 0,
|
||||
"git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
then, you'll want to modify your `versions/baseline.json` with your new version
|
||||
as well:
|
||||
|
||||
```json
|
||||
{
|
||||
"default": {
|
||||
"kitten": {
|
||||
"baseline": "2.6.3",
|
||||
"port-version": 0
|
||||
},
|
||||
"port-b": {
|
||||
"baseline": "19.00",
|
||||
"port-version": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
and amend your current commit:
|
||||
|
||||
```pwsh
|
||||
> git commit --amend
|
||||
```
|
||||
|
||||
then share away!
|
||||
|
||||
### Filesystem Registries
|
||||
|
||||
As you're following along with this documentation, it may be helpful to have
|
||||
a working example to refer to. We've written one and put it here:
|
||||
<https://github.com/vcpkg/example-filesystem-registry>.
|
||||
|
||||
All filesystem registries must have a `versions/baseline.json` file. This file
|
||||
contains the set of "latest versions" for a certain version of the registry.
|
||||
It is laid out as a top-level object containing a map from version name to
|
||||
"baseline objects", which map port names to the version which is considered
|
||||
"latest" for that version of the registry.
|
||||
|
||||
Filesystem registries need to decide on a versioning scheme. Unlike git
|
||||
registries, which have the implicit versioning scheme of refs, filesystem
|
||||
registries can't rely on the version control system here. One possible option
|
||||
is to do a daily release, and have your "versions" be dates.
|
||||
|
||||
_WARNING_: A baseline must not be modified once published. If you want to change or update versions, you need to create a new baseline in the `baseline.json` file.
|
||||
|
||||
Here's an example of a valid `baseline.json`, for a registry that has decided
|
||||
upon dates for their versions:
|
||||
|
||||
```json
|
||||
{
|
||||
"2021-04-16": {
|
||||
"kitten": {
|
||||
"baseline": "2.6.2",
|
||||
"port-version": 0
|
||||
},
|
||||
"port-b": {
|
||||
"baseline": "19.00",
|
||||
"port-version": 2
|
||||
}
|
||||
},
|
||||
"2021-04-15": {
|
||||
"kitten": {
|
||||
"baseline": "2.6.2",
|
||||
"port-version": 0
|
||||
},
|
||||
"port-b": {
|
||||
"baseline": "19.00",
|
||||
"port-version": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `versions` directory contains all the information about which versions of
|
||||
which packages are contained in the registry, along with where those versions
|
||||
are stored. The rest of the registry just acts as a backing store, as far as
|
||||
vcpkg is concerned: only things inside the `versions` directory will be used
|
||||
to direct how your registry is seen by vcpkg.
|
||||
|
||||
Each port in a registry should exist in the versions directory as
|
||||
`<first letter of port>-/<name of port>.json`; in other words, the
|
||||
information about the `kitten` port would be located in
|
||||
`versions/k-/kitten.json`. This should be a top-level object with only a
|
||||
single field: `"versions"`. This field should contain an array of version
|
||||
objects:
|
||||
|
||||
- The version of the port in question; should be exactly the same as the
|
||||
`vcpkg.json` file, including the version fields and `"port-version"`.
|
||||
- The `"path"` field: a relative directory, rooted at the base of the registry
|
||||
(in other words, the directory where `versions` is located), to the port
|
||||
directory. It should look something like `"$/path/to/port/dir`"
|
||||
|
||||
Note that the version fields for ports with `CONTROL` files, is
|
||||
`"version-string"`; we do not recommend using `CONTROL` files in new
|
||||
registries, however.
|
||||
|
||||
In general, it's not important where you place port directories. However, the
|
||||
idiom in vcpkg is to follow somewhat closely to what the built in vcpkg
|
||||
registry does: your `kitten` port at version `x.y.z` should be placed in
|
||||
`ports/kitten/x.y.z`, with port versions appended as you see fit (although
|
||||
since `#` is not a good character to use for file names, perhaps use `_`).
|
||||
|
||||
_WARNING_: One very important part of registries is that versions should
|
||||
_never_ be changed. One should never remove or change an existing version.
|
||||
Your changes to your registry shouldn't change behavior to downstream users.
|
||||
|
||||
Here's an example of a valid version database for a `kitten` port with one
|
||||
version:
|
||||
|
||||
```json
|
||||
{
|
||||
"versions": [
|
||||
{
|
||||
"version": "2.6.2",
|
||||
"port-version": 0,
|
||||
"path": "$/ports/kitten/2.6.2_0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Adding a New Version
|
||||
|
||||
Unlike git registries, adding a new version to a filesystem registry mostly
|
||||
involves a lot of copying. The first thing to do is to copy the latest
|
||||
version of your port into a new version directory, update the version and
|
||||
`"port-version"` fields as you need to, and then test with `overlay-ports`:
|
||||
`vcpkg install kitten --overlay-ports=ports/kitten/new-version`.
|
||||
|
||||
Once you've finished your testing, you can add this new version to the top of
|
||||
your `versions/k-/kitten.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"versions": [
|
||||
{
|
||||
"version": "2.6.3",
|
||||
"port-version": 0,
|
||||
"path": "$/ports/kitten/2.6.3_0"
|
||||
},
|
||||
{
|
||||
"version": "2.6.2",
|
||||
"port-version": 0,
|
||||
"path": "$/ports/kitten/2.6.2_0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
then, you'll want to modify your `versions/baseline.json` with your new version
|
||||
as well (remember not to modify existing baselines):
|
||||
|
||||
```json
|
||||
{
|
||||
"2021-04-17": {
|
||||
"kitten": {
|
||||
"baseline": "2.6.3",
|
||||
"port-version": 0
|
||||
},
|
||||
"port-b": {
|
||||
"baseline": "19.00",
|
||||
"port-version": 2
|
||||
}
|
||||
},
|
||||
"2021-04-16": {
|
||||
"kitten": {
|
||||
"baseline": "2.6.2",
|
||||
"port-version": 0
|
||||
},
|
||||
"port-b": {
|
||||
"baseline": "19.00",
|
||||
"port-version": 2
|
||||
}
|
||||
},
|
||||
"2021-04-15": {
|
||||
"kitten": {
|
||||
"baseline": "2.6.2",
|
||||
"port-version": 0
|
||||
},
|
||||
"port-b": {
|
||||
"baseline": "19.00",
|
||||
"port-version": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
and you're done!
|
||||
@ -1,60 +0,0 @@
|
||||
# vcpkg_acquire_msys
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_acquire_msys.md).
|
||||
|
||||
Download and prepare an MSYS2 instance.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_acquire_msys(<MSYS_ROOT_VAR>
|
||||
PACKAGES <package>...
|
||||
[NO_DEFAULT_PACKAGES]
|
||||
[DIRECT_PACKAGES <URL> <SHA512> <URL> <SHA512> ...]
|
||||
)
|
||||
```
|
||||
|
||||
## 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.16)`
|
||||
|
||||
### NO_DEFAULT_PACKAGES
|
||||
Exclude the normal base packages.
|
||||
|
||||
The list of base packages includes: bash, coreutils, sed, grep, gawk, gzip, diffutils, make, and pkg-config
|
||||
|
||||
### DIRECT_PACKAGES
|
||||
A list of URL/SHA512 pairs to acquire in msys.
|
||||
|
||||
This parameter can be used by a port to privately extend the list of msys packages to be acquired.
|
||||
The URLs can be found on the msys2 website[1] and should be a direct archive link:
|
||||
|
||||
https://repo.msys2.org/mingw/i686/mingw-w64-i686-gettext-0.19.8.1-9-any.pkg.tar.zst
|
||||
|
||||
[1] https://packages.msys2.org/search
|
||||
|
||||
## 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)
|
||||
@ -1,27 +0,0 @@
|
||||
# vcpkg_add_to_path
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_add_to_path.md).
|
||||
|
||||
Add a directory or directories to the PATH environment variable
|
||||
|
||||
```cmake
|
||||
vcpkg_add_to_path([PREPEND] [<path>...])
|
||||
```
|
||||
|
||||
`vcpkg_add_to_path` adds all of the paths passed to it to the PATH environment variable.
|
||||
If PREPEND is passed, then those paths are prepended to the PATH environment variable,
|
||||
so that they are searched first; otherwise, those paths are appended, so they are
|
||||
searched after the paths which are already in the environment variable.
|
||||
|
||||
The paths are added in the order received, so that the first path is always searched
|
||||
before a later path.
|
||||
|
||||
If no paths are passed, then nothing will be done.
|
||||
|
||||
## 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)
|
||||
@ -1,18 +0,0 @@
|
||||
# vcpkg_apply_patches
|
||||
|
||||
**This function has been deprecated in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md) et al.**
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_apply_patches.md).
|
||||
|
||||
Apply a set of patches to a source tree.
|
||||
|
||||
```cmake
|
||||
vcpkg_apply_patches(
|
||||
SOURCE_PATH <${SOURCE_PATH}>
|
||||
[QUIET]
|
||||
PATCHES <patch1.patch>...
|
||||
)
|
||||
```
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)
|
||||
@ -1,26 +0,0 @@
|
||||
# vcpkg_backup_restore_env_vars
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_backup_restore_env_vars.md).
|
||||
|
||||
Backup or restore the environment variables
|
||||
|
||||
## Usage:
|
||||
```cmake
|
||||
vcpkg_backup_env_variables(VARS [<environment-variable>...])
|
||||
vcpkg_restore_env_variables(VARS [<environment-variable>...])
|
||||
```
|
||||
|
||||
### VARS
|
||||
The variables to back up or restore.
|
||||
These are placed in the parent scope, so you must backup and restore
|
||||
from the same scope.
|
||||
|
||||
## Notes
|
||||
One must always call `vcpkg_backup_env_variables` before
|
||||
`vcpkg_restore_env_variables`; however, `vcpkg_restore_env_variables`
|
||||
does not change the back up variables, and so you may call `restore`
|
||||
multiple times for one `backup`.
|
||||
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_backup\_restore\_env\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_backup_restore_env_vars.cmake)
|
||||
@ -1,38 +0,0 @@
|
||||
# vcpkg_build_cmake
|
||||
|
||||
**This function has been deprecated in favor of [`vcpkg_cmake_build`](vcpkg_cmake_build.md) from the vcpkg-cmake port.**
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_cmake.md).
|
||||
|
||||
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 preceded 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)
|
||||
@ -1,57 +0,0 @@
|
||||
# vcpkg_build_make
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_make.md).
|
||||
|
||||
Build a linux makefile project.
|
||||
|
||||
## Usage:
|
||||
```cmake
|
||||
vcpkg_build_make([BUILD_TARGET <target>]
|
||||
[INSTALL_TARGET <target>]
|
||||
[ADD_BIN_TO_PATH]
|
||||
[ENABLE_INSTALL]
|
||||
[MAKEFILE <makefileName>]
|
||||
[LOGFILE_ROOT <logfileroot>]
|
||||
[DISABLE_PARALLEL]
|
||||
[SUBPATH <path>])
|
||||
```
|
||||
|
||||
### BUILD_TARGET
|
||||
The target passed to the make build command (`./make <target>`). If not specified, the 'all' target will
|
||||
be passed.
|
||||
|
||||
### INSTALL_TARGET
|
||||
The target passed to the make build command (`./make <target>`) if `ENABLE_INSTALL` is used. Defaults to 'install'.
|
||||
|
||||
### 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()
|
||||
|
||||
### MAKEFILE
|
||||
Specifies the Makefile as a relative path from the root of the sources passed to `vcpkg_configure_make()`
|
||||
|
||||
### LOGFILE_ROOT
|
||||
Specifies a log file prefix.
|
||||
|
||||
### DISABLE_PARALLEL
|
||||
The underlying buildsystem will be instructed to not parallelize
|
||||
|
||||
### SUBPATH
|
||||
Additional subdir to invoke make in. Useful if only parts of a port should be built.
|
||||
|
||||
## Notes:
|
||||
This command should be preceded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md).
|
||||
You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your makefile 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)
|
||||
@ -1,66 +0,0 @@
|
||||
# vcpkg_build_msbuild
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_msbuild.md).
|
||||
|
||||
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)
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_build\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)
|
||||
@ -1,19 +0,0 @@
|
||||
# vcpkg_build_ninja
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_ninja.md).
|
||||
|
||||
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)
|
||||
@ -1,89 +0,0 @@
|
||||
# vcpkg_build_nmake
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_nmake.md).
|
||||
|
||||
Build a msvc makefile project.
|
||||
|
||||
## Usage:
|
||||
```cmake
|
||||
vcpkg_build_nmake(
|
||||
SOURCE_PATH <${SOURCE_PATH}>
|
||||
[PROJECT_SUBPATH <${SUBPATH}>]
|
||||
[PROJECT_NAME <${MAKEFILE_NAME}>]
|
||||
[LOGFILE_ROOT <prefix>]
|
||||
[CL_LANGUAGE <language-name>]
|
||||
[PREFER_JOM]
|
||||
[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 <all>...]
|
||||
[ENABLE_INSTALL]
|
||||
)
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
### PROJECT_NAME
|
||||
Specifies the name of the makefile.
|
||||
Default is `makefile.vc`
|
||||
|
||||
### LOGFILE_ROOT
|
||||
Specifies a log file prefix.
|
||||
|
||||
### CL_LANGUAGE
|
||||
Specifies the language for setting up flags in the `_CL_` environment variable.
|
||||
The default language is `CXX`.
|
||||
To disable the modification of `_CL_`, use `NONE`.
|
||||
|
||||
### PREFER_JOM
|
||||
Specifies that a parallel build with `jom` should be attempted.
|
||||
This is useful for faster builds of makefiles which process many independent targets
|
||||
and which cannot benefit from the `/MP` cl option.
|
||||
To mitigate issues with concurrency-unaware makefiles, a normal `nmake` build is run after `jom` errors.
|
||||
|
||||
### 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 the build command.
|
||||
|
||||
### OPTIONS_RELEASE
|
||||
Additional options passed to the build command for the release build. These are in addition to `OPTIONS`.
|
||||
|
||||
### OPTIONS_DEBUG
|
||||
Additional options passed to the build command for the debug build. These are in addition to `OPTIONS`.
|
||||
|
||||
### TARGET
|
||||
The list of targets passed to the build command.
|
||||
If not specified, target `all` will be passed.
|
||||
|
||||
### ENABLE_INSTALL
|
||||
Adds `install` to the list of targets passed to the build command,
|
||||
and passes the install prefix in the `INSTALLDIR` makefile variable.
|
||||
|
||||
## Notes:
|
||||
You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function if your makefile supports the
|
||||
"install" target.
|
||||
|
||||
## Examples
|
||||
|
||||
* [librttopo](https://github.com/microsoft/vcpkg/blob/master/ports/librttopo/portfile.cmake)
|
||||
* [openssl](https://github.com/microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_build\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)
|
||||
@ -1,12 +0,0 @@
|
||||
# vcpkg_build_qmake
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_qmake.md).
|
||||
|
||||
Build a qmake-based project, previously configured using vcpkg_configure_qmake.
|
||||
|
||||
```cmake
|
||||
vcpkg_build_qmake()
|
||||
```
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_build\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake)
|
||||
@ -1,16 +0,0 @@
|
||||
# vcpkg_buildpath_length_warning
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_buildpath_length_warning.md).
|
||||
|
||||
Warns the user if their vcpkg installation path might be too long for the package they're installing.
|
||||
|
||||
```cmake
|
||||
vcpkg_buildpath_length_warning(<N>)
|
||||
```
|
||||
|
||||
`vcpkg_buildpath_length_warning` warns the user if the number of bytes in the
|
||||
path to `buildtrees` is bigger than `N`. Note that this is simply a warning,
|
||||
and isn't relied on for correctness.
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_buildpath\_length\_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake)
|
||||
@ -1,136 +0,0 @@
|
||||
# vcpkg_check_features
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_check_features.md).
|
||||
Check if one or more features are a part of a package installation.
|
||||
|
||||
```cmake
|
||||
vcpkg_check_features(
|
||||
OUT_FEATURE_OPTIONS <out-var>
|
||||
[PREFIX <prefix>]
|
||||
[FEATURES
|
||||
[<feature-name> <feature-var>]...
|
||||
]
|
||||
[INVERTED_FEATURES
|
||||
[<feature-name> <feature-var>]...
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
The `<out-var>` should be set to `FEATURE_OPTIONS` by convention.
|
||||
|
||||
`vcpkg_check_features()` will:
|
||||
|
||||
- for each `<feature-name>` passed in `FEATURES`:
|
||||
- if the feature is set, add `-D<feature-var>=ON` to `<out-var>`,
|
||||
and set `<prefix>_<feature-var>` to ON.
|
||||
- if the feature is not set, add `-D<feature-var>=OFF` to `<out-var>`,
|
||||
and set `<prefix>_<feature-var>` to OFF.
|
||||
- for each `<feature-name>` passed in `INVERTED_FEATURES`:
|
||||
- if the feature is set, add `-D<feature-var>=OFF` to `<out-var>`,
|
||||
and set `<prefix>_<feature-var>` to OFF.
|
||||
- if the feature is not set, add `-D<feature-var>=ON` to `<out-var>`,
|
||||
and set `<prefix>_<feature-var>` to ON.
|
||||
|
||||
If `<prefix>` is not passed, then the feature vars set are simply `<feature-var>`,
|
||||
not `_<feature-var>`.
|
||||
|
||||
If `INVERTED_FEATURES` is not passed, then the `FEATURES` keyword is optional.
|
||||
This behavior is deprecated.
|
||||
|
||||
If the same `<feature-var>` is passed multiple times,
|
||||
then `vcpkg_check_features` will cause a fatal error,
|
||||
since that is a bug.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Regular features
|
||||
|
||||
```cmake
|
||||
$ ./vcpkg install mimalloc[asm,secure]
|
||||
|
||||
# ports/mimalloc/portfile.cmake
|
||||
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
|
||||
FEATURES
|
||||
asm MI_SEE_ASM
|
||||
override MI_OVERRIDE
|
||||
secure MI_SECURE
|
||||
)
|
||||
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH "${SOURCE_PATH}"
|
||||
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
|
||||
brotli CPPREST_EXCLUDE_BROTLI
|
||||
websockets CPPREST_EXCLUDE_WEBSOCKETS
|
||||
)
|
||||
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH "${SOURCE_PATH}"
|
||||
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
|
||||
FEATURES
|
||||
cuda WITH_CUDA
|
||||
cuda BUILD_CUDA
|
||||
cuda BUILD_GPU
|
||||
)
|
||||
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH "${SOURCE_PATH}"
|
||||
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
|
||||
tbb WITH_TBB
|
||||
INVERTED_FEATURES
|
||||
tbb ROCKSDB_IGNORE_PACKAGE_TBB
|
||||
)
|
||||
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH "${SOURCE_PATH}"
|
||||
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)
|
||||
@ -1,38 +0,0 @@
|
||||
# vcpkg_check_linkage
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_check_linkage.md).
|
||||
|
||||
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.
|
||||
|
||||
Note: If the user requested a dynamic build ONLY_STATIC_LIBRARY will result in a note being printed, not a fatal error.
|
||||
|
||||
### 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)
|
||||
@ -1,25 +0,0 @@
|
||||
# vcpkg_clean_executables_in_bin
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_clean_executables_in_bin.md).
|
||||
|
||||
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)
|
||||
@ -1,17 +0,0 @@
|
||||
# vcpkg_clean_msbuild
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_clean_msbuild.md).
|
||||
|
||||
Clean intermediate files generated by `vcpkg_install_msbuild()`.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_clean_msbuild()
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
* [python3](https://github.com/Microsoft/vcpkg/blob/master/ports/python3/portfile.cmake)
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_clean\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)
|
||||
@ -1,68 +0,0 @@
|
||||
# vcpkg_cmake_build
|
||||
|
||||
**The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_build.md).**
|
||||
|
||||
Build a cmake project with a custom install target.
|
||||
|
||||
Conventionally, CMake uses the target `install` to build and copy binaries into the [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). In rare circumstances, a project might have more specific targets that should be used instead.
|
||||
|
||||
Ports should prefer calling [`vcpkg_cmake_install()`](vcpkg_cmake_install.md) when possible.
|
||||
|
||||
## Usage
|
||||
|
||||
```cmake
|
||||
vcpkg_cmake_build(
|
||||
[TARGET <target>]
|
||||
[LOGFILE_BASE <base>]
|
||||
[DISABLE_PARALLEL]
|
||||
[ADD_BIN_TO_PATH]
|
||||
)
|
||||
```
|
||||
|
||||
To use this function, you must depend on the helper port [`vcpkg-cmake`](ports/vcpkg-cmake.md):
|
||||
```no-highlight
|
||||
"dependencies": [
|
||||
{
|
||||
"name": "vcpkg-cmake",
|
||||
"host": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
All supported parameters to [`vcpkg_cmake_install()`] are supported by `vcpkg_cmake_build()`. See [`vcpkg_cmake_install()`] for additional parameter documentation.
|
||||
|
||||
[`vcpkg_cmake_install()`]: vcpkg_cmake_install.md#parameters
|
||||
|
||||
### TARGET
|
||||
The CMake target to build.
|
||||
|
||||
If this parameter is not passed, no target will be passed to the build.
|
||||
|
||||
### LOGFILE_BASE
|
||||
An alternate root name for the logs.
|
||||
|
||||
Defaults to `build-${TARGET_TRIPLET}`. It should not contain any path separators. Logs will be generated matching the pattern `${CURRENT_BUILDTREES_DIR}/${LOGFILE_BASE}-<suffix>.log`
|
||||
|
||||
## Examples
|
||||
|
||||
```cmake
|
||||
vcpkg_from_github(OUT_SOURCE_PATH source_path ...)
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH "${source_path}"
|
||||
OPTIONS
|
||||
-DBUILD_EXAMPLES=OFF
|
||||
-DBUILD_TESTS=OFF
|
||||
)
|
||||
vcpkg_cmake_build(TARGET my.install.target)
|
||||
```
|
||||
|
||||
[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_build+path%3A%2Fports)
|
||||
|
||||
## Remarks
|
||||
|
||||
This command replaces [`vcpkg_build_cmake()`](vcpkg_build_cmake.md).
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake)
|
||||
@ -1,137 +0,0 @@
|
||||
# vcpkg_cmake_configure
|
||||
|
||||
**The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_configure.md).**
|
||||
|
||||
Configure a CMake-based project.
|
||||
|
||||
## Usage
|
||||
|
||||
```cmake
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH <source-path>
|
||||
[DISABLE_PARALLEL_CONFIGURE]
|
||||
[NO_CHARSET_FLAG]
|
||||
[WINDOWS_USE_MSBUILD]
|
||||
[GENERATOR <generator>]
|
||||
[LOGFILE_BASE <logname-base>]
|
||||
[OPTIONS
|
||||
<configure-setting>...]
|
||||
[OPTIONS_RELEASE
|
||||
<configure-setting>...]
|
||||
[OPTIONS_DEBUG
|
||||
<configure-setting>...]
|
||||
[MAYBE_UNUSED_VARIABLES
|
||||
<option-name>...]
|
||||
)
|
||||
```
|
||||
|
||||
To use this function, you must depend on the helper port [`vcpkg-cmake`](ports/vcpkg-cmake.md):
|
||||
```no-highlight
|
||||
"dependencies": [
|
||||
{
|
||||
"name": "vcpkg-cmake",
|
||||
"host": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
### SOURCE_PATH
|
||||
Specifies the directory containing the `CMakeLists.txt`.
|
||||
|
||||
This value is usually obtained as a result of calling a source acquisition command like [`vcpkg_from_github()`](vcpkg_from_github.md).
|
||||
|
||||
### DISABLE_PARALLEL_CONFIGURE
|
||||
Disables running the CMake configure step in parallel.
|
||||
|
||||
By default vcpkg disables writing back to the source directory (via the undocumented CMake flag `CMAKE_DISABLE_SOURCE_CHANGES`) and (on Windows) configures Release and Debug in parallel. This flag instructs vcpkg to allow source directory writes and to execute the configure steps sequentially.
|
||||
|
||||
### NO_CHARSET_FLAG
|
||||
Disables passing `/utf-8` when using the [built-in Windows toolchain][VCPKG_CHAINLOAD_TOOLCHAIN_FILE].
|
||||
|
||||
This is needed for libraries that set their own source code's character set when targeting MSVC. See the [MSVC documentation for `/utf-8`](https://docs.microsoft.com/cpp/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8) for more information.
|
||||
|
||||
### WINDOWS_USE_MSBUILD
|
||||
Use MSBuild instead of another generator when targeting a Windows platform.
|
||||
|
||||
By default vcpkg prefers to use Ninja as the CMake Generator for all platforms. However, there are edge cases where MSBuild has different behavior than Ninja. This flag should only be passed if the project requires MSBuild to build correctly.
|
||||
This flag has no effect for MinGW targets.
|
||||
|
||||
### GENERATOR
|
||||
Specifies the Generator to use.
|
||||
|
||||
By default vcpkg prefers to use Ninja as the CMake Generator for all platforms,
|
||||
or "Unix Makefiles" for non-Windows platforms when Ninja is not available.
|
||||
This parameter can be used for edge cases where project-specific buildsystems depend on a particular generator.
|
||||
|
||||
### LOGFILE_BASE
|
||||
An alternate root name for the configure logs.
|
||||
|
||||
Defaults to `config-${TARGET_TRIPLET}`. It should not contain any path separators. Logs will be generated matching the pattern `${CURRENT_BUILDTREES_DIR}/${LOGFILE_BASE}-<suffix>.log`
|
||||
|
||||
### OPTIONS
|
||||
Additional options to pass to CMake during the configuration.
|
||||
|
||||
See also [Implicit Options](#implicit-options).
|
||||
|
||||
### OPTIONS_RELEASE
|
||||
Additional options to pass to CMake during the Release configuration.
|
||||
|
||||
These are in addition to `OPTIONS`.
|
||||
|
||||
### OPTIONS_DEBUG
|
||||
Additional options to pass to CMake during the Debug configuration.
|
||||
|
||||
These are in addition to `OPTIONS`.
|
||||
|
||||
### MAYBE_UNUSED_VARIABLES
|
||||
List of CMake options that may not be read during the configure step.
|
||||
|
||||
vcpkg will warn about any options outside this list that were not read during the CMake configure step. This list should contain options that are only read during certain configurations (such as when `VCPKG_LIBRARY_LINKAGE` is `"static"` or when certain features are enabled).
|
||||
|
||||
## Implicit Options
|
||||
This command automatically provides several options to CMake.
|
||||
|
||||
- [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) is set to `"Release"` or `"Debug"` as appropriate.
|
||||
- [`BUILD_SHARED_LIBS`](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html) is set according to the value of [`VCPKG_LIBRARY_LINKAGE`](../users/triplets.md#vcpkg_library_linkage).
|
||||
- [`CMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}</debug>`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) as appropriate to the configuration
|
||||
- [`CMAKE_TOOLCHAIN_FILE`](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html) and `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` are set to include the [vcpkg toolchain file](../users/buildsystems/cmake-integration.md#cmake_toolchain_file) and the [triplet toolchain][VCPKG_CHAINLOAD_TOOLCHAIN_FILE].
|
||||
- [`CMAKE_SYSTEM_NAME=${VCPKG_CMAKE_SYSTEM_NAME}`](https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_NAME.html). If `VCPKG_CMAKE_SYSTEM_NAME` is unset, defaults to `"Windows"`.
|
||||
- [`CMAKE_SYSTEM_VERSION=${VCPKG_CMAKE_SYSTEM_VERSION}`](https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html) if `VCPKG_CMAKE_SYSTEM_VERSION` is set.
|
||||
- [`CMAKE_EXPORT_NO_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.html)
|
||||
- [`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.html)
|
||||
- [`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.html)
|
||||
- [`CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP=TRUE`](https://cmake.org/cmake/help/latest/module/InstallRequiredSystemLibraries.html)
|
||||
- [`CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.html)
|
||||
- [`CMAKE_INSTALL_LIBDIR:STRING=lib`](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html)
|
||||
- [`CMAKE_INSTALL_BINDIR:STRING=bin`](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html)
|
||||
|
||||
This command also passes all options in [`VCPKG_CMAKE_CONFIGURE_OPTIONS`](../users/triplets.md#vcpkg_cmake_configure_options) and the configuration-specific options from `VCPKG_CMAKE_CONFIGURE_OPTIONS_RELEASE` or `VCPKG_CMAKE_CONFIGURE_OPTIONS_DEBUG`.
|
||||
|
||||
Finally, there are additional internal options passed in (with a `VCPKG_` prefix) that should not be depended upon.
|
||||
|
||||
## Examples
|
||||
|
||||
```cmake
|
||||
vcpkg_from_github(OUT_SOURCE_PATH source_path ...)
|
||||
vcpkg_cmake_configure(
|
||||
SOURCE_PATH "${source_path}"
|
||||
OPTIONS
|
||||
-DBUILD_EXAMPLES=OFF
|
||||
-DBUILD_TESTS=OFF
|
||||
)
|
||||
vcpkg_cmake_install()
|
||||
```
|
||||
|
||||
[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_configure+path%3A%2Fports)
|
||||
|
||||
## Remarks
|
||||
|
||||
This command replaces [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake)
|
||||
|
||||
[ninja]: https://ninja-build.org/
|
||||
[VCPKG_CHAINLOAD_TOOLCHAIN_FILE]: ../users/triplets.md#VCPKG_CHAINLOAD_TOOLCHAIN_FILE
|
||||
@ -1,53 +0,0 @@
|
||||
# vcpkg_cmake_install
|
||||
|
||||
**The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_install.md).**
|
||||
|
||||
Build and install a cmake project.
|
||||
|
||||
## Usage
|
||||
|
||||
```cmake
|
||||
vcpkg_cmake_install(
|
||||
[DISABLE_PARALLEL]
|
||||
[ADD_BIN_TO_PATH]
|
||||
)
|
||||
```
|
||||
|
||||
To use this function, you must depend on the helper port [`vcpkg-cmake`](ports/vcpkg-cmake.md):
|
||||
```no-highlight
|
||||
"dependencies": [
|
||||
{
|
||||
"name": "vcpkg-cmake",
|
||||
"host": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
### DISABLE_PARALLEL
|
||||
Disables running the build in parallel.
|
||||
|
||||
By default builds are run with up to [VCPKG_MAX_CONCURRENCY](../users/config-environment.md#VCPKG_MAX_CONCURRENCY) jobs. This option limits the build to a single job and should be used only if the underlying build is unable to run correctly with concurrency.
|
||||
|
||||
### ADD_BIN_TO_PATH
|
||||
Adds the configuration-specific `bin/` directory to the `PATH` during the build.
|
||||
|
||||
When building for a Windows dynamic triplet, newly built executables may not be immediately executable because their dependency DLLs may not be findable from the build environment. This flag instructs vcpkg to add any additional paths needed to locate those dependency DLLs to the `PATH` environment variable. This is required if the project needs to execute newly built binaries as part of the build (such as to generate code).
|
||||
|
||||
## Examples:
|
||||
|
||||
```cmake
|
||||
vcpkg_from_github(OUT_SOURCE_PATH source_path ...)
|
||||
vcpkg_cmake_configure(SOURCE_PATH "${source_path}")
|
||||
vcpkg_cmake_install()
|
||||
```
|
||||
|
||||
[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_install+path%3A%2Fports)
|
||||
|
||||
## Remarks
|
||||
|
||||
This command replaces [`vcpkg_install_cmake()`](vcpkg_install_cmake.md).
|
||||
|
||||
## Source
|
||||
[ports/vcpkg-cmake/vcpkg\_cmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_install.cmake)
|
||||
@ -1,38 +0,0 @@
|
||||
# vcpkg_common_definitions
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_common_definitions.md).
|
||||
|
||||
This file defines the following variables which are commonly needed or used in portfiles:
|
||||
|
||||
```cmake
|
||||
PORT The name of the port that is currently being built
|
||||
VERSION The version of the port that is currently being built
|
||||
VCPKG_TARGET_IS_<target> with <target> being one of the following: WINDOWS, UWP, MINGW, LINUX, OSX, ANDROID, FREEBSD, OPENBSD, EMSCRIPTEN. only defined if <target>
|
||||
VCPKG_HOST_IS_<host> with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <host>
|
||||
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_HOST_BUNDLE_SUFFIX bundle suffix of the host
|
||||
VCPKG_TARGET_BUNDLE_SUFFIX bundle 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
|
||||
TARGET_TRIPLET the name of the current triplet to build for
|
||||
CURRENT_INSTALLED_DIR the absolute path to the installed files for the current triplet
|
||||
HOST_TRIPLET the name of the triplet corresponding to the host
|
||||
CURRENT_HOST_INSTALLED_DIR the absolute path to the installed files for the host triplet
|
||||
VCPKG_CROSSCOMPILING Whether vcpkg is cross-compiling: in other words, whether TARGET_TRIPLET and HOST_TRIPLET are different
|
||||
```
|
||||
|
||||
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)
|
||||
@ -1,87 +0,0 @@
|
||||
# vcpkg_configure_cmake
|
||||
|
||||
**This function has been deprecated in favor of [`vcpkg_cmake_configure`](vcpkg_cmake_configure.md) from the [`vcpkg-cmake`](ports/vcpkg-cmake.md) port.**
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_cmake.md).
|
||||
|
||||
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>...]
|
||||
[MAYBE_UNUSED_VARIABLES <OPTION_NAME>...]
|
||||
)
|
||||
```
|
||||
|
||||
## 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`.
|
||||
|
||||
### MAYBE_UNUSED_VARIABLES
|
||||
Any CMake variables which are explicitly passed in, but which may not be used on all platforms.
|
||||
For example:
|
||||
```cmake
|
||||
vcpkg_cmake_configure(
|
||||
...
|
||||
OPTIONS
|
||||
-DBUILD_EXAMPLE=OFF
|
||||
...
|
||||
MAYBE_UNUSED_VARIABLES
|
||||
BUILD_EXAMPLE
|
||||
)
|
||||
```
|
||||
|
||||
### LOGNAME
|
||||
Name of the log to write the output of the configure call to.
|
||||
|
||||
## 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)
|
||||
@ -1,34 +0,0 @@
|
||||
# vcpkg_configure_gn
|
||||
|
||||
**This function has been deprecated in favor of [`vcpkg_gn_configure`](ports/vcpkg-gn/vcpkg_gn_configure.md) from the vcpkg-gn port.**
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_gn.md).
|
||||
|
||||
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)
|
||||
@ -1,97 +0,0 @@
|
||||
# vcpkg_configure_make
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_make.md).
|
||||
|
||||
Configure configure for Debug and Release builds of a project.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_configure_make(
|
||||
SOURCE_PATH <${SOURCE_PATH}>
|
||||
[AUTOCONFIG]
|
||||
[USE_WRAPPERS] [NO_WRAPPERS]
|
||||
[DETERMINE_BUILD_TRIPLET]
|
||||
[BUILD_TRIPLET "--host=x64 --build=i686-unknown-pc"]
|
||||
[NO_ADDITIONAL_PATHS]
|
||||
[CONFIG_DEPENDENT_ENVIRONMENT <SOME_VAR>...]
|
||||
[CONFIGURE_ENVIRONMENT_VARIABLES <SOME_ENVVAR>...]
|
||||
[ADD_BIN_TO_PATH]
|
||||
[DISABLE_VERBOSE_FLAGS]
|
||||
[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
|
||||
|
||||
### USE_WRAPPERS
|
||||
Use autotools ar-lib and compile wrappers (only applies to windows cl and lib)
|
||||
|
||||
### NO_WRAPPERS
|
||||
Deactivate the use of autotools ar-lib and compile wrappers (only applies to windows cl and lib)
|
||||
|
||||
### BUILD_TRIPLET
|
||||
Used to pass custom --build/--target/--host to configure. Can be globally overwritten by VCPKG_MAKE_BUILD_TRIPLET
|
||||
|
||||
### DETERMINE_BUILD_TRIPLET
|
||||
For ports having a configure script following the autotools rules for selecting the triplet
|
||||
|
||||
### NO_ADDITIONAL_PATHS
|
||||
Don't pass any additional paths except for --prefix to the configure call
|
||||
|
||||
### 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)
|
||||
|
||||
### ADD_BIN_TO_PATH
|
||||
Adds the appropriate Release and Debug `bin\` directories to the path during configure such that executables can run against the in-tree DLLs.
|
||||
|
||||
### DISABLE_VERBOSE_FLAGS
|
||||
Do not pass '--disable-silent-rules --verbose' to 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`.
|
||||
|
||||
### CONFIG_DEPENDENT_ENVIRONMENT
|
||||
List of additional configuration dependent environment variables to set.
|
||||
Pass SOMEVAR to set the environment and have SOMEVAR_(DEBUG|RELEASE) set in the portfile to the appropriate values
|
||||
General environment variables can be set from within the portfile itself.
|
||||
|
||||
### CONFIGURE_ENVIRONMENT_VARIABLES
|
||||
List of additional environment variables to pass via the configure call.
|
||||
|
||||
## 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)
|
||||
@ -1,44 +0,0 @@
|
||||
# vcpkg_configure_meson
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_meson.md).
|
||||
|
||||
Configure Meson for Debug and Release builds of a project.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_configure_meson(
|
||||
SOURCE_PATH <${SOURCE_PATH}>
|
||||
[NO_PKG_CONFIG]
|
||||
[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`.
|
||||
|
||||
### NO_PKG_CONFIG
|
||||
Disable pkg-config setup
|
||||
|
||||
## 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)
|
||||
@ -1,29 +0,0 @@
|
||||
# vcpkg_configure_qmake
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_qmake.md).
|
||||
|
||||
Configure a qmake-based project.
|
||||
|
||||
```cmake
|
||||
vcpkg_configure_qmake(
|
||||
SOURCE_PATH <pro_file_path>
|
||||
[OPTIONS arg1 [arg2 ...]]
|
||||
[OPTIONS_RELEASE arg1 [arg2 ...]]
|
||||
[OPTIONS_DEBUG arg1 [arg2 ...]]
|
||||
[BUILD_OPTIONS arg1 [arg2 ...]]
|
||||
[BUILD_OPTIONS_RELEASE arg1 [arg2 ...]]
|
||||
[BUILD_OPTIONS_DEBUG arg1 [arg2 ...]]
|
||||
)
|
||||
```
|
||||
|
||||
### SOURCE_PATH
|
||||
The path to the *.pro qmake project file.
|
||||
|
||||
### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
|
||||
The options passed to qmake to the configure step.
|
||||
|
||||
### BUILD\_OPTIONS, BUILD\_OPTIONS\_RELEASE, BUILD\_OPTIONS\_DEBUG
|
||||
The options passed to qmake to the build step.
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_configure\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)
|
||||
@ -1,29 +0,0 @@
|
||||
# vcpkg_copy_pdbs
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_pdbs.md).
|
||||
|
||||
Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
|
||||
|
||||
```cmake
|
||||
vcpkg_copy_pdbs(
|
||||
[BUILD_PATHS <glob>...])
|
||||
```
|
||||
|
||||
The `<glob>`s are patterns which will be passed to `file(GLOB_RECURSE)`,
|
||||
for locating DLLs. It defaults to using:
|
||||
|
||||
- `${CURRENT_PACKAGES_DIR}/bin/*.dll`
|
||||
- `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`
|
||||
|
||||
since that is generally where DLLs are located.
|
||||
|
||||
## Notes
|
||||
This command should always be called by portfiles after they have finished rearranging the binary output.
|
||||
|
||||
## Examples
|
||||
|
||||
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
|
||||
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_copy\_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)
|
||||
@ -1,23 +0,0 @@
|
||||
# vcpkg_copy_tool_dependencies
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_tool_dependencies.md).
|
||||
|
||||
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)
|
||||
@ -1,36 +0,0 @@
|
||||
# vcpkg_copy_tools
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_tools.md).
|
||||
|
||||
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>]
|
||||
[DESTINATION <${CURRENT_PACKAGES_DIR}/tools/${PORT}>]
|
||||
[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 omitted.
|
||||
|
||||
### DESTINATION
|
||||
Destination to copy the tools to. This will be set to `${CURRENT_PACKAGES_DIR}/tools/${PORT}` if omitted.
|
||||
|
||||
### AUTO_CLEAN
|
||||
Auto clean the copied executables from `${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)
|
||||
@ -1,62 +0,0 @@
|
||||
# vcpkg_download_distfile
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_download_distfile.md).
|
||||
|
||||
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...>
|
||||
[ALWAYS_REDOWNLOAD]
|
||||
)
|
||||
```
|
||||
## 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.
|
||||
|
||||
### QUIET
|
||||
Suppress output on cache hit
|
||||
|
||||
### SKIP_SHA512
|
||||
Skip SHA512 hash check for file.
|
||||
|
||||
This switch is only valid when building with the `--head` command line flag.
|
||||
|
||||
### ALWAYS_REDOWNLOAD
|
||||
Avoid caching; this is a REST call or otherwise unstable.
|
||||
|
||||
Requires `SKIP_SHA512`.
|
||||
|
||||
### 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)
|
||||
@ -1,38 +0,0 @@
|
||||
# vcpkg_execute_build_process
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_build_process.md).
|
||||
|
||||
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)
|
||||
@ -1,21 +0,0 @@
|
||||
# vcpkg_execute_in_download_mode
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_in_download_mode.md).
|
||||
|
||||
Execute a process even in download mode.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_execute_in_download_mode(
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
The signature of this function is identical to `execute_process()`.
|
||||
|
||||
See [`execute_process()`] for more details.
|
||||
|
||||
[`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_execute\_in\_download\_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)
|
||||
@ -1,62 +0,0 @@
|
||||
# vcpkg_execute_required_process
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_required_process.md).
|
||||
|
||||
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>
|
||||
[TIMEOUT <seconds>]
|
||||
[OUTPUT_VARIABLE <var>]
|
||||
[ERROR_VARIABLE <var>]
|
||||
[SAVE_LOG_FILES <relative-path> [ALIAS <unique-alias>] [<relative-path>...]]
|
||||
)
|
||||
```
|
||||
## 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.
|
||||
|
||||
### TIMEOUT
|
||||
Optional timeout after which to terminate the command.
|
||||
|
||||
### OUTPUT_VARIABLE
|
||||
Optional variable to receive stdout of the command.
|
||||
|
||||
### ERROR_VARIABLE
|
||||
Optional variable to receive stderr of the command.
|
||||
|
||||
This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
|
||||
|
||||
### SAVE_LOG_FILES
|
||||
|
||||
Optional files to be moved from the working directory to `${CURRENT_BUILDTREES_DIR}`.
|
||||
The files are copied even if the process failed.
|
||||
This helps to collect relevant log files in CI setups.
|
||||
|
||||
The target filename is constructed from the `LOGNAME` parameter and the parameter of the `ALIAS` keyword following the source path.
|
||||
If `ALIAS` is absent, the target filename is constructed from the `LOGNAME` parameter, the source filename,
|
||||
and the suffix `.log` if the source filename doesn't already end with this suffix.
|
||||
|
||||
## Examples
|
||||
|
||||
* [boost-build](https://github.com/Microsoft/vcpkg/blob/master/ports/boost-build/portfile.cmake)
|
||||
* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
|
||||
* [qt5-base](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5-base/cmake/configure_qt.cmake)
|
||||
* [vcpkg-cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake)
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_execute\_required\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)
|
||||
@ -1,19 +0,0 @@
|
||||
# vcpkg_execute_required_process_repeat
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_required_process_repeat.md).
|
||||
|
||||
Execute a process until the command succeeds, or until the COUNT is reached.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_execute_required_process_repeat(
|
||||
COMMAND <cmd> [<arguments>]
|
||||
COUNT <num>
|
||||
WORKING_DIRECTORY <directory>
|
||||
LOGNAME <name>
|
||||
[ALLOW_IN_DOWNLOAD_MODE]
|
||||
)
|
||||
```
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_execute\_required\_process\_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)
|
||||
@ -1,154 +0,0 @@
|
||||
# vcpkg_extract_source_archive
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_extract_source_archive.md).
|
||||
|
||||
Extract an archive.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_extract_source_archive(
|
||||
<out-var>
|
||||
ARCHIVE <path>
|
||||
[NO_REMOVE_ONE_LEVEL]
|
||||
[SKIP_PATCH_CHECK]
|
||||
[PATCHES <patch>...]
|
||||
[SOURCE_BASE <base>]
|
||||
[BASE_DIRECTORY <relative-path> | WORKING_DIRECTORY <absolute-path>]
|
||||
)
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
<a id="out-var"></a>
|
||||
|
||||
### `<out-var>`
|
||||
|
||||
Name of the variable to set with the directory containing the extracted contents.
|
||||
|
||||
### ARCHIVE
|
||||
|
||||
Full path to the archive to extract.
|
||||
|
||||
### NO_REMOVE_ONE_LEVEL
|
||||
|
||||
Skip removing the top level directory of the archive.
|
||||
|
||||
Most archives contain a single top-level directory, such as:
|
||||
|
||||
```
|
||||
zlib-1.2.11/
|
||||
doc/
|
||||
...
|
||||
examples/
|
||||
...
|
||||
ChangeLog
|
||||
CMakeLists.txt
|
||||
README
|
||||
zlib.h
|
||||
...
|
||||
```
|
||||
|
||||
By default, `vcpkg_extract_source_archive` removes this directory and moves all contents into the directory returned in `<out-var>`. If there is no top-level directory, it is an error.
|
||||
|
||||
With this flag, the top-level directory will be preserved and it is not an error to not have one.
|
||||
|
||||
### SKIP_PATCH_CHECK
|
||||
|
||||
Silence and ignore errors when applying patches.
|
||||
|
||||
This option should only be passed when operating in an unstable mode like `--head`. If the sources are pinned, failing to apply a patch should be considered a fatal error.
|
||||
|
||||
### PATCHES
|
||||
|
||||
List of patches to apply to the extracted source.
|
||||
|
||||
Patches will be applied in order, after any top-level directories are removed (see [`NO_REMOVE_ONE_LEVEL`](#no_remove_one_level)). Relative paths are interpreted relative to the current port directory.
|
||||
|
||||
If a patch should be conditionally applied based on target information, you can construct a list and splat it.
|
||||
|
||||
```cmake
|
||||
set(patches "")
|
||||
if(VCPKG_TARGET_IS_WINDOWS)
|
||||
list(APPEND patches only-windows.patch)
|
||||
endif()
|
||||
vcpkg_extract_source_archive(src
|
||||
ARCHIVE "${archive}"
|
||||
PATCHES
|
||||
always-applied.patch
|
||||
${patches}
|
||||
)
|
||||
```
|
||||
|
||||
### SOURCE_BASE
|
||||
|
||||
Pretty name for the extracted directory.
|
||||
|
||||
Must not contain path separators (`/` or `\\`).
|
||||
|
||||
See [`WORKING_DIRECTORY`](#working_directory) for more details.
|
||||
|
||||
### BASE_DIRECTORY
|
||||
|
||||
Root subfolder for the extracted directory.
|
||||
|
||||
Defaults to `src`. Must be a relative path.
|
||||
|
||||
See [`WORKING_DIRECTORY`](#working_directory) for more details.
|
||||
|
||||
### WORKING_DIRECTORY
|
||||
|
||||
Root folder for the extracted directory.
|
||||
|
||||
Defaults to `${CURRENT_BUILDTREES_DIR}/<BASE_DIRECTORY>`. Must be an absolute path.
|
||||
|
||||
`vcpkg_extract_source_archive` extracts the archive into `<WORKING_DIRECTORY>/<SOURCE_BASE>-<short-hash>.clean`. If the folder exists, it is deleted before extraction. Without specifying `SOURCE_BASE`, `BASE_DIRECTORY`, or `WORKING_DIRECTORY`, this will default to `${CURRENT_BUILDTREES_DIR}/src/<archive-stem>-<short-hash>.clean`.
|
||||
|
||||
In [`--editable`](../commands/install.md#editable) mode:
|
||||
1. No `.clean` suffix is added to the extracted folder
|
||||
2. The extracted folder is not deleted. If it exists, `vcpkg_extract_source_archive` does nothing.
|
||||
|
||||
`<short-hash>` unambiguously identifies a particular set of archive and patch file contents.
|
||||
Any modifications to the contents of the working directory after calling this function should be applied unconditionally
|
||||
in order to avoid unexpected behavior in editable mode.
|
||||
|
||||
## Examples
|
||||
|
||||
```cmake
|
||||
vcpkg_download_distfile(
|
||||
archive # "archive" is set to the path to the downloaded file
|
||||
URLS "https://nmap.org/dist/nmap-7.70.tar.bz2"
|
||||
FILENAME "nmap-7.70.tar.bz2"
|
||||
SHA512 084c148b022ff6550e269d976d0077f7932a10e2ef218236fe13aa3a70b4eb6506df03329868fc68cb3ce78e4360b200f5a7a491d3145028fed679ef1c9ecae5
|
||||
)
|
||||
vcpkg_extract_source_archive(
|
||||
src # "src" is set to the path to the extracted files
|
||||
ARCHIVE "${archive}"
|
||||
SOURCE_BASE nmap.org-nmap-7.70
|
||||
PATCHES
|
||||
0001-disable-werror.patch
|
||||
)
|
||||
vcpkg_cmake_configure(SOURCE_PATH "${src}")
|
||||
```
|
||||
|
||||
* [GitHub Search](https://github.com/microsoft/vcpkg/search?q=vcpkg_extract_source_archive+path%3A%2Fports)
|
||||
|
||||
## Remarks
|
||||
|
||||
**Deprecated Syntax**
|
||||
|
||||
This command also supports a deprecated overload:
|
||||
|
||||
```cmake
|
||||
vcpkg_extract_source_archive(<archive> [<working_directory>])
|
||||
```
|
||||
|
||||
The deprecated overload extracts `<archive>` into `${working_directory}/<archive-filename>.extracted` if the target does not exist. This incorrect behavior allows patches and other modifications to leak between different builds, resulting in hard-to-debug errors.
|
||||
|
||||
All uses of the deprecated overload should be replaced with the syntax in [Usage](#usage) above by adding an explicit [`ARCHIVE`](#archive) parameter and replacing direct references to the extracted path with uses of the [`<out-var>`](#out-var).
|
||||
|
||||
**Replacement**
|
||||
|
||||
This command replaces [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md).
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_extract\_source\_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)
|
||||
@ -1,22 +0,0 @@
|
||||
# vcpkg_extract_source_archive_ex
|
||||
|
||||
**This function has been deprecated in favor of [`vcpkg_extract_source_archive()`].**
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_extract_source_archive_ex.md).
|
||||
|
||||
Extract an archive.
|
||||
|
||||
## Usage
|
||||
```cmake
|
||||
vcpkg_extract_source_archive_ex(
|
||||
[OUT_SOURCE_PATH <out-var>]
|
||||
[<options>...]
|
||||
)
|
||||
```
|
||||
|
||||
This command forwards all options to [`vcpkg_extract_source_archive()`], with `<out-var>` as the first argument. Equivalent to `vcpkg_extract_source_archive(<out-var> <options>...)`. See the documentation for [`vcpkg_extract_source_archive()`] for parameter help.
|
||||
|
||||
[`vcpkg_extract_source_archive()`]: vcpkg_extract_source_archive.md
|
||||
|
||||
## Source
|
||||
[scripts/cmake/vcpkg\_extract\_source\_archive\_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)
|
||||
@ -1,45 +0,0 @@
|
||||
# vcpkg_fail_port_install
|
||||
|
||||
**This function has been deprecated in favor of the `supports` field in [`manifest file`](manifest-files.md#supports) et al.**
|
||||
|
||||
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fail_port_install.md).
|
||||
|
||||
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)
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user