vcpkg:用于 Windows、Linux 和 MacOS 的 C++ 包管理器vcpkg: A C++ package manager for Windows, Linux and MacOS

vcpkg 是一种命令行包管理器,可极大简化 Windows、Linux 和 MacOS 上第三方库的购置与安装。vcpkg is a command-line package manager that greatly simplifies the acquisition and installation of third-party libraries on Windows, Linux and MacOS. 如果项目要使用第三方库,建议通过 vcpkg 来安装它们。If your project uses third-party libraries, we recommend that you use vcpkg to install them. vcpkg 同时支持开源和专有库。vcpkg supports both open-source and proprietary libraries. 已测试 vcpkg Windows 目录中所有库与 Visual Studio 2015 及 Visual Studio 2017 的兼容性。All libraries in the vcpkg Windows catalog have been tested for compatibility with Visual Studio 2015 and Visual Studio 2017. 截至 2018 年 5 月,Windows 目录中已有 900 多个库,Linux/MacOS 目录中有 350 多个库。As of May 2018 there are over 900 libraries in the Windows catalog and over 350 in the Linux/MacOS catalog. C++ 社区正在不断向两个目录添加更多的库。The C++ community is adding more libraries to both catalogs on an ongoing basis.

简单而灵活Simple yet flexible

仅通过单个命令就能下载源并生成库。With a single command, you can download sources and build a library. vcpkg 本身就是一个开源项目,可通过 GitHub 获取。vcpkg is itself an open-source project, available on GitHub. 可凭喜好自定义个人专用克隆。You can customize your private clone(s) in any way you like. 例如,除在公共目录中找到的内容外,还可指定不同的库或不同版本的库。For example, you can specify different libraries, or different versions of libraries than what are found in the public catalog. 可在单台计算机上拥有多个 vcpkg 克隆,每个克隆都可生成自定义库集和/或编译开关等。每个克隆都是一个自包含、x 可复制的环境,它自身的 vcpkg.exe 副本仅可在自己的层次结构中运行。You can have multiple clones of vcpkg on a single machine, each one producing custom sets of libraries and/or compilation switches, etc. Each clone is a self-contained, x-copyable environment with its own copy of vcpkg.exe that operates only on its own hierarchy. vcpkg 不会被添加到任何环境变量,并且在 Windows 注册表或 Visual Studio 上也不会有依赖项。vcpkg is not added to any environment variables, and has no dependency on the Windows Registry or Visual Studio.

源不是二进制文件Sources not binaries

对于 Windows 目录中的库,vcpkg 会下载源,而不是二进制文件[1]。For libraries in the Windows catalog, vcpkg downloads sources instead of binaries[1]. 它将使用 Visual Studio 2017 或 Visual Studio 2015(如果未安装 Visual Studio 2017)对源进行编译。It compiles those sources using Visual Studio 2017, or Visual Studio 2015 if 2017 is not installed. 在 C++ 中,作为链接到它的应用程序代码,使用相同的编译器及编译器版本来编译任何要用的库至关重要。In C++, it is very important that any libraries you use are complied with the same compiler, and compiler version, as the application code that links to it. 通过 vcpkg 可以消除或最大程度减少不匹配二进制文件的存在风险及它可能造成的问题。By using vcpkg, you eliminate or at least greatly reduce the potential for mismatched binaries and the problems they can cause. 对于使用特定编译器版本的标准化团队,可让一位成员使用 vcpkg 下载源并编译一组二进制文件,然后通过导出命令将二进制文件和标头压缩打包,即可与其他团队成员进行共享。In teams that are standardized on a specific version of a compiler, one team member can use vcpkg to download sources and compile a set of binaries and then use the export command to zip up the binaries and headers for other team members. 有关详细信息,请参阅下方的导出已编译二进制文件及标头For more information, see Export compiled binaries and headers below.

如果在端口集合中使用专用库创建 vcpkg 克隆,则可以添加一个端口来下载预生成二进制文件和标头,并编写一个 portfile.cmake 文件,轻松将上述文件复制到所需的地方。If you create a vcpkg clone with private libraries in the ports collection, you can add a port that downloads prebuilt binaries and headers and write a portfile.cmake file that simply copies those files to the desired location.

[1] 注意:某些专有库不具有这些源。在这些情况下,vcpkg 将下载可兼容预生成二进制文件。*[1] Note: for some proprietary libraries, sources are not available. Vcpkg will download compatible prebuilt binaries in these cases.

