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