Introducing the background of vcpkg What is vcpkg vcpkg is an open source C++ library management tool that helps developers quickly install and manage C++ libraries on operating systems such as Windows, Linux, and macOS. vcpkg supports more than 1500 C++ libraries, including Boost, OpenSSL, SDL2 and other commonly used libraries. The history and development of vcpkg vcpkg was originally developed by Microsoft to provide Visual Studio users with a convenient C++ library management tool. With the continuous development of vcpkg, it has become a cross-platform C++ library management tool and has been widely used and supported. Advantages and features of vcpkg The advantages and features of vcpkg mainly include: Supports multiple operating systems and compilers Supports over 1500 C++ libraries Support automatic resolution of dependency issues Support integration into projects Supports custom installation options How to install vcpkg Supported operating systems and compilers Operating systems and compilers supported by vcpkg include: Windows: Visual Studio 2015 and above, MSBuild, MinGW, Cygwin, etc. Linux: GCC, Clang, etc. macOS: Xcode, Clang, etc. Steps to install vcpkg The steps to install vcpkg are as follows: Clone the vcpkg repository: git clone https://github.com/microsoft/vcpkg.git Enter the vcpkg directory: cd vcpkg Run the bootstrap script: ./bootstrap-vcpkg.sh Install vcpkg: ./vcpkg install vcpkg Configure environment variables for vcpkg Configuring vcpkg's environment variables allows you to use the vcpkg command from anywhere. The configuration method is as follows: Open the environment variable setting interface Create a new environment variable named VCPKG_ROOT, with the value being the root directory of vcpkg Add the root directory of vcpkg to the PATH environment variable Usage examples of vcpkg **Install and manage libraries** Installing and managing libraries is one of the main functions of vcpkg. You can use the following commands to install and manage the library: ./vcpkg install <library>: Install the specified library ./vcpkg remove <library>: Uninstall the specified library ./vcpkg list: List all installed libraries ./vcpkg search <library>: Search for the specified library For example, to install the Boost library, you can use the following command: ./vcpkg install boost Integrate vcpkg into the project Integrating vcpkg into your project makes it easier for you to manage your library's dependencies. You can use the following command to integrate vcpkg into your project: ./vcpkg integrate install This will automatically add the vcpkg library directory to the system path and generate a vcpkg.json file describing the project's dependencies. Resolve dependency issues vcpkg can automatically resolve library dependencies, allowing you to manage library dependencies more conveniently. For example, to install the SDL2 library and its dependent libraries, you can use the following command: ./vcpkg install --recurse sdl2 This will automatically install the SDL2 library and its dependent libraries, and resolve dependencies between them. Summarize vcpkg is a very convenient C++ library management tool, which can help developers quickly install and manage C++ libraries. This article introduces the background, installation method and usage examples of vcpkg, hoping to help you use vcpkg better. The following is a translation of the official documentation of vcpkg: What is vcpkg Vcpkg helps you manage C and C++ libraries on Windows, Linux, and MacOS. This tool and ecological chain are constantly developing, and we are always looking forward to your contributions! If you have never used vcpkg, or if you are trying to learn how to use vcpkg, check out the Getting Started chapter. For a brief description of the available commands, execute vcpkg help after compiling vcpkg or vcpkg help [command] for specific help information. GitHub: https://github.com/microsoft/vcpkg Slack: https://cppalliance.org/slack/, #vcpkg channel Discord: #include <C++>, #vcpkg channel Documentation: Documentation
**
How to use vcpkg
**
getting Started
First, read the quick start guide for either: Windows or macOS and Linux, depending on which platform you are using.
For more information, see Installing and Using Packages. If the library you need is not in the vcpkg directory, you can open an issue on GitHub. A place where the vcpkg team and contributors can see it and potentially add this library to vcpkg.
After installing and running vcpkg, you may want to add TAB completion to your shell.
Finally, if you’re interested in the future of vcpkg, check out the manifest! This is an experimental feature and bugs may occur. So give it a try and open all questions!
Quick Start: Windows
Preconditions:
Windows 7 or newer
Git
Visual Studio 2015 Update 3 or newer (includes English language pack)
First, use git clone vcpkg and execute the bootstrap.bat script. You can install vcpkg anywhere, but generally we recommend that you use vcpkg as a submodule of your CMake project and install it globally into your Visual Studio project. We recommend that you use an installation directory such as C:\src\vcpkg or C:\dev\vcpkg, otherwise you may encounter path issues with some library build systems.
> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat
Use the following command to install the libraries required for your project:
> .\vcpkg\vcpkg install [packages to install]
Please note: vcpkg compiles and installs the x86 version of the library by default on Windows. To compile and install the x64 version, execute:
> .\vcpkg\vcpkg install [package name]:x64-windows
or
> .\vcpkg\vcpkg install [packages to install] –triplet=x64-windows
You can also use the search subcommand to find libraries integrated in vcpkg:
> .\vcpkg\vcpkg search [search term]
If you want to use vcpkg in Visual Studio, run the following command (may require administrator privileges)
> .\vcpkg\vcpkg search [search term]
After this, you can create a non-CMake project (or open an existing one). In your project, all installed libraries can be #included to include the header files for the libraries you need to use out of the box with no additional configuration required.
If you are using CMake projects in Visual Studio, please check here.
In order to use vcpkg with CMake outside of the IDE, you need to use the following toolchain files:
> cmake -B [build directory] -S . “-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake”
> cmake –build [build directory]
1
2
In CMake, you still need to use find_package to use the installed libraries in vcpkg. Please see the CMake chapter for more information, which covers using CMake with an IDE.
For other tools (including Visual Studio Code), check out the integration guide.
Quick Start: Unix
Linux platform prerequisites:
Git
g + + >= 6
macOS platform prerequisites:
Apple Developer Tools
First, use git clone vcpkg and execute the bootstrap.sh script. We recommend that you use vcpkg as a submodule of your CMake project.
$ git clone https://github.com/microsoft/vcpkg
$ ./vcpkg/bootstrap-vcpkg.sh
Install any package using the following command:
$ ./vcpkg/vcpkg install [packages to install]
You can also use the search subcommand to find libraries integrated in vcpkg:
$ ./vcpkg/vcpkg search [search term]
In order to use vcpkg with CMake, you need to use the following toolchain files:
$ cmake -B [build directory] -S . “-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake”
$ cmake –build [build directory]
In CMake, you still need to use find_package to use the installed libraries in vcpkg. To help you use vcpkg with CMake or VSCode CMake Tools, please check out the CMake chapter for more information, which covers using CMake with an IDE.
For other tools, check out the integration guide.
Install Linux Developer Tools
In different distributions of Linux, you need to install different tool packages:
Debian, Ubuntu, popOS or other Debian-based distributions:
$ sudo apt-get update
$ sudo apt-get install build-essential tar curl zip unzip
CentOS
$ sudo yum install centos-release-scl
$ sudo yum install devtoolset-7
$ scl enable devtoolset-7 bash
For other distributions, make sure you have g++ 6 or newer installed. If you would like to add distribution-specific instructions, please submit a PR!
Install macOS Developer Tools
In macOS, the only thing you need to do is run the following command in Terminal:
$ xcode-select –install
Then follow the prompts in the window that appears. At this point, you can use bootstrap.sh to compile vcpkg. See Quick start
Using vcpkg with CMake
If you want to use vcpkg with CMake, the following may help you:
CMake Tools in Visual Studio Code
Adding the following to your workspace’s settings.json will cause CMake Tools to automatically use third-party libraries from vcpkg:
{
“cmake.configureSettings”: {
“CMAKE_TOOLCHAIN_FILE”: “[vcpkg root]/scripts/buildsystems/vcpkg.cmake”
}
}
Using vcpkg in Visual Studio CMake projects
Open the CMake settings option and put the vcpkg toolchain file path in the CMake toolchain file:
[vcpkg root]/scripts/buildsystems/vcpkg.cmake
Using vcpkg in CLion
Open the Toolchains settings (File > Settings on Windows and Linux, CLion > Preferences on macOS), and open the CMake settings (Build, Execution, Deployment > CMake). Finally add the following lines in CMake options:
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
Unfortunately, you must manually add this option to each project configuration file.
Make vcpkg a submodule
When you wish to add vcpkg as a submodule to your project, you can add the following to CMakeLists.txt before the first project() call without passing CMAKE_TOOLCHAIN_FILE to the CMake call.
set(CMAKE_TOOLCHAIN_FILE “${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake”
CACHE STRING “Vcpkg toolchain file”)
Using this method, you can use vcpkg without setting CMAKE_TOOLCHAIN_FILE, and it is easier to complete the configuration work.
Tab completion/auto-completion
vcpkg supports commands, package names, and options in Powershell and Bash. If you need to enable tab completion in a specific shell, please run:
> .\vcpkg integrate powershell
or
$ ./vcpkg integrate bash # or zsh
Then restart the console.
Example
Check out the documentation for specific examples of installing and using a package, adding a package using a zip file, and adding a package from a GitHub source.
Our documentation is also now available online at vcpkg.io. We sincerely hope you can give us any suggestions about this website! Please create an issue here.
Watch the 4-minute demo video.
contribute
Vcpkg is an open source project and is continuously developed through your contributions. Here are some ways you can contribute:
Submit a new issue about vcpkg or a supported package
Submit fix PR and create new package
Please see our Contribution Guidelines for more details.
This project adopts the Microsoft Open Source Code of Conduct. See the Code of Conduct FAQ for more information or contact [email protected] with additional questions or comments.
Open source agreement
Code used in this repository is licensed under the MIT License.
data collection
vcpkg collects usage data to help us improve your experience. The data collected by Microsoft is anonymous. You can also disable data collection by following these steps:
Pass option -disableMetrics to bootstrap-vcpkg script and rerun this script
Pass option –disable-metrics to vcpkg command
Set environment variable VCPKG_DISABLE_METRICS
Learn more about vcpkg data collection at privacy.md.