diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 72b93180..14ee6220 100644 --- a/.openpublishing.redirection.json +++ b/.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" } ] } \ No newline at end of file diff --git a/vcpkg/TOC.yml b/vcpkg/TOC.yml index 4f5adc03..05a7b992 100644 --- a/vcpkg/TOC.yml +++ b/vcpkg/TOC.yml @@ -70,7 +70,7 @@ - name: Produce packages expanded: true items: - # TODO: Modernize: examples/packaging-github-repos.md + # TODO: Modernize: examples/packaging-github-repos.md - name: Package a dependency from a public GitHub repository href: examples/packaging-github-repos.md # TODO: Modernize: examples/packaging-zipfiles.md @@ -116,7 +116,7 @@ - name: Manual integration href: users/buildsystems/manual-integration.md - name: Classic mode - href: users/classic-mode.md + href: concepts/classic-mode.md - name: Default features href: concepts/default-features.md - name: Features @@ -138,8 +138,6 @@ - name: Host Dependencies displayName: host, dependencies href: users/host-dependencies.md - - name: Manifests - href: users/manifests.md - name: Open-source registry items: - name: Maintainer guide @@ -166,236 +164,236 @@ href: users/versioning.concepts.md - name: Reference items: - - name: vcpkg.json Reference - href: reference/vcpkg-json.md - - name: vcpkg-configuration.json Reference - href: reference/vcpkg-configuration-json.md - - name: Command-Line - items: - - name: Common Command Options - href: commands/common-options.md - - name: vcpkg add - href: commands/add.md - - name: vcpkg x-add-version - href: commands/add-version.md - - name: vcpkg contact - href: commands/contact.md - - name: vcpkg create - href: commands/create.md - - name: vcpkg depend-info - href: commands/depend-info.md - - name: vcpkg edit - href: commands/edit.md - - name: vcpkg env - href: commands/env.md - - name: vcpkg export - href: commands/export.md - - name: vcpkg format-manifest - href: commands/format-manifest.md - - name: vcpkg hash - href: commands/hash.md - - name: vcpkg help - href: commands/help.md - - name: vcpkg install - href: commands/install.md - - name: vcpkg integrate - href: commands/integrate.md - - name: vcpkg list - href: commands/list.md - - name: vcpkg new - href: commands/new.md - - name: vcpkg owns - href: commands/owns.md - - name: vcpkg remove - href: commands/remove.md - - name: vcpkg search - href: commands/search.md - - name: vcpkg update - href: commands/update.md - - name: vcpkg x-update-baseline - href: commands/update-baseline.md - - name: vcpkg upgrade - href: commands/upgrade.md - - name: vcpkg version - href: commands/version.md - - name: Asset caching - displayName: airgap, offline, source, mirror - href: users/assetcaching.md - - name: Binary caching - displayName: binaries, build - href: users/binarycaching.md - - name: Environment variables - href: users/config-environment.md - - name: Installation tree layout - href: reference/installation-tree-layout.md - - name: Portfile functions - items: - - name: vcpkg_acquire_msys - href: maintainers/functions/vcpkg_acquire_msys.md - - name: vcpkg_add_to_path - href: maintainers/functions/vcpkg_add_to_path.md - - name: vcpkg_apply_patches - href: maintainers/functions/vcpkg_apply_patches.md - - name: vcpkg_backup_env_variables - href: maintainers/functions/vcpkg_backup_env_variables.md - - name: vcpkg_build_cmake - href: maintainers/functions/vcpkg_build_cmake.md - - name: vcpkg_build_make - href: maintainers/functions/vcpkg_build_make.md - - name: vcpkg_build_msbuild - href: maintainers/functions/vcpkg_build_msbuild.md - - name: vcpkg_build_ninja - href: maintainers/functions/vcpkg_build_ninja.md - - name: vcpkg_build_nmake - href: maintainers/functions/vcpkg_build_nmake.md - - name: vcpkg_build_qmake - href: maintainers/functions/vcpkg_build_qmake.md - - name: vcpkg_buildpath_length_warning - href: maintainers/functions/vcpkg_buildpath_length_warning.md - - name: vcpkg_check_features - href: maintainers/functions/vcpkg_check_features.md - - name: vcpkg_check_linkage - href: maintainers/functions/vcpkg_check_linkage.md - - name: vcpkg_clean_executables_in_bin - href: maintainers/functions/vcpkg_clean_executables_in_bin.md - - name: vcpkg_clean_msbuild - href: maintainers/functions/vcpkg_clean_msbuild.md - - name: vcpkg_cmake_build - href: maintainers/functions/vcpkg_cmake_build.md - - name: vcpkg_cmake_config_fixup - href: maintainers/functions/vcpkg_cmake_config_fixup.md - - name: vcpkg_cmake_configure - href: maintainers/functions/vcpkg_cmake_configure.md - - name: vcpkg_cmake_get_vars - href: maintainers/functions/vcpkg_cmake_get_vars.md - - name: vcpkg_cmake_install - href: maintainers/functions/vcpkg_cmake_install.md - - name: vcpkg_configure_cmake - href: maintainers/functions/vcpkg_configure_cmake.md - - name: vcpkg_configure_gn - href: maintainers/functions/vcpkg_configure_gn.md - - name: vcpkg_configure_make - href: maintainers/functions/vcpkg_configure_make.md - - name: vcpkg_configure_meson - href: maintainers/functions/vcpkg_configure_meson.md - - name: vcpkg_configure_qmake - href: maintainers/functions/vcpkg_configure_qmake.md - - name: vcpkg_copy_pdbs - href: maintainers/functions/vcpkg_copy_pdbs.md - - name: vcpkg_copy_tool_dependencies - href: maintainers/functions/vcpkg_copy_tool_dependencies.md - - name: vcpkg_copy_tools - href: maintainers/functions/vcpkg_copy_tools.md - - name: vcpkg_download_distfile - href: maintainers/functions/vcpkg_download_distfile.md - - name: vcpkg_download_sourceforge - href: maintainers/functions/vcpkg_download_sourceforge.md - - name: vcpkg_execute_build_process - href: maintainers/functions/vcpkg_execute_build_process.md - - name: vcpkg_execute_in_download_mode - href: maintainers/functions/vcpkg_execute_in_download_mode.md - - name: vcpkg_execute_required_process - href: maintainers/functions/vcpkg_execute_required_process.md - - name: vcpkg_execute_required_process_repeat - href: maintainers/functions/vcpkg_execute_required_process_repeat.md - - name: vcpkg_extract_archive - href: maintainers/functions/vcpkg_extract_archive.md - - name: vcpkg_extract_source_archive - href: maintainers/functions/vcpkg_extract_source_archive.md - - name: vcpkg_extract_source_archive_ex - href: maintainers/functions/vcpkg_extract_source_archive_ex.md - - name: vcpkg_fail_port_install - href: maintainers/functions/vcpkg_fail_port_install.md - - name: vcpkg_find_acquire_program - href: maintainers/functions/vcpkg_find_acquire_program.md - - name: vcpkg_find_fortran - href: maintainers/functions/vcpkg_find_fortran.md - - name: vcpkg_fixup_cmake_targets - href: maintainers/functions/vcpkg_fixup_cmake_targets.md - - name: vcpkg_fixup_pkgconfig - href: maintainers/functions/vcpkg_fixup_pkgconfig.md - - name: vcpkg_from_bitbucket - href: maintainers/functions/vcpkg_from_bitbucket.md - - name: vcpkg_from_git - href: maintainers/functions/vcpkg_from_git.md - - name: vcpkg_from_github - href: maintainers/functions/vcpkg_from_github.md - - name: vcpkg_from_gitlab - href: maintainers/functions/vcpkg_from_gitlab.md - - name: vcpkg_from_sourceforge - href: maintainers/functions/vcpkg_from_sourceforge.md - - name: vcpkg_get_program_files_platform_bitness - href: maintainers/functions/vcpkg_get_program_files_platform_bitness.md - - name: x_vcpkg_get_python_packages - href: maintainers/functions/vcpkg_get_python_packages.md - - name: vcpkg_get_windows_sdk - href: maintainers/functions/vcpkg_get_windows_sdk.md - - name: vcpkg_gn_configure - href: maintainers/functions/vcpkg_gn_configure.md - - name: vcpkg_gn_install - href: maintainers/functions/vcpkg_gn_install.md - - name: vcpkg_host_path_list - href: maintainers/functions/vcpkg_host_path_list.md - - name: vcpkg_install_cmake - href: maintainers/functions/vcpkg_install_cmake.md - - name: vcpkg_install_copyright - href: maintainers/functions/vcpkg_install_copyright.md - - name: vcpkg_install_gn - href: maintainers/functions/vcpkg_install_gn.md - - name: vcpkg_install_make - href: maintainers/functions/vcpkg_install_make.md - - name: vcpkg_install_meson - href: maintainers/functions/vcpkg_install_meson.md - - name: vcpkg_install_msbuild - href: maintainers/functions/vcpkg_install_msbuild.md - - name: vcpkg_install_nmake - href: maintainers/functions/vcpkg_install_nmake.md - - name: vcpkg_install_qmake - href: maintainers/functions/vcpkg_install_qmake.md - - name: vcpkg_list - href: maintainers/functions/vcpkg_list.md - - name: vcpkg_minimum_required - href: maintainers/functions/vcpkg_minimum_required.md - - name: x_vcpkg_pkgconfig_get_modules - href: maintainers/functions/vcpkg_pkgconfig_get_modules.md - - name: vcpkg_qmake_build - href: maintainers/functions/vcpkg_qmake_build.md - - name: vcpkg_qmake_configure - href: maintainers/functions/vcpkg_qmake_configure.md - - name: vcpkg_qmake_install - href: maintainers/functions/vcpkg_qmake_install.md - - name: vcpkg_replace_string - href: maintainers/functions/vcpkg_replace_string.md - - name: vcpkg_restore_env_variables - href: maintainers/functions/vcpkg_restore_env_variables.md - - name: Internal - items: - - name: z_vcpkg_apply_patches - href: maintainers/functions/internal/z_vcpkg_apply_patches.md - - name: z_vcpkg_forward_output_variable - href: maintainers/functions/internal/z_vcpkg_forward_output_variable.md - - name: z_vcpkg_function_arguments - href: maintainers/functions/internal/z_vcpkg_function_arguments.md - - name: z_vcpkg_get_cmake_vars - href: maintainers/functions/internal/z_vcpkg_get_cmake_vars.md - - name: z_vcpkg_prettify_command_line - href: maintainers/functions/internal/z_vcpkg_prettify_command_line.md - - name: z_vcpkg_restore_pkgconfig_path - href: maintainers/functions/internal/z_vcpkg_restore_pkgconfig_path.md - - name: z_vcpkg_setup_pkgconfig_path - href: maintainers/functions/internal/z_vcpkg_setup_pkgconfig_path.md - - name: Portfile variables - href: maintainers/variables.md - - name: Software Bill of Materials generation - href: reference/software-bill-of-materials.md - - name: Triplets - href: users/triplets.md - - name: Versioning - href: users/versioning.md - - name: Deprecated features + - name: vcpkg.json Reference + href: reference/vcpkg-json.md + - name: vcpkg-configuration.json Reference + href: reference/vcpkg-configuration-json.md + - name: Command-Line + items: + - name: Common Command Options + href: commands/common-options.md + - name: vcpkg add + href: commands/add.md + - name: vcpkg x-add-version + href: commands/add-version.md + - name: vcpkg contact + href: commands/contact.md + - name: vcpkg create + href: commands/create.md + - name: vcpkg depend-info + href: commands/depend-info.md + - name: vcpkg edit + href: commands/edit.md + - name: vcpkg env + href: commands/env.md + - name: vcpkg export + href: commands/export.md + - name: vcpkg format-manifest + href: commands/format-manifest.md + - name: vcpkg hash + href: commands/hash.md + - name: vcpkg help + href: commands/help.md + - name: vcpkg install + href: commands/install.md + - name: vcpkg integrate + href: commands/integrate.md + - name: vcpkg list + href: commands/list.md + - name: vcpkg new + href: commands/new.md + - name: vcpkg owns + href: commands/owns.md + - name: vcpkg remove + href: commands/remove.md + - name: vcpkg search + href: commands/search.md + - name: vcpkg update + href: commands/update.md + - name: vcpkg x-update-baseline + href: commands/update-baseline.md + - name: vcpkg upgrade + href: commands/upgrade.md + - name: vcpkg version + href: commands/version.md + - name: Asset caching + displayName: airgap, offline, source, mirror + href: users/assetcaching.md + - name: Binary caching + displayName: binaries, build + href: users/binarycaching.md + - name: Environment variables + href: users/config-environment.md + - name: Installation tree layout + href: reference/installation-tree-layout.md + - name: Portfile functions + items: + - name: vcpkg_acquire_msys + href: maintainers/functions/vcpkg_acquire_msys.md + - name: vcpkg_add_to_path + href: maintainers/functions/vcpkg_add_to_path.md + - name: vcpkg_apply_patches + href: maintainers/functions/vcpkg_apply_patches.md + - name: vcpkg_backup_env_variables + href: maintainers/functions/vcpkg_backup_env_variables.md + - name: vcpkg_build_cmake + href: maintainers/functions/vcpkg_build_cmake.md + - name: vcpkg_build_make + href: maintainers/functions/vcpkg_build_make.md + - name: vcpkg_build_msbuild + href: maintainers/functions/vcpkg_build_msbuild.md + - name: vcpkg_build_ninja + href: maintainers/functions/vcpkg_build_ninja.md + - name: vcpkg_build_nmake + href: maintainers/functions/vcpkg_build_nmake.md + - name: vcpkg_build_qmake + href: maintainers/functions/vcpkg_build_qmake.md + - name: vcpkg_buildpath_length_warning + href: maintainers/functions/vcpkg_buildpath_length_warning.md + - name: vcpkg_check_features + href: maintainers/functions/vcpkg_check_features.md + - name: vcpkg_check_linkage + href: maintainers/functions/vcpkg_check_linkage.md + - name: vcpkg_clean_executables_in_bin + href: maintainers/functions/vcpkg_clean_executables_in_bin.md + - name: vcpkg_clean_msbuild + href: maintainers/functions/vcpkg_clean_msbuild.md + - name: vcpkg_cmake_build + href: maintainers/functions/vcpkg_cmake_build.md + - name: vcpkg_cmake_config_fixup + href: maintainers/functions/vcpkg_cmake_config_fixup.md + - name: vcpkg_cmake_configure + href: maintainers/functions/vcpkg_cmake_configure.md + - name: vcpkg_cmake_get_vars + href: maintainers/functions/vcpkg_cmake_get_vars.md + - name: vcpkg_cmake_install + href: maintainers/functions/vcpkg_cmake_install.md + - name: vcpkg_configure_cmake + href: maintainers/functions/vcpkg_configure_cmake.md + - name: vcpkg_configure_gn + href: maintainers/functions/vcpkg_configure_gn.md + - name: vcpkg_configure_make + href: maintainers/functions/vcpkg_configure_make.md + - name: vcpkg_configure_meson + href: maintainers/functions/vcpkg_configure_meson.md + - name: vcpkg_configure_qmake + href: maintainers/functions/vcpkg_configure_qmake.md + - name: vcpkg_copy_pdbs + href: maintainers/functions/vcpkg_copy_pdbs.md + - name: vcpkg_copy_tool_dependencies + href: maintainers/functions/vcpkg_copy_tool_dependencies.md + - name: vcpkg_copy_tools + href: maintainers/functions/vcpkg_copy_tools.md + - name: vcpkg_download_distfile + href: maintainers/functions/vcpkg_download_distfile.md + - name: vcpkg_download_sourceforge + href: maintainers/functions/vcpkg_download_sourceforge.md + - name: vcpkg_execute_build_process + href: maintainers/functions/vcpkg_execute_build_process.md + - name: vcpkg_execute_in_download_mode + href: maintainers/functions/vcpkg_execute_in_download_mode.md + - name: vcpkg_execute_required_process + href: maintainers/functions/vcpkg_execute_required_process.md + - name: vcpkg_execute_required_process_repeat + href: maintainers/functions/vcpkg_execute_required_process_repeat.md + - name: vcpkg_extract_archive + href: maintainers/functions/vcpkg_extract_archive.md + - name: vcpkg_extract_source_archive + href: maintainers/functions/vcpkg_extract_source_archive.md + - name: vcpkg_extract_source_archive_ex + href: maintainers/functions/vcpkg_extract_source_archive_ex.md + - name: vcpkg_fail_port_install + href: maintainers/functions/vcpkg_fail_port_install.md + - name: vcpkg_find_acquire_program + href: maintainers/functions/vcpkg_find_acquire_program.md + - name: vcpkg_find_fortran + href: maintainers/functions/vcpkg_find_fortran.md + - name: vcpkg_fixup_cmake_targets + href: maintainers/functions/vcpkg_fixup_cmake_targets.md + - name: vcpkg_fixup_pkgconfig + href: maintainers/functions/vcpkg_fixup_pkgconfig.md + - name: vcpkg_from_bitbucket + href: maintainers/functions/vcpkg_from_bitbucket.md + - name: vcpkg_from_git + href: maintainers/functions/vcpkg_from_git.md + - name: vcpkg_from_github + href: maintainers/functions/vcpkg_from_github.md + - name: vcpkg_from_gitlab + href: maintainers/functions/vcpkg_from_gitlab.md + - name: vcpkg_from_sourceforge + href: maintainers/functions/vcpkg_from_sourceforge.md + - name: vcpkg_get_program_files_platform_bitness + href: maintainers/functions/vcpkg_get_program_files_platform_bitness.md + - name: x_vcpkg_get_python_packages + href: maintainers/functions/vcpkg_get_python_packages.md + - name: vcpkg_get_windows_sdk + href: maintainers/functions/vcpkg_get_windows_sdk.md + - name: vcpkg_gn_configure + href: maintainers/functions/vcpkg_gn_configure.md + - name: vcpkg_gn_install + href: maintainers/functions/vcpkg_gn_install.md + - name: vcpkg_host_path_list + href: maintainers/functions/vcpkg_host_path_list.md + - name: vcpkg_install_cmake + href: maintainers/functions/vcpkg_install_cmake.md + - name: vcpkg_install_copyright + href: maintainers/functions/vcpkg_install_copyright.md + - name: vcpkg_install_gn + href: maintainers/functions/vcpkg_install_gn.md + - name: vcpkg_install_make + href: maintainers/functions/vcpkg_install_make.md + - name: vcpkg_install_meson + href: maintainers/functions/vcpkg_install_meson.md + - name: vcpkg_install_msbuild + href: maintainers/functions/vcpkg_install_msbuild.md + - name: vcpkg_install_nmake + href: maintainers/functions/vcpkg_install_nmake.md + - name: vcpkg_install_qmake + href: maintainers/functions/vcpkg_install_qmake.md + - name: vcpkg_list + href: maintainers/functions/vcpkg_list.md + - name: vcpkg_minimum_required + href: maintainers/functions/vcpkg_minimum_required.md + - name: x_vcpkg_pkgconfig_get_modules + href: maintainers/functions/vcpkg_pkgconfig_get_modules.md + - name: vcpkg_qmake_build + href: maintainers/functions/vcpkg_qmake_build.md + - name: vcpkg_qmake_configure + href: maintainers/functions/vcpkg_qmake_configure.md + - name: vcpkg_qmake_install + href: maintainers/functions/vcpkg_qmake_install.md + - name: vcpkg_replace_string + href: maintainers/functions/vcpkg_replace_string.md + - name: vcpkg_restore_env_variables + href: maintainers/functions/vcpkg_restore_env_variables.md + - name: Internal items: - - name: CONTROL Files - href: maintainers/control-files.md + - name: z_vcpkg_apply_patches + href: maintainers/functions/internal/z_vcpkg_apply_patches.md + - name: z_vcpkg_forward_output_variable + href: maintainers/functions/internal/z_vcpkg_forward_output_variable.md + - name: z_vcpkg_function_arguments + href: maintainers/functions/internal/z_vcpkg_function_arguments.md + - name: z_vcpkg_get_cmake_vars + href: maintainers/functions/internal/z_vcpkg_get_cmake_vars.md + - name: z_vcpkg_prettify_command_line + href: maintainers/functions/internal/z_vcpkg_prettify_command_line.md + - name: z_vcpkg_restore_pkgconfig_path + href: maintainers/functions/internal/z_vcpkg_restore_pkgconfig_path.md + - name: z_vcpkg_setup_pkgconfig_path + href: maintainers/functions/internal/z_vcpkg_setup_pkgconfig_path.md + - name: Portfile variables + href: maintainers/variables.md + - name: Software Bill of Materials generation + href: reference/software-bill-of-materials.md + - name: Triplets + href: users/triplets.md + - name: Versioning + href: users/versioning.md + - name: Deprecated features + items: + - name: CONTROL Files + href: maintainers/control-files.md - name: Troubleshooting items: - name: Troubleshoot asset caching issues diff --git a/vcpkg/about/faq.md b/vcpkg/about/faq.md index 1edd0985..6481c70a 100644 --- a/vcpkg/about/faq.md +++ b/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\\`. 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`. diff --git a/vcpkg/commands/common-options.md b/vcpkg/commands/common-options.md index de713d2b..97457e96 100644 --- a/vcpkg/commands/common-options.md +++ b/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. ### `--x-manifest-root=` [!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`. ### `--overlay-ports=` diff --git a/vcpkg/commands/export.md b/vcpkg/commands/export.md index 29b4aaf1..85093839 100644 --- a/vcpkg/commands/export.md +++ b/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. diff --git a/vcpkg/commands/install.md b/vcpkg/commands/install.md index 71dbbe0d..e128d77f 100644 --- a/vcpkg/commands/install.md +++ b/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. #### 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` diff --git a/vcpkg/commands/remove.md b/vcpkg/commands/remove.md index c5fde451..bc513023 100644 --- a/vcpkg/commands/remove.md +++ b/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 `` 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 diff --git a/vcpkg/commands/update-baseline.md b/vcpkg/commands/update-baseline.md index 93954f49..8e9d4a77 100644 --- a/vcpkg/commands/update-baseline.md +++ b/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. diff --git a/vcpkg/commands/update.md b/vcpkg/commands/update.md index 3c1e8452..1c887d5d 100644 --- a/vcpkg/commands/update.md +++ b/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 diff --git a/vcpkg/commands/upgrade.md b/vcpkg/commands/upgrade.md index 5f62d1f3..da70a041 100644 --- a/vcpkg/commands/upgrade.md +++ b/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 diff --git a/vcpkg/concepts/classic-mode.md b/vcpkg/concepts/classic-mode.md new file mode 100644 index 00000000..22787797 --- /dev/null +++ b/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. diff --git a/vcpkg/concepts/manifest-mode.md b/vcpkg/concepts/manifest-mode.md index 29258344..78df9942 100644 --- a/vcpkg/concepts/manifest-mode.md +++ b/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 } ``` +## 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=` 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) diff --git a/vcpkg/concepts/triplets.md b/vcpkg/concepts/triplets.md index 3d6ec481..dae0ac26 100644 --- a/vcpkg/concepts/triplets.md +++ b/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=`](../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=`](../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]. diff --git a/vcpkg/get_started/get-started-msbuild.md b/vcpkg/get_started/get-started-msbuild.md index 77a786af..8658f6e0 100644 --- a/vcpkg/get_started/get-started-msbuild.md +++ b/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) diff --git a/vcpkg/get_started/get-started-vs.md b/vcpkg/get_started/get-started-vs.md index fc867443..6e466371 100644 --- a/vcpkg/get_started/get-started-vs.md +++ b/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) diff --git a/vcpkg/get_started/get-started-vscode.md b/vcpkg/get_started/get-started-vscode.md index 9e45c28f..19a06822 100644 --- a/vcpkg/get_started/get-started-vscode.md +++ b/vcpkg/get_started/get-started-vscode.md @@ -227,4 +227,4 @@ To learn more about `vcpkg.json`, see our reference documentation: - [Packaging a library](get-started-packaging.md) - [vcpkg.json](..\reference\vcpkg-json.md) -- [manifest](..\users\manifests.md) +- [manifest](..\concepts\manifest-mode.md) diff --git a/vcpkg/get_started/get-started.md b/vcpkg/get_started/get-started.md index 595c1c8c..7ff26923 100644 --- a/vcpkg/get_started/get-started.md +++ b/vcpkg/get_started/get-started.md @@ -169,4 +169,4 @@ To learn more about `vcpkg.json`, see our reference documentation: - [Packaging a library](get-started-packaging.md) - [vcpkg.json](..\reference\vcpkg-json.md) -- [manifest](..\users\manifests.md) +- [manifest](..\concepts\manifest-mode.md) diff --git a/vcpkg/get_started/overview.md b/vcpkg/get_started/overview.md index b3e8c22d..731e89bc 100644 --- a/vcpkg/get_started/overview.md +++ b/vcpkg/get_started/overview.md @@ -37,7 +37,8 @@ While vcpkg builds libraries from source whenever it's necessary, you can back u ### Manifests -You can declare your direct dependencies and add optional features or version constraints in a [manifest file](../users/manifests.md). +You can declare your direct dependencies and add optional features or version +constraints in a [manifest file](../concepts/manifest-mode.md). ### Versioning diff --git a/vcpkg/github-integration.md b/vcpkg/github-integration.md index 466274e7..1ea17777 100644 --- a/vcpkg/github-integration.md +++ b/vcpkg/github-integration.md @@ -57,7 +57,9 @@ You must enable the GitHub dependency graph in your repository's settings (enabl ### Example GitHub Actions workflow > [!NOTE] -> This example assumes that there is a valid `vcpkg.json` manifest that lists some dependent ports. For more information on manifests, see our [documentation on manifest mode](./users/manifests.md). +> This example assumes that there is a valid `vcpkg.json` manifest that lists +> some dependent ports. For more information on manifests, see our +> [documentation on manifest mode](concepts/manifest-mode.md). ```yaml name: Populate dependencies diff --git a/vcpkg/maintainers/control-files.md b/vcpkg/maintainers/control-files.md index 241c69d0..eabc5df5 100644 --- a/vcpkg/maintainers/control-files.md +++ b/vcpkg/maintainers/control-files.md @@ -7,9 +7,12 @@ ms.topic: reference # CONTROL files > [!WARNING] -> `CONTROL` files are deprecated and only retained for backwards compatibility with earlier versions of vcpkg. Use [vcpkg.json manifest files](../users/manifests.md) for any newly authored port. +> `CONTROL` files are deprecated and only retained for backwards compatibility +> with earlier versions of vcpkg. Use [vcpkg.json manifest +> files](../concepts/manifest-mode.md) for any newly authored port. > -> Use `./vcpkg format-manifest path/to/CONTROL` to convert an existing `CONTROL` file to a `vcpkg.json` file. +> Use `./vcpkg format-manifest path/to/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](https://www.debian.org/doc/debian-policy/ch-controlfields.html) although we only support the subset of fields documented here. diff --git a/vcpkg/maintainers/handling-usage-files.md b/vcpkg/maintainers/handling-usage-files.md index ce4ab873..96fdea57 100644 --- a/vcpkg/maintainers/handling-usage-files.md +++ b/vcpkg/maintainers/handling-usage-files.md @@ -32,7 +32,11 @@ After installing ports, vcpkg detects files installed to `${CURRENT_PACKAGES_DIR Provide clear instructions on how to use the package. The content should be concise, well-structured, and emphasize the minimum build system integration required to use the library. -Be clear and concise about how to utilize the package effectively. Avoid overwhelming users with code snippets, command-line instructions, or configuration details. Instead, use the [`"documentation"` property in the port's `vcpkg.json` file](../users/manifests.md) so users can learn more about your library. +Be clear and concise about how to utilize the package effectively. Avoid +overwhelming users with code snippets, command-line instructions, or +configuration details. Instead, use the [`"documentation"` property in the +port's `vcpkg.json` file](../concepts/manifest-mode.md) so users can learn more +about your library. Use the following templates as a pattern for your `usage` files: diff --git a/vcpkg/reference/installation-tree-layout.md b/vcpkg/reference/installation-tree-layout.md index 2cb9b3aa..6813fdb7 100644 --- a/vcpkg/reference/installation-tree-layout.md +++ b/vcpkg/reference/installation-tree-layout.md @@ -13,11 +13,11 @@ directory. The installation directory holds the files installed by each package. Port authors should ensure that their packages follow the conventions described in this article. -In [classic mode](../users/classic-mode.md), the installation directory is +In [classic mode](../concepts/classic-mode.md), the installation directory is located in `$VCPKG_ROOT/installed` (where `$VCPKG_ROOT` is your vcpkg -installation path). In [manifest mode](../users/manifests.md), each manifest -file has a corresponding `vcpkg_installed` directory. The location of the -installation directory can be changed with the +installation path). In [manifest mode](../concepts/manifest-mode.md), each +manifest file has a corresponding `vcpkg_installed` directory. The location of +the installation directory can be changed with the [`--x-install-root`](../commands/common-options.md#install-root) option. Regardless of the operation mode, the layout of the installation directory remains the same. diff --git a/vcpkg/reference/software-bill-of-materials.md b/vcpkg/reference/software-bill-of-materials.md index c435cb10..5e641ec0 100644 --- a/vcpkg/reference/software-bill-of-materials.md +++ b/vcpkg/reference/software-bill-of-materials.md @@ -8,9 +8,23 @@ ms.topic: reference --- # Software Bill of Materials in vcpkg -vcpkg generates a Software Bill of Materials (SBOM) based on the [Software Package Data Exchange (SPDX)](https://spdx.github.io/spdx-spec/v2.3/) specification. It tracks important information used to build a package, such as source origin, and aims to provide package consumers with software transparency and integrity. See this [blog post about SBOM and SPDX](https://devblogs.microsoft.com/engineering-at-microsoft/generating-software-bills-of-materials-sboms-with-spdx-at-microsoft/) for more information. -vcpkg generates a SPDX file containing the SBOM information for each package that is installed. The files are located in `//share//vcpkg.spdx.json`. The installation directory depends on whether vcpkg is running on [manifest mode](../concepts/manifest-mode.md) or [classic mode](../users/classic-mode.md). Since a package can have different dependencies depending on the target platform, the generated files are separated by triplet as well. +vcpkg generates a Software Bill of Materials (SBOM) based on the [Software +Package Data Exchange (SPDX)](https://spdx.github.io/spdx-spec/v2.3/) +specification. It tracks important information used to build a package, such as +source origin, and aims to provide package consumers with software transparency +and integrity. See this [blog post about SBOM and +SPDX](https://devblogs.microsoft.com/engineering-at-microsoft/generating-software-bills-of-materials-sboms-with-spdx-at-microsoft/) +for more information. + +vcpkg generates a SPDX file containing the SBOM information for each package +that is installed. The files are located in +`//share//vcpkg.spdx.json`. The +installation directory depends on whether vcpkg is running on [manifest +mode](../concepts/manifest-mode.md) or [classic +mode](../concepts/classic-mode.md). Since a package can have different +dependencies depending on the target platform, the generated files are separated +by triplet as well. ## vcpkg specific fields The following fields generated by vcpkg may appear in your SBOM depending on how your package is built. diff --git a/vcpkg/reference/vcpkg-configuration-json.md b/vcpkg/reference/vcpkg-configuration-json.md index 962978dd..b196faa0 100644 --- a/vcpkg/reference/vcpkg-configuration-json.md +++ b/vcpkg/reference/vcpkg-configuration-json.md @@ -6,11 +6,19 @@ ms.topic: reference --- # vcpkg-configuration.json Reference -The `vcpkg-configuration.json` file forms part of a project's [manifest](../users/manifests.md), along with [`vcpkg.json`](vcpkg-json.md). All fields in the `vcpkg-configuration.json` file are only used from the top-level project -- the `vcpkg-configuration.json` files in any dependencies are ignored. - -In [Manifest Mode](../users/manifests.md), `vcpkg-configuration.json` can be in a separate file beside [`vcpkg.json`](vcpkg-json.md) or it can be embedded in the [`"vcpkg-configuration" field`](vcpkg-json.md#vcpkg-configuration). - -In [Classic Mode](../users/classic-mode.md), vcpkg will use the `vcpkg-configuration.json` file in the [root](../commands/common-options.md#vcpkg-root) of the vcpkg instance. +The `vcpkg-configuration.json` file forms part of a project's +[manifest](../concepts/manifest-mode.md), along with +[`vcpkg.json`](vcpkg-json.md). All fields in the `vcpkg-configuration.json` file +are only used from the top-level project -- the `vcpkg-configuration.json` files +in any dependencies are ignored. + +In [Manifest Mode](../concepts/manifest-mode.md), `vcpkg-configuration.json` can +be in a separate file beside [`vcpkg.json`](vcpkg-json.md) or it can be embedded +in the [`"vcpkg-configuration" field`](vcpkg-json.md#vcpkg-configuration). + +In [Classic Mode](../concepts/classic-mode.md), vcpkg will use the +`vcpkg-configuration.json` file in the +[root](../commands/common-options.md#vcpkg-root) of the vcpkg instance. For an overview of using registries with vcpkg, see [Using Registries](../consume/git-registries.md). diff --git a/vcpkg/reference/vcpkg-json.md b/vcpkg/reference/vcpkg-json.md index 94575db1..87a13bbe 100644 --- a/vcpkg/reference/vcpkg-json.md +++ b/vcpkg/reference/vcpkg-json.md @@ -6,7 +6,8 @@ ms.topic: reference --- # vcpkg.json Reference -For an overview of using manifests with vcpkg, see [Manifest mode](../users/manifests.md). +For an overview of using manifests with vcpkg, see [Manifest +mode](../concepts/manifest-mode.md). Manifests are strict [JSON](https://www.json.org) documents. They cannot contain C++-style comments (`//`) nor trailing commas. However you can use field names that start with `$` to write your comments in any object that has a well-defined set of keys. These comment fields are not allowed in any objects which permit user-defined keys (such as `"features"`). diff --git a/vcpkg/users/binarycaching-troubleshooting.md b/vcpkg/users/binarycaching-troubleshooting.md index 98ffeea0..cbc4cd83 100644 --- a/vcpkg/users/binarycaching-troubleshooting.md +++ b/vcpkg/users/binarycaching-troubleshooting.md @@ -14,8 +14,9 @@ This guide is intended for users experiencing issues with [binary caching](./bin ## Enable vcpkg debugging information It is highly recommended that you enable debug output when following this guide. -* [Classic mode](classic-mode.md): add `--debug` to your command invocation. -* CMake toolchain: add `-DVCPKG_INSTALL_OPTIONS="--debug"` in your CMake configure call or in your `CMakePresets.json` file. +* [Classic mode](../concepts/classic-mode.md): add `--debug` to your command invocation. +* CMake toolchain: add `-DVCPKG_INSTALL_OPTIONS="--debug"` in your CMake + configure call or in your `CMakePresets.json` file. * MSBuild/Visual Studio: set the property `VcpkgAdditionalInstallOptions` to `--debug`. * Set the `VCPKG_INSTALL_OPTIONS` environment variable to `--debug`. diff --git a/vcpkg/users/binarycaching.md b/vcpkg/users/binarycaching.md index e5e5c631..5fbedada 100644 --- a/vcpkg/users/binarycaching.md +++ b/vcpkg/users/binarycaching.md @@ -372,7 +372,9 @@ steps: ./vcpkg/vcpkg install sqlite3 cpprestsdk --triplet ${{ matrix.triplet }} ``` -If you're using [manifests](manifests.md), you can omit the `vcpkg package restore` step: it will be run automatically as part of your build. +If you're using [manifests](../concepts/manifest-mode.md), you can omit the +`vcpkg package restore` step: it will be run automatically as part of your +build. See the [GitHub Packages' NuGet documentation](https://docs.github.com/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages) for more information. diff --git a/vcpkg/users/buildsystems/cmake-integration.md b/vcpkg/users/buildsystems/cmake-integration.md index 6bd72be5..414e7c56 100644 --- a/vcpkg/users/buildsystems/cmake-integration.md +++ b/vcpkg/users/buildsystems/cmake-integration.md @@ -31,11 +31,13 @@ You can still use a toolchain file to configure your own toolsets by using the The vcpkg integration works differently depending on the operation mode you're using: -In [classic mode](../classic-mode.md), vcpkg sets CMake search paths appropriately to make -installed packages available via the `find_package()`, `find_library()`, and `find_path()` functions. +In [classic mode](../../concepts/classic-mode.md), vcpkg sets CMake search paths +appropriately to make installed packages available via the `find_package()`, +`find_library()`, and `find_path()` functions. -In [manifest mode](../manifests.md), in addition to the above, the toolchain detects manifest files -(`vcpkg.json` files) and runs `vcpkg install` to automatically acquire the project's dependencies. +In [manifest mode](../../concepts/manifest-mode.md), in addition to the above, +the toolchain detects manifest files (`vcpkg.json` files) and runs `vcpkg +install` to automatically acquire the project's dependencies. Because the toolchain file is evaluated during the `project()` call, all CMake-level variables that modify a vcpkg setting must be set before the first call to `project()`. It may also be necessary to diff --git a/vcpkg/users/buildsystems/manual-integration.md b/vcpkg/users/buildsystems/manual-integration.md index d49aa575..f55d11f3 100644 --- a/vcpkg/users/buildsystems/manual-integration.md +++ b/vcpkg/users/buildsystems/manual-integration.md @@ -8,7 +8,10 @@ ms.topic: concept-article When installing libraries, vcpkg creates a single common layout partitioned by triplet. -The root of the tree in [Classic mode](../classic-mode.md) is `/installed`. The root of the tree in [Manifest mode](../manifests.md) is `/vcpkg_installed`. +The root of the tree in [Classic mode](../../concepts/classic-mode.md) is +`/installed`. The root of the tree in [Manifest +mode](../../concepts/manifest-mode.md) is `/vcpkg_installed`. Underneath this root, in a subfolder named after the triplet: diff --git a/vcpkg/users/buildsystems/msbuild-integration.md b/vcpkg/users/buildsystems/msbuild-integration.md index 5f66252e..9a988d67 100644 --- a/vcpkg/users/buildsystems/msbuild-integration.md +++ b/vcpkg/users/buildsystems/msbuild-integration.md @@ -171,11 +171,13 @@ This property has no effect when `$(VcpkgApplocalDeps)` is false. ## Manifest mode configuration -To use [manifests](../manifests.md) ([`vcpkg.json`](../../reference/vcpkg-json.md)) with MSBuild, -first you need to use one of the integration methods above. Then, add a vcpkg.json above your +To use [manifests](../../concepts/manifest-mode.md) +([`vcpkg.json`](../../reference/vcpkg-json.md)) with MSBuild, first you need to +use one of the integration methods above. Then, add a vcpkg.json above your project file (such as in the root of your source repository) and set the property -`VcpkgEnableManifest` to `true`. You can set this property via the IDE in **Project Properties** > -**Vcpkg** > **Use Vcpkg Manifest**. You may need to reload the IDE to see the vcpkg Property Page. +`VcpkgEnableManifest` to `true`. You can set this property via the IDE in +**Project Properties** > **Vcpkg** > **Use Vcpkg Manifest**. You may need to +reload the IDE to see the vcpkg Property Page. vcpkg will run during your project's build and install any listed dependencies to `vcpkg_installed/$(VcpkgTriplet)/` adjacent to the `vcpkg.json` file; these libraries will then diff --git a/vcpkg/users/classic-mode.md b/vcpkg/users/classic-mode.md deleted file mode 100644 index a4764627..00000000 --- a/vcpkg/users/classic-mode.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Classic mode -description: Use vcpkg in Classic mode to share a central instance of installed libraries. -ms.date: 01/10/2024 -ms.topic: concept-article ---- -# Classic mode - -vcpkg has two modes for consuming packages - Classic mode and [Manifest mode](manifests.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. diff --git a/vcpkg/users/manifests.md b/vcpkg/users/manifests.md deleted file mode 100644 index 7fb8ffa2..00000000 --- a/vcpkg/users/manifests.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Manifest mode reference -description: Use a manifest with vcpkg to configure libraries on a per project basis. -ms.date: 01/10/2024 -ms.topic: concept-article ---- -# Manifest mode - -vcpkg has two modes for consuming packages - [Classic mode](classic-mode.md) and [Manifest mode](manifests.md). For most users, we recommend Manifest mode. - -In Manifest mode, vcpkg creates separate *installed trees* for each project and configuration. This allows separate projects to use different versions of libraries. The [`vcpkg.json` file](../reference/vcpkg-json.md) and optional [`vcpkg-configuration.json` file](../reference/vcpkg-configuration-json.md) form a project's _manifest_. The manifest declares the project's direct dependencies, version constraints, and registries used. - -Check out the [manifest CMake example](../examples/manifest-mode-cmake.md) for an example project using CMake and manifest mode. - -Check out the [`vcpkg.json` Syntax Reference](../reference/vcpkg-json.md) for a full list of fields and functionality. - -## Example - -```json -{ - "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json", - "name": "my-application", - "version": "0.15.2", - "dependencies": [ - "boost-system", - "libxml2", - "yajl" - ] -} -``` - -## Features - -Manifests can define additive sets of functionality, behavior, and dependencies called _features_. - -Each feature should be additive with other features: if a project provides features `A` and `B`, then it should build successfully with both `A` and `B` enabled together. Features should not be used to define alternatives. For example, features cannot be used to choose between multiple, exclusive graphics APIs since it is not possible to choose both. Features can depend on other features within same project if the project's manifest has a [`"name"`](../reference/vcpkg-json.md#name). - -The set of features available are defined by the [`"features"` field](../reference/vcpkg-json.md#features). - -### Example 1: Multiple File Formats - -For example, an image manipulation library might optionally support several different image types by depending on different sets of other libraries. - -```json -{ - "name": "my-image-lib", - "version": "0.1", - "features": { - "png": { "description": "Support PNG files", "dependencies": ["libpng"]}, - "jpeg": { "description": "Support JPEG files", "dependencies": ["libjpeg-turbo"]}, - "tiff": { "description": "Support TIFF files", "dependencies": ["libtiff"]}, - } -} -``` - -In a single dependency graph, multiple libraries can depend on features from a common core library. - -```json -{ - "name": "library-a", - "version": "1", - "dependencies": [{"name": "my-image-lib", "features": ["png"]}] -} -``` -```json -{ - "name": "library-b", - "version": "1", - "dependencies": [{"name": "my-image-lib", "features": ["jpeg"]}] -} -``` - -When resolving these dependencies, all required features and dependencies will be unioned together. In this example, if a top-level project used `library-a` and `library-b`, they would see an install plan similar to: - -``` -libjpeg-turbo[core] -libpng[core] -library-a[core] -library-b[core] -my-image-lib[core,png,jpeg] -``` - -The build of `my-image-lib` would activate PNG and JPEG support but deactivate TIFF support. - -### Example 2: Multiple Related Projects in a Single Repository - -When a single repository contains several separate buildable components, for example client and server applications with some shared code, developers of each piece may want to avoid installing expensive dependencies required by other pieces. - -```json -{ - "name": "my-game", - "dependencies": ["grpc"], - "features": { - "client": { "description": "Client Game Executable", "dependencies": ["sdl2", "bullet3"]}, - "server": { "description": "Multiplayer Server Executable", "dependencies": ["proxygen"]}, - "tests": { "description": "Build tests", "dependencies": ["gtest"] } - } -} -``` - -Individual developers can then select which features to install: - -- On the [install command line](../commands/install.md), pass [`--x-feature=`](../commands/install.md#feature) -- When using [CMake Integration](buildsystems/cmake-integration.md), set [`VCPKG_MANIFEST_FEATURES`](buildsystems/cmake-integration.md#vcpkg_manifest_features) before the `project()` command. -- When using [MSBuild Integration](buildsystems/msbuild-integration.md), pass `--x-feature=` via [`VcpkgAdditionalInstallOptions`](buildsystems/msbuild-integration.md#vcpkg-additional-install-options) - -### Default Features - -Default features are a set of features to be automatically activated if the top-level project does not explicitly request a build without them. Default features are intended to ensure a minimum level of functionality regardless of how complex and customizable the dependency graph of a project grows. They are not intended to model "curation" or "suggestions". - -For example, consider a library `"extract-any"` that supports over 10 different archive formats, including several that are quite obscure. Because they are all optional, if none are selected the library is not functional: it cannot extract any files. - -Default features ensure that a user who simply adds `"extract-any"` to the list of dependencies in their `vcpkg.json`: - -```json -{ - "name": "my-application", - "version": "0.15.2", - "dependencies": [ - "extract-any" - ] -} -``` - -will get a baseline level of functionality, for example automatically selecting `.zip` and `.tar.gz` decompressors. - -If the user wants to explicitly disable the default features, they can do so by adding `"default-features": false` to the dependency: - -```json -{ - "name": "my-application", - "version": "0.15.2", - "dependencies": [ - { - "name": "extract-any", - "default-features": false - } - ] -} -``` diff --git a/vcpkg/users/versioning-troubleshooting.md b/vcpkg/users/versioning-troubleshooting.md index f84b8f22..90fc8ccc 100644 --- a/vcpkg/users/versioning-troubleshooting.md +++ b/vcpkg/users/versioning-troubleshooting.md @@ -29,7 +29,7 @@ For more details on versioning, see our reference documentation: - [versioning concepts](./versioning.concepts.md) - [versioning](./versioning.md) -For more details on using a manifest, see [manifest](./manifests.md) +For more details on using a manifest, see [manifest](../concepts/manifest-mode.md) ## Cause: Requesting a non-existent version of a package