安装Installation

从 GitHub 克隆 vcpkg 存储库:https://github.com/Microsoft/vcpkg.Clone the vcpkg repo from GitHub: https://github.com/Microsoft/vcpkg. 可凭喜好下载到任意文件夹位置。You can download to any folder location you prefer.

在根文件夹中运行 bootstrapper:Run the bootstrapper in the root folder:

  • bootstrap-vcpkg.bat (Windows)bootstrap-vcpkg.bat (Windows)
  • ./bootstrap-vcpkg.sh (Linux、MacOS)./bootstrap-vcpkg.sh (Linux, MacOS)

在列表中搜索可用库Search the list of available libraries

要查看哪些包可用,请在命令提示符中键入:vcpkg searchTo see what packages are available, at the command prompt type: vcpkg search

此命令枚举 vcpkg/ports 子文件夹中的控件文件。This command enumerates the control files in the vcpkg/ports subfolders. 将出现如下的文件列表:You will see a listing like this:

ace       6.4.3   The ADAPTIVE Communication Environment
anax      2.1.0-1 An open source C++ entity system. \<https://github...
antlr4    4.6-1   ANother Tool for Language Recognition
apr       1.5.2   The Apache Portable Runtime (APR) is a C library ...
asio      1.10.8  Asio is a cross-platform C++ library for network ...
assimp    3.3.1   The Open Asset import library
atk       2.24.0  GNOME Accessibility Toolkit
...

可以根据模式筛选,例如 vcpkg search ta:You can filter on a pattern, for example vcpkg search ta:

botan       2.0.1      A cryptography library written in C++11
portaudio   19.0.6.00  PortAudio Portable Cross-platform Audio I/O API P...
taglib      1.11.1-2   TagLib Audio Meta-Data Library

在本地计算机上安装库Install a library on your local machine

在使用 vcpkg search 获取库的名称后,可使用 vcpkg install 下载库并对其进行编译。After you get the name of a library by using vcpkg search, you use vcpkg install to download the library and compile it. vcpkg 在端口目录中使用库的端口文件。vcpkg uses the library's portfile in the ports directory. 如果未指定三元组,则 vcpkg 将针对目标平台的默认三元组进行安装和编译:x86-windows、x64-linux.cmake 或 x64-osx.cmake。If no triplet is specified, vcpkg will install and compile for the default triplet for the target platform: x86-windows, x64-linux.cmake, or x64-osx.cmake.

对于 Linux 库,vcpkg 取决于本地计算机上安装的 gcc。For Linux libraries, vcpkg depends on gcc being installed on the local machine. 在 MacOS 上,vcpkg 使用 Clang。On MacOS, vcpkg uses Clang.

如果端口文件指定了依赖项,vcpkg 还会下载并安装这些依赖项。If the portfile specifies dependencies, vcpkg downloads and installs those also. 下载完成后,vcpkg 使用库所使用的生成系统(版本不限)来生成库。After downloading, vcpkg builds the library by using whatever build system the library uses. 首选 CMake 和 MSBuild(Windows 上)项目,但同时还支持 MAKE 以及其他任何生成系统。CMake and (on Windows) MSBuild projects are preferred, but MAKE is supported along with any other build system. 如果 vcpkg 在本地计算机上找不到指定的生成系统,它会下载并安装一个。If vcpkg cannot find the specified build system on the local machine, it downloads and installs it.

> vcpkg install boost:x86-windows

The following packages will be built and installed:
    boost:x86-windows
  * bzip2:x86-windows
  * zlib:x86-windows
Additional packages (*) will be installed to complete this operation.

对于 CMAKE 项目,使用 CMAKE_TOOLCHAIN_FILE 实现库与 find_package() 的结合使用。For CMAKE projects, use use CMAKE_TOOLCHAIN_FILE to make libraries available with find_package(). 例如:For example:

cmake .. -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake (Linux/MacOS)
cmake .. -DCMAKE_TOOLCHAIN_FILE=vcpkg\scripts\buildsystems\vcpkg.cmake (Windows)

列出已安装的库List the libraries already installed

在安装某些库以后,可使用 vcpkg list 来查看所获得的内容:After you have installed some libraries, you can use vcpkg list to see what you have:

> vcpkg list

boost:x86-windows       1.64-3   Peer-reviewed portable C++ source libraries
bzip2:x86-windows       1.0.6-1  High-quality data compressor.
cpprestsdk:x86-windows  2.9.0-2  C++11 JSON, REST, and OAuth library The C++ REST ...
openssl:x86-windows     1.0.2k-2 OpenSSL is an open source project that provides a...
websocketpp:x86-windows 0.7.0    Library that implements RFC6455 The WebSocket Pro...
zlib:x86-windows        1.2.11   A compression library

与 Visual Studio (Windows) 集成Integrate with Visual Studio (Windows)

按用户Per-user

运行 vcpkg integrate install 来配置 Visual Studio,以便按用户找到所有 vcpkg 头文件和二进制文件,同时还无需手动编辑 VC++ 目录路径。Run vcpkg integrate install to configure Visual Studio to locate all vcpkg header files and binaries on a per-user basis without the need for manual editing of VC++ Directories paths. 如果有多个克隆,则运行此命令的克隆将成为新的默认位置。If you have multiple clones, the clone from which you run this command becomes the new default location.

现在,只需键入文件夹/标头就可轻松加入标头,自动完成功能将帮助你完成这一切。Now you can #include headers simply by typing the folder/header, and auto-complete assists you. 在链接到 lib 或添加项目引用时,无需额外步骤。No additional steps are required for linking to libs or adding project references. 下图演示了 Visual Studio 查找 azure-storage-cpp 标头的方法。The following illustration shows how Visual Studio finds the azure-storage-cpp headers. vcpkg 将其标头放置在 /installed 子文件夹中,由目标平台予以分区。vcpkg places its headers in the /installed subfolder, partitioned by target platform. 下图显示库的 /was 子文件夹中包含文件的列表:The following diagram shows the list of include files in the /was subfolder for the library:

vcpkg IntelliSense 集成vcpkg IntelliSense integration

按项目Per project

如果需要使用的库的版本与活动 vcpkg 实例中的版本不同,请按以下步骤操作:If you need to use a specific version of a library that is different from the version in your active vcpkg instance, follow these steps:

  1. 新建 vcpkg 克隆Make a new clone of vcpkg
  2. 修改库的端口文件以获取所需版本Modify the portfile for the library to obtain the version you need
  3. 运行 vcpkg install <library>。Run vcpkg install <library>.
  4. 使用 vcpkg integrate project 创建 NuGet 包,它会按项目来引用该库。Use vcpkg integrate project to create a NuGet package that references that library on a per-project basis.

与 Visual Studio Code (Linux/MacOS) 集成Integrate with Visual Studio Code (Linux/MacOS)

运行 vcpkg integrate install,使用 vcpkg 登记的位置在 Linux/MacOS 上配置 Visual Studio Code,并在源文件上启用 IntelliSense。Run vcpkg integrate install to configure Visual Studio Code on Linux/MacOS with the location of the vcpkg enlistement and enable IntelliSense on source files.

通过 WSL 从 Windows 指向 LinuxTarget Linux from Windows via WSL

可使用适用于 Linux 的 Windows 子系统 (WSL) 从 Windows 计算机生成 Linux 二进制文件。You can produce Linux binaries from a Windows machine by using the Windows Subsystem for Linux (WSL). 按照说明在 Windows 10 上设置 WSL,并使用适用于 Linux 的 Visual Studio 扩展进行配置。Follow the instructions to Set up WSL on Windows 10, and configure it with the Visual Studio extension for Linux. 可将生成的所有 Windows 和 Linux 库放在同一文件夹中,并从 Windows 和 WSL 进行访问。You can put all your built libraries for both Windows and Linux into the same folder and access it from both Windows and WSL.

导出已编译的二进制文件和标头Export compiled binaries and headers

让团队中的每个成员都去下载和生成库可能会造成效率低下。Requiring everyone on a team to download and build libraries can be inefficient. 一个团队成员就可完成该工作,然后使用 vcpkg export 创建二进制文件和标头的 zip 文件或 NuGet 包(各种格式均可),将其与其他团队成员进行轻松共享。A single team member can do that work, and then use vcpkg export to create a zip file of the binaries and headers, or a NuGet package (various format available), that can be easily shared with other team members.

更新/升级已安装的库Update/upgrade installed libraries

