Unify manifest mode articles and fix links

.openpublishing.redirection.json

@@ -9,6 +9,15 @@
             "source_path": "vcpkg/users/registries.md",
             "redirect_url": "/vcpkg/concepts/registries",
             "redirect_document_id": true
+        },
+        {
+            "source_path": "vcpkg/users/classic-mode.md",
+            "redirect_url": "/vcpkg/concepts/classic-mode",
+            "redirect_document_id": true
+        },
+        {
+            "source_path": "vcpkg/users/manifests.md",
+            "redirect_url": "/vcpkg/concepts/manifest-mode"
         }
     ]
 }

vcpkg/about/faq.md

@@ -10,8 +10,25 @@ ms.topic: faq
 
 There are two ways to manage your dependencies with vcpkg:
 
-1. **Manifest mode** lets you declare your direct dependencies, version constraints, and used registries in a file called [`vcpkg.json`](../reference/vcpkg-json.md). This file should be included in your code repository and can be checked in to your source control system. Dependencies are installed in a subfolder named `vcpkg_installed`. This way, each code project can have its own set of dependencies; nothing is installed system-wide. You can run vcpkg in manifest mode by running `vcpkg install` (with no other arguments), or by taking advantage of the automatic [integration with MSBuild](../users/buildsystems/msbuild-integration.md) and [CMake projects](../users/buildsystems/cmake-integration.md). We recommend using manifests for your projects over classic mode in most cases, as you have better control over your dependencies. See our [Manifest mode article](../concepts/manifest-mode.md) for more details.
-2. **Classic mode** is the more traditional way of managing dependencies, which involves running vcpkg commands that specify each direct dependency to install, modify, or remove. Dependencies are stored within the vcpkg installation directory, so multiple consuming projects can reference the same set of dependencies. See our [Classic mode article](../users/classic-mode.md) for more details.
+1. **Manifest mode** lets you declare your direct dependencies, version
+   constraints, and used registries in a file called
+   [`vcpkg.json`](../reference/vcpkg-json.md). This file should be included in
+   your code repository and can be checked in to your source control system.
+   Dependencies are installed in a subfolder named `vcpkg_installed`. This way,
+   each code project can have its own set of dependencies; nothing is installed
+   system-wide. You can run vcpkg in manifest mode by running `vcpkg install`
+   (with no other arguments), or by taking advantage of the automatic
+   [integration with MSBuild](../users/buildsystems/msbuild-integration.md) and
+   [CMake projects](../users/buildsystems/cmake-integration.md). We recommend
+   using manifests for your projects over classic mode in most cases, as you
+   have better control over your dependencies. See our [Manifest mode
+   article](../concepts/manifest-mode.md) for more details.
+2. **Classic mode** is the more traditional way of managing dependencies, which
+   involves running vcpkg commands that specify each direct dependency to
+   install, modify, or remove. Dependencies are stored within the vcpkg
+   installation directory, so multiple consuming projects can reference the same
+   set of dependencies. See our [Classic mode
+   article](../concepts/classic-mode.md) for more details.
 
 ## Can I contribute a new library?
 
