diff --git a/docs/examples/manifest-mode-cmake.md b/docs/examples/manifest-mode-cmake.md index 7087da020b5608..2a780f7de43745 100644 --- a/docs/examples/manifest-mode-cmake.md +++ b/docs/examples/manifest-mode-cmake.md @@ -1,6 +1,6 @@ # Manifest Mode: CMake Example -We would like to add vcpkg manifest support to an existing cmake project! +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. diff --git a/docs/users/versioning.getting-started.md b/docs/examples/versioning.getting-started.md similarity index 79% rename from docs/users/versioning.getting-started.md rename to docs/examples/versioning.getting-started.md index 6be419adfdd7c7..c83eddb5914b35 100644 --- a/docs/users/versioning.getting-started.md +++ b/docs/examples/versioning.getting-started.md @@ -1,22 +1,43 @@ # 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. ## Enabling versions -To start using the versioning feature, first you need to enable the `versions` feature flag in any of the following manners: +To start using [versioning](../users/versioning.md), first you need to enable the `versions` feature flag in any of the following manners: -* Setting the `VCPKG_FEATURE_FLAGS` environment variable. +* Setting the `VCPKG_FEATURE_FLAGS` environment variable ```PowerShell # Example for PowerShell $env:VCPKG_FEATURE_FLAGS="versions" -./vcpkg install +``` +```bash +# Example for bash +export VCPKG_FEATURE_FLAGS=versions +``` +```cmd +REM Example for cmd +SET VCPKG_FEATURE_FLAGS=versions ``` -* Passing the feature flags in the vcpkg command line. -```PowerShell -./vcpkg --feature-flags="versions" install +* Passing the feature flags in the vcpkg command line +```bash +./vcpkg install --feature-flags=versions +``` + +* Setting `VCPKG_FEATURE_FLAGS` before your `project()` CMake directive +```cmake +set(VCPKG_FEATURE_FLAGS versions) +project(myapp) +``` +* Setting `VcpkgAdditionalInstallOptions` (Project Properties -> Vcpkg -> Additional Options) in your MSBuild project +```xml + + --feature-flags=versions + ``` ## Using versions with manifests @@ -28,7 +49,7 @@ 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", @@ -61,7 +82,7 @@ int main() ```CMake cmake_minimum_required(VERSION 3.18) -project(versions-test CXX) +project(versionstest CXX) add_executable(main main.cpp) @@ -109,42 +130,40 @@ fmt[core]:x86-windows -> 7.1.3 -- D:\vcpkg\buildtrees\versioning\versions\fmt\dd 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 or when the `versions` feature flag is disabled. +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 or when the `versions` feature flag is disabled. -_NOTE: Output from the 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._ +_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`** -``` +#### **`version`** +```json { "name": "versions-test", - "version": "1.0.0", - ... + "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`. +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-date` | Dates in `YYYY-MM-DD` format: `2021-01-01` `version-string` | Arbitrary strings: `vista`, `candy`. -* **`version>=`** -``` -"dependencies": [ - { - "name": "fmt", - "version>=": "7.1.3" - }, - "zlib" -], +#### **`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` of `fmt`. @@ -155,7 +174,7 @@ Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8. If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline. -* **`builtin-baseline`** +#### **`builtin-baseline`** ``` "builtin-baseline": "b60f003ccf5fe8613d029f49f835c8929a66eb61" @@ -163,7 +182,7 @@ If you want to upgrade your dependencies, you can bump the minimum version const 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. But what is a baseline? What does it do? Why is the value a SHA? -From the [versioning documentation](versioning.md): +From the [versioning documentation](../users/versioning.md): > The baseline references a commit within the vcpkg repository that establishes a minimum version on every dependency in the graph. If @@ -197,7 +216,7 @@ Baselines are also a convenient mechanism to upgrade multiple versions at a time But what if you want to pin a version older than the baseline? -* **`overrides`** +#### **`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. @@ -264,11 +283,11 @@ If you want to have flexible port customization along with versioning features, ## 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](versioning.implementation-details.md). +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](versioning.md) +* [Versioning docs](../users/versioning.md) * [Original specification](../specifications/versioning.md) -* [Versioning reference](versioning.reference.md) -* [Versioning implementation details](versioning.implementation-details.md) +* [Versioning reference](../users/versioning.reference.md) +* [Versioning implementation details](../users/versioning.implementation-details.md) diff --git a/docs/index.md b/docs/index.md index af8584fb97c275..00a17a5b4444c9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,7 @@ ### Quick Start +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/index.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 @@ -8,20 +10,23 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too - [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md) - [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md) - [Patching Example: Patching libpng to work for x86-uwp](examples/patching.md) +- [Getting Started with Versioning](examples/versioning.getting-started.md) ### User Help - [Integration with build systems](users/integration.md) - [Triplet files](users/triplets.md) - [Configuration and Environment](users/config-environment.md) +- [Manifests](users/manifests.md) +- [Binary Caching](users/binarycaching.md) +- [Versioning](users/versioning.md) - [Usage with Android](users/android.md) -- [Using a manifest file to declare your dependencies](users/manifests.md) - [Host Dependencies](users/host-dependencies.md) -### Maintainer help +### Maintainer Help -- [Control files](maintainers/control-files.md) - in general, one should use manifest files instead -- [Manifest files](maintainers/manifest-files.md) +- [Manifest files - vcpkg.json](maintainers/manifest-files.md) +- [Control files](maintainers/control-files.md) - [Portfile functions](maintainers/portfile-functions.md) - [Maintainer Guidelines](maintainers/maintainer-guide.md) diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md index ab5f0eea34ee60..4951a8888ba3a9 100644 --- a/docs/maintainers/control-files.md +++ b/docs/maintainers/control-files.md @@ -1,7 +1,7 @@ # CONTROL files -CONTROL files are retained for backwards compatibility with earlier versions of vcpkg; -all new features are added only to vcpkg.json, and we recommend using vcpkg.json for any newly authored port. +**CONTROL files are retained for backwards compatibility with earlier versions of vcpkg; +all new features are added only to [vcpkg.json](manifests.md), and we recommend using vcpkg.json for any newly authored port.** The `CONTROL` file contains metadata about the port. The syntax is based on [the Debian `control` format][debian] although we only support the subset of fields documented here. diff --git a/docs/specifications/binarycaching.md b/docs/specifications/binarycaching.md index 3bbd766e1adb03..d9c55d5d140ffb 100644 --- a/docs/specifications/binarycaching.md +++ b/docs/specifications/binarycaching.md @@ -2,6 +2,8 @@ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** +**Up-to-date documentation is available at [Binarycaching](../users/binarycaching.md).** + ## Motivation The primary motivation of binary caching is to accelerate two broad scenarios in an easily accessible way diff --git a/docs/specifications/export-command.md b/docs/specifications/export-command.md index 4111bfed44b531..5464e9408d5783 100644 --- a/docs/specifications/export-command.md +++ b/docs/specifications/export-command.md @@ -1,5 +1,7 @@ # Binary Export (Apr 28, 2017) +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** + ## 1. Motivation ### A. Build once and share diff --git a/docs/specifications/feature-packages.md b/docs/specifications/feature-packages.md index 81afba0807c04a..5737c650a64dd7 100644 --- a/docs/specifications/feature-packages.md +++ b/docs/specifications/feature-packages.md @@ -1,6 +1,8 @@ # Proposal: Features / Feature packages (Feb 23 2017) -**Note: this is the proposal as it was initially accepted and does not necessarily reflect the current behavior.** +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** + +**Up-to-date documentation is available at [Selecting Library Features](../users/selecting-library-features.md).** ## 1. Motivation diff --git a/docs/specifications/manifests.md b/docs/specifications/manifests.md index bc4e1d7cca4ad3..f095e77f25cc8c 100644 --- a/docs/specifications/manifests.md +++ b/docs/specifications/manifests.md @@ -1,5 +1,9 @@ # Manifests -- `vcpkg.json` +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** + +**Up-to-date documentation is available at [Manifests](../users/manifests.md).** + For many other language package managers, there exists a way of writing one's dependencies in a declarative manifest format; we want something similar for vcpkg. What follows is the specification of that feature; this should mean that vcpkg becomes far more user and enterprise-friendly, and is additionally an important diff --git a/docs/specifications/ports-overlay.md b/docs/specifications/ports-overlay.md index d486cfe193bff1..632954fc34375d 100644 --- a/docs/specifications/ports-overlay.md +++ b/docs/specifications/ports-overlay.md @@ -1,5 +1,6 @@ # Ports Overlay (Jun 19, 2019) +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** ## 1. Motivation diff --git a/docs/specifications/prefab.md b/docs/specifications/prefab.md index 4574e01ee8779a..f94758b490f8a0 100644 --- a/docs/specifications/prefab.md +++ b/docs/specifications/prefab.md @@ -1,5 +1,7 @@ # Vcpkg: export Android prefab Archives (AAR files) +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** + Vcpkg can export android archives ([AAR files](https://developer.android.com/studio/projects/android-library)). Once an archive is created, it can imported in Android Studio as a native dependent. The archive is automatically consumed using [android studio's prefab tool](https://github.com/google/prefab). For more information on Prefab, refer to: diff --git a/docs/specifications/registries-2.md b/docs/specifications/registries-2.md index 41a32886b9c62e..46429db705e3b8 100644 --- a/docs/specifications/registries-2.md +++ b/docs/specifications/registries-2.md @@ -1,5 +1,7 @@ # Registries: Take 2 (including Git Registries) +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** + Originally, the design of registries was decided upon and written up in the [Registries RFC](registries.md). However, as we've gotten further into the design process of git registries and versioning, and discussed the interaction of versioning with registries, diff --git a/docs/specifications/registries.md b/docs/specifications/registries.md index 48b392a5c1d684..426593829cf005 100644 --- a/docs/specifications/registries.md +++ b/docs/specifications/registries.md @@ -1,5 +1,7 @@ # Package Federation: Custom Registries +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** + As it is now, vcpkg has over 1400 ports in the default registry (the `/ports` directory). For the majority of users, this repository of packages is enough. However, many enterprises need to more closely control their dependencies for one reason or another, and this document diff --git a/docs/specifications/scripts-extraction.md b/docs/specifications/scripts-extraction.md index a617a77413f735..396e2d4e0273aa 100644 --- a/docs/specifications/scripts-extraction.md +++ b/docs/specifications/scripts-extraction.md @@ -1,5 +1,7 @@ # Scripts Tree Extraction +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** + ## Background We extracted vcpkg-tool as part of a future wherein Registries are the primary mechanism for interacting with the ports tree, which would allow the vcpkg tool and associated artifacts to be deployed and figure the rest out on their own. Unfortunately, we have concurrently edited things in the so called "scripts" tree which lives in support of ports but really probably belongs in the vcpkg-tool repo. diff --git a/docs/specifications/versioning.md b/docs/specifications/versioning.md index 960e87f1892019..e8122c3595a517 100644 --- a/docs/specifications/versioning.md +++ b/docs/specifications/versioning.md @@ -1,5 +1,9 @@ # Versioning Specification +**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** + +**Up-to-date documentation is available at [Versioning](../users/versioning.md).** + ## Glossary Some of the terms used in this document have similar meaning when discussed by the community, and because of that, they can cause confusion and ambiguity. To solve this issue, we will assign specific meaning to these terms and try to keep a consistent usage through the document. diff --git a/docs/users/android.md b/docs/users/android.md index 6ff1d05d15bef7..b56030f55d7014 100644 --- a/docs/users/android.md +++ b/docs/users/android.md @@ -1,5 +1,7 @@ # Vcpkg and Android +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/android.md).** + Android is not officialy supported, and there are no official android triplets at the moment. However, some packages can compile to Android, and the situation is improving: see the list of [PR related to Android](https://github.com/Microsoft/vcpkg/pulls?q=+android+). diff --git a/docs/users/binarycaching.md b/docs/users/binarycaching.md index a388e406569a12..b7783698454fb4 100644 --- a/docs/users/binarycaching.md +++ b/docs/users/binarycaching.md @@ -1,5 +1,7 @@ # Binary Caching +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/binarycaching.md).** + Binary caching is vcpkg's method for reusing package builds between projects and between machines. Think of it as a "package restore accelerator" that gives you the same results as though you built from source. Each build is packaged independently, so changing one library only requires rebuilding consuming libraries. If your CI provider offers a native "caching" function, we recommend using both methods for the most performant results. diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md index e164bc0e7c4c81..169b2aff73299f 100644 --- a/docs/users/config-environment.md +++ b/docs/users/config-environment.md @@ -1,5 +1,7 @@ ## Environment and Configuration +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/config-environment.md).** + ### Environment Variables #### VCPKG_DOWNLOADS diff --git a/docs/users/integration.md b/docs/users/integration.md index 933d2ce82e482f..ba8ea4d8bcbce3 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -1,5 +1,7 @@ ## Buildsystem Integration +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/integration.md).** + Vcpkg offers many ways to integrate into your build so you can do what's right for your project. There are two main categories of integration: - [`integrate` command](#integrate) diff --git a/docs/users/manifests.md b/docs/users/manifests.md index 2ee64ec3e0fe45..9cec98cfaa91a1 100644 --- a/docs/users/manifests.md +++ b/docs/users/manifests.md @@ -1,6 +1,8 @@ # Manifest Mode -vcpkg has two modes of operation - classic mode and manifest mode. +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/manifests.md).** + +vcpkg has two modes of consuming dependencies - classic mode and manifest mode. In classic mode, vcpkg produces an "installed" tree, whose contents are changed by explicit calls to `vcpkg install` or `vcpkg remove`. The installed tree is intended for consumption by any number of projects: for example, installing a diff --git a/docs/users/selecting-library-features.md b/docs/users/selecting-library-features.md index 03c1863b34de81..51d828280af940 100644 --- a/docs/users/selecting-library-features.md +++ b/docs/users/selecting-library-features.md @@ -1,30 +1,25 @@ # Selecting library features +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/selecting-library-features.md).** + ## Installing a library -We will look at [llvm](https://llvm.org/) as an example. -LLVM is a compiler infrasture. It supports optimizing llvm-ir and generating machine code. -You could install it using: +We will look at [llvm](https://llvm.org/) as an example. You could install it using: ```powershell -> .\vcpkg install llvm +> vcpkg install llvm ``` - -On Windows, this will install the 32-bit x86 LLVM, since that's the default triplet on Windows. -If you are building for 64-bit Windows instead, you can use the following command to change the default triplet: - -```powershell -> .\vcpkg install --triplet x64-windows llvm +or via a manifest with +```json +{ + "dependencies": ["llvm"] +} ``` -We have more documentation on triplets [here](triplets.md). -Currently we can't choose build type `debug` or `release` using command line switches. - With llvm now installed, we can execute: ```powershell -> # llc takes llvm IR and generates machine code -> .\installed\x86-windows\bin\llc.exe --version # or x86-windows, or replace with the actual triplet +> installed\x86-windows\bin\llc.exe --version ``` we see: @@ -45,7 +40,7 @@ The llvm port allows this via the "target-*" features. If we do: ```powershell -.\vcpkg search llvm +> vcpkg search llvm ``` We can see: @@ -64,17 +59,33 @@ llvm[target-arm] Build with ARM backend. We can install any of these targets by using the install-feature syntax: ```powershell -> .\vcpkg install llvm[target-arm] # Installs LLVM with the ARM target +> vcpkg install llvm[target-arm] # Installs LLVM with the ARM target +``` +```json +{ + "dependencies": [{ "name": "llvm", "features": ["target-arm"] }] +} ``` -## Opting out of default feature +## Opting out of default features + The llvm port includes a few default features that you as a user may not want: for example, the `clang` feature is default, which means that `vcpkg install llvm` will also build and install clang. If you are writing a compiler that uses LLVM as a backend, you're likely not interested in installing clang as well, and we can do that by disabling default features with the special `core` "feature": ```powershell -> .\vcpkg install llvm[core,default-targets] # removing the default-feature with "core" also removes all of the default targets you get +> vcpkg install llvm[core,target-arm] # removing the default-feature with "core" also removes all of the default targets you get +``` +or in manifest files: +```json +{ + "dependencies": [{ + "name": "llvm", + "default-features": false, + "features": ["target-arm"] + }] +} ``` # Further reading diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 37efd590d09838..61192575a64b8b 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -1,5 +1,7 @@ # Triplet files +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/triplets.md).** + Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name. In Vcpkg, we use triplets to describe an imaginary "target configuration set" for every library. Within a triplet, libraries are generally built with the same configuration, but it is not a requirement. For example, you could have one triplet that builds `openssl` statically and `zlib` dynamically, one that builds them both statically, and one that builds them both dynamically (all for the same target OS and architecture). A single build will consume files from a single triplet. diff --git a/docs/users/versioning.implementation-details.md b/docs/users/versioning.implementation-details.md index f363fb438d99a1..fc5981e24f20ab 100644 --- a/docs/users/versioning.implementation-details.md +++ b/docs/users/versioning.implementation-details.md @@ -1,5 +1,7 @@ # Versioning: Implementation details +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.implementation-details.md).** + ## Contents * [Minimum versioning](#minimum-versioning) diff --git a/docs/users/versioning.md b/docs/users/versioning.md index 5db7f42c21e0e2..6fdc678e520c41 100644 --- a/docs/users/versioning.md +++ b/docs/users/versioning.md @@ -1,11 +1,13 @@ # Versioning +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.md).** + **This feature is experimental and requires `--feature-flags=versions`** Versioning allows you to deterministically control the precise revisions of dependencies used by your project from within your manifest file. -See our guide to [getting started with versioning](versioning.getting-started.md). +See our guide to [getting started with versioning](../examples/versioning.getting-started.md). ## Version schemes diff --git a/docs/users/versioning.reference.md b/docs/users/versioning.reference.md index eb49b44e2d152b..976b8461228d04 100644 --- a/docs/users/versioning.reference.md +++ b/docs/users/versioning.reference.md @@ -1,5 +1,7 @@ # Versioning reference +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.reference.md).** + ## Contents * [Version schemes](#version-schemes) @@ -114,7 +116,7 @@ Each port in vcpkg has a corresponding versions file, the location of a port's v ``` ${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json -```` +``` For example, for `zlib` the corresponding versions file is: