2020-07-08 01:53:14 +08:00
# Vcpkg: Overview
2020-09-01 00:07:55 +08:00
2020-07-08 01:53:14 +08:00
[中文总览 ](README_zh_CN.md )
2020-10-01 00:18:49 +08:00
[Español ](README_es.md )
2020-11-13 06:34:55 +08:00
[한국어 ](README_ko_KR.md )
2020-10-31 04:21:48 +08:00
[Français ](README_fr.md )
2017-06-08 06:26:55 +08:00
2020-07-08 01:53:14 +08:00
Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS.
This tool and ecosystem are constantly evolving, and we always appreciate contributions!
2016-09-19 11:50:08 +08:00
2020-07-08 01:53:14 +08:00
If you've never used vcpkg before, or if you're trying to figure out how to use vcpkg,
check out our [Getting Started ](#getting-started ) section for how to start using vcpkg.
For short description of available commands, once you've installed vcpkg,
you can run `vcpkg help` , or `vcpkg help [command]` for command-specific help.
2016-09-19 11:50:08 +08:00
2019-11-05 09:00:30 +08:00
* Github: [https://github.com/microsoft/vcpkg ](https://github.com/microsoft/vcpkg )
2020-04-25 05:58:49 +08:00
* Slack: [https://cppalliance.org/slack/ ](https://cppalliance.org/slack/ ), the #vcpkg channel
2020-06-06 02:00:43 +08:00
* Discord: [\#include \<C++\> ](https://www.includecpp.org ), the #🌏vcpkg channel
2021-03-23 06:15:29 +08:00
* Docs: [Documentation ](docs/README.md )
2019-11-05 09:00:30 +08:00
2020-05-06 03:05:34 +08:00
[](https://dev.azure.com/vcpkg/public/_build/latest?definitionId=29& branchName=master)
2019-11-05 09:00:30 +08:00
2020-07-08 01:53:14 +08:00
# Table of Contents
- [Vcpkg: Overview ](#vcpkg-overview )
- [Table of Contents ](#table-of-contents )
- [Getting Started ](#getting-started )
- [Quick Start: Windows ](#quick-start-windows )
- [Quick Start: Unix ](#quick-start-unix )
- [Installing Linux Developer Tools ](#installing-linux-developer-tools )
- [Installing macOS Developer Tools ](#installing-macos-developer-tools )
- [Installing GCC for macOS before 10.15 ](#installing-gcc-for-macos-before-1015 )
- [Using vcpkg with CMake ](#using-vcpkg-with-cmake )
- [Visual Studio Code with CMake Tools ](#visual-studio-code-with-cmake-tools )
- [Vcpkg with Visual Studio CMake Projects ](#vcpkg-with-visual-studio-cmake-projects )
- [Vcpkg with CLion ](#vcpkg-with-clion )
- [Vcpkg as a Submodule ](#vcpkg-as-a-submodule )
- [Tab-Completion/Auto-Completion ](#tab-completionauto-completion )
- [Examples ](#examples )
- [Contributing ](#contributing )
- [License ](#license )
- [Telemetry ](#telemetry )
# Getting Started
First, follow the quick start guide for either
[Windows ](#quick-start-windows ), or [macOS and Linux ](#quick-start-unix ),
depending on what you're using.
2020-07-08 13:08:09 +08:00
For more information, see [Installing and Using Packages][getting-started:using-a-package].
2020-07-08 01:53:14 +08:00
If a library you need is not present in the vcpkg catalog,
2020-07-08 13:08:09 +08:00
you can [open an issue on the GitHub repo][contributing:submit-issue]
2020-07-08 01:53:14 +08:00
where the vcpkg team and community can see it,
and potentially add the port to vcpkg.
After you've gotten vcpkg installed and working,
you may wish to add [tab completion ](#tab-completionauto-completion ) to your shell.
Finally, if you're interested in the future of vcpkg,
2020-09-25 02:36:44 +08:00
check out the [manifest][getting-started:manifest-spec] guide!
2020-07-08 01:53:14 +08:00
This is an experimental feature and will likely have bugs,
so try it out and [open all the issues][contributing:submit-issue]!
## Quick Start: Windows
2016-11-02 12:51:28 +08:00
Prerequisites:
2020-07-08 01:53:14 +08:00
- Windows 7 or newer
2020-07-08 13:08:09 +08:00
- [Git][getting-started:git]
- [Visual Studio][getting-started:visual-studio] 2015 Update 3 or greater with the English language pack
2020-07-08 01:53:14 +08:00
First, download and bootstrap vcpkg itself; it can be installed anywhere,
but generally we recommend using vcpkg as a submodule for CMake projects,
and installing it globally for Visual Studio projects.
We recommend somewhere like `C:\src\vcpkg` or `C:\dev\vcpkg` ,
since otherwise you may run into path issues for some port build systems.
```cmd
> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat
```
To install the libraries for your project, run:
```cmd
> .\vcpkg\vcpkg install [packages to install]
```
2021-04-13 01:54:53 +08:00
Note: This will install x86 libraries by default. To install x64, run:
```cmd
2021-06-04 03:43:05 +08:00
> .\vcpkg\vcpkg install [package name]:x64-windows
2021-04-13 01:54:53 +08:00
```
Or
```cmd
> .\vcpkg\vcpkg install [packages to install] --triplet=x64-windows
```
2020-07-08 01:53:14 +08:00
You can also search for the libraries you need with the `search` subcommand:
```cmd
> .\vcpkg\vcpkg search [search term]
```
In order to use vcpkg with Visual Studio,
run the following command (may require administrator elevation):
```cmd
> .\vcpkg\vcpkg integrate install
```
After this, you can now create a New non-CMake Project (or open an existing one).
All installed libraries are immediately ready to be `#include` 'd and used
in your project without additional configuration.
If you're using CMake with Visual Studio,
continue [here ](#vcpkg-with-visual-studio-cmake-projects ).
In order to use vcpkg with CMake outside of an IDE,
you can use the toolchain file:
2020-07-08 13:08:09 +08:00
```cmd
2020-07-08 01:53:14 +08:00
> cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake
> cmake --build [build directory]
```
With CMake, you will still need to `find_package` and the like to use the libraries.
Check out the [CMake section ](#using-vcpkg-with-cmake ) for more information,
including on using CMake with an IDE.
For any other tools, including Visual Studio Code,
2020-07-08 13:08:09 +08:00
check out the [integration guide][getting-started:integration].
2020-07-08 01:53:14 +08:00
## Quick Start: Unix
Prerequisites for Linux:
2020-07-08 13:08:09 +08:00
- [Git][getting-started:git]
- [g++][getting-started:linux-gcc] >= 6
2020-07-08 01:53:14 +08:00
Prerequisites for macOS:
2020-07-08 13:08:09 +08:00
- [Apple Developer Tools][getting-started:macos-dev-tools]
2020-07-08 01:53:14 +08:00
- On macOS 10.14 or below, you will also need:
2020-07-08 13:08:09 +08:00
- [Homebrew][getting-started:macos-brew]
- [g++][getting-started:macos-gcc] >= 6 from Homebrew
2020-07-08 01:53:14 +08:00
First, download and bootstrap vcpkg itself; it can be installed anywhere,
but generally we recommend using vcpkg as a submodule for CMake projects.
```sh
$ git clone https://github.com/microsoft/vcpkg
$ ./vcpkg/bootstrap-vcpkg.sh
```
To install the libraries for your project, run:
```sh
$ ./vcpkg/vcpkg install [packages to install]
```
You can also search for the libraries you need with the `search` subcommand:
```sh
$ ./vcpkg/vcpkg search [search term]
```
In order to use vcpkg with CMake, you can use the toolchain file:
2020-07-08 13:08:09 +08:00
```sh
$ cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake
$ cmake --build [build directory]
2020-07-08 01:53:14 +08:00
```
With CMake, you will still need to `find_package` and the like to use the libraries.
Check out the [CMake section ](#using-vcpkg-with-cmake )
for more information on how best to use vcpkg with CMake,
and CMake Tools for VSCode.
2020-07-08 13:08:09 +08:00
For any other tools, check out the [integration guide][getting-started:integration].
2020-07-08 01:53:14 +08:00
## Installing Linux Developer Tools
2016-11-02 12:51:28 +08:00
2020-07-08 01:53:14 +08:00
Across the different distros of Linux, there are different packages you'll
need to install:
- Debian, Ubuntu, popOS, and other Debian-based distributions:
```sh
$ sudo apt-get update
$ sudo apt-get install build-essential tar curl zip unzip
2016-09-19 11:50:08 +08:00
```
2018-04-26 08:58:32 +08:00
2020-07-08 01:53:14 +08:00
- CentOS
```sh
$ sudo yum install centos-release-scl
$ sudo yum install devtoolset-7
$ scl enable devtoolset-7 bash
2016-09-19 11:50:08 +08:00
```
2018-04-26 08:58:32 +08:00
2020-07-08 01:53:14 +08:00
For any other distributions, make sure you're installing g++ 6 or above.
If you want to add instructions for your specific distro,
[please open a PR][contributing:submit-pr]!
## Installing macOS Developer Tools
On macOS 10.15, the only thing you should need to do is run the following in your terminal:
```sh
$ xcode-select --install
2016-09-19 11:50:08 +08:00
```
2020-07-08 01:53:14 +08:00
Then follow along with the prompts in the windows that comes up.
On macOS 10.14 and previous, you'll also need to install g++ from homebrew;
follow the instructions in the following section.
### Installing GCC for macOS before 10.15
This will _only_ be necessary if you're using a macOS version from before 10.15.
Installing homebrew should be very easy; check out < brew.sh > for more information,
but at its simplest, run the following command:
```sh
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
2016-09-19 11:50:08 +08:00
```
2018-04-26 08:58:32 +08:00
2020-07-08 01:53:14 +08:00
Then, in order to grab an up-to-date version of gcc, run the following:
```sh
$ brew install gcc
2016-09-19 11:50:08 +08:00
```
2020-07-08 01:53:14 +08:00
You'll then be able to bootstrap vcpkg along with the [quick start guide ](#quick-start-unix )
## Using vcpkg with CMake
If you're using vcpkg with CMake, the following may help!
### Visual Studio Code with CMake Tools
Adding the following to your workspace `settings.json` will make
CMake Tools automatically use vcpkg for libraries:
```json
{
"cmake.configureSettings": {
"CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
}
}
2016-09-19 11:50:08 +08:00
```
2017-05-25 14:33:16 +08:00
2020-07-08 01:53:14 +08:00
### Vcpkg with Visual Studio CMake Projects
Open the CMake Settings Editor, and under `CMake toolchain file` ,
add the path to the vcpkg toolchain file:
2018-04-26 08:58:32 +08:00
2020-07-08 01:53:14 +08:00
```
[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
2018-04-26 08:58:32 +08:00
2020-07-08 01:53:14 +08:00
### Vcpkg with CLion
2018-04-26 08:58:32 +08:00
2020-07-08 01:53:14 +08:00
Open the Toolchains settings
(File > Settings on Windows and Linux, CLion > Preferences on macOS),
and go to the CMake settings (Build, Execution, Deployment > CMake).
Finally, in `CMake options` , add the following line:
2016-09-19 11:50:08 +08:00
2017-12-05 08:01:16 +08:00
```
2020-08-22 02:46:35 +08:00
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
2017-12-05 08:01:16 +08:00
```
2020-07-08 01:53:14 +08:00
Unfortunately, you'll have to add this to each profile.
### Vcpkg as a Submodule
When using vcpkg as a submodule of your project,
you can add the following to your CMakeLists.txt before the first `project()` call,
instead of passing `CMAKE_TOOLCHAIN_FILE` to the cmake invocation.
```cmake
set(CMAKE_TOOLCHAIN_FILE ${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake
CACHE STRING "Vcpkg toolchain file")
```
2017-12-05 08:01:16 +08:00
2020-07-08 01:53:14 +08:00
This will still allow people to not use vcpkg,
by passing the `CMAKE_TOOLCHAIN_FILE` directly,
but it will make the configure-build step slightly easier.
2020-08-01 02:38:02 +08:00
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
2020-07-08 13:08:09 +08:00
[getting-started:integration]: docs/users/integration.md
2020-07-08 01:53:14 +08:00
[getting-started:git]: https://git-scm.com/downloads
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
[getting-started:linux-gcc]: #installing -linux-developer-tools
[getting-started:macos-dev-tools]: #installing -macos-developer-tools
[getting-started:macos-brew]: #installing -gcc-on-macos
[getting-started:macos-gcc]: #installing -gcc-on-macos
[getting-started:visual-studio]: https://visualstudio.microsoft.com/
2020-09-25 02:36:44 +08:00
[getting-started:manifest-spec]: docs/specifications/manifests.md
2020-07-08 01:53:14 +08:00
# Tab-Completion/Auto-Completion
`vcpkg` supports auto-completion of commands, package names,
and options in both powershell and bash.
To enable tab-completion in the shell of your choice, run:
```pwsh
> .\vcpkg integrate powershell
```
or
```sh
$ ./vcpkg integrate bash
```
depending on the shell you use, then restart your console.
# Examples
2021-03-23 06:15:29 +08:00
See the [documentation ](docs/README.md ) for specific walkthroughs,
2020-07-08 01:53:14 +08:00
including [installing and using a package ](docs/examples/installing-and-using-packages.md ),
[adding a new package from a zipfile ](docs/examples/packaging-zipfiles.md ),
and [adding a new package from a GitHub repo ](docs/examples/packaging-github-repos.md ).
2016-09-19 11:50:08 +08:00
2021-06-04 03:43:05 +08:00
Our docs are now also available online at our website https://vcpkg.io/. We really appreciate any and all feedback! You can submit an issue in https://github.com/vcpkg/vcpkg.github.io/issues.
2017-06-07 02:40:47 +08:00
2017-05-25 14:33:16 +08:00
See a 4 minute [video demo ](https://www.youtube.com/watch?v=y41WFKbQFTw ).
2016-09-19 11:50:08 +08:00
2020-07-08 01:53:14 +08:00
# Contributing
Vcpkg is an open source project, and is thus built with your contributions.
Here are some ways you can contribute:
* [Submit Issues][contributing:submit-issue] in vcpkg or existing packages
* [Submit Fixes and New Packages][contributing:submit-pr]
2016-09-19 11:50:08 +08:00
2020-07-08 01:53:14 +08:00
Please refer to our [Contributing Guide ](CONTRIBUTING.md ) for more details.
2016-09-19 11:50:08 +08:00
2020-07-08 01:53:14 +08:00
This project has adopted the [Microsoft Open Source Code of Conduct][contributing:coc].
For more information see the [Code of Conduct FAQ][contributing:coc-faq]
or email [opencode@microsoft.com ](mailto:opencode@microsoft.com )
with any additional questions or comments.
2016-09-19 11:50:08 +08:00
2020-07-08 01:53:14 +08:00
[contributing:submit-issue]: https://github.com/microsoft/vcpkg/issues/new/choose
[contributing:submit-pr]: https://github.com/microsoft/vcpkg/pulls
[contributing:coc]: https://opensource.microsoft.com/codeofconduct/
[contributing:coc-faq]: https://opensource.microsoft.com/codeofconduct/
2016-09-19 11:50:08 +08:00
2020-07-08 01:53:14 +08:00
# License
2016-09-19 11:50:08 +08:00
2020-07-08 01:53:14 +08:00
The code in this repository is licensed under the [MIT License ](LICENSE.txt ).
2020-05-06 03:34:48 +08:00
2020-07-08 01:53:14 +08:00
# Telemetry
2020-05-06 03:34:48 +08:00
2020-05-30 05:09:03 +08:00
vcpkg collects usage data in order to help us improve your experience.
The data collected by Microsoft is anonymous.
2021-09-29 23:41:39 +08:00
You can opt-out of telemetry by
- running the bootstrap-vcpkg script with -disableMetrics
- passing --disable-metrics to vcpkg on the command line
- setting the VCPKG_DISABLE_METRICS environment variable
2020-05-06 03:34:48 +08:00
Read more about vcpkg telemetry at docs/about/privacy.md
