You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
vcpkg: added text for new upgrade and survey command (#570)
* added text for new upgrade and survey commands, and reformatted command ref as a table plus misc acrolinx suggestions
* Confirm merge from FromPublicMasterBranch to master to sync with https://github.com/MicrosoftDocs/cpp-docs (branch master) (#568)
* Update cricheditctrl-class.md
LineLength is a wrapper of EM_LINELENGTH, which returns length in characters not bytes.
* Update csettingsstore-class.md
contraction between the meaning of bAdmin in the parameters and remarks section of CSettingsStore::CSettingsStore
* Update clistbox-class_23.cpp
the buffer required by later code would be 16 bytes in ANSI and 32 bytes in Unicode, preallocating 10 bytes is useless.
* Fix unwind opcode values
* Update algorithm.md
Fix minor typo in Remarks section
* Undesired indentation in CFile.
Fix for undesired indentation in CFile constructor documentation.
* Update cricheditctrl-class.md
clarify that length is in TCHARs, add situations when index is out of bound, and when there's a carriage return based on EM_LINELENGTH docs
* Update compiler-warning-level-4-c4295.md
Clarify warning intent and ways to fix it, per comment by Kinichiro_Inoguchi
* Fix type error on the namespace
* Merge to live for offline publishing (MicrosoftDocs#532)
* Confirm merge from FromPublicMasterBranch to master to sync with https://github.com/MicrosoftDocs/cpp-docs (branch master) (#527)
* Update cricheditctrl-class.md
LineLength is a wrapper of EM_LINELENGTH, which returns length in characters not bytes.
* Update csettingsstore-class.md
contraction between the meaning of bAdmin in the parameters and remarks section of CSettingsStore::CSettingsStore
* Update clistbox-class_23.cpp
the buffer required by later code would be 16 bytes in ANSI and 32 bytes in Unicode, preallocating 10 bytes is useless.
* Fix unwind opcode values
* Update algorithm.md
Fix minor typo in Remarks section
* Undesired indentation in CFile.
Fix for undesired indentation in CFile constructor documentation.
* Update cricheditctrl-class.md
clarify that length is in TCHARs, add situations when index is out of bound, and when there's a carriage return based on EM_LINELENGTH docs
* Update compiler-warning-level-4-c4295.md
Clarify warning intent and ways to fix it, per comment by Kinichiro_Inoguchi
* Fix type error on the namespace
* Add /Zc:ternary switch docs (#525)
* Create topic, not linked yet
* Include links in TOC and overview
* Fix dash
* Add link to Zc:ternary to permissive
* Fix link typo
* fixed up art files for VC++ directories (#529)
* CMake updates for 15.6 (#524)
* added new content on cmake cache import
* added new art for cmake
* updates to cmake tools intro
* new art for 15.6 updates
* updates for environment variables and inherited environments
* proofreading pass
* updated art for what's new page (MicrosoftDocs#528)
* Second attempt at merge (#531)
* added new content on cmake cache import
* added new art for cmake
* updates to cmake tools intro
* new art for 15.6 updates
* updates for environment variables and inherited environments
* proofreading pass
* Update cmake-tools-for-visual-cpp.md (MicrosoftDocs#530)
I played editor in this file. I only meant to change one thing, but it was hard to stop.
* [mkdir-wmkdir.md] Fix wrong indentation
Remove redundant spaces in the code.
* Fix indentation [ _rotl ]
* Update get-wpgmptr.md
Mention entry point restriction on using _get_wpgmptr() - only for programs for wide entry points.
* Update get-pgmptr.md
Mention entry point restriction on calling _get_pgmptr
* fixed up formatting
* removed incorrect escape char
title: vcpkg-- a C++ Package Manager for Windows| Microsoft Docs
2
+
title: vcpkg-- a C++ Package Manager for Windows| Microsoft Docs
3
3
description: vcpkg is a command line package manager that greatly simplifies the acquisition and installation of open-source C++ libraries on Windows.
4
4
keywords: vcpkg
5
5
author: mikeblome
6
6
ms.author: mblome
7
-
ms.date: 05/30/2017
7
+
ms.date: 01/21/2018
8
8
ms.technology: ["cpp-ide"]
9
9
ms.tgt_pltfrm: "windows"
10
10
ms.assetid: f50d459a-e18f-4b4e-814b-913e444cedd6
@@ -15,13 +15,13 @@ ms.workload: [cplusplus]
15
15
---
16
16
17
17
# vcpkg: C++ Package Manager for Windows
18
-
vcpkg is a commandline package manager that greatly simplifies the acquisition and installation of third-party libraries on Windows. If your project uses third-party libraries, we recommend that you use vcpkg to install them. vcpkg supports both open-source and proprietary libraries. All libraries in the vcpkg public catalog have been tested for compatibility with Visual Studio 2015 and Visual Studio 2017. As of May 2017 there are over 238 libraries in the catalog and the C++ community is adding more libraries on an ongoing basis.
18
+
vcpkg is a command-line package manager that greatly simplifies the acquisition and installation of third-party libraries on Windows. If your project uses third-party libraries, we recommend that you use vcpkg to install them. vcpkg supports both open-source and proprietary libraries. All libraries in the vcpkg public catalog have been tested for compatibility with Visual Studio 2015 and Visual Studio 2017. As of January 2018 there are over 600 libraries in the catalog and the C++ community is adding more libraries on an ongoing basis.
19
19
20
20
## Simple yet flexible
21
-
With a single command, you can download sources and build a library. vcpkg is itself an open-source project, available on GitHub. You can customize your private clone(s) in any way you like, for example by specifying different libraries, or different versions of libraries than what are found in the public catalog. 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 completely self-contained, x-copyable environment with its own copy of vcpkg.exe that operates only on its own hierarchy. vcpkg is not added to any environment variables, and has no dependency on the Windows Registry or Visual Studio.
21
+
With a single command, you can download sources and build a library. 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. 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 is not added to any environment variables, and has no dependency on the Windows Registry or Visual Studio.
22
22
23
23
## Sources not binaries
24
-
For libraries in the public catalog, vcpkg downloads sources instead of binaries[1]. It compiles those sources using Visual Studio 2017, or Visual Studio 2015 if 2017 is not installed. 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. By using vcpkg you eliminate or at least greatly reduce the potential for mismatched binaries and the problems they can cause. In teams that are standardized on a specific version of the Visual C++ 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.
24
+
For libraries in the public catalog, vcpkg downloads sources instead of binaries[1]. It compiles those sources using Visual Studio 2017, or Visual Studio 2015 if 2017 is not installed. 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. By using vcpkg, you eliminate or at least greatly reduce the potential for mismatched binaries and the problems they can cause. In teams that are standardized on a specific version of the Visual C++ 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.
25
25
26
26
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.
27
27
@@ -32,10 +32,8 @@ Clone the vcpkg repo from GitHub: https://github.com/Microsoft/vcpkg. You can do
32
32
33
33
Run the bootstrapper in the root folder: bootstrap-vcpkg.bat.
34
34
35
-
## Basic tasks
36
-
37
-
### Search the list of available libraries
38
-
To see what packages are available, at the command prompt type: `vcpkg search`
35
+
## Search the list of available libraries
36
+
To see what packages are available, at the command prompt type: **vcpkg search**
39
37
40
38
This command enumerates the control files in the vcpkg/ports subfolders. You will see a listing like this:
After you get the name of a library by using `vcpkg search`, you use `vcpkg install` to download the library and compile it. vcpkg uses the library's portfile in the ports directory. If no triplet is specified, vcpkg will install and compile for x86-windows. If the portfile specifies dependencies, vcpkg will download and install those also. After downloading, vcpkg builds the library by using whatever build system the library uses. CMake and MSBuild projects files are preferred, but MAKE is supported along with any other build system. If vcpkg cannot find the specified build system on the local machine, it will download and install it.
60
+
## Install a library on your local machine
61
+
After you get the name of a library by using **vcpkg search**, you use **vcpkg install** to download the library and compile it. vcpkg uses the library's portfile in the ports directory. If no triplet is specified, vcpkg will install and compile for x86-windows. If the portfile specifies dependencies, vcpkg downloads and installs those also. After downloading, vcpkg builds the library by using whatever build system the library uses. CMake and MSBuild projects files are preferred, but MAKE is supported along with any other build system. If vcpkg cannot find the specified build system on the local machine, it downloads and installs it.
64
62
65
63
```cmd
66
64
> vcpkg install boost:x86-windows
@@ -72,8 +70,8 @@ The following packages will be built and installed:
72
70
Additional packages (*) will be installed to complete this operation.
73
71
```
74
72
75
-
###List the libraries already installed
76
-
After you have installed some libraries, you can use `vcpkg list` to see what you have:
73
+
## List the libraries already installed
74
+
After you have installed some libraries, you can use **vcpkg list** to see what you have:
77
75
78
76
```cmd
79
77
> vcpkg list
@@ -86,70 +84,116 @@ websocketpp:x86-windows 0.7.0 Library that implements RFC6455 The WebSocket P
86
84
zlib:x86-windows 1.2.11 A compression library
87
85
```
88
86
89
-
###Integrate with Visual Studio
90
-
####Per-user
91
-
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.
87
+
## Integrate with Visual Studio
88
+
### Per-user
89
+
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.
92
90
93
-
Now you can #include headers simply by typing the folder/header, and auto-complete will help you. No additional steps are required for linking to libs or adding project references. The following illustration shows how Visual Studio finds the azure-storage-cpp headers. vcpkg places its headers in the \installed subfolder, partitioned by target platform. The following diagram shows the list of include files in the `/was` subfolder for the library:
91
+
Now you can #include headers simply by typing the folder/header, and auto-complete assists you. No additional steps are required for linking to libs or adding project references. The following illustration shows how Visual Studio finds the azure-storage-cpp headers. vcpkg places its headers in the \installed subfolder, partitioned by target platform. The following diagram shows the list of include files in the `/was` subfolder for the library:
94
92
95
93
![vcpkg Intellisense integration](media/vcpkg-intellisense.png"vcpkg and Intellisense")
96
94
97
-
####Per project
98
-
If you need to use a specific version of a library that is different from the version in your active vcpkg instance, you can make a new clone of vcpkg, modify the portfile for the library to obtain the version you need, and then run `vcpkg install <library>`. After that, you can use `vcpkg integrate project` to create a NuGet package that references that library on a per-project basis.
95
+
### Per project
96
+
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:
99
97
100
-
### Export compiled binaries and headers
101
-
Requiring everyone on a team to download and build libraries can be inefficient. A single team member can do that work, and then use `vcpkg export` to create a zip file of the binaries and headers that can be easily shared with other team members.
98
+
1. Make a new clone of vcpkg
99
+
1. Modify the portfile for the library to obtain the version you need
100
+
1. Run **vcpkg install \<library>**.
101
+
1. Use **vcpkg integrate project** to create a NuGet package that references that library on a per-project basis.
102
102
103
-
### Update installed libraries
104
-
The public catalog is kept up-to-date with the latest versions of the libraries. To determine which of your local libraries are out-of-date, use `vcpkg update`. When you're ready to update your ports collection to the latest version of the public catalog, just do a git pull operation against the github repo, or create a new clone and keep the old one if it is still needed.
105
103
106
-
### Contribute new libraries
104
+
## Export compiled binaries and headers
105
+
Requiring everyone on a team to download and build libraries can be inefficient. A single team member can do that work, and then use **vcpkg export** to create a zip file of the binaries and headers that can be easily shared with other team members.
106
+
107
+
## Update/upgrade installed libraries
108
+
The public catalog is kept up-to-date with the latest versions of the libraries. To determine which of your local libraries are out-of-date, use **vcpkg update**. 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.
109
+
110
+
By default, the **upgrade** command only lists the libraries that are out of date; it doesn’t upgrade them. To perform the upgrade, use the **--no-dry-run** option.
111
+
112
+
```cmd
113
+
vcpkg upgrade --no-dry-run
114
+
```
115
+
116
+
### Upgrade Options
117
+
118
+
-**--no-dry-run** Perform the upgrade; when not specified, the command only lists the out-of-date packages.
119
+
-**--keep-going** Continue installing packages even if one fails.
120
+
-**--triplet \<t>** Set the default triplet for unqualified packages.
121
+
-**--vcpkg-root \<path>** Specify the vcpkg directory to use instead of current directory or tool directory.
122
+
123
+
### Upgrade example
124
+
125
+
The following example shows how to upgrade only specified libraries. Note that vcpgk automatically pulls in dependencies as necessary.
Additional packages (*) will be modified to complete this operation.
137
+
If you are sure you want to rebuild the above packages, run this command with the --no-dry-run option.
138
+
```
139
+
140
+
## Contribute new libraries
107
141
You can include any libraries you like in your private ports collection. To suggest a new library for the public catalog, open an issue on the [GitHub vcpkg issue page](https://github.com/Microsoft/vcpkg/issues).
108
142
109
-
###Remove a library
110
-
Type `vcpkg remove` to remove an installed library. If any other libraries depend on it, you'll be asked to re-run the command with `--recurse`, which will cause all downstream libraries to be removed.
143
+
## Remove a library
144
+
Type **vcpkg remove** to remove an installed library. If any other libraries depend on it, you are asked to rerun the command with **--recurse**, which causes all downstream libraries to be removed.
111
145
112
-
###Customize vcpkg
146
+
## Customize vcpkg
113
147
You can modify your clone of vcpkg in any way you like. 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. 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.
114
148
115
-
###Uninstall vcpkg
149
+
## Uninstall vcpkg
116
150
Just delete the directory.
117
151
152
+
## Send feedback about vcpkg
153
+
Use the **--survey** command to send feedback to Microsoft about vcpkg, including bug reports and suggestions for features.
154
+
118
155
## The vcpkg folder hierarchy
119
-
All vcpkg functionality and data is completely self-contained in a single directory hierarchy; this is called an "instance". There are no registry settings or environment variables. You can have any number of instances of vcpkg on a machine and they will not interfere with each other.
156
+
All vcpkg functionality and data is self-contained in a single directory hierarchy, called an "instance". There are no registry settings or environment variables. You can have any number of instances of vcpkg on a machine and they do not interfere with each other.
120
157
121
158
The contents of a vcpkg instance are:
159
+
122
160
- buildtrees -- contains subfolders of sources from which each library is built
123
161
- docs -- documentation and examples
124
162
- downloads -- cached copies of any downloaded tools or sources. vcpkg searches here first when you run the install command .
125
-
- installed-- Contains the headers and binaries for each installed library. When you integrate with VIsual Studio, you are essentially telling it add this folder to its search paths.
163
+
- installed-- Contains the headers and binaries for each installed library. When you integrate with Visual Studio, you are essentially telling it add this folder to its search paths.
126
164
- packages -- Internal folder for staging between installs.
127
165
- ports -- Files that describe each library in the catalog, its version, and where to download it. You can add your own ports if needed.
128
166
- scripts -- Scripts (cmake, powershell) used by vcpkg.
129
167
- toolsrc -- C++ source code for vcpkg and related components
130
-
- triplets -- Contains the settings for each supported target platform (e.g. x86-windows or x64-uwp).
131
-
132
-
## Command line reference
133
-
- vcpkg search [pat] Search for packages available to be built
134
-
- vcpkg install <pkg>... Install a package
135
-
- vcpkg remove <pkg>... Uninstall a package
136
-
- vcpkg remove --outdated Uninstall all out-of-date packages
137
-
- vcpkg list List installed packages
138
-
- vcpkg update Display list of packages for updating
139
-
- vcpkg hash <file> [alg] Hash a file by specific algorithm, default SHA512
140
-
- vcpkg integrate install Make installed packages available user-wide. Requires admin privileges on first use
0 commit comments