From 286c400417e323693cba8c6f04c1be7898cc0e75 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Mon, 30 Apr 2018 14:54:50 -0700 Subject: [docs] Update docs --- docs/maintainers/vcpkg_build_cmake.md | 3 +++ docs/maintainers/vcpkg_find_acquire_program.md | 1 + 2 files changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md index ddfa46f6b..1e17eb975 100644 --- a/docs/maintainers/vcpkg_build_cmake.md +++ b/docs/maintainers/vcpkg_build_cmake.md @@ -15,6 +15,9 @@ The underlying buildsystem will be instructed to not parallelize The target passed to the cmake build command (`cmake --build . --target `). If not specified, no target will be passed. +### ADD_BIN_TO_PATH +Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs. + ## Notes: This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md). You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md index 8107c8dd2..57a2bf75a 100644 --- a/docs/maintainers/vcpkg_find_acquire_program.md +++ b/docs/maintainers/vcpkg_find_acquire_program.md @@ -25,6 +25,7 @@ The current list of programs includes: - NASM - NINJA - YASM +- ARIA2 (Downloader) Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md). -- cgit v1.2.3 From 316a3cb2452ab7faf8cf1d0b03d739617b5d09e7 Mon Sep 17 00:00:00 2001 From: Jozef Izso Date: Tue, 1 May 2018 10:48:16 +0200 Subject: Clarify toolset numbers and Visual Studio versions (#3355) --- docs/users/triplets.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index eb83aeb10..911ab5469 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -35,6 +35,9 @@ Specifies the C/C++ compiler toolchain to use. This can be set to `v141`, `v140`, or left blank. If left blank, we select the latest compiler toolset available on your machine. +Visual Studio 2015 platform toolset is `v140` +Visual Studio 2017 platform toolset is `v141` + ## Per-port customization The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE`) on a per-port basis. -- cgit v1.2.3 From 1d39174ca5a15462764fb65c04571f45794b0711 Mon Sep 17 00:00:00 2001 From: Eric Mittelette Date: Wed, 16 May 2018 09:25:44 -0700 Subject: adding a blog link in the doc --- docs/index.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index 1d12b282e..c34715a27 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,6 +26,7 @@ Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are ### Blog posts - [Announcing a single C++ library manager for Linux, macOS and Windows: Vcpkg](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/) +- [Vcpkg: Using multiple enlistments to handle multiple versions of a library](https://blogs.msdn.microsoft.com/vcblog/2017/10/23/vcpkg-using-multiple-enlistments/) - [Vcpkg: introducing the export command](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) - [Binary Compatibility and Pain-free Upgrade Why Moving to Visual Studio 2017 is almost "too easy"](https://blogs.msdn.microsoft.com/vcblog/2017/03/07/binary-compatibility-and-pain-free-upgrade-why-moving-to-visual-studio-2017-is-almost-too-easy/) - [Vcpkg recent enhancements](https://blogs.msdn.microsoft.com/vcblog/2017/02/14/vcpkg-recent-enhancements/) -- cgit v1.2.3 From 2988f8577b8ee3e977c187401af544e9eae4ff7b Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Thu, 17 May 2018 23:39:36 -0700 Subject: [faq.md] Update with support for Linux/OSX. Fixes #3416. --- docs/about/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index b345b4fd0..87496da44 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -26,7 +26,7 @@ To see an example of this, look at [`ports\opengl\portfile.cmake`](https://githu We currently target Windows Desktop (x86 and x64) as well as the Universal Windows Platform (x86, x64, and ARM). See `vcpkg help triplet` for the current list. ## Does Vcpkg run on Linux/OSX? -No, for this preview we are focusing on Windows as a host platform. If you'd be interested in having Vcpkg run on Linux or OSX, please let us know in [this issue](https://github.com/microsoft/vcpkg/issues/57)! +Yes! We continously test on OSX and Ubuntu 16.04, however we know users have been successful with Arch, Fedora, and FreeBSD. If you have trouble with your favorite Linux distribution, let us know in an issue and we'd be happy to help! ## How do I use different versions of a library on one machine? Within a single instance of Vcpkg (e.g. one set of `installed\`, `packages\`, `ports\` and so forth), you can only have one version of a library installed (otherwise, the headers would conflict with each other!). For those with experience with system-wide package managers, packages in Vcpkg correspond to the `X-dev` or `X-devel` packages. -- cgit v1.2.3 From 22a7da849d0d44c8a75ebaf205905e53e40f4dc6 Mon Sep 17 00:00:00 2001 From: Cleroth Date: Mon, 28 May 2018 02:07:04 +0900 Subject: Fixed misspelling --- docs/examples/using-sqlite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/examples/using-sqlite.md b/docs/examples/using-sqlite.md index d12695bfb..35da141d0 100644 --- a/docs/examples/using-sqlite.md +++ b/docs/examples/using-sqlite.md @@ -71,7 +71,7 @@ See `.\vcpkg help triplet` for all supported targets. #### VS/MSBuild Project (User-wide integration) -The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwords is no longer required and the integration is configured on a per-user basis. +The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwards is no longer required and the integration is configured on a per-user basis. ```no-highlight PS D:\src\vcpkg> .\vcpkg integrate install Applied user-wide integration for this vcpkg root. -- cgit v1.2.3 From 39c70573df301fb5e4297abbc7f05cc05c0af0a4 Mon Sep 17 00:00:00 2001 From: Alexander Karatarakis Date: Fri, 8 Jun 2018 16:33:38 -0700 Subject: Update documentation --- docs/about/faq.md | 2 +- docs/about/privacy.md | 7 ++++++- docs/index.md | 2 +- 3 files changed, 8 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index 87496da44..ff7ecdba5 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -42,7 +42,7 @@ See the [Privacy document](privacy.md) for all information regarding privacy. Yes. If you already have a CMake toolchain file, you will need to include our toolchain file at the end of yours. This should be as simple as an `include(\scripts\buildsystems\vcpkg.cmake)` directive. Alternatively, you could copy the contents of our `scripts\buildsystems\vcpkg.cmake` into the end of your existing toolchain file. ## Can I use my own/specific flags for rebuilding libs? -Yes. In the current preview, there is not yet a standardized global way to change them, however you can edit individual portfiles and tweak the exact build process however you'd like. +Yes. In the current version, there is not yet a standardized global way to change them, however you can edit individual portfiles and tweak the exact build process however you'd like. By saving the changes to the portfile (and checking them in), you'll get the same results even if you're rebuilding from scratch in the future and forgot what exact settings you used. diff --git a/docs/about/privacy.md b/docs/about/privacy.md index 9ff0e7a47..419a25faf 100644 --- a/docs/about/privacy.md +++ b/docs/about/privacy.md @@ -7,7 +7,12 @@ We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY colle ## What telemetry is collected? -We collect the command line used, the time of invocation, and how long the command took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event. For this preview, we do not offer a mechanism to disable this data collection since it is critical for improving the product. In the full release, you will be able to opt-out with a simple configuration. For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-us/privacy. +We collect the command line used, the time of invocation, and how long execution took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event. +In order to opt-out of data collection, you can re-run the boostrap script with the following flag: + +```PS> .\bootstrap-vcpkg.bat -disableMetrics 1``` + +For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-us/privacy. Here is an example of an event for the command line `vcpkg install zlib`: ```json diff --git a/docs/index.md b/docs/index.md index c34715a27..90245d36a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ ### Quick Start -Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are currently in a preview state; your involvement is vital to its success. +Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement are vital to its success! - [How to use Sqlite in your application](examples/using-sqlite.md) -- cgit v1.2.3 From 52b945f8a388c573d1cfc67fd3890e0021d6fdcb Mon Sep 17 00:00:00 2001 From: Alexander Karatarakis Date: Fri, 8 Jun 2018 18:33:27 -0700 Subject: Update doc --- docs/about/privacy.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about/privacy.md b/docs/about/privacy.md index 419a25faf..adc5f6561 100644 --- a/docs/about/privacy.md +++ b/docs/about/privacy.md @@ -8,10 +8,12 @@ We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY colle ## What telemetry is collected? We collect the command line used, the time of invocation, and how long execution took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event. -In order to opt-out of data collection, you can re-run the boostrap script with the following flag: +In order to opt-out of data collection, you can re-run the boostrap script with the following flag, for Windows and Linux/OSX, respectively: ```PS> .\bootstrap-vcpkg.bat -disableMetrics 1``` +```PS> .\bootstrap-vcpkg.sh -disableMetrics``` + For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-us/privacy. Here is an example of an event for the command line `vcpkg install zlib`: -- cgit v1.2.3 From 5af585756cc80295373e537f61414a7d84ce1f05 Mon Sep 17 00:00:00 2001 From: Alexander Karatarakis Date: Fri, 8 Jun 2018 18:41:46 -0700 Subject: Fix shell prefix --- docs/about/privacy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about/privacy.md b/docs/about/privacy.md index adc5f6561..84cde34ec 100644 --- a/docs/about/privacy.md +++ b/docs/about/privacy.md @@ -12,7 +12,7 @@ In order to opt-out of data collection, you can re-run the boostrap script with ```PS> .\bootstrap-vcpkg.bat -disableMetrics 1``` -```PS> .\bootstrap-vcpkg.sh -disableMetrics``` +```~/$ .\bootstrap-vcpkg.sh -disableMetrics``` For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-us/privacy. -- cgit v1.2.3 From 82f53ac82c2f36fc41cc0c57c57e0f1323dd43a9 Mon Sep 17 00:00:00 2001 From: Alexander Karatarakis Date: Mon, 11 Jun 2018 13:26:16 -0700 Subject: Fix slash --- docs/about/privacy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about/privacy.md b/docs/about/privacy.md index 84cde34ec..634393504 100644 --- a/docs/about/privacy.md +++ b/docs/about/privacy.md @@ -12,7 +12,7 @@ In order to opt-out of data collection, you can re-run the boostrap script with ```PS> .\bootstrap-vcpkg.bat -disableMetrics 1``` -```~/$ .\bootstrap-vcpkg.sh -disableMetrics``` +```~/$ ./bootstrap-vcpkg.sh -disableMetrics``` For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-us/privacy. -- cgit v1.2.3 From 56cc9ac15ce63c81a64537d01ace890bd62b5e79 Mon Sep 17 00:00:00 2001 From: Alexander Karatarakis Date: Tue, 12 Jun 2018 17:12:33 -0700 Subject: Make bootstrap.bat parameters match bootstrap.sh --- docs/about/privacy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about/privacy.md b/docs/about/privacy.md index 634393504..91d709372 100644 --- a/docs/about/privacy.md +++ b/docs/about/privacy.md @@ -10,7 +10,7 @@ We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY colle We collect the command line used, the time of invocation, and how long execution took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event. In order to opt-out of data collection, you can re-run the boostrap script with the following flag, for Windows and Linux/OSX, respectively: -```PS> .\bootstrap-vcpkg.bat -disableMetrics 1``` +```PS> .\bootstrap-vcpkg.bat -disableMetrics``` ```~/$ ./bootstrap-vcpkg.sh -disableMetrics``` -- cgit v1.2.3 From c2b9c33adf25ac78fac63ddd0ea9b26a923e1b6e Mon Sep 17 00:00:00 2001 From: martin-s Date: Sat, 16 Jun 2018 16:42:25 +0000 Subject: Added parameter to vcpkg_copy_pdbs.cmake (#3688) * - Added paths argument to locate pdbs. * n/a * - fixed line endings. * [vcpkg-copy-pdbs] Tweak argument to replace patterns instead of adding patterns. Add slightly more detailed documentation. --- docs/maintainers/vcpkg_copy_pdbs.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_copy_pdbs.md b/docs/maintainers/vcpkg_copy_pdbs.md index 6bfa488db..1583f777f 100644 --- a/docs/maintainers/vcpkg_copy_pdbs.md +++ b/docs/maintainers/vcpkg_copy_pdbs.md @@ -4,12 +4,18 @@ Automatically locate pdbs in the build tree and copy them adjacent to all DLLs. ## Usage ```cmake -vcpkg_copy_pdbs() +vcpkg_copy_pdbs([BUILD_PATHS <${CURRENT_PACKAGES_DIR}/bin/*.dll> ...]) ``` ## Notes This command should always be called by portfiles after they have finished rearranging the binary output. +## Parameters +### BUILD_PATHS +Path patterns passed to `file(GLOB_RECURSE)` for locating dlls. + +Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`. + ## Examples * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) -- cgit v1.2.3 From baf6d78a4518b188c7440c26f3aca5685621c8c7 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Mon, 18 Jun 2018 11:21:03 -0700 Subject: [docs] Add VCPKG_CHAINLOAD_TOOLCHAIN_FILE to the Triplets documentation. --- docs/users/triplets.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 911ab5469..7aea35dd2 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -31,13 +31,20 @@ Valid options are `WindowsStore` or empty. Empty corresponds to Windows Desktop When setting this variable to `WindowsStore`, you must also set `VCPKG_CMAKE_SYSTEM_VERSION` to `10.0`. ### VCPKG_PLATFORM_TOOLSET -Specifies the C/C++ compiler toolchain to use. +Specifies the VS-based C/C++ compiler toolchain to use. This can be set to `v141`, `v140`, or left blank. If left blank, we select the latest compiler toolset available on your machine. Visual Studio 2015 platform toolset is `v140` Visual Studio 2017 platform toolset is `v141` +### VCPKG_CHAINLOAD_TOOLCHAIN_FILE +Specifies an alternate CMake Toolchain file to use. + +This (if set) will override all other compiler detection logic. By default, a toolchain file is selected from `scripts/toolchains/` appropriate to the platform. + +See also the CMake documentation for toolchain files: https://cmake.org/cmake/help/v3.11/manual/cmake-toolchains.7.html. + ## Per-port customization The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE`) on a per-port basis. -- cgit v1.2.3 From a2b932594843e3df8d7fa48fa016c7cf0ed929b6 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Mon, 25 Jun 2018 22:14:07 -0700 Subject: [docs-triplets] Improve triplet documentation --- docs/users/triplets.md | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 7aea35dd2..70580df46 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -12,10 +12,10 @@ To change the triplet used by your project, such as to enable static linking, se ### VCPKG_TARGET_ARCHITECTURE Specifies the target machine architecture. -Valid options are `x86`, `x64`, and `arm`. +Valid options are `x86`, `x64`, `arm`, and `arm64`. ### VCPKG_CRT_LINKAGE -Specifies the desired MSVCRT linkage. +Specifies the desired CRT linkage (for MSVC). Valid options are `dynamic` and `static`. @@ -27,8 +27,11 @@ Valid options are `dynamic` and `static`. Note that libraries can ignore this se ### VCPKG_CMAKE_SYSTEM_NAME Specifies the target platform. -Valid options are `WindowsStore` or empty. Empty corresponds to Windows Desktop and `WindowsStore` corresponds to UWP. -When setting this variable to `WindowsStore`, you must also set `VCPKG_CMAKE_SYSTEM_VERSION` to `10.0`. +Valid options include any CMake system name, such as: +- Empty (Windows Desktop for legacy reasons) +- `WindowsStore` (Universal Windows Platform) +- `Darwin` (Mac OSX) +- `Linux` (Linux) ### VCPKG_PLATFORM_TOOLSET Specifies the VS-based C/C++ compiler toolchain to use. @@ -45,22 +48,35 @@ This (if set) will override all other compiler detection logic. By default, a to See also the CMake documentation for toolchain files: https://cmake.org/cmake/help/v3.11/manual/cmake-toolchains.7.html. +### VCPKG_CXX_FLAGS +Sets additional compiler flags to be used when not using `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`. + +This option also has forms for configuration-specific and C flags: +- `VCPKG_CXX_FLAGS_DEBUG` +- `VCPKG_CXX_FLAGS_RELEASE` +- `VCPKG_C_FLAGS` +- `VCPKG_C_FLAGS_DEBUG` +- `VCPKG_C_FLAGS_RELEASE` + ## Per-port customization The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE`) on a per-port basis. Example: ```cmake set(VCPKG_LIBRARY_LINKAGE static) -set(VCPKG_CRT_LINKAGE dynamic) if(PORT MATCHES "qt5-") set(VCPKG_LIBRARY_LINKAGE dynamic) endif() ``` -This will build all the `qt5-*` libraries as DLLs against the dynamic CRT, but every other library as a static library (still against the dynamic CRT). +This will build all the `qt5-*` libraries as DLLs, but every other library as a static library. For an example in a real project, see https://github.com/Intelight/vcpkg/blob/master/triplets/x86-windows-mixed.cmake. ## Additional Remarks -The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or `x86-windows` if that environment variable is undefined. +The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or a platform-specific choice if that environment variable is undefined. + +- Windows: `x86-windows` +- Linux: `x64-linux` +- OSX: `x64-osx` We recommend using a systematic naming scheme when creating new triplets. The Android toolchain naming scheme is a good source of inspiration: https://developer.android.com/ndk/guides/standalone_toolchain.html. -- cgit v1.2.3 From 2f50e20a3688088490f50b158e0ab14944217b90 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Mon, 2 Jul 2018 23:45:31 -0700 Subject: [docs-integration] Add more documentation about using the CMake toolchain file --- docs/users/integration.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/users/integration.md b/docs/users/integration.md index f1b5014bf..ce52abe23 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -40,10 +40,32 @@ See [Example: Using Sqlite](../examples/using-sqlite.md) for a fully worked exam Note that we do not automatically add ourselves to your compiler include paths. To use a header-only library, simply use `find_path()`, which will correctly work on all platforms: ```cmake # To find and use catch -find_path(CATCH_INCLUDE_DIR catch.hpp) +find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2) include_directories(${CATCH_INCLUDE_DIR}) ``` +##### Using an environment variable instead of a command line option + +The `CMAKE_TOOLCHAIN_FILE` setting simply must be set before the `project()` directive is first called. This means that you can easily read from an environment variable to avoid passing it on the configure line: + +```cmake +if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE) + set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" + CACHE STRING "") +endif() + +project(myproject CXX) +``` + +##### Using multiple toolchain files + +To use an external toolchain file with a project using vcpkg, you can set the cmake variable `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` on the configure line: +```no-highlight +cmake ../my/project \ + -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \ + -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/compiler-settings-toolchain.cmake +``` + #### Linking NuGet file We also provide individual VS project integration through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects. -- cgit v1.2.3 From bd5bad18e40c2cc8af26558166a580f37993ac01 Mon Sep 17 00:00:00 2001 From: Frederik Gladhorn Date: Mon, 9 Jul 2018 06:07:26 +0200 Subject: Fix typo (#3856) * Fix typo * [docs] Simplify wording further --- docs/examples/packaging-zlib.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zlib.md index ce176d451..508947f1a 100644 --- a/docs/examples/packaging-zlib.md +++ b/docs/examples/packaging-zlib.md @@ -21,7 +21,7 @@ PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib-1. ``` ### Create the CONTROL file -In addition to the generated `ports\\portfile.cmake`, we also need a `ports\\CONTROL` file. This file is a simply formatted set of fields describing the package's metadata. +In addition to the generated `ports\\portfile.cmake`, we also need a `ports\\CONTROL` file. This file is a simple set of fields describing the package's metadata. *For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:* ```no-highlight -- cgit v1.2.3 From cc00cf05fb70ddec3197ca0ee7cbd47cc1c8ccfe Mon Sep 17 00:00:00 2001 From: Frederik Carlier Date: Wed, 8 Aug 2018 13:15:13 +0200 Subject: New packages: libimobiledevice, getopt, readline (#3504) * Add libplist * Add libusbmuxd * Fix typos * Add getopt * Add libimobiledevice * Fix typos * Add libideviceactivation * Add ideviceinstaller * Include utilities * Install usbmuxd * Add readline * Fix readline on 64-bit windows * Add libirecovery * libideviceactivation: include tools * Bump versions to fix build issues * Bump versions * Add idevicerestore * [getopt][getopt-win32] Rename to getopt-win32 and only install on Windows Desktop * [readline][readline-win32] Rename to readline-win32 and only install for Windows Desktop * [vcpkg_from_github][vcpkg_apply_patches] Make PATCHES relative to the current port directory * [vcpkg_install_msbuild][vcpkg_check_linkage] Introduce vcpkg_install_msbuild() and vcpkg_check_linkage(). * [libimobiledevice et al] Use vcpkg_from_github() and vcpkg_install_msbuild() * [readline] Fix static builds --- docs/maintainers/portfile-functions.md | 2 + docs/maintainers/vcpkg_build_msbuild.md | 3 +- docs/maintainers/vcpkg_check_linkage.md | 34 ++++++++++++ docs/maintainers/vcpkg_install_msbuild.md | 88 +++++++++++++++++++++++++++++++ 4 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 docs/maintainers/vcpkg_check_linkage.md create mode 100644 docs/maintainers/vcpkg_install_msbuild.md (limited to 'docs') diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index e16147f7d..6a05d884d 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -5,6 +5,7 @@ - [vcpkg\_apply\_patches](vcpkg_apply_patches.md) - [vcpkg\_build\_cmake](vcpkg_build_cmake.md) - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md) +- [vcpkg\_check\_linkage](vcpkg_check_linkage.md) - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md) - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md) @@ -15,3 +16,4 @@ - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md) - [vcpkg\_from\_github](vcpkg_from_github.md) - [vcpkg\_install\_cmake](vcpkg_install_cmake.md) +- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md) diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md index 37f8d8df2..862587eb4 100644 --- a/docs/maintainers/vcpkg_build_msbuild.md +++ b/docs/maintainers/vcpkg_build_msbuild.md @@ -1,6 +1,6 @@ # vcpkg_build_msbuild -Build an msbuild-based project. +Build an msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`. ## Usage ```cmake @@ -15,6 +15,7 @@ vcpkg_build_msbuild( [OPTIONS ...] [OPTIONS_RELEASE ...] [OPTIONS_DEBUG ...] + [USE_VCPKG_INTEGRATION] ) ``` diff --git a/docs/maintainers/vcpkg_check_linkage.md b/docs/maintainers/vcpkg_check_linkage.md new file mode 100644 index 000000000..406325dba --- /dev/null +++ b/docs/maintainers/vcpkg_check_linkage.md @@ -0,0 +1,34 @@ +# vcpkg_check_linkage + +Asserts the available library and CRT linkage options for the port. + +## Usage +```cmake +vcpkg_check_linkage( + [ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY] + [ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT] +) +``` + +## Parameters +### ONLY_STATIC_LIBRARY +Indicates that this port can only be built with static library linkage. + +### ONLY_DYNAMIC_LIBRARY +Indicates that this port can only be built with dynamic/shared library linkage. + +### ONLY_STATIC_CRT +Indicates that this port can only be built with static CRT linkage. + +### ONLY_DYNAMIC_CRT +Indicates that this port can only be built with dynamic/shared CRT linkage. + +## Notes +This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail, depending on what was requested by the user versus what the library supports. + +## Examples + +* [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_check_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake) diff --git a/docs/maintainers/vcpkg_install_msbuild.md b/docs/maintainers/vcpkg_install_msbuild.md new file mode 100644 index 000000000..76578c2ef --- /dev/null +++ b/docs/maintainers/vcpkg_install_msbuild.md @@ -0,0 +1,88 @@ +# vcpkg_install_msbuild + +Build and install an msbuild-based project. This replaces `vcpkg_build_msbuild()`. + +## Usage +```cmake +vcpkg_install_msbuild( + SOURCE_PATH <${SOURCE_PATH}> + PROJECT_SUBPATH + [INCLUDES_SUBPATH ] + [LICENSE_SUBPATH ] + [RELEASE_CONFIGURATION ] + [DEBUG_CONFIGURATION ] + [TARGET ] + [TARGET_PLATFORM_VERSION <10.0.15063.0>] + [PLATFORM <${TRIPLET_SYSTEM_ARCH}>] + [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>] + [OPTIONS ...] + [OPTIONS_RELEASE ...] + [OPTIONS_DEBUG ...] + [USE_VCPKG_INTEGRATION] + [ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES] +) +``` + +## Parameters +### SOURCE_PATH +The path to the root of the source tree. + +Because MSBuild uses in-source builds, the source tree will be copied into a temporary location for the build. This +parameter is the base for that copy and forms the base for all XYZ_SUBPATH options. + +### USE_VCPKG_INTEGRATION +Apply the normal `integrate install` integration for building the project. + +By default, projects built with this command will not automatically link libraries or have header paths set. + +### PROJECT_SUBPATH +The subpath to the solution (`.sln`) or project (`.vcxproj`) file relative to `SOURCE_PATH`. + +### LICENSE_SUBPATH +The subpath to the license file relative to `SOURCE_PATH`. + +### INCLUDES_SUBPATH +The subpath to the includes directory relative to `SOURCE_PATH`. + +This parameter should be a directory and should not end in a trailing slash. + +### ALLOW_ROOT_INCLUDES +Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed. + +### REMOVE_ROOT_INCLUDES +Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed. + +### RELEASE_CONFIGURATION +The configuration (``/p:Configuration`` msbuild parameter) used for Release builds. + +### DEBUG_CONFIGURATION +The configuration (``/p:Configuration`` msbuild parameter) +used for Debug builds. + +### TARGET_PLATFORM_VERSION +The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter) + +### TARGET +The MSBuild target to build. (``/t:``) + +### PLATFORM +The platform (``/p:Platform`` msbuild parameter) used for the build. + +### PLATFORM_TOOLSET +The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build. + +### OPTIONS +Additional options passed to msbuild for all builds. + +### OPTIONS_RELEASE +Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`. + +### OPTIONS_DEBUG +Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`. + +## Examples + +* [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_install_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake) -- cgit v1.2.3 From 0a2564482197ec5bf6495c705d5e93265af55e4a Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 8 Aug 2018 04:16:15 -0700 Subject: [docs] Add docs for vcpkg_from_gitlab() --- docs/maintainers/portfile-functions.md | 1 + docs/maintainers/vcpkg_from_gitlab.md | 55 ++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/maintainers/vcpkg_from_gitlab.md (limited to 'docs') diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index 6a05d884d..f9476d3a7 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -15,5 +15,6 @@ - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md) - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md) - [vcpkg\_from\_github](vcpkg_from_github.md) +- [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md) - [vcpkg\_install\_cmake](vcpkg_install_cmake.md) - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md) diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md new file mode 100644 index 000000000..697e32f44 --- /dev/null +++ b/docs/maintainers/vcpkg_from_gitlab.md @@ -0,0 +1,55 @@ +# vcpkg_from_gitlab + +Download and extract a project from Gitlab instances. Enables support for `install --head`. + +## Usage: +```cmake +vcpkg_from_gitlab( + GITLAB_INSTANCE + OUT_SOURCE_PATH + REPO + [REF ] + [SHA512 <45d0d7f8cc350...>] + [HEAD_REF ] +) +``` + +## Parameters: + +### GITLAB_URL +The URL of the Gitlab instance to use. + +### OUT_SOURCE_PATH +Specifies the out-variable that will contain the extracted location. + +This should be set to `SOURCE_PATH` by convention. + +### REPO +The organization or user plus the repository name on the Gitlab instance. + +### REF +A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.** + +For repositories without official releases, this can be set to the full commit id of the current latest master. + +If `REF` is specified, `SHA512` must also be specified. + +### SHA512 +The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz). +The REPO_NAME variable is parsed from the value of REPO. + +This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile. + +### HEAD_REF +The unstable git commit-ish (ideally a branch) to pull for `--head` builds. + +For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. + +## Notes: +At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. + +This exports the `VCPKG_HEAD_VERSION` variable during head builds. + + +## Source +[scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake) -- cgit v1.2.3 From cfc7f61b61be49020044a17df67ae696cb6fa8fd Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 8 Aug 2018 05:25:20 -0700 Subject: [docs] Fix GITLAB_INSTANCE-> GITLAB_URL --- docs/maintainers/vcpkg_from_gitlab.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md index 697e32f44..69deea933 100644 --- a/docs/maintainers/vcpkg_from_gitlab.md +++ b/docs/maintainers/vcpkg_from_gitlab.md @@ -5,7 +5,7 @@ Download and extract a project from Gitlab instances. Enables support for `insta ## Usage: ```cmake vcpkg_from_gitlab( - GITLAB_INSTANCE + GITLAB_URL OUT_SOURCE_PATH REPO [REF ] -- cgit v1.2.3 From 393ac2880a72d10cac1e1f19e7787c2eb9573abe Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Sat, 11 Aug 2018 22:12:18 -0700 Subject: [vcpkg_from_github] Improve documentation to include PATCHES argument --- docs/maintainers/vcpkg_from_github.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_from_github.md b/docs/maintainers/vcpkg_from_github.md index cf50dc445..8f9731629 100644 --- a/docs/maintainers/vcpkg_from_github.md +++ b/docs/maintainers/vcpkg_from_github.md @@ -10,6 +10,7 @@ vcpkg_from_github( [REF ] [SHA512 <45d0d7f8cc350...>] [HEAD_REF ] + [PATCHES ...] ) ``` @@ -23,7 +24,7 @@ This should be set to `SOURCE_PATH` by convention. The organization or user and repository on GitHub. ### REF -A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.** +A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.** For repositories without official releases, this can be set to the full commit id of the current latest master. @@ -39,6 +40,11 @@ The unstable git commit-ish (ideally a branch) to pull for `--head` builds. For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. +### PATCHES +A list of patches to be applied to the extracted sources. + +Relative paths are based on the port directory. + ## Notes: At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. -- cgit v1.2.3 From e441811bc283fdbff8c5a5de98eee45c1b1faa5e Mon Sep 17 00:00:00 2001 From: Alexander Karatarakis Date: Thu, 23 Aug 2018 02:45:32 -0700 Subject: Fix typo in FAQ --- docs/about/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index ff7ecdba5..eb35ca241 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -93,7 +93,7 @@ Enabling user-wide integration (`vcpkg integrate install`) changes the default f ## Why not NuGet? NuGet is a package manager for .NET libraries with a strong dependency on MSBuild. It does not meet the specific needs of Native C++ customers in at least three ways. -- **Compilation Flavors**. With so many possible combinations of compilation options, the task of providing a truly complete set of options is intrinsicly impossible. Furthermore, the download size for reasonably complete binary packages becomes enormous. This makes it a requirement to split the results into multiple packages, but then searching becomes very difficult. +- **Compilation Flavors**. With so many possible combinations of compilation options, the task of providing a truly complete set of options is intrinsically impossible. Furthermore, the download size for reasonably complete binary packages becomes enormous. This makes it a requirement to split the results into multiple packages, but then searching becomes very difficult. - **Binary vs Source**. Very closely tied to the first point, NuGet is designed from the ground up to provide relatively small, prebuilt binaries. Due to the nature of native code, developers need to have access to the source code to ensure ABI compatibility, performance, integrity, and debuggability. -- cgit v1.2.3 From 6b049c9d5acdcb33b734a0cde7c67262550463e9 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Mon, 27 Aug 2018 16:50:18 -0700 Subject: [docs] Add documentation for VCPKG_VISUAL_STUDIO_PATH --- docs/users/triplets.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 70580df46..d547725ea 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -41,6 +41,16 @@ This can be set to `v141`, `v140`, or left blank. If left blank, we select the l Visual Studio 2015 platform toolset is `v140` Visual Studio 2017 platform toolset is `v141` +### VCPKG_VISUAL_STUDIO_PATH +Specifies the Visual Studio installation to use. + +When unspecified, a Visual Studio instance is selected automatically, preferring Stable 2017, then Preview 2017, then 2015. + +The path should be absolute, formatted with backslashes, and have no trailing slash: +```cmake +set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Community") +``` + ### VCPKG_CHAINLOAD_TOOLCHAIN_FILE Specifies an alternate CMake Toolchain file to use. -- cgit v1.2.3 From 60820a02eb8b35792a2568c3679d647bbcad1db6 Mon Sep 17 00:00:00 2001 From: tbeu Date: Sun, 2 Sep 2018 20:56:19 +0200 Subject: Update zlib version --- docs/examples/packaging-zlib.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zlib.md index 508947f1a..1d61cfee1 100644 --- a/docs/examples/packaging-zlib.md +++ b/docs/examples/packaging-zlib.md @@ -3,7 +3,7 @@ ### Bootstrap with `create` First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors. -*Looking at zlib's website, the URL http://zlib.net/zlib128.zip looks appropriate.* +*Looking at zlib's website, the URL http://zlib.net/zlib1211.zip looks appropriate.* Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name. @@ -11,7 +11,7 @@ Second, determine a suitable package name. This should be ASCII, lowercase, and Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `-.zip`. -*`zlib128.zip` is a fine name, so no change needed.* +*`zlib1211.zip` is a fine name, so no change needed.* All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports\`. @@ -26,7 +26,7 @@ In addition to the generated `ports\\portfile.cmake`, we also need a `p *For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:* ```no-highlight Source: zlib2 -Version: 1.2.8 +Version: 1.2.11 Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library ``` -- cgit v1.2.3 From 0178015bf727597bc23e623c0a8be3c7506f316a Mon Sep 17 00:00:00 2001 From: mcgoo Date: Fri, 12 Oct 2018 18:30:30 -0500 Subject: note existence of VCPKG_CXX_FLAGS also (#4208) --- docs/users/triplets.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index d547725ea..2bb9c74b3 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -62,6 +62,7 @@ See also the CMake documentation for toolchain files: https://cmake.org/cmake/he Sets additional compiler flags to be used when not using `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`. This option also has forms for configuration-specific and C flags: +- `VCPKG_CXX_FLAGS` - `VCPKG_CXX_FLAGS_DEBUG` - `VCPKG_CXX_FLAGS_RELEASE` - `VCPKG_C_FLAGS` -- cgit v1.2.3 From 26d431c120d7d02ea23cb3be67948baecb4c5d2f Mon Sep 17 00:00:00 2001 From: Raydelto Hernandez Date: Thu, 18 Oct 2018 17:37:20 -0300 Subject: Removing cases and making clearer the text The word Privacy was capitalized for no reason. I've also added to word programming so that it's clear that the document refers to programming languages, before it referred only to language. --- docs/about/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index eb35ca241..0178e051a 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -35,7 +35,7 @@ To use different versions of a library for different projects, we recommend maki If your application is very sensitive to the versions of libraries, we recommend checking in the specific set of portfiles you need into your source control along with your project sources and using the `--vcpkg-root` option to redirect the working directory of `vcpkg.exe`. -## How does Vcpkg protect my Privacy? +## How does Vcpkg protect my privacy? See the [Privacy document](privacy.md) for all information regarding privacy. ## Can I use my own CMake toolchain file with Vcpkg's toolchain file? @@ -108,7 +108,7 @@ Conan.io is a publicly-federated, project-centric, cross-platform, C++ package m - **Cross-platform vs single-platform**. While being hosted on many platforms is an excellent north star, we believe the level of system integration and stability provided by apt-get, yum, and homebrew is well worth needing to exchange `apt-get install libboost-all-dev` with `brew install boost` in automated scripts. We chose to make our system as easy as possible to integrate into a world with these very successful system managers -- one more line for `vcpkg install boost` -- instead of attempting to replace them where they are already so successful and well-loved. -- **C++/CMake vs python**. While Python is an excellent language loved by many, we believe that transparency and familiarity are the most important factors when choosing a tool as important to your workflow as a package manager. Consequently, we chose to make the implementation languages be as universally accepted as possible: C++ should be used in a C++ package manager for C++ programmers. You should not be required to learn another language just to understand your package manager. +- **C++/CMake vs python**. While Python is an excellent language loved by many, we believe that transparency and familiarity are the most important factors when choosing a tool as important to your workflow as a package manager. Consequently, we chose to make the implementation languages be as universally accepted as possible: C++ should be used in a C++ package manager for C++ programmers. You should not be required to learn another programming language just to understand your package manager. ## Why not Chocolatey? Chocolatey is an excellent system for managing applications. However, it is not currently designed to acquire redistributable developer assets and help you with debugging. Vcpkg, in comparison, is designed to get you the libraries you need to build your application and help you deliver through any platform you'd like (including Chocolatey!). -- cgit v1.2.3 From 16e7f4187bd2864705b11e24b29896a2987deaeb Mon Sep 17 00:00:00 2001 From: LRFLEW Date: Tue, 23 Oct 2018 17:49:48 -0600 Subject: Create macOS configuration variables for triplets (#4477) * Create macOS configuration variables for triplets * Add new macOS configuration variables to documentation * [vcpkg-configure-cmake] Fix typo --- docs/users/triplets.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 2bb9c74b3..9ff372aed 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -69,6 +69,17 @@ This option also has forms for configuration-specific and C flags: - `VCPKG_C_FLAGS_DEBUG` - `VCPKG_C_FLAGS_RELEASE` +## macOS Variables + +### VCPKG_INSTALL_NAME_DIR +Sets the install name used when building macOS dynamic libraries. Default value is `@rpath`. See the CMake documentation for [CMAKE_INSTALL_NAME_DIR](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_NAME_DIR.html) for more information. + +### VCPKG_OSX_DEPLOYMENT_TARGET +Sets the minimum macOS version for compiled binaries. This also changes what versions of the macOS platform SDK that CMake will search for. See the CMake documentation for [CMAKE_OSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) for more information. + +### VCPKG_OSX_SYSROOT +Set the name or path of the macOS platform SDK that will be used by CMake. See the CMake documentation for [CMAKE_OSX_SYSROOT](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html) for more information. + ## Per-port customization The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE`) on a per-port basis. -- cgit v1.2.3 From 6d5eba6a6d4f99a03f104e0a639cbbba5325d41b Mon Sep 17 00:00:00 2001 From: Roger Leigh Date: Thu, 25 Oct 2018 20:34:45 +0100 Subject: xalan-c: Install headers correctly (#4565) * Add SKIP_CLEAN option to vcpkg_install_msbuild Also add vcpkg_clean_msbuild function to factor out clean logic and allow re-use in portfiles. * xalan-c: Correct header globbing * vcpkg_install_msbuild: SKIP_CLEAN documentation correction * [xalan-c] Add explicit check for localmsgindex header. [docs] Regenerate --- docs/maintainers/portfile-functions.md | 3 +++ docs/maintainers/vcpkg_add_to_path.md | 20 ++++++++++++++++++++ docs/maintainers/vcpkg_clean_msbuild.md | 15 +++++++++++++++ docs/maintainers/vcpkg_from_bitbucket.md | 6 ++++++ docs/maintainers/vcpkg_from_gitlab.md | 6 ++++++ docs/maintainers/vcpkg_install_msbuild.md | 9 +++++++-- docs/maintainers/vcpkg_test_cmake.md | 20 ++++++++++++++++++++ 7 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 docs/maintainers/vcpkg_add_to_path.md create mode 100644 docs/maintainers/vcpkg_clean_msbuild.md create mode 100644 docs/maintainers/vcpkg_test_cmake.md (limited to 'docs') diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index f9476d3a7..3180609ad 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -2,10 +2,12 @@ # Portfile helper functions - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md) +- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md) - [vcpkg\_apply\_patches](vcpkg_apply_patches.md) - [vcpkg\_build\_cmake](vcpkg_build_cmake.md) - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md) - [vcpkg\_check\_linkage](vcpkg_check_linkage.md) +- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md) - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md) - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md) @@ -18,3 +20,4 @@ - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md) - [vcpkg\_install\_cmake](vcpkg_install_cmake.md) - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md) +- [vcpkg\_test\_cmake](vcpkg_test_cmake.md) diff --git a/docs/maintainers/vcpkg_add_to_path.md b/docs/maintainers/vcpkg_add_to_path.md new file mode 100644 index 000000000..3657a5ea7 --- /dev/null +++ b/docs/maintainers/vcpkg_add_to_path.md @@ -0,0 +1,20 @@ +# vcpkg_add_to_path + +Add a directory to the PATH environment variable + +## Usage +```cmake +vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>) +``` + +## Parameters +### +The directory to add + +### PREPEND +Prepends the directory. + +The default is to append. + +## Source +[scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake) diff --git a/docs/maintainers/vcpkg_clean_msbuild.md b/docs/maintainers/vcpkg_clean_msbuild.md new file mode 100644 index 000000000..39d07077b --- /dev/null +++ b/docs/maintainers/vcpkg_clean_msbuild.md @@ -0,0 +1,15 @@ +# vcpkg_clean_msbuild + +Clean intermediate files generated by `vcpkg_install_msbuild()`. + +## Usage +```cmake +vcpkg_clean_msbuild() +``` + +## Examples + +* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_clean_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake) diff --git a/docs/maintainers/vcpkg_from_bitbucket.md b/docs/maintainers/vcpkg_from_bitbucket.md index c8850b725..7e699f8ea 100644 --- a/docs/maintainers/vcpkg_from_bitbucket.md +++ b/docs/maintainers/vcpkg_from_bitbucket.md @@ -11,6 +11,7 @@ vcpkg_from_bitbucket( [REF ] [SHA512 <45d0d7f8cc350...>] [HEAD_REF ] + [PATCHES ...] ) ``` @@ -40,6 +41,11 @@ The unstable git commit-ish (ideally a branch) to pull for `--head` builds. For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. +### PATCHES +A list of patches to be applied to the extracted sources. + +Relative paths are based on the port directory. + ## Notes: At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md index 69deea933..bc312f37a 100644 --- a/docs/maintainers/vcpkg_from_gitlab.md +++ b/docs/maintainers/vcpkg_from_gitlab.md @@ -11,6 +11,7 @@ vcpkg_from_gitlab( [REF ] [SHA512 <45d0d7f8cc350...>] [HEAD_REF ] + [PATCHES ...] ) ``` @@ -45,6 +46,11 @@ The unstable git commit-ish (ideally a branch) to pull for `--head` builds. For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. +### PATCHES +A list of patches to be applied to the extracted sources. + +Relative paths are based on the port directory. + ## Notes: At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. diff --git a/docs/maintainers/vcpkg_install_msbuild.md b/docs/maintainers/vcpkg_install_msbuild.md index 76578c2ef..1de68ce70 100644 --- a/docs/maintainers/vcpkg_install_msbuild.md +++ b/docs/maintainers/vcpkg_install_msbuild.md @@ -52,12 +52,16 @@ Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed ### REMOVE_ROOT_INCLUDES Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed. +### SKIP_CLEAN +Indicates that the intermediate files should not be removed. + +Ports using this option should later call [`vcpkg_clean_msbuild()`](vcpkg_clean_msbuild.md) to manually clean up. + ### RELEASE_CONFIGURATION The configuration (``/p:Configuration`` msbuild parameter) used for Release builds. ### DEBUG_CONFIGURATION -The configuration (``/p:Configuration`` msbuild parameter) -used for Debug builds. +The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds. ### TARGET_PLATFORM_VERSION The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter) @@ -82,6 +86,7 @@ Additional options passed to msbuild for Debug builds. These are in addition to ## Examples +* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake) * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake) ## Source diff --git a/docs/maintainers/vcpkg_test_cmake.md b/docs/maintainers/vcpkg_test_cmake.md new file mode 100644 index 000000000..15b3ad797 --- /dev/null +++ b/docs/maintainers/vcpkg_test_cmake.md @@ -0,0 +1,20 @@ +# vcpkg_test_cmake + +Tests a built package for CMake `find_package()` integration. + +## Usage: +```cmake +vcpkg_test_cmake(PACKAGE_NAME [MODULE]) +``` + +## Parameters: + +### PACKAGE_NAME +The expected name to find with `find_package()`. + +### MODULE +Indicates that the library expects to be found via built-in CMake targets. + + +## Source +[scripts/cmake/vcpkg_test_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_test_cmake.cmake) -- cgit v1.2.3 From d2ffdca39b4cbc250d4ae753b6017f9fa631b5bb Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Tue, 6 Nov 2018 15:47:02 -0800 Subject: [docs] Regenerate docs for vcpkg_from_git --- docs/maintainers/portfile-functions.md | 1 + docs/maintainers/vcpkg_from_git.md | 48 ++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 docs/maintainers/vcpkg_from_git.md (limited to 'docs') diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index 3180609ad..1aad301eb 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -16,6 +16,7 @@ - [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md) - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md) - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md) +- [vcpkg\_from\_git](vcpkg_from_git.md) - [vcpkg\_from\_github](vcpkg_from_github.md) - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md) - [vcpkg\_install\_cmake](vcpkg_install_cmake.md) diff --git a/docs/maintainers/vcpkg_from_git.md b/docs/maintainers/vcpkg_from_git.md new file mode 100644 index 000000000..6b24a558d --- /dev/null +++ b/docs/maintainers/vcpkg_from_git.md @@ -0,0 +1,48 @@ +# vcpkg_from_git + +Download and extract a project from git + +## Usage: +```cmake +vcpkg_from_git( + OUT_SOURCE_PATH + URL + REF <59f7335e4d...> + SHA512 + [PATCHES ...] +) +``` + +## Parameters: +### OUT_SOURCE_PATH +Specifies the out-variable that will contain the extracted location. + +This should be set to `SOURCE_PATH` by convention. + +### URL +The url of the git repository. + +### SHA512 +The SHA512 hash that should match the archive form of the commit. + +This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile. + +### REF +A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.** + +For repositories without official releases, this can be set to the full commit id of the current latest master. + +### PATCHES +A list of patches to be applied to the extracted sources. + +Relative paths are based on the port directory. + +## Notes: +`OUT_SOURCE_PATH`, `REF`, `SHA512`, and `URL` must be specified. + +## Examples: + +* [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_from_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake) -- cgit v1.2.3 From 56c94a81027dae14ea8adabcbda800d0f7c10d0b Mon Sep 17 00:00:00 2001 From: Simon Brand Date: Thu, 15 Nov 2018 11:18:48 +0000 Subject: Rename example documents The current names and titles of the examples put too much emphasis on the package which is being demonstrated rather than the concept. This can be jarring for newcomers. This patch renames them to put the emphasis on the concept instead. --- docs/about/faq.md | 4 +- docs/examples/installing-and-using-packages.md | 177 +++++++++++++++++++++ docs/examples/packaging-zipfiles.md | 79 ++++++++++ docs/examples/packaging-zlib.md | 79 ---------- docs/examples/patching-libpng.md | 204 ------------------------- docs/examples/patching.md | 204 +++++++++++++++++++++++++ docs/examples/using-sqlite.md | 177 --------------------- docs/index.md | 8 +- docs/users/integration.md | 2 +- 9 files changed, 467 insertions(+), 467 deletions(-) create mode 100644 docs/examples/installing-and-using-packages.md create mode 100644 docs/examples/packaging-zipfiles.md delete mode 100644 docs/examples/packaging-zlib.md delete mode 100644 docs/examples/patching-libpng.md create mode 100644 docs/examples/patching.md delete mode 100644 docs/examples/using-sqlite.md (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index 0178e051a..57b908f48 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -10,12 +10,12 @@ Yes! See [the `export` command](../users/integration.md#export). The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command. ## How do I get more libraries? -The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see [Example #2](../examples/packaging-zlib.md). +The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see our [packaging example](../examples/packaging-zipfiles.md). We recommend cloning directly from [GitHub](https://github.com/microsoft/vcpkg) and using `git pull` to update the list of portfiles. Once you've updated your portfiles, `vcpkg update` will indicate any installed libraries that are now out of date. ## Can I build a private library with this tool? -Yes. Follow [our Packaging zlib Example](../examples/packaging-zlib.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code. +Yes. Follow [our packaging zlib Example](../examples/packaging-zipfiles.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code. ## Can I use a prebuilt private library with this tool? Yes. The `portfile.cmake` for a library is fundamentally a script that places the headers and binaries into the correct arrangement in the `${CURRENT_PACKAGES_DIR}`, so to pull in prebuilt binaries you can write a portfile which directly downloads and arranges the files. diff --git a/docs/examples/installing-and-using-packages.md b/docs/examples/installing-and-using-packages.md new file mode 100644 index 000000000..50200c877 --- /dev/null +++ b/docs/examples/installing-and-using-packages.md @@ -0,0 +1,177 @@ +## Installing and Using Packages Example: SQLite + + - [Step 1: Install](#install) + - [Step 2: Use](#use) + - [VS/MSBuild Project (User-wide integration)](#msbuild) + - [CMake (Toolchain file)](#cmake) + - [Other integration options](../users/integration.md) + +--- + +## Step 1: Install + +First, we need to know what name [SQLite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output: +```no-highlight +PS D:\src\vcpkg> .\vcpkg search sqlite +libodb-sqlite 2.4.0 Sqlite support for the ODB ORM library +sqlite3 3.15.0 SQLite is a software library that implements a se... + +If your library is not listed, please open an issue at: + https://github.com/Microsoft/vcpkg/issues +``` +Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages. + +Installing is then as simple as using the `install` command. +```no-highlight +PS D:\src\vcpkg> .\vcpkg install sqlite3 +-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows +-- DOWNLOADS=D:/src/vcpkg/downloads +-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/sqlite3_x86-windows +-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/sqlite3 +-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/sqlite3/. +-- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip... +-- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip... OK +-- Testing integrity of downloaded file... +-- Testing integrity of downloaded file... OK +-- Extracting source D:/src/vcpkg/downloads/sqlite-amalgamation-3150000.zip +-- Extracting done +-- Configuring x86-windows-rel +-- Configuring x86-windows-rel done +-- Configuring x86-windows-dbg +-- Configuring x86-windows-dbg done +-- Build x86-windows-rel +-- Build x86-windows-rel done +-- Build x86-windows-dbg +-- Build x86-windows-dbg done +-- Package x86-windows-rel +-- Package x86-windows-rel done +-- Package x86-windows-dbg +-- Package x86-windows-dbg done +-- Performing post-build validation +-- Performing post-build validation done +Package sqlite3:x86-windows is installed +``` + +We can check that sqlite3 was successfully installed for x86 windows desktop by running the `list` command. +```no-highlight +PS D:\src\vcpkg> .\vcpkg list +sqlite3:x86-windows 3.15.0 SQLite is a software library that implements a se... +``` + +To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:`. +```no-highlight +PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows +``` + +See `.\vcpkg help triplet` for all supported targets. + +--- + +## Step 2: Use + +#### VS/MSBuild Project (User-wide integration) + +The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwards is no longer required and the integration is configured on a per-user basis. +```no-highlight +PS D:\src\vcpkg> .\vcpkg integrate install +Applied user-wide integration for this vcpkg root. + +All C++ projects can now #include any installed libraries. +Linking will be handled automatically. +Installing new libraries will make them instantly available. +``` +*Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.* + +You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 and the library will be automatically available. For SQLite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html). + +To remove the integration for your user, you can use `.\vcpkg integrate remove`. + + +#### CMake (Toolchain File) + +The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as `-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`. + +If you are using CMake through Open Folder with Visual Studio 2017 you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations: + +```json +{ + "configurations": [{ + "name": "x86-Debug", + "generator": "Visual Studio 15 2017", + "configurationType" : "Debug", + "buildRoot": "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}", + "cmakeCommandArgs": "", + "buildCommandArgs": "-m -v:minimal", + "variables": [{ + "name": "CMAKE_TOOLCHAIN_FILE", + "value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake" + }] + }] +} +``` + +Now let's make a simple CMake project with a main file. +```cmake +# CMakeLists.txt +cmake_minimum_required(VERSION 3.0) +project(test) + +find_package(Sqlite3 REQUIRED) + +add_executable(main main.cpp) +target_link_libraries(main sqlite3) +``` +```cpp +// main.cpp +#include +#include + +int main() +{ + printf("%s\n", sqlite3_libversion()); + return 0; +} +``` + +Then, we build our project in the normal CMake way: +```no-highlight +PS D:\src\cmake-test> mkdir build +PS D:\src\cmake-test> cd build +PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake" + // omitted CMake output here // +-- Build files have been written to: D:/src/cmake-test/build +PS D:\src\cmake-test\build> cmake --build . + // omitted MSBuild output here // +Build succeeded. + 0 Warning(s) + 0 Error(s) + +Time Elapsed 00:00:02.38 +PS D:\src\cmake-test\build> .\Debug\main.exe +3.15.0 +``` + +*Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.* + +##### Handling libraries without native cmake support + +Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2]. + +```cmake +# To find and use catch +find_path(CATCH_INCLUDE_DIR catch.hpp) +include_directories(${CATCH_INCLUDE_DIR}) + +# To find and use azure-storage-cpp +find_path(WASTORAGE_INCLUDE_DIR was/blob.h) +find_library(WASTORAGE_LIBRARY wastorage) +include_directories(${WASTORAGE_INCLUDE_DIR}) +link_libraries(${WASTORAGE_LIBRARY}) + +# Note that we recommend using the target-specific directives for a cleaner cmake: +# target_include_directories(main ${LIBRARY}) +# target_link_libraries(main PRIVATE ${LIBRARY}) +``` + +[1]: https://cmake.org/cmake/help/latest/command/find_path.html +[2]: https://cmake.org/cmake/help/latest/command/find_library.html diff --git a/docs/examples/packaging-zipfiles.md b/docs/examples/packaging-zipfiles.md new file mode 100644 index 000000000..ed63637fd --- /dev/null +++ b/docs/examples/packaging-zipfiles.md @@ -0,0 +1,79 @@ +## Packaging Zipfiles Example: zlib + +### Bootstrap with `create` +First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors. + +*Looking at zlib's website, the URL http://zlib.net/zlib1211.zip looks appropriate.* + +Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name. + +*Since zlib is already packaged as zlib, we will use the name zlib2 for this example.* + +Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `-.zip`. + +*`zlib1211.zip` is a fine name, so no change needed.* + +All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports\`. + +```no-highlight +PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib-1.2.11.zip +-- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake +``` + +### Create the CONTROL file +In addition to the generated `ports\\portfile.cmake`, we also need a `ports\\CONTROL` file. This file is a simple set of fields describing the package's metadata. + +*For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:* +```no-highlight +Source: zlib2 +Version: 1.2.11 +Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library +``` + +### Tweak the generated portfile +The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build. + +```no-highlight +PS D:\src\vcpkg> .\vcpkg build zlib2 +-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows +-- DOWNLOADS=D:/src/vcpkg/downloads +-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/zlib2_x86-windows +-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/zlib2 +-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/zlib2/. +-- Using cached D:/src/vcpkg/downloads/zlib-1.2.11.tar.gz +-- Testing integrity of cached file... +-- Testing integrity of cached file... OK +-- Extracting source D:/src/vcpkg/downloads/zlib-1.2.11.tar.gz +-- Extracting done +-- Configuring x86-windows-rel +-- Configuring x86-windows-rel done +-- Configuring x86-windows-dbg +-- Configuring x86-windows-dbg done +-- Build x86-windows-rel +-- Build x86-windows-rel done +-- Build x86-windows-dbg +-- Build x86-windows-dbg done +-- Performing post-build validation +Include files should not be duplicated into the /debug/include directory. If this cannot be disabled in the project cmake, use + file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include) +/debug/share should not exist. Please reorganize any important files, then use + file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share) +The software license must be available at ${CURRENT_PACKAGES_DIR}/share/zlib2/copyright +Found 3 error(s). Please correct the portfile: + D:\src\vcpkg\ports\zlib2\portfile.cmake +``` + +At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed. + +### Suggested example portfiles +In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake. + +- Header only libraries + - rapidjson + - range-v3 +- MSBuild-based + - cppunit + - mpg123 +- Non-CMake, custom buildsystem + - openssl + - ffmpeg diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zlib.md deleted file mode 100644 index 1d61cfee1..000000000 --- a/docs/examples/packaging-zlib.md +++ /dev/null @@ -1,79 +0,0 @@ -## Example 2: Packaging zlib - -### Bootstrap with `create` -First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors. - -*Looking at zlib's website, the URL http://zlib.net/zlib1211.zip looks appropriate.* - -Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name. - -*Since zlib is already packaged as zlib, we will use the name zlib2 for this example.* - -Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `-.zip`. - -*`zlib1211.zip` is a fine name, so no change needed.* - -All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports\`. - -```no-highlight -PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib-1.2.11.zip --- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake -``` - -### Create the CONTROL file -In addition to the generated `ports\\portfile.cmake`, we also need a `ports\\CONTROL` file. This file is a simple set of fields describing the package's metadata. - -*For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:* -```no-highlight -Source: zlib2 -Version: 1.2.11 -Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library -``` - -### Tweak the generated portfile -The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build. - -```no-highlight -PS D:\src\vcpkg> .\vcpkg build zlib2 --- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows --- DOWNLOADS=D:/src/vcpkg/downloads --- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/zlib2_x86-windows --- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/zlib2 --- CURRENT_PORT_DIR=D:/src/vcpkg/ports/zlib2/. --- Using cached D:/src/vcpkg/downloads/zlib-1.2.11.tar.gz --- Testing integrity of cached file... --- Testing integrity of cached file... OK --- Extracting source D:/src/vcpkg/downloads/zlib-1.2.11.tar.gz --- Extracting done --- Configuring x86-windows-rel --- Configuring x86-windows-rel done --- Configuring x86-windows-dbg --- Configuring x86-windows-dbg done --- Build x86-windows-rel --- Build x86-windows-rel done --- Build x86-windows-dbg --- Build x86-windows-dbg done --- Performing post-build validation -Include files should not be duplicated into the /debug/include directory. If this cannot be disabled in the project cmake, use - file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include) -/debug/share should not exist. Please reorganize any important files, then use - file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share) -The software license must be available at ${CURRENT_PACKAGES_DIR}/share/zlib2/copyright -Found 3 error(s). Please correct the portfile: - D:\src\vcpkg\ports\zlib2\portfile.cmake -``` - -At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed. - -### Suggested example portfiles -In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake. - -- Header only libraries - - rapidjson - - range-v3 -- MSBuild-based - - cppunit - - mpg123 -- Non-CMake, custom buildsystem - - openssl - - ffmpeg diff --git a/docs/examples/patching-libpng.md b/docs/examples/patching-libpng.md deleted file mode 100644 index 2337b73da..000000000 --- a/docs/examples/patching-libpng.md +++ /dev/null @@ -1,204 +0,0 @@ -## Example 3: Patching libpng to work for x86-uwp - -### Initial error logs -First, try building: - -```no-highlight -PS D:\src\vcpkg> vcpkg install libpng:x86-uwp --- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp --- DOWNLOADS=D:/src/vcpkg/downloads --- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/libpng_x86-uwp --- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/libpng --- CURRENT_PORT_DIR=D:/src/vcpkg/ports/libpng/. --- Using cached D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz --- Extracting done --- Configuring x86-uwp-rel --- Configuring x86-uwp-rel done --- Configuring x86-uwp-dbg --- Configuring x86-uwp-dbg done --- Build x86-uwp-rel -CMake Error at scripts/cmake/execute_required_process.cmake:14 (message): - Command failed: C:/Program - Files/CMake/bin/cmake.exe;--build;.;--config;Release - - Working Directory: D:/src/vcpkg/buildtrees/libpng/x86-uwp-rel - - See logs for more information: - - D:\src\vcpkg\buildtrees\libpng\build-x86-uwp-rel-out.log - D:\src\vcpkg\buildtrees\libpng\build-x86-uwp-rel-err.log - -Call Stack (most recent call first): - scripts/cmake/vcpkg_build_cmake.cmake:3 (execute_required_process) - ports/libpng/portfile.cmake:22 (vcpkg_build_cmake) - scripts/ports.cmake:84 (include) - - -Error: build command failed -``` - -Next, looking at the above logs (build-...-out.log and build-...-err.log). - -```no-highlight -// build-x86-uwp-rel-out.log -... -"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) -> -"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) -> -(ClCompile target) -> - D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj] - - -"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) -> -"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) -> -(Link target) -> - pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj] - D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj] - - 1 Warning(s) - 2 Error(s) - -Time Elapsed 00:00:04.19 -``` - -### Identify the problematic code - -Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658(v=vs.85).aspx) shows that `ExitProcess` is only available for desktop apps. Additionally, it's useful to see the surrounding context: - -```c -/* buildtrees\libpng\src\libpng-1.6.24\pngerror.c:769 */ - /* If control reaches this point, png_longjmp() must not return. The only - * choice is to terminate the whole process (or maybe the thread); to do - * this the ANSI-C abort() function is used unless a different method is - * implemented by overriding the default configuration setting for - * PNG_ABORT(). - */ - PNG_ABORT(); -``` - -A recursive search for `PNG_ABORT` reveals the definition: -```no-highlight -PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> findstr /snipl "PNG_ABORT" * -CHANGES:701: Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros -libpng-manual.txt:432:errors will result in a call to PNG_ABORT() which defaults to abort(). -libpng-manual.txt:434:You can #define PNG_ABORT() to a function that does something -libpng-manual.txt:2753:errors will result in a call to PNG_ABORT() which defaults to abort(). -libpng-manual.txt:2755:You can #define PNG_ABORT() to a function that does something -libpng-manual.txt:4226:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()), -libpng.3:942:errors will result in a call to PNG_ABORT() which defaults to abort(). -libpng.3:944:You can #define PNG_ABORT() to a function that does something -libpng.3:3263:errors will result in a call to PNG_ABORT() which defaults to abort(). -libpng.3:3265:You can #define PNG_ABORT() to a function that does something -libpng.3:4736:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()), -png.h:994: * will use it; otherwise it will call PNG_ABORT(). This function was -pngerror.c:773: * PNG_ABORT(). -pngerror.c:775: PNG_ABORT(); -pngpriv.h:459:#ifndef PNG_ABORT -pngpriv.h:461:# define PNG_ABORT() ExitProcess(0) -pngpriv.h:463:# define PNG_ABORT() abort() -``` - -This already gives us some great clues, but the full definition tells the complete story. - -```c -/* buildtrees\libpng\src\libpng-1.6.24\pngpriv.h:459 */ -#ifndef PNG_ABORT -# ifdef _WINDOWS_ -# define PNG_ABORT() ExitProcess(0) -# else -# define PNG_ABORT() abort() -# endif -#endif -``` - -`abort()` is a standard CRT call and certainly available in UWP, so we just need to convince libpng to be more platform agnostic. The easiest and most reliable way to achieve this is to patch the code; while in this particular case we could pass in a compiler flag to override `PNG_ABORT` because this is a private header, in general it is more reliable to avoid adding more required compiler switches when possible (especially when it isn't already exposed as a CMake option). - -### Patching the code to improve compatibility - -We recommend using git to create the patch file, since you'll already have it installed. -```no-highlight -PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git init . -Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/libpng-1.6.24/.git/ - -PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git add . -warning: LF will be replaced by CRLF in ANNOUNCE. -The file will have its original line endings in your working directory. -... - -PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git commit -m "temp" -[master (root-commit) 68f253f] temp - 422 files changed, 167717 insertions(+) -... -``` - -Now we can modify `pngpriv.h` to use `abort()` everywhere. -```c -/* buildtrees\libpng\src\libpng-1.6.24\pngpriv.h:459 */ -#ifndef PNG_ABORT -# define PNG_ABORT() abort() -#endif -``` - -The output of `git diff` is already in patch format, so we just need to save the patch into the `ports/libpng` directory. -```no-highlight -PS buildtrees\libpng\src\libpng-1.6.24> git diff | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch -``` - -Finally, we need to apply the patch after extracting the source. -```cmake -# ports\libpng\portfile.cmake -... -vcpkg_extract_source_archive(${ARCHIVE}) - -vcpkg_apply_patches( - SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/libpng-1.6.24 - PATCHES "${CMAKE_CURRENT_LIST_DIR}/use-abort-on-all-platforms.patch" -) - -vcpkg_configure_cmake( -... -``` - -### Verification - -To be completely sure this works from scratch, we need to remove the package and rebuild it: - -```no-highlight -PS D:\src\vcpkg> vcpkg remove libpng:x86-uwp -Package libpng:x86-uwp was successfully removed -``` -and complete delete the building directory: D:\src\vcpkg\buildtrees\libpng - -Now we try a fresh, from scratch install. -```no-highlight -PS D:\src\vcpkg> vcpkg install libpng:x86-uwp --- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp --- DOWNLOADS=D:/src/vcpkg/downloads --- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/libpng_x86-uwp --- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/libpng --- CURRENT_PORT_DIR=D:/src/vcpkg/ports/libpng/. --- Using cached D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz --- Extracting source D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz --- Extracting done --- Configuring x86-uwp-rel --- Configuring x86-uwp-rel done --- Configuring x86-uwp-dbg --- Configuring x86-uwp-dbg done --- Build x86-uwp-rel --- Build x86-uwp-rel done --- Build x86-uwp-dbg --- Build x86-uwp-dbg done --- Package x86-uwp-rel --- Package x86-uwp-rel done --- Package x86-uwp-dbg --- Package x86-uwp-dbg done -Package libpng:x86-uwp is installed -``` - -Finally, to fully commit and publish the changes, we need to bump the internal release number and add the patch file to source control, then make a Pull Request! - -```no-highlight -# ports\libpng\CONTROL -Source: libpng -Version: 1.6.24-1 -Build-Depends: zlib -``` diff --git a/docs/examples/patching.md b/docs/examples/patching.md new file mode 100644 index 000000000..98115400e --- /dev/null +++ b/docs/examples/patching.md @@ -0,0 +1,204 @@ +## Patching Example: Patching libpng to work for x86-uwp + +### Initial error logs +First, try building: + +```no-highlight +PS D:\src\vcpkg> vcpkg install libpng:x86-uwp +-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp +-- DOWNLOADS=D:/src/vcpkg/downloads +-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/libpng_x86-uwp +-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/libpng +-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/libpng/. +-- Using cached D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz +-- Extracting done +-- Configuring x86-uwp-rel +-- Configuring x86-uwp-rel done +-- Configuring x86-uwp-dbg +-- Configuring x86-uwp-dbg done +-- Build x86-uwp-rel +CMake Error at scripts/cmake/execute_required_process.cmake:14 (message): + Command failed: C:/Program + Files/CMake/bin/cmake.exe;--build;.;--config;Release + + Working Directory: D:/src/vcpkg/buildtrees/libpng/x86-uwp-rel + + See logs for more information: + + D:\src\vcpkg\buildtrees\libpng\build-x86-uwp-rel-out.log + D:\src\vcpkg\buildtrees\libpng\build-x86-uwp-rel-err.log + +Call Stack (most recent call first): + scripts/cmake/vcpkg_build_cmake.cmake:3 (execute_required_process) + ports/libpng/portfile.cmake:22 (vcpkg_build_cmake) + scripts/ports.cmake:84 (include) + + +Error: build command failed +``` + +Next, looking at the above logs (build-...-out.log and build-...-err.log). + +```no-highlight +// build-x86-uwp-rel-out.log +... +"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) -> +"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) -> +(ClCompile target) -> + D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj] + + +"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) -> +"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) -> +(Link target) -> + pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj] + D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj] + + 1 Warning(s) + 2 Error(s) + +Time Elapsed 00:00:04.19 +``` + +### Identify the problematic code + +Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658(v=vs.85).aspx) shows that `ExitProcess` is only available for desktop apps. Additionally, it's useful to see the surrounding context: + +```c +/* buildtrees\libpng\src\libpng-1.6.24\pngerror.c:769 */ + /* If control reaches this point, png_longjmp() must not return. The only + * choice is to terminate the whole process (or maybe the thread); to do + * this the ANSI-C abort() function is used unless a different method is + * implemented by overriding the default configuration setting for + * PNG_ABORT(). + */ + PNG_ABORT(); +``` + +A recursive search for `PNG_ABORT` reveals the definition: +```no-highlight +PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> findstr /snipl "PNG_ABORT" * +CHANGES:701: Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros +libpng-manual.txt:432:errors will result in a call to PNG_ABORT() which defaults to abort(). +libpng-manual.txt:434:You can #define PNG_ABORT() to a function that does something +libpng-manual.txt:2753:errors will result in a call to PNG_ABORT() which defaults to abort(). +libpng-manual.txt:2755:You can #define PNG_ABORT() to a function that does something +libpng-manual.txt:4226:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()), +libpng.3:942:errors will result in a call to PNG_ABORT() which defaults to abort(). +libpng.3:944:You can #define PNG_ABORT() to a function that does something +libpng.3:3263:errors will result in a call to PNG_ABORT() which defaults to abort(). +libpng.3:3265:You can #define PNG_ABORT() to a function that does something +libpng.3:4736:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()), +png.h:994: * will use it; otherwise it will call PNG_ABORT(). This function was +pngerror.c:773: * PNG_ABORT(). +pngerror.c:775: PNG_ABORT(); +pngpriv.h:459:#ifndef PNG_ABORT +pngpriv.h:461:# define PNG_ABORT() ExitProcess(0) +pngpriv.h:463:# define PNG_ABORT() abort() +``` + +This already gives us some great clues, but the full definition tells the complete story. + +```c +/* buildtrees\libpng\src\libpng-1.6.24\pngpriv.h:459 */ +#ifndef PNG_ABORT +# ifdef _WINDOWS_ +# define PNG_ABORT() ExitProcess(0) +# else +# define PNG_ABORT() abort() +# endif +#endif +``` + +`abort()` is a standard CRT call and certainly available in UWP, so we just need to convince libpng to be more platform agnostic. The easiest and most reliable way to achieve this is to patch the code; while in this particular case we could pass in a compiler flag to override `PNG_ABORT` because this is a private header, in general it is more reliable to avoid adding more required compiler switches when possible (especially when it isn't already exposed as a CMake option). + +### Patching the code to improve compatibility + +We recommend using git to create the patch file, since you'll already have it installed. +```no-highlight +PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git init . +Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/libpng-1.6.24/.git/ + +PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git add . +warning: LF will be replaced by CRLF in ANNOUNCE. +The file will have its original line endings in your working directory. +... + +PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git commit -m "temp" +[master (root-commit) 68f253f] temp + 422 files changed, 167717 insertions(+) +... +``` + +Now we can modify `pngpriv.h` to use `abort()` everywhere. +```c +/* buildtrees\libpng\src\libpng-1.6.24\pngpriv.h:459 */ +#ifndef PNG_ABORT +# define PNG_ABORT() abort() +#endif +``` + +The output of `git diff` is already in patch format, so we just need to save the patch into the `ports/libpng` directory. +```no-highlight +PS buildtrees\libpng\src\libpng-1.6.24> git diff | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch +``` + +Finally, we need to apply the patch after extracting the source. +```cmake +# ports\libpng\portfile.cmake +... +vcpkg_extract_source_archive(${ARCHIVE}) + +vcpkg_apply_patches( + SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/libpng-1.6.24 + PATCHES "${CMAKE_CURRENT_LIST_DIR}/use-abort-on-all-platforms.patch" +) + +vcpkg_configure_cmake( +... +``` + +### Verification + +To be completely sure this works from scratch, we need to remove the package and rebuild it: + +```no-highlight +PS D:\src\vcpkg> vcpkg remove libpng:x86-uwp +Package libpng:x86-uwp was successfully removed +``` +and complete delete the building directory: D:\src\vcpkg\buildtrees\libpng + +Now we try a fresh, from scratch install. +```no-highlight +PS D:\src\vcpkg> vcpkg install libpng:x86-uwp +-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp +-- DOWNLOADS=D:/src/vcpkg/downloads +-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/libpng_x86-uwp +-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/libpng +-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/libpng/. +-- Using cached D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz +-- Extracting source D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz +-- Extracting done +-- Configuring x86-uwp-rel +-- Configuring x86-uwp-rel done +-- Configuring x86-uwp-dbg +-- Configuring x86-uwp-dbg done +-- Build x86-uwp-rel +-- Build x86-uwp-rel done +-- Build x86-uwp-dbg +-- Build x86-uwp-dbg done +-- Package x86-uwp-rel +-- Package x86-uwp-rel done +-- Package x86-uwp-dbg +-- Package x86-uwp-dbg done +Package libpng:x86-uwp is installed +``` + +Finally, to fully commit and publish the changes, we need to bump the internal release number and add the patch file to source control, then make a Pull Request! + +```no-highlight +# ports\libpng\CONTROL +Source: libpng +Version: 1.6.24-1 +Build-Depends: zlib +``` diff --git a/docs/examples/using-sqlite.md b/docs/examples/using-sqlite.md deleted file mode 100644 index 35da141d0..000000000 --- a/docs/examples/using-sqlite.md +++ /dev/null @@ -1,177 +0,0 @@ -# Example: Using Sqlite - - - [Step 1: Install](#install) - - [Step 2: Use](#use) - - [VS/MSBuild Project (User-wide integration)](#msbuild) - - [CMake (Toolchain file)](#cmake) - - [Other integration options](../users/integration.md) - ---- - -## Step 1: Install - -First, we need to know what name [Sqlite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output: -```no-highlight -PS D:\src\vcpkg> .\vcpkg search sqlite -libodb-sqlite 2.4.0 Sqlite support for the ODB ORM library -sqlite3 3.15.0 SQLite is a software library that implements a se... - -If your library is not listed, please open an issue at: - https://github.com/Microsoft/vcpkg/issues -``` -Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages. - -Installing is then as simple as using the `install` command. -```no-highlight -PS D:\src\vcpkg> .\vcpkg install sqlite3 --- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows --- DOWNLOADS=D:/src/vcpkg/downloads --- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/sqlite3_x86-windows --- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/sqlite3 --- CURRENT_PORT_DIR=D:/src/vcpkg/ports/sqlite3/. --- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip... --- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip... OK --- Testing integrity of downloaded file... --- Testing integrity of downloaded file... OK --- Extracting source D:/src/vcpkg/downloads/sqlite-amalgamation-3150000.zip --- Extracting done --- Configuring x86-windows-rel --- Configuring x86-windows-rel done --- Configuring x86-windows-dbg --- Configuring x86-windows-dbg done --- Build x86-windows-rel --- Build x86-windows-rel done --- Build x86-windows-dbg --- Build x86-windows-dbg done --- Package x86-windows-rel --- Package x86-windows-rel done --- Package x86-windows-dbg --- Package x86-windows-dbg done --- Performing post-build validation --- Performing post-build validation done -Package sqlite3:x86-windows is installed -``` - -We can check that sqlite3 was successfully installed for x86 windows desktop by running the `list` command. -```no-highlight -PS D:\src\vcpkg> .\vcpkg list -sqlite3:x86-windows 3.15.0 SQLite is a software library that implements a se... -``` - -To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:`. -```no-highlight -PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows -``` - -See `.\vcpkg help triplet` for all supported targets. - ---- - -## Step 2: Use - -#### VS/MSBuild Project (User-wide integration) - -The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwards is no longer required and the integration is configured on a per-user basis. -```no-highlight -PS D:\src\vcpkg> .\vcpkg integrate install -Applied user-wide integration for this vcpkg root. - -All C++ projects can now #include any installed libraries. -Linking will be handled automatically. -Installing new libraries will make them instantly available. -``` -*Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.* - -You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 and the library will be automatically available. For Sqlite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html). - -To remove the integration for your user, you can use `.\vcpkg integrate remove`. - - -#### CMake (Toolchain File) - -The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as `-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`. - -If you are using CMake through Open Folder with Visual Studio 2017 you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations: - -```json -{ - "configurations": [{ - "name": "x86-Debug", - "generator": "Visual Studio 15 2017", - "configurationType" : "Debug", - "buildRoot": "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}", - "cmakeCommandArgs": "", - "buildCommandArgs": "-m -v:minimal", - "variables": [{ - "name": "CMAKE_TOOLCHAIN_FILE", - "value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake" - }] - }] -} -``` - -Now let's make a simple CMake project with a main file. -```cmake -# CMakeLists.txt -cmake_minimum_required(VERSION 3.0) -project(test) - -find_package(Sqlite3 REQUIRED) - -add_executable(main main.cpp) -target_link_libraries(main sqlite3) -``` -```cpp -// main.cpp -#include -#include - -int main() -{ - printf("%s\n", sqlite3_libversion()); - return 0; -} -``` - -Then, we build our project in the normal CMake way: -```no-highlight -PS D:\src\cmake-test> mkdir build -PS D:\src\cmake-test> cd build -PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake" - // omitted CMake output here // --- Build files have been written to: D:/src/cmake-test/build -PS D:\src\cmake-test\build> cmake --build . - // omitted MSBuild output here // -Build succeeded. - 0 Warning(s) - 0 Error(s) - -Time Elapsed 00:00:02.38 -PS D:\src\cmake-test\build> .\Debug\main.exe -3.15.0 -``` - -*Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.* - -##### Handling libraries without native cmake support - -Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2]. - -```cmake -# To find and use catch -find_path(CATCH_INCLUDE_DIR catch.hpp) -include_directories(${CATCH_INCLUDE_DIR}) - -# To find and use azure-storage-cpp -find_path(WASTORAGE_INCLUDE_DIR was/blob.h) -find_library(WASTORAGE_LIBRARY wastorage) -include_directories(${WASTORAGE_INCLUDE_DIR}) -link_libraries(${WASTORAGE_LIBRARY}) - -# Note that we recommend using the target-specific directives for a cleaner cmake: -# target_include_directories(main ${LIBRARY}) -# target_link_libraries(main PRIVATE ${LIBRARY}) -``` - -[1]: https://cmake.org/cmake/help/latest/command/find_path.html -[2]: https://cmake.org/cmake/help/latest/command/find_library.html diff --git a/docs/index.md b/docs/index.md index 90245d36a..d7b104ebc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,13 +2,13 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement are vital to its success! -- [How to use Sqlite in your application](examples/using-sqlite.md) +- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md) ### Examples -- [Example 1: Using Sqlite](examples/using-sqlite.md) -- [Example 2: Packaging zlib](examples/packaging-zlib.md) -- [Example 3: Patching libpng for x86-uwp](examples/patching-libpng.md) +- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md) +- [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md) +- [Patching Example: Patching libpng to work for x86-uwp](examples/patching.md) ### User Help diff --git a/docs/users/integration.md b/docs/users/integration.md index ce52abe23..fbaea41d9 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -35,7 +35,7 @@ cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.c ``` Projects configured with the Vcpkg toolchain file will have the appropriate Vcpkg folders added to the cmake search paths. This makes all libraries available to be found through `find_package()`, `find_path()`, and `find_library()`. -See [Example: Using Sqlite](../examples/using-sqlite.md) for a fully worked example using our CMake toolchain. +See [Installing and Using Packages Example: sqlite](../examples/installing-and-using-packages.md) for a fully worked example using our CMake toolchain. Note that we do not automatically add ourselves to your compiler include paths. To use a header-only library, simply use `find_path()`, which will correctly work on all platforms: ```cmake -- cgit v1.2.3 From 077b7f1378537478ec97a57af664ebba2efc0c86 Mon Sep 17 00:00:00 2001 From: Simon Brand Date: Fri, 16 Nov 2018 11:24:19 +0000 Subject: Add packaging GitHub repo example --- docs/about/faq.md | 2 +- docs/examples/packaging-github-repos.md | 59 +++++++++++++++++++++++++++++++++ docs/index.md | 1 + 3 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 docs/examples/packaging-github-repos.md (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index 57b908f48..b7c9d67c8 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -10,7 +10,7 @@ Yes! See [the `export` command](../users/integration.md#export). The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command. ## How do I get more libraries? -The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see our [packaging example](../examples/packaging-zipfiles.md). +The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see our examples on packaging [zipfiles](../examples/packaging-zipfiles.md) and [GitHub repos](../examples/packaging-github-repos.md). We recommend cloning directly from [GitHub](https://github.com/microsoft/vcpkg) and using `git pull` to update the list of portfiles. Once you've updated your portfiles, `vcpkg update` will indicate any installed libraries that are now out of date. diff --git a/docs/examples/packaging-github-repos.md b/docs/examples/packaging-github-repos.md new file mode 100644 index 000000000..af2e6141a --- /dev/null +++ b/docs/examples/packaging-github-repos.md @@ -0,0 +1,59 @@ +## Packaging Github Repos Example: libogg +### Create the CONTROL file +The `CONTROL` file is a simple set of fields describing the package's metadata. + +*For libogg, we'll create the file `ports\libogg\CONTROL` with the following contents:* +```no-highlight +Source: libogg +Version: 1.3.3 +Description: Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs. +``` + +### Create the portfile +`portfile.cmake` describes how to build and install the package. First we include `vcpkg_common_functions` to give us utilities for carrying this out: + +```no-highlight +include(vcpkg_common_functions) +``` + +Now we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md): + +```no-highlight +vcpkg_from_github( + OUT_SOURCE_PATH SOURCE_PATH + REPO xiph/ogg + REF v1.3.3 + SHA512 0bd6095d647530d4cb1f509eb5e99965a25cc3dd9b8125b93abd6b248255c890cf20710154bdec40568478eb5c4cde724abfb2eff1f3a04e63acef0fbbc9799b + HEAD_REF master +) +``` + +The important parts to update are `REPO` for the GitHub repository path, `REF` for a stable tag/commit to use, and `SHA512` with the checksum of the downloaded zipfile (you can get this easily by setting it to `1`, trying to install the package, and copying the checksum). + +Finally, we configure the project with CMake, install the package, and copy over the license file: + +```no-highlight +vcpkg_configure_cmake( + SOURCE_PATH ${SOURCE_PATH} + PREFER_NINJA +) +vcpkg_install_cmake() +file(INSTALL ${SOURCE_PATH}/COPYING DESTINATION ${CURRENT_PACKAGES_DIR}/share/libogg RENAME copyright) +``` + +Check the documentation for [`vcpkg_configure_cmake`](../maintainers/vcpkg_configure_cmake.md) and [`vcpkg_install_cmake`](../maintainers/vcpkg_install_cmake.md) if your package needs additional options. + +Now you can run `vcpkg install libogg` to build and install the package. + +### Suggested example portfiles +In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake. + +- Header only libraries + - rapidjson + - range-v3 +- MSBuild-based + - cppunit + - mpg123 +- Non-CMake, custom buildsystem + - openssl + - ffmpeg diff --git a/docs/index.md b/docs/index.md index d7b104ebc..69dbdcd1e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,6 +8,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too - [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md) - [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md) +- [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md) - [Patching Example: Patching libpng to work for x86-uwp](examples/patching.md) ### User Help -- cgit v1.2.3 From 380485194e9611241d3c9d6c93e92a6235d2b180 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Thu, 22 Nov 2018 14:48:18 -0800 Subject: [vcpkg_extract_source_archive_ex] Document vcpkg_extract_source_archive_ex --- docs/maintainers/portfile-functions.md | 1 + docs/maintainers/vcpkg_extract_source_archive.md | 2 +- .../maintainers/vcpkg_extract_source_archive_ex.md | 52 ++++++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/maintainers/vcpkg_extract_source_archive_ex.md (limited to 'docs') diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index 1aad301eb..f159f7f64 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -14,6 +14,7 @@ - [vcpkg\_download\_distfile](vcpkg_download_distfile.md) - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md) - [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md) +- [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md) - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md) - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md) - [vcpkg\_from\_git](vcpkg_from_git.md) diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md index 104032ffc..4971df960 100644 --- a/docs/maintainers/vcpkg_extract_source_archive.md +++ b/docs/maintainers/vcpkg_extract_source_archive.md @@ -1,6 +1,6 @@ # vcpkg_extract_source_archive -Extract an archive into the source directory. +Extract an archive into the source directory. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md). ## Usage ```cmake diff --git a/docs/maintainers/vcpkg_extract_source_archive_ex.md b/docs/maintainers/vcpkg_extract_source_archive_ex.md new file mode 100644 index 000000000..92c90b296 --- /dev/null +++ b/docs/maintainers/vcpkg_extract_source_archive_ex.md @@ -0,0 +1,52 @@ +# vcpkg_extract_source_archive_ex + +Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md). + +## Usage +```cmake +vcpkg_extract_source_archive_ex( + OUT_SOURCE_PATH + ARCHIVE <${ARCHIVE}> + [REF <1.0.0>] + [NO_REMOVE_ONE_LEVEL] + [WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/src>] + [PATCHES ...] +) +``` +## Parameters +### OUT_SOURCE_PATH +Specifies the out-variable that will contain the extracted location. + +This should be set to `SOURCE_PATH` by convention. + +### ARCHIVE +The full path to the archive to be extracted. + +This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md). + +### REF +A friendly name that will be used instead of the filename of the archive. + +By convention, this is set to the version number or tag fetched + +### WORKING_DIRECTORY +If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`. + +Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`). + +### PATCHES +A list of patches to be applied to the extracted sources. + +Relative paths are based on the port directory. + +### NO_REMOVE_ONE_LEVEL +Specifies that the default removal of the top level folder should not occur. + +## Examples + +* [bzip2](https://github.com/Microsoft/vcpkg/blob/master/ports/bzip2/portfile.cmake) +* [sqlite3](https://github.com/Microsoft/vcpkg/blob/master/ports/sqlite3/portfile.cmake) +* [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_extract_source_archive_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake) -- cgit v1.2.3