公共目录始终与最新版本的库保持一致。The public catalog is kept up-to-date with the latest versions of the libraries. 要判断哪个本地库已过期,请使用 vcpkg update。To determine which of your local libraries are out-of-date, use vcpkg update. 准备好将端口集合更新为公共目录的最新版本后,运行 vcpkg upgrade 命令以自动下载和重新生成任一或所有已安装的过期库。When you're ready to update your ports collection to the latest version of the public catalog, run the vcpkg upgrade command to automatically download and rebuild any or all of your installed libraries that are out of date.

默认情况下,upgrade 命令仅列出过期库;而不会对它们进行升级。By default, the upgrade command only lists the libraries that are out of date; it doesn’t upgrade them. 要执行升级操作,请使用 --no-dry-run 选项。To perform the upgrade, use the --no-dry-run option.

  vcpkg upgrade --no-dry-run

升级选项Upgrade Options

  • --no-dry-run 执行升级,在没有指定条件的情况下,命令只列出过期的包。--no-dry-run Perform the upgrade; when not specified, the command only lists the out-of-date packages.
  • --keep-going 继续安装包(即使出现了失败)。--keep-going Continue installing packages even if one fails.
  • --triplet <t> 为非限定的包设置默认的三元组。--triplet <t> Set the default triplet for unqualified packages.
  • --vcpkg-root <path> 指定要使用的 vcpkg 目录,而不是使用当前目录或工具目录。--vcpkg-root <path> Specify the vcpkg directory to use instead of current directory or tool directory.

升级示例Upgrade example

以下示例演示如何只升级指定的库。The following example shows how to upgrade only specified libraries. 请注意,必要时 vcpgk 会自动拉取依赖项。Note that vcpgk automatically pulls in dependencies as necessary.

c:\users\satyan\vcpkg> vcpkg upgrade tiny-dnn:x86-windows zlib
The following packages are up-to-date:
   tiny-dnn:x86-windows

The following packages will be rebuilt:
    * libpng[core]:x86-windows
    * tiff[core]:x86-windows
      zlib[core]:x86-windows
Additional packages (*) will be modified to complete this operation.
If you are sure you want to rebuild the above packages, run this command with the --no-dry-run option.

发布新库Contribute new libraries

可以在自己的专用端口集合中添加任意库。You can include any libraries you like in your private ports collection. 要建议适合公共目录的新库,请在 GitHub vcpkg 问题页上打开一个问题。To suggest a new library for the public catalog, open an issue on the GitHub vcpkg issue page.

删除库Remove a library

键入 vcpkg remove 可删除已安装的库。Type vcpkg remove to remove an installed library. 如果存在任何其他依赖于它的库,则系统会提示通过 --recurse 重新运行命令,如执行此操作,则下游的所有库都会被删除。If any other libraries depend on it, you are asked to rerun the command with --recurse, which causes all downstream libraries to be removed.

自定义 vcpkgCustomize vcpkg

可凭自身喜好随意修改 vcpkg 的克隆。You can modify your clone of vcpkg in any way you like. 可创建多个 vcpkg 克隆,修改每个克隆中的端口文件,使其包含特定版本的库或指定命令行参数。You can create multiple vcpkg clones and modify the portfiles in each one to obtain specific versions of libraries or specify command-line parameters. 例如在某企业中,某组的开发者可能正在使用拥有某一依赖项集的软件,而其他组可能拥有不同的集。For example, in an enterprise, one group of developers might be working on software that has one set of dependencies, and another group might have a different set. 可设置两个 vcpkg 克隆并对其进行修改,以便根据需要来下载不同版本的库和编译开关等。You can set up two clones of vcpkg, and modify each one to download the versions of the libraries and the compilation switches, etc, according to your needs.

卸载 vcpkgUninstall vcpkg

只需删除目录。Just delete the directory.

发送关于 vcpkg 反馈Send feedback about vcpkg

使用 vcpkg contact --survey 命令向 Microsoft 发送关于 vcpkg 的反馈,包括 Bug 报告和功能上的建议。Use the vcpkg contact --survey command to send feedback to Microsoft about vcpkg, including bug reports and suggestions for features.

vcpkg 文件夹层次结构The vcpkg folder hierarchy