@@ -76,7 +93,10 @@ Execute `git pull` to get the latest sources, then run `bootstrap-vcpkg.bat` (Wi
 
 ## How do I use different versions of a library on one machine?
 
-We suggest using [manifest files](../users/manifests.md) to manage dependencies for individual projects, which works even if multiple projects are on the same machine and allow you to easily manage package versions and which registries libraries are coming from.
+We suggest using [manifest files](../concepts/manifest-mode.md) to manage
+dependencies for individual projects, which works even if multiple projects are
+on the same machine and allow you to easily manage package versions and which
+registries libraries are coming from.
 
 However, if you are using classic mode instead, 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. In this case, to use different versions of a library for different projects, we recommend making separate instances of vcpkg and using the per-project integration mechanisms. 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`.
 

vcpkg/commands/common-options.md

@@ -90,17 +90,20 @@ Defaults to the [`VCPKG_DEFAULT_HOST_TRIPLET`](../users/config-environment.md#vc
 
 Specifies the path to lay out installed packages.
 
-In [Classic mode](../users/classic-mode.md), defaults to `installed/` under the vcpkg root folder.
+In [Classic mode](../concepts/classic-mode.md), defaults to `installed/` under
+the vcpkg root folder.
 
-In [Manifest mode](../users/manifests.md), defaults to `vcpkg_installed/` under the manifest folder.
+In [Manifest mode](../concepts/manifest-mode.md), defaults to `vcpkg_installed/`
+under the manifest folder.
 
 ### <a name="manifest-root"></a> `--x-manifest-root=<path>`
 
 [!INCLUDE [experimental](../../includes/experimental.md)]
 
-Specifies the directory containing [`vcpkg.json`](../users/manifests.md).
+Specifies the directory containing [`vcpkg.json`](../concepts/manifest-mode.md).
 
-Defaults to searching upwards from the current working directory for the nearest `vcpkg.json`.
+Defaults to searching upwards from the current working directory for the nearest
+`vcpkg.json`.
 
 ### <a name="overlay-ports"></a> `--overlay-ports=<path>`
 

vcpkg/commands/export.md

@@ -22,7 +22,9 @@ Exports built packages from the [installed directory](common-options.md#install-
 3. [Integration files](#standard-integration), such as a [CMake toolchain][cmake] or [MSBuild props/targets][msbuild]
 
 >[!NOTE]
->This command's behavior is different in [Classic Mode](../users/classic-mode.md) and [Manifest Mode](../users/manifests.md)
+> This command's behavior is different in [Classic
+> Mode](../concepts/classic-mode.md) and [Manifest
+> Mode](../concepts/manifest-mode.md)
 
 The `export` command does not install any packages or transitive dependencies. It only exports packages that are already installed. 
 

vcpkg/commands/install.md

@@ -25,7 +25,10 @@ Build and install port packages.
 
 ### Classic mode
 
-In [Classic mode](../users/classic-mode.md), this verb adds port packages to the existing set in the [installed directory](common-options.md#install-root) (defaults to `installed/` under the vcpkg root). This can require removing and rebuilding existing packages, which can fail.
+In [Classic mode](../concepts/classic-mode.md), this verb adds port packages to
+the existing set in the [installed directory](common-options.md#install-root)
+(defaults to `installed/` under the vcpkg root). This can require removing and
+rebuilding existing packages, which can fail.
 
 #### <a name="package-syntax"></a> Package Syntax
 
@@ -37,7 +40,9 @@ Package references without a triplet are automatically qualified by the [default
 
 ### Manifest mode
 
-In [Manifest mode](../users/manifests.md), this verb sets the [installed directory](common-options.md#install-root) to the state specified by the `vcpkg.json` manifest file, adding, removing, or rebuilding packages as needed.
+In [Manifest mode](../concepts/manifest-mode.md), this command sets the [installed
+directory](common-options.md#install-root) to the state specified by the
+`vcpkg.json` manifest file, adding, removing, or rebuilding packages as needed.
 
 ## Options
 
@@ -105,7 +110,10 @@ By default, vcpkg will run several checks on built packages and emit warnings if
 
 Specify an additional [feature](../concepts/features.md) from the `vcpkg.json` to install dependencies for.
 
-By default, only [`"dependencies"`](../reference/vcpkg-json.md#dependencies) and the dependencies of [`"default-features"`](../reference/vcpkg-json.md#default-features) will be installed.
+By default, only [`"dependencies"`](../reference/vcpkg-json.md#dependencies) and
+the dependencies of
+[`"default-features"`](../reference/vcpkg-json.md#default-features) will be
+installed.
 
 ### `--head`
 

vcpkg/commands/remove.md

@@ -21,7 +21,7 @@ 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](../users/manifests.md).
+This command is not currently supported in [Manifest mode](../concepts/manifest-mode.md).
 
 ## Options
 

vcpkg/commands/update-baseline.md

@@ -17,7 +17,11 @@ vcpkg x-update-baseline [options] [--add-initial-baseline] [--dry-run]
 
 Update baselines for all configured [registries](../reference/vcpkg-configuration-json.md#registries).
 
-In [Manifest mode](../users/manifests.md), this command operates on all registries in the [`vcpkg.json`](../reference/vcpkg-json.md) and the [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md). In Classic mode, this command operates on the `vcpkg-configuration.json` in the vcpkg instance (`$VCPKG_ROOT`).
+In [Manifest mode](../concepts/manifest-mode.md), this command operates on all
+registries in the [`vcpkg.json`](../reference/vcpkg-json.md) and the
+[`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md). In
+Classic mode, this command operates on the `vcpkg-configuration.json` in the
+vcpkg instance (`$VCPKG_ROOT`).
 
 See the [versioning documentation](../users/versioning.md#baselines) for more information about baselines.
 

vcpkg/commands/update.md

@@ -38,4 +38,4 @@ To only remove outdated packages, run
 
 All vcpkg commands support a set of [common options](common-options.md).
 
-[Classic mode]: ../users/classic-mode.md
+[Classic mode]: ../concepts/classic-mode.md

vcpkg/commands/upgrade.md

@@ -54,5 +54,5 @@ By default, on a package install failure, vcpkg will continue to attempt to inst
 
 Allow performing upgrades to unsupported packages.
 
-[Classic mode]: ../users/classic-mode.md
-[Manifest mode]: ../users/manifests.md
+[Classic mode]: ../concepts/classic-mode.md
+[Manifest mode]: ../concepts/manifest-mode.md

vcpkg/concepts/classic-mode.md

@@ -0,0 +1,24 @@
+---
+title: Classic mode
+description: Use vcpkg in Classic mode to share a central instance of installed libraries.
+author: vicroms
+ms.author: viromer
+ms.date: 02/10/2024
+ms.topic: concept-article
+---
+
+# Classic mode
+
+vcpkg has two operation modes: classic mode and
+[manifest mode](manifest-mode.md). For most users, we recommend manifest mode.
+
+In classic mode, vcpkg maintains a central *installed tree* inside the vcpkg
+instance built up by individual [`vcpkg install`](../commands/install.md) and
+[`vcpkg remove`](../commands/remove.md) commands. This central set of packages
+can then be shared by any number of projects.
+
+Because the set of installed packages is not associated with an individual
+project, classic mode operates similarly to tools like `brew` or `apt`. However,
+the set is still associated with a vcpkg instance, and each instance of vcpkg
+(such as separate `git clone` copies) will have its own set of classic mode
+packages installed.

vcpkg/concepts/manifest-mode.md

@@ -11,26 +11,29 @@ ms.topic: concept-article
 
 # What is manifest mode?
 
-vcpkg has two operation modes: classic mode and manifest mode. This article
-describes the capabilities of manifest mode, which is the recommended
-mode for most users.
+vcpkg has two operation modes: [classic mode](classic-mode.md) and manifest
+mode. For most users, we recommned manifest mode.
 
 Manifest mode uses declarative JSON files to describe metadata about your
-project or package. In any case, the name of this file is 
+project or package. In any case, the name of this file is
 [`vcpkg.json`](../reference/vcpkg-json.md).
 
+Manifest mode is engaged by running the `vcpkg install` command while there's a
+manifest file (`vcpkg.json`) in the working directory. Read ahead for details on
+how to [install packages in manifest mode](#install-manifest-mode).
+
 Manifest mode is also required to use advanced features like
-[versioning](../users/versioning.md) and 
+[versioning](../users/versioning.md) and
 [custom registries](../users/registries.md).
 
-## Manifest files in your packages
+## Manifest files in ports
 
 All vcpkg ports must include a `vcpkg.json` file that describes metadata about
 the package they install.
 
 vcpkg uses the metadata in the package manifest for various purposes, such as,
 calculating dependency trees, searching for packages by name or description,
-resolving version constraints, etc.
+resolving features, etc.
 
 ### Package manifest example
 
@@ -54,10 +57,12 @@ resolving version constraints, etc.
 }
 ```
 
-## Manifest files in your projects
+## Manifest files in projects
+
 The main purpose of using a manifest file in your project is to declare your
-dependencies. When used on a project, you're also able to specify version 
-constraints and overrides to lock specific versions of your dependencies.
+dependencies. When using a project manifest, you're able to specify version
+constraints and overrides to lock specific versions of your dependencies. This 
+feature is not available in classic mode.
 
 ### Project manifest example
 
@@ -72,8 +77,9 @@ constraints and overrides to lock specific versions of your dependencies.
 ```
 
 ## Configuration file
+
 vcpkg can be configured through a `vcpkg-configuration.json` file to add more
-[package registries](../users/registries.md) or 
+[package registries](../users/registries.md) or
 [overlay ports and triplets](../concepts/overlay-ports.md) locations.
 
 ### Configuration file example
@@ -99,10 +105,82 @@ vcpkg can be configured through a `vcpkg-configuration.json` file to add more
 }
 ```
 
+## <a name="install-manifest-mode"></a> Installing packages in manifest mode
+
+To install packages using a manifest file you use the
+[`vcpkg install`](../commands/install.md) command without any package arguments.
+The command must be executed from a directory containing a manifest
+([`vcpkg.json`](../reference/vcpkg-json.md)) file, or the path to a manifest
+file provided by using the `--x-manifest-root=<path>` option.
+
+Packages installed in manifest mode will not be installed in the global
+[`installed`](../reference/installation-tree-layout.md) directory as they do in
+classic mode. Instead, each manifest gets its own installation directory named
+`vcpkg_installed`; the `vcpkg_installed` directory is created in the same
+directory that contains the manifest file.
+
+Having independent installation trees per manifest allows separation of
+dependencies between different projects. This circumvents a crucial limitation
+of classic mode, which only allows one version of each port to be installed.
+Manifest mode keeps versions of ports separated per project.
+
+## Using features in project manifests
+
+Manifest files can define additive sets of functionality, behavior, and
+dependencies through the use of
+["features"](../reference/vcpkg-json.md#features).
+
+In your projects, you may define features to enable or disable dependencies that
+apply to parts of your project. For example, if your project contains multiple
+components, you may want to keep common dependencies in the `"dependencies"`
+list but limit some others to their respective components.
+
+To enable features of your project you can use one of the following methods:
+
+- Pass the [`--x-feature`](../commands/install.md#feature) option to your `vpckg
+  install` command.
+- On CMake, set the
+  [`VCPKG_MANIFEST_FEATURES`](../users/buildsystems/cmake-integration.md) before
+  the first call to `project()`.
+- On MSBuild, pass the `--x-feature` option via
+  [`VcpkgAdditionalInstallOptions](../users/buildsystems/msbuild-integration.md#vcpkg-additional-install-options).
+
+### Example: Features in project manifests
+
+```json
+{
+  "name": "my-game",
+  "dependencies": [ "grpc" ],
+  "features": {
+    "client": {
+      "description": "client game executable",
+      "dependencies": [ "sdl2", "bullet3" ]
+    }, 
+    "server": {
+      "description": "multiplayer server executable",
+      "dependencies": [ "proxygen" ]
+    }, 
+    "tests": {
+      "description": "development tests",
+      "dependencies": [ "gtest" ]
+    }
+  }
+} 
+```
+
+To build only the "client" component's dependencies run:
+
+```Console
+vcpkg install --x-feature=client
+```
+
 ## Next steps
 
 Here are some tasks to try next:
 
-* Lock down your versions for repeatable builds using [versioning](../users/versioning.concepts.md)
-* Reuse binaries across local or continuous integration runs using [binary caching](../users/binarycaching.md)
-* Manage your private libraries using custom [registries](../maintainers/registries.md)
+- Complete the [manifest mode tutorial](../consume/manifest-mode.md)
+- Read the [`vcpkg.json`](../reference/vcpkg-json.md) and
+  [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md)
+  reference articles.
+- Lock down your versions for repeatable builds using
+  [versioning](../users/versioning.concepts.md)

vcpkg/concepts/triplets.md

@@ -34,7 +34,7 @@ environment.
 
 To select a target triplet:
 
-* In [classic mode](../users/classic-mode.md):
+* In [classic mode](../concepts/classic-mode.md):
   * Qualify package references with the triplet name, such as `zlib:x64-windows-static-md`.
   * Pass [`--triplet=<triplet>`](../commands/common-options.md#triplet).
 * In CMake:
@@ -44,7 +44,7 @@ To select a target triplet:
 
 To select the host triplet for the current machine:
 
-* In [classic mode](../users/classic-mode.md):
+* In [classic mode](../concepts/classic-mode.md):
   * Pass [`--host-triplet=<triplet>`](../commands/common-options.md#host-triplet).
 * In CMake:
   * Set [`VCPKG_HOST_TRIPLET`](../users/buildsystems/cmake-integration.md#vcpkg_host_triplet).
@@ -76,7 +76,8 @@ First, copy a built-in triplet file from the `triplets\` directory into a
 different filesystem location. Then, add that directory to the list of overlay
 triplet paths when interacting with vcpkg.
 
-* In [Manifest mode](../users/manifests.md), you can use [`$.vcpkg-configuration.overlay-triplets`](../reference/vcpkg-configuration-json.md#overlay-triplets).
+* In [Manifest mode](../concepts/manifest-mode.md), you can use
+  [`$.vcpkg-configuration.overlay-triplets`](../reference/vcpkg-configuration-json.md#overlay-triplets).
 * When using vcpkg from CMake, you can set [`VCPKG_OVERLAY_TRIPLETS`](../users/buildsystems/cmake-integration.md#vcpkg_overlay_triplets).
 * When using vcpkg from MSBuild, you can add [`--overlay-triplets=...`][overlay-triplets] to [MSBuild Additional Options](../users/buildsystems/msbuild-integration.md#vcpkg-additional-install-options).
 * When using the CLI directly, you can pass [`--overlay-triplets=...`][overlay-triplets].

vcpkg/get_started/get-started-msbuild.md

@@ -176,5 +176,5 @@ If MSBuild detects a `vcpkg.json` file and manifests are enabled in your project
 To learn more about `vcpkg.json` and vcpkg MSBuild integration, see our reference documentation:
 
 - [vcpkg.json](..\reference\vcpkg-json.md)
-- [manifest](..\users\manifests.md)
+- [manifest](..\concepts\manifest-mode.md)
 - [vcpkg in MSBuild projects](..\users\buildsystems\msbuild-integration.md)

vcpkg/get_started/get-started-vs.md

@@ -180,4 +180,4 @@ This tutorial shows you how to create a C++ "Hello World" program that uses the
 To learn more about `vcpkg.json`, see our reference documentation:
 
 - [vcpkg.json](..\reference\vcpkg-json.md)
-- [manifest](..\users\manifests.md)
+- [manifest](..\concepts\manifest-mode.md)