Vcpkg - Revision history

Sam at 10:43, 16 February 2021

2021-02-16T10:43:06Z

Sam: /* Prerequisites */

2021-02-16T10:40:55Z

Prerequisites

Admin: Created page with "[https://github.com/Microsoft/vcpkg vcpkg] is Microsoft's C++ package manager. It ships as source code that you build. It includes several tools such as: * [https://cmake.org/..."

2020-05-18T20:41:24Z

Created page with "[https://github.com/Microsoft/vcpkg vcpkg] is Microsoft's C++ package manager. It ships as source code that you build. It includes several tools such as: * [https://cmake.org/..."

New page

[https://github.com/Microsoft/vcpkg vcpkg] is Microsoft's C++ package manager.
It ships as source code that you build.
It includes several tools such as:
* [https://cmake.org/ CMake] - Because the other build tools that Microsoft ships ([https://docs.microsoft.com/en-us/cpp/build/reference/nmake-reference?view=vs-2019 nmake], [https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild?view=vs-2019 MSBuild]) just aren't good enough.
* [https://www.7-zip.org/ 7Zip] (7za)
* [https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29 bash]
* [https://git-scm.com/ git]
* [http://mingw.org/ MinGW]
* [https://www.nuget.org/ nuget]

=What It Does=
[https://github.com/Microsoft/vcpkg vcpkg] performs three basic tasks:
# Download source code
# Compile source code into libraries/executables
# Copy files to well known folders

=Prerequisites=
* A [https://git-scm.com/download/win command line git] client.
* Powershell

=Getting vcpkg=

Here's how to put a C++ library project into a package.
These steps are derived from [https://github.com/microsoft/vcpkg/blob/master/docs/examples/packaging-github-repos.md this] article.

# Create a folder
#: <syntaxhighlight lang="bat">mkdir MyProject</syntaxhighlight>
# Go into that folder
#: <syntaxhighlight lang="bat">cd MyProject</syntaxhighlight>
# Get the vcpkg source code
#: <syntaxhighlight lang="bat">git clone https://github.com/Microsoft/vcpkg.git</syntaxhighlight>
# Go into the vcpkg folder
#: <syntaxhighlight lang="bat">cd vcpkg</syntaxhighlight>
# Start Powershell
#: <syntaxhighlight lang="bat">powershell</syntaxhighlight>
# Compile vcpkg
#: <syntaxhighlight lang="bat">.\bootstrap-vcpkg.bat</syntaxhighlight>
# As of this writing, 2019-10-24, vcpkg defaults to 32-bit builds. To get it to use 64-bit you must set a global environment variable to something called a [https://github.com/microsoft/vcpkg/blob/master/docs/users/triplets.md "triplet"] which is a long string with two fields in it.
#: <syntaxhighlight lang="bat">VCPKG_DEFAULT_TRIPLET=x64-windows</syntaxhighlight>
# [https://github.com/microsoft/vcpkg/blob/master/docs/users/integration.md Integrate] vcpkg with your build system
#: <syntaxhighlight lang="bat">.\vcpkg integrate install</syntaxhighlight>
#: You can uninstall the integration by:
#: <syntaxhighlight lang="bat">.\vcpkg integrate remove</syntaxhighlight>
# vcpkg is now ready to use. To get and compile a package, you use the <code>install</code> command.
#: <syntaxhighlight lang="bat">.\vcpkg install curl</syntaxhighlight>

=Recommended Environment Variables=
* <code>VCPKG_DEFAULT_TRIPLET=x64-windows</code>
* <code>VCPKG_PLATFORM_TOOLSET=v142</code>
* <code>VCPKG_TARGET_ARCHITECTURE=x64</code>

=How it Works=
The [https://github.com/Microsoft/vcpkg vcpkg] package manager gets the package information for packages it knows how to get from a folder named <code>ports</code>
The package name is the name of a folder in <code>ports</code>
That named folder will contain at least a <code>CONTROL</code> file and a <code>portfile.cmake</code>.
When you "install" a package, the compilation result will be written to a sub-folder named <code>packages</code> with the name of the package, an underscore and the [https://github.com/microsoft/vcpkg/blob/master/docs/users/triplets.md triplet] (the two-field string).

vcpkg uses [https://cmake.org CMake] as the primary build tool that can spawn other build tools to build your code.

==Sample==
<syntaxhighlight lang="bat">vcpkg install wfc</syntaxhighlight>

vcpkg will then:
# Read a file named <code>ports/wfc/portfile.cmake</code>
# Download the source code to a folder named <code>buildtrees/wfc/src</code>
# It will then build the source code
# It will copy the compiled results from step 2 to a folder named <code>packages/wfc_x64-windows</code>

If you want to delete an installed package:

<syntaxhighlight lang="bat">vcpkg remove wfc</syntaxhighlight>

=Adding a New Package=

Make a folder in the <code>ports</code> folder with the name of your new package (<code>wfc</code>).
Go into that folder to do your work.
You must create two files, <code>CONTROL</code> and <code>portfile.cmake</code>

==CONTROL==
This file gives you a description of the package (aka library).
<syntaxhighlight lang="text">
Source: wfc
Version: 77
Description: Win32 Foundation Classes is a C++ library to help with Win32 programming.
</syntaxhighlight>

==portfile.cmake==
This file is basically a build script, in yet another build-script language.
This one is in [https://cmake.org/ CMake].
<pre>
include(vcpkg_common_functions)

if (NOT VCPKG_TARGET_IS_WINDOWS)
message(FATAL_ERROR "\n${PORT} does not support your system, only Windows for now. Please open a ticket issue on github.com/microsoft/vcpkg if necessary\n")
endif()

vcpkg_from_github(
OUT_SOURCE_PATH SOURCE_PATH
REPO SammyB428/WFC
REF dd41bd5e3f2ed8daa9d87adde938b156317bc3b9
SHA512 d02c7cde8cfed24db5ca52e46e15f866d1dcec3f42013d059ad60fc98bedeec3409b8dad768ad53918a4f152ee07442dcbe9234aa2e625daba4038f1ef24efc9
HEAD_REF master
)

vcpkg_install_msbuild(
SOURCE_PATH ${SOURCE_PATH}
PROJECT_SUBPATH lib/WFC.sln
INCLUDES_SUBPATH INCLUDE
LICENSE_SUBPATH LICENSE
REMOVE_ROOT_INCLUDES
USE_VCPKG_INTEGRATION
PLATFORM x64
RELEASE_CONFIGURATION "STL Unicode Release"
DEBUG_CONFIGURATION "STL Unicode Debug"
)
</pre>

The really important fields are:

===vcpkg_from_github===
This is a [https://cmake.org CMake] function defined in <code>vcpkg\scripts\cmake\vcpkg_from_github.cmake</code> which will clone a [https://github.com/ GitHub] project so it can be built locally.

====REPO====
This field holds the github repository name (<code>SammyB428/WFC</code>) to retrieve.

====REF====
This is either the release name of the repository to get '''OR''' the hash of the commit to retrieve.
In our example, we are retrieving a specific commit <code>dd41bd5e3f2ed8daa9d87adde938b156317bc3b9</code>

====SHA512====
This is the [https://en.wikipedia.org/wiki/SHA-2 SHA-512] of the [https://en.wikipedia.org/wiki/Zip_(file_format) ZIP] file downloaded from github.

The get the correct [https://en.wikipedia.org/wiki/SHA-2 SHA-512] value for the <code>SHA512</code> line, just set it to "1" then run:
<syntaxhighlight lang="bat">vcpkg install wfc</syntaxhighlight>
This will generate an error message with the desired hash in it.

<syntaxhighlight lang="bat">
C:\Users\Sam\Documents\vcpkg\vcpkg>vcpkg.exe install wfc
The following packages will be built and installed:
wfc[core]:x86-windows
Starting package 1/1: wfc:x86-windows
Building package wfc[core]:x86-windows...
-- Using cached C:/Users/Sam/Documents/vcpkg/vcpkg/downloads/SammyB428-WFC-dd41bd5e3f2ed8daa9d87adde938b156317bc3b9.tar.gz
CMake Error at scripts/cmake/vcpkg_download_distfile.cmake:99 (message):

File does not have expected hash:

File path: [ C:/Users/Sam/Documents/vcpkg/vcpkg/downloads/SammyB428-WFC-dd41bd5e3f2ed8daa9d87adde938b156317bc3b9.tar.gz ]
Expected hash: [ 1 ]
Actual hash: [ d02c7cde8cfed24db5ca52e46e15f866d1dcec3f42013d059ad60fc98bedeec3409b8dad768ad53918a4f152ee07442dcbe9234aa2e625daba4038f1ef24efc9 ]

Please delete the file and retry if this file should be downloaded again.
</syntaxhighlight>

Copy the value from the <code>Actual hash:</code> field of the error message to the <code>SHA512</code> field.

===vcpkg_install_msbuild===
This is a [https://cmake.org CMake] function defined in <code>vcpkg\scripts\cmake\vcpkg_install_msbuild.cmake</code> which will build then install an [https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild?view=vs-2019 MSBuild]-based project.

====PROJECT_SUBPATH====
The relative path from the root of the unzipped file where your solution file resides.

====PLATFORM====
The platform identifier that matches the platform identifier in your vcxproj file.

====RELEASE_CONFIGURATION====
The name of the configuration in your vcxproj file that will produce the "Release" build.

====DEBUG_CONFIGURATION====
The name of the configuration in your vcxproj file that will produce the "Debug" build.

@@ Line 25: / Line 25: @@
 # Create a folder
-#: <syntaxhighlight lang="bat">mkdir MyProject</syntaxhighlight>
+#: <source lang="bat">mkdir MyProject</source>
 # Go into that folder
-#: <syntaxhighlight lang="bat">cd MyProject</syntaxhighlight>
+#: <source lang="bat">cd MyProject</source>
 # Get the vcpkg source code
-#: <syntaxhighlight lang="bat">git clone https://github.com/Microsoft/vcpkg.git</syntaxhighlight>
+#: <source lang="bat">git clone https://github.com/Microsoft/vcpkg.git</source>
 # Go into the vcpkg folder
-#: <syntaxhighlight lang="bat">cd vcpkg</syntaxhighlight>
+#: <source lang="bat">cd vcpkg</source>
 # Start Powershell
-#: <syntaxhighlight lang="bat">powershell</syntaxhighlight>
+#: <source lang="bat">powershell</source>
 # Compile vcpkg
-#: <syntaxhighlight lang="bat">.\bootstrap-vcpkg.bat</syntaxhighlight>
+#: <source lang="bat">.\bootstrap-vcpkg.bat</source>
 # As of this writing, 2019-10-24, vcpkg defaults to 32-bit builds. To get it to use 64-bit you must set a global environment variable to something called a [https://github.com/microsoft/vcpkg/blob/master/docs/users/triplets.md "triplet"] which is a long string with two fields in it.
-#: <syntaxhighlight lang="bat">VCPKG_DEFAULT_TRIPLET=x64-windows</syntaxhighlight>
+#: <source lang="bat">VCPKG_DEFAULT_TRIPLET=x64-windows</source>
 # [https://github.com/microsoft/vcpkg/blob/master/docs/users/integration.md Integrate] vcpkg with your build system
-#: <syntaxhighlight lang="bat">.\vcpkg integrate install</syntaxhighlight>
+#: <source lang="bat">.\vcpkg integrate install</source>
 #: You can uninstall the integration by:
-#: <syntaxhighlight lang="bat">.\vcpkg integrate remove</syntaxhighlight>
+#: <source lang="bat">.\vcpkg integrate remove</source>
 # vcpkg is now ready to use. To get and compile a package, you use the <code>install</code> command.
-#: <syntaxhighlight lang="bat">.\vcpkg install curl</syntaxhighlight>
+#: <source lang="bat">.\vcpkg install curl</source>
 =Recommended Environment Variables=
@@ Line 59: / Line 59: @@
 ==Sample==
-<syntaxhighlight lang="bat">vcpkg install wfc</syntaxhighlight>
+<source lang="bat">vcpkg install wfc</source>
 vcpkg will then:
@@ Line 69: / Line 69: @@
 If you want to delete an installed package:
-<syntaxhighlight lang="bat">vcpkg remove wfc</syntaxhighlight>
+<source lang="bat">vcpkg remove wfc</source>
 =Adding a New Package=
 Make a folder in the <code>ports</code> folder with the name of your new package (<code>wfc</code>).
 Go into that folder to do your work.
@@ Line 79: / Line 78: @@
 ==CONTROL==
 This file gives you a description of the package (aka library).
-<syntaxhighlight lang="text">
+<source lang="text">
 Source: wfc
 Version: 77
 Description: Win32 Foundation Classes is a C++ library to help with Win32 programming.
-</syntaxhighlight>
+</source>
 ==portfile.cmake==
@@ Line 132: / Line 131: @@
 The get the correct [https://en.wikipedia.org/wiki/SHA-2 SHA-512] value for the <code>SHA512</code> line, just set it to "1" then run:
-<syntaxhighlight lang="bat">vcpkg install wfc</syntaxhighlight>
+<source lang="bat">vcpkg install wfc</source>
 This will generate an error message with the desired hash in it.
-<syntaxhighlight lang="bat">
+<source lang="bat">
 C:\Users\Sam\Documents\vcpkg\vcpkg>vcpkg.exe install wfc
 The following packages will be built and installed:
@@ Line 152: / Line 151: @@
    Please delete the file and retry if this file should be downloaded again.
-</syntaxhighlight>
+</source>
 Copy the value from the <code>Actual hash:</code> field of the error message to the <code>SHA512</code> field.

@@ Line 17: / Line 17: @@
 =Prerequisites=
 * A [https://git-scm.com/download/win command line git] client.
-* Powershell
+* [https://docs.microsoft.com/en-us/powershell/ PowerShell]
 =Getting vcpkg=