所有 vcpkg 功能和数据都自包含在称为“实例”的单独目录层次结构中。All vcpkg functionality and data is self-contained in a single directory hierarchy, called an "instance". 没有注册表设置或环境变量。There are no registry settings or environment variables. 可以在计算机上设置任意数量的 vcpkg 实例,它们彼此互不干扰。You can have any number of instances of vcpkg on a machine and they do not interfere with each other.

vcpkg 实例的内容如下:The contents of a vcpkg instance are:

  • buildtrees - 包含从中生成每个库的源的子文件夹buildtrees -- contains subfolders of sources from which each library is built
  • docs - 文档和示例docs -- documentation and examples
  • downloads - 任何已下载工具或源的缓存副本。downloads -- cached copies of any downloaded tools or sources. 运行安装命令时,vcpkg 会首先搜索此处。vcpkg searches here first when you run the install command .
  • installed - 包含每个已安装库的标头和二进制文件。installed-- Contains the headers and binaries for each installed library. 与 Visual Studio 集成时,实质上相当于告知它将此文件夹添加到其搜索路径。When you integrate with Visual Studio, you are essentially telling it add this folder to its search paths.
  • packages - 在不同的安装之间用于暂存的内部文件夹。packages -- Internal folder for staging between installs.
  • ports - 用于描述每个库的目录、版本和下载位置的文件。ports -- Files that describe each library in the catalog, its version, and where to download it. 如有需要,可添加自己的端口。You can add your own ports if needed.
  • scripts - 由 vcpkg 使用的脚本(cmake、powershell)。scripts -- Scripts (cmake, powershell) used by vcpkg.
  • toolsrc - vcpkg 和相关组件的 C++ 源代码toolsrc -- C++ source code for vcpkg and related components
  • triplets - 包含每个受支持目标平台(如 x86-windows 或 x64-uwp)的设置。triplets -- Contains the settings for each supported target platform (for example, x86-windows or x64-uwp).

命令行参考Command-line reference

命令Command 描述Description
vcpkg search [pat]vcpkg search [pat] 搜索可安装的包Search for packages available to install
vcpkg install <pkg>...vcpkg install <pkg>... 安装包Install a package
vcpkg remove <pkg>...vcpkg remove <pkg>... 卸载包Uninstall a package
vcpkg remove --outdatedvcpkg remove --outdated 卸载所有过期包Uninstall all out-of-date packages
vcpkg listvcpkg list 列出已安装的包List installed packages
vcpkg updatevcpkg update 显示用于更新的包列表Display list of packages for updating
vcpkg upgradevcpkg upgrade 重新生成所有过期包Rebuild all outdated packages
vcpkg hash <file> [alg]vcpkg hash <file> [alg] 通过特定算法对文件执行哈希操作,默认为 SHA512Hash a file by specific algorithm, default SHA512
vcpkg integrate installvcpkg integrate install 使已安装包在用户范围内可用。Make installed packages available user-wide. 首次使用时需要管理权限Requires admin privileges on first use
vcpkg integrate removevcpkg integrate remove 删除用户范围的集成Remove user-wide integration
vcpkg integrate projectvcpkg integrate project 为使用单个 VS 项目生成引用 NuGet 包Generate a referencing NuGet package for individual VS project use
vcpkg export <pkg>... [opt]...vcpkg export <pkg>... [opt]... 导出包Export a package
vcpkg edit <pkg>vcpkg edit <pkg> 打开端口进行编辑(使用 %EDITOR%,默认为“code”)Open up a port for editing (uses %EDITOR%, default 'code')
vcpkg create <pkg> <url> [archivename]vcpkg create <pkg> <url> [archivename] 创建新程序包Create a new package
vcpkg cachevcpkg cache 列出缓存的已编译包List cached compiled packages
vcpkg versionvcpkg version 显示版本信息Display version information
vcpkg contact --surveyvcpkg contact --survey 显示联系信息,以便发送反馈。Display contact information to send feedback.

选项Options

选项Option 描述Description
--triplet <t>--triplet <t> 指定目标体系结构三元组。Specify the target architecture triplet. (默认:%VCPKG_DEFAULT_TRIPLET%,另请参阅“vcpkg help triplet”)(default: %VCPKG_DEFAULT_TRIPLET%, see also vcpkg help triplet)
--vcpkg-root <path>--vcpkg-root <path> 指定 vcpkg 根目录(默认:%VCPKG_ROOT%Specify the vcpkg root directory (default: %VCPKG_ROOT%)