From 49cd3995862c0bed0701f84535812e1d0690896f Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 24 May 2017 23:33:16 -0700 Subject: [vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs. --- docs/EXAMPLES.md | 302 --------------------- docs/FAQ.md | 93 ------- docs/PRIVACY.md | 48 ---- docs/ROADMAP.md | 3 - docs/_config.yml | 2 +- docs/about/faq.md | 84 ++++++ docs/about/privacy.md | 44 +++ docs/example-3-patch-libpng.md | 204 -------------- docs/examples/packaging-zlib.md | 80 ++++++ docs/examples/patching-libpng.md | 204 ++++++++++++++ docs/examples/using-sqlite.md | 177 ++++++++++++ docs/index.md | 38 +++ docs/maintainers/control-files.md | 51 ++++ docs/maintainers/portfile-functions.md | 15 + docs/maintainers/vcpkg_acquire_msys.md | 47 ++++ docs/maintainers/vcpkg_apply_patches.md | 35 +++ docs/maintainers/vcpkg_build_msbuild.md | 59 ++++ docs/maintainers/vcpkg_configure_cmake.md | 49 ++++ docs/maintainers/vcpkg_copy_pdbs.md | 19 ++ docs/maintainers/vcpkg_copy_tool_dependencies.md | 21 ++ docs/maintainers/vcpkg_download_distfile.md | 39 +++ docs/maintainers/vcpkg_execute_required_process.md | 33 +++ docs/maintainers/vcpkg_extract_source_archive.md | 32 +++ docs/maintainers/vcpkg_find_acquire_program.md | 37 +++ docs/maintainers/vcpkg_from_github.md | 52 ++++ docs/maintainers/vcpkg_install_cmake.md | 25 ++ docs/regenerate.ps1 | 27 ++ docs/specifications/export-command.md | 172 ++++++++++++ docs/users/integration.md | 85 ++++++ 29 files changed, 1426 insertions(+), 651 deletions(-) delete mode 100644 docs/EXAMPLES.md delete mode 100644 docs/FAQ.md delete mode 100644 docs/PRIVACY.md delete mode 100644 docs/ROADMAP.md create mode 100644 docs/about/faq.md create mode 100644 docs/about/privacy.md delete mode 100644 docs/example-3-patch-libpng.md create mode 100644 docs/examples/packaging-zlib.md create mode 100644 docs/examples/patching-libpng.md create mode 100644 docs/examples/using-sqlite.md create mode 100644 docs/index.md create mode 100644 docs/maintainers/control-files.md create mode 100644 docs/maintainers/portfile-functions.md create mode 100644 docs/maintainers/vcpkg_acquire_msys.md create mode 100644 docs/maintainers/vcpkg_apply_patches.md create mode 100644 docs/maintainers/vcpkg_build_msbuild.md create mode 100644 docs/maintainers/vcpkg_configure_cmake.md create mode 100644 docs/maintainers/vcpkg_copy_pdbs.md create mode 100644 docs/maintainers/vcpkg_copy_tool_dependencies.md create mode 100644 docs/maintainers/vcpkg_download_distfile.md create mode 100644 docs/maintainers/vcpkg_execute_required_process.md create mode 100644 docs/maintainers/vcpkg_extract_source_archive.md create mode 100644 docs/maintainers/vcpkg_find_acquire_program.md create mode 100644 docs/maintainers/vcpkg_from_github.md create mode 100644 docs/maintainers/vcpkg_install_cmake.md create mode 100644 docs/regenerate.ps1 create mode 100644 docs/specifications/export-command.md create mode 100644 docs/users/integration.md (limited to 'docs') diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md deleted file mode 100644 index 0d58b17d7..000000000 --- a/docs/EXAMPLES.md +++ /dev/null @@ -1,302 +0,0 @@ -# Vcpkg - -## Overview -Vcpkg helps you get C and C++ libraries on Windows. - -For short description of available commands, run `.\vcpkg help`. - -## Table of Contents -- Example 1: Using Sqlite - - Step 1: Build - - Step 2: Use - - Option A: VS Project (User-wide integration) - - Option B: CMake (Toolchain file) - - Option C: Other buildsystems - - Option D: VS Project (Individual Project integration) -- Example 2: Package a remote project (zlib) -- Example 3: Patching libpng to work for uwp-x86 - - -## Example 1: Using Sqlite - -### Step 1: Build - -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: -``` -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. -``` -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. -``` -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 `:`. -``` -PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows -``` - -See `.\vcpkg help triplet` for all supported targets. - - -### Step 2: Use - -#### Option A: VS 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 require administrator access the first time it is used on a given machine. After the first use, administrator access is no longer required and the integration is on a per-user basis. -``` -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`. - - -#### Option B: 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`. - -Alternatively, 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) - -link_libraries(sqlite3) -add_executable(main main.cpp) -``` -```cpp -// main.cpp -#include -#include - -int main() -{ - printf("%s\n", sqlite3_libversion()); - return 0; -} -``` - -Then, we build our project in the normal CMake way: -``` -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.* - -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 - - -#### Option C: Other buildsystems - -Libraries are installed into the `installed\` subfolder, partitioned by architecture (e.g. x86-windows): -* The header files are installed to `installed\x86-windows\include` -* Release `.lib` files are installed to `installed\x86-windows\lib` or `installed\x86-windows\lib\manual-link` -* Release `.dll` files are installed to `installed\x86-windows\bin` -* Debug `.lib` files are installed to `installed\x86-windows\debug\lib` or `installed\x86-windows\debug\lib\manual-link` -* Debug `.dll` files are installed to `installed\x86-windows\debug\bin` - -See your build system specific documentation for how to use prebuilt binaries. - -Generally, to run any produced executables you will also need to either copy the needed `dll` files to the same folder as your `exe` or *prepend* the correct `bin` directory to your path. - -Example for setting the path for debug mode in powershell: -``` -PS D:\src\vcpkg> $env:path = "D:\src\vcpkg\installed\x86-windows\debug\bin;" + $env:path -``` - -#### Option D: VS Project (Individual Project integration) - -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. -``` -PS D:\src\vcpkg> .\vcpkg integrate project -Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg - -With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste: - Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems" -``` -*Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.* - - -## Example 2: Package a remote project (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/zlib128.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`. - -*`zlib128.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\`. - -``` -PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib128.zip zlib128.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 simply formatted set of fields describing the package's metadata. - -*For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:* -``` -Source: zlib2 -Version: 1.2.8 -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. - -``` -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/zlib128.zip --- Extracting source D:/src/vcpkg/downloads/zlib128.zip --- Extracting done --- Configuring x86-windows-rel -CMake Error at scripts/cmake/vcpkg_execute_required_process.cmake:13 (message): - Command failed: C:/Program Files - (x86)/CMake/bin/cmake.exe;D:/src/vcpkg/buildtrees/zlib2/src/zlib128;-G;Ninja;-DCMAKE_VERBOSE_MAKEFILE=ON;-DCMAKE_BUILD_TYPE=Release;-DCMAKE_TOOLCHAIN_FILE=D:/src/vcpkg/triplets/x86-windows.cmake;-DCMAKE_PREFIX_PATH=D:/src/vcpkg/installed/x86-windows;- -DCMAKE_INSTALL_PREFIX=D:/src/vcpkg/packages/zlib2_x86-windows - - - Working Directory: D:/src/vcpkg/buildtrees/zlib2/x86-windows-rel - - See logs for more information: - - D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-out.log - D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-err.log - -Call Stack (most recent call first): - scripts/cmake/vcpkg_configure_cmake.cmake:15 (vcpkg_execute_required_process) - ports/zlib2/portfile.cmake:8 (vcpkg_configure_cmake) - scripts/ports.cmake:105 (include) - scripts/ports.cmake:184 (build) -``` - -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 - - mpg123 - - glew -- Non-CMake, custom buildsystem - - openssl - - boost diff --git a/docs/FAQ.md b/docs/FAQ.md deleted file mode 100644 index 0a82d320e..000000000 --- a/docs/FAQ.md +++ /dev/null @@ -1,93 +0,0 @@ -# Frequently Asked Questions: Vcpkg - -Vcpkg is a tool to acquire C++ open source library and rebuild them on Windows. - -## Can I contribute a new library? -Yes! Start out by reading our [contribution guidelines](../CONTRIBUTING.md). - -## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg? -In the preview release, we do not have a supported way to distribute individual binary packages. This avoids the issue of trying to use a specific pre-built package against differently built dependencies. As such, we have also not specified a stable format for the built library packages. - -We instead recommend copying the entire system as a whole (which ensures that every package and its dependencies stay in sync with each other). - -## How do I update libraries? -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\`](../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.md#example-2)). - -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 [Example #2](EXAMPLES.md#example-2) 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 `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. - -To see an example of this, look at [`ports\opengl\portfile.cmake`](../ports/opengl/portfile.cmake) package which simply copies files out of the Windows SDK. - -## Which platforms I can target with Vcpkg? -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.exe` 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). - -## 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!). This is because a package in Vcpkg corresponds to the `X-dev` or `X-devel` packages in other system package managers. - -To use different versions of a library (for different projects), we recommend making separate instances of Vcpkg and using the [per-project integration mechanisms](EXAMPLES.md#example-1-2-d). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard VCS techniques. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\package\`. - -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? -See the [Privacy document](PRIVACY.md) for all information regarding privacy. - -## Can I use my own CMake toolchain file with Vcpkg's toolchain file? -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. - -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. - -## How is CMake used internally by Vcpkg? -Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows (does not require system-wide installation) and reasonably legible for unfamiliar users. - -## Will Vcpkg support downloading compiled binaries from a public or private server? -We do plan to eventually support downloading precompiled binaries, similar to other system package managers. - -In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. - -## What Visual C++ toolsets are supported? -We plan to only support Visual Studio 2015 and above. - -## Why does Visual Studio not use my libraries with user-wide integration enabled? -Enabling user-wide integration (`vcpkg integrate install`) changes the default for some project properties. In particular, "C/C++/General/Additional Include Directories" and "Linker/General/Additional Library Directories" are normally blank *without* user-wide integration. *With* integration, a blank value means that the augmented default supplied by vcpkg is overridden, and headers/libraries will not be found. To reinstate the default, set the properties to inherit from parent. - -## Can I acquire my package's sources by Git url+tag? -Yes, however we prefer compressed archives of the specific release/commit since the internal downloads and build trees are meant to be read only. Github provides archives for every commit, tag, and branch, so it's always possible to perform this substitution for repositories hosted there. - -See [`ports\cpprestsdk\portfile.cmake`](../ports/cpprestsdk/portfile.cmake) for an example of using git directly. - -## 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. - -- **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. - -- **Per-dll vs Per-application**. NuGet is highly project centric. This works well in managed languages with naturally stable ABIs, because base libraries can continue to evolve without breaking those higher up. However, in native languages where the ABI is much more fragile, the only robust strategy is to explicitly build each library against the exact dependencies that will be included in the final application. This is difficult to ensure in NuGet and leads to a highly disconnected and independently versioned ecosystem. - -## Why not Conan? -Conan.io is a publicly-federated, project-centric, cross-platform, C++ package manager written in python. Our primary differences are: - -- **Public federation vs private federation**. Conan relies on individuals publishing independent copies of each package. We believe this approach encourages a large number of packages that are all broken in different ways. We believe it is a waste of user's time to pick through the list of 20+ public packages for Boost 1.56 to determine the handful that will work for their particular situation. In contrast, we believe there should be a single, collaboratively maintained version which works for the vast majority of cases and allow users to hack freely on their private versions. We believe this will result in a set of high quality packages that are heavily tested with each other and form a fantastic base for any private modifications you need. - -- **Per-dll vs Per-application**. When dependencies are independently versioned on a library level, it encourages every build environment to be a completely unique, unable to take advantage of or contribute to a solid, well tested ecosystem. In contrast, by versioning all libraries together as a platform (similar to a system package manager), we hope to congregate testing and effort on very common sets of library versions to maximize the quality and stability of the ecosystem. This also completely designs out the ability for a library to ask for versions that conflict with the application's choices (I want openssl Z and boost X but X only works with openssl Y). - -- **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. - -## Why not Chocolatey? -Chocolatey is an excellent system for managing software. 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!). diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md deleted file mode 100644 index ad345c809..000000000 --- a/docs/PRIVACY.md +++ /dev/null @@ -1,48 +0,0 @@ - -# Privacy document for vcpkg - - -## Do you collect telemetry data? What is it used for? - -We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY collect information from invocations of the tool itself; we do NOT add any tracking information into the produced libraries. -We use this information to understand usage issues and to guide tool improvements. - - -## 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. - -Here is an example of an event for the command line `vcpkg install zlib`: -``` -[{ - "ver": 1, - "name": "Microsoft.ApplicationInsights.Event", - "time": "2016-09-01T00:19:10.949Z", - "sampleRate": 100.000000, - "seq": "0:0", - "iKey": "aaaaaaaa-4393-4dd9-ab8e-97e8fe6d7603", - "flags": 0.000000, - "tags": { - "ai.device.os": "Windows", - "ai.device.osVersion": "10.0.14912", - "ai.session.id": "aaaaaaaa-7c69-4b83-7d82-8a4198d7e88d", - "ai.user.id": "aaaaaaaa-c9ab-4bf5-0847-a3455f539754", - "ai.user.accountAcquisitionDate": "2016-08-20T00:38:09.860Z" - }, - "data": { - "baseType": "EventData", - "baseData": { - "ver": 2, - "name": "commandline_test7", - "properties": { "version":"0.0.30-9b4e44a693459c0a618f370681f837de6dd95a30","cmdline":"install zlib","command":"install","installplan":"zlib:x86-windows" }, - "measurements": { "elapsed_us":68064.355736 } - } - } -}] -``` -In the source code (included in `toolsrc\`), you can search for calls to the functions `TrackProperty()` and `TrackMetric()` to see every specific data point we collect. - - -## Is the data stored on my system? - -We store each event document in your temporary files directory. These will be cleaned out whenever you clear your temporary files. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index df6e3853e..000000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -1,3 +0,0 @@ -# Roadmap - - diff --git a/docs/_config.yml b/docs/_config.yml index 2f7efbeab..c4192631f 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1 +1 @@ -theme: jekyll-theme-minimal \ No newline at end of file +theme: jekyll-theme-cayman \ No newline at end of file diff --git a/docs/about/faq.md b/docs/about/faq.md new file mode 100644 index 000000000..85a0c14db --- /dev/null +++ b/docs/about/faq.md @@ -0,0 +1,84 @@ +# Frequently Asked Questions + +## Can I contribute a new library? +Yes! Start out by reading our [contribution guidelines](https://github.com/Microsoft/vcpkg/blob/master/CONTRIBUTING.md). + +## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg? +Yes! See [the `export` command](../users/integration.md#export). + +## How do I update libraries? +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). + +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. + +## 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. + +To see an example of this, look at [`ports\opengl\portfile.cmake`](https://github.com/microsoft/vcpkg/blob/master/ports/opengl/portfile.cmake) which simply copies files out of the Windows SDK. + +## Which platforms I can target with Vcpkg? +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)! + +## 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. + +To use different versions of a library for different projects, we recommend making separate instances of Vcpkg and using the [per-project integration mechanisms](../users/integration.md). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard `git` commands. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\\`. + +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? +See the [Privacy document](privacy.md) for all information regarding privacy. + +## Can I use my own CMake toolchain file with Vcpkg's toolchain file? +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. + +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. + +## How is CMake used internally by Vcpkg? +Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows, does not require system-wide installation, and legible for unfamiliar users. + +## Will Vcpkg support downloading compiled binaries from a public or private server? +We would like to eventually support downloading precompiled binaries, similar to other system package managers. + +In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See [the `export` command](../users/integration.md#export). + +## What Visual C++ toolsets are supported? +We support Visual Studio 2015 Update 3 and above. + +## Why does Visual Studio not use my libraries with user-wide integration enabled? +Enabling user-wide integration (`vcpkg integrate install`) changes the default for some project properties. In particular, "C/C++/General/Additional Include Directories" and "Linker/General/Additional Library Directories" are normally blank *without* user-wide integration. *With* integration, a blank value means that the augmented default supplied by vcpkg is overridden, and headers/libraries will not be found. To reinstate the default, set the properties to inherit from parent. + +## 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. + +- **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. + +- **Per-dll vs Per-application**. NuGet is highly project centric. This works well in managed languages with naturally stable ABIs, because base libraries can continue to evolve without breaking those higher up. However, in native languages where the ABI is much more fragile, the only robust strategy is to explicitly build each library against the exact dependencies that will be included in the final application. This is difficult to ensure in NuGet and leads to a highly disconnected and independently versioned ecosystem. + +## Why not Conan? +Conan.io is a publicly-federated, project-centric, cross-platform, C++ package manager written in python. Our primary differences are: + +- **Public federation vs private federation**. Conan relies on individuals publishing independent copies of each package. We believe this approach encourages a large number of packages that are all broken in different ways. We believe it is a waste of user's time to pick through the list of 20+ public packages for Boost 1.56 to determine the handful that will work for their particular situation. In contrast, we believe there should be a single, collaboratively maintained version which works for the vast majority of cases and allow users to hack freely on their private versions. We believe this will result in a set of high quality packages that are heavily tested with each other and form a fantastic base for any private modifications you need. + +- **Per-dll vs Per-application**. When dependencies are independently versioned on a library level, it encourages every build environment to be a completely unique, unable to take advantage of or contribute to a solid, well tested ecosystem. In contrast, by versioning all libraries together as a platform (similar to a system package manager), we hope to congregate testing and effort on very common sets of library versions to maximize the quality and stability of the ecosystem. This also completely designs out the ability for a library to ask for versions that conflict with the application's choices (I want openssl Z and boost X but X only claims to work with openssl Y). + +- **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. + +## 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!). diff --git a/docs/about/privacy.md b/docs/about/privacy.md new file mode 100644 index 000000000..9ff0e7a47 --- /dev/null +++ b/docs/about/privacy.md @@ -0,0 +1,44 @@ + +# Privacy and Vcpkg + +## Do you collect telemetry data? What is it used for? + +We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY collect information from invocations of the tool itself; we do NOT add any tracking information into the produced libraries. We use this information to understand usage issues, such as failing packages, and to guide tool improvements. + +## 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. + +Here is an example of an event for the command line `vcpkg install zlib`: +```json +[{ + "ver": 1, + "name": "Microsoft.ApplicationInsights.Event", + "time": "2016-09-01T00:19:10.949Z", + "sampleRate": 100.000000, + "seq": "0:0", + "iKey": "aaaaaaaa-4393-4dd9-ab8e-97e8fe6d7603", + "flags": 0.000000, + "tags": { + "ai.device.os": "Windows", + "ai.device.osVersion": "10.0.14912", + "ai.session.id": "aaaaaaaa-7c69-4b83-7d82-8a4198d7e88d", + "ai.user.id": "aaaaaaaa-c9ab-4bf5-0847-a3455f539754", + "ai.user.accountAcquisitionDate": "2016-08-20T00:38:09.860Z" + }, + "data": { + "baseType": "EventData", + "baseData": { + "ver": 2, + "name": "commandline_test7", + "properties": { "version":"0.0.30-9b4e44a693459c0a618f370681f837de6dd95a30","cmdline":"install zlib","command":"install","installplan":"zlib:x86-windows" }, + "measurements": { "elapsed_us":68064.355736 } + } + } +}] +``` +In the source code (included in `toolsrc\`), you can search for calls to the functions `TrackProperty()` and `TrackMetric()` to see every specific data point we collect. + +## Is the data stored on my system? + +We store each event document in your temporary files directory. These will be cleaned out whenever you clear your temporary files. diff --git a/docs/example-3-patch-libpng.md b/docs/example-3-patch-libpng.md deleted file mode 100644 index a47a2626a..000000000 --- a/docs/example-3-patch-libpng.md +++ /dev/null @@ -1,204 +0,0 @@ -## Example 3: Patching libpng to work for uwp-x86 - -### Initial error logs -First, try building: - -``` -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). - -``` -// 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: -``` -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 - -I recommend using git to create the patch file, since you'll already have it installed. -``` -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. -``` -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: - -``` -PS D:\src\vcpkg> vcpkg remove libpng:x86-uwp -Package libpng:x86-uwp was successfully removed -``` -and delete the building directory: D:\src\vcpkg\buildtrees\libpng - -Now we try a fresh, from scratch install. -``` -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. - -``` -# ports\libpng\CONTROL -Source: libpng -Version: 1.6.24-1 -Build-Depends: zlib -``` diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zlib.md new file mode 100644 index 000000000..81bc58314 --- /dev/null +++ b/docs/examples/packaging-zlib.md @@ -0,0 +1,80 @@ +## 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/zlib128.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`. + +*`zlib128.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/zlib128.zip zlib128.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 simply formatted 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.8 +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/zlib128.zip +-- Extracting source D:/src/vcpkg/downloads/zlib128.zip +-- Extracting done +-- Configuring x86-windows-rel +CMake Error at scripts/cmake/vcpkg_execute_required_process.cmake:13 (message): + Command failed: C:/Program Files + (x86)/CMake/bin/cmake.exe;D:/src/vcpkg/buildtrees/zlib2/src/zlib128;-G;Ninja;-DCMAKE_VERBOSE_MAKEFILE=ON;-DCMAKE_BUILD_TYPE=Release;-DCMAKE_TOOLCHAIN_FILE=D:/src/vcpkg/triplets/x86-windows.cmake;-DCMAKE_PREFIX_PATH=D:/src/vcpkg/installed/x86-windows;- +DCMAKE_INSTALL_PREFIX=D:/src/vcpkg/packages/zlib2_x86-windows + + + Working Directory: D:/src/vcpkg/buildtrees/zlib2/x86-windows-rel + + See logs for more information: + + D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-out.log + D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-err.log + +Call Stack (most recent call first): + scripts/cmake/vcpkg_configure_cmake.cmake:15 (vcpkg_execute_required_process) + ports/zlib2/portfile.cmake:8 (vcpkg_configure_cmake) + scripts/ports.cmake:105 (include) + scripts/ports.cmake:184 (build) +``` + +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 + - mpg123 + - glew +- Non-CMake, custom buildsystem + - openssl + - boost diff --git a/docs/examples/patching-libpng.md b/docs/examples/patching-libpng.md new file mode 100644 index 000000000..2337b73da --- /dev/null +++ b/docs/examples/patching-libpng.md @@ -0,0 +1,204 @@ +## 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/using-sqlite.md b/docs/examples/using-sqlite.md new file mode 100644 index 000000000..d12695bfb --- /dev/null +++ b/docs/examples/using-sqlite.md @@ -0,0 +1,177 @@ +# 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 afterwords 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 new file mode 100644 index 000000000..9b279baf0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,38 @@ +### 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. + +- [How to use Sqlite in your application](examples/using-sqlite.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) + +### User Help + +- [Integration with build systems](users/integration.md) + +### Maintainer help + +- [Control files](maintainers/control-files.md) +- [Portfile functions](maintainers/portfile-functions.md) + +### Specifications + +- [Export](specifications/export-command.md) + +### Blog posts + +- [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/) +- [Vcpkg 3 Months Anniversary, Survey](https://blogs.msdn.microsoft.com/vcblog/2017/01/11/vcpkg-3-months-anniversary-survey/) +- [Vcpkg updates: Static linking is now available](https://blogs.msdn.microsoft.com/vcblog/2016/11/01/vcpkg-updates-static-linking-is-now-available/) +- [Vcpkg: a tool to acquire and build C++ open source libraries on Windows](https://blogs.msdn.microsoft.com/vcblog/2016/09/19/vcpkg-a-tool-to-acquire-and-build-c-open-source-libraries-on-windows/) + +### Other + +- [FAQ](about/faq.md) +- [Privacy](about/privacy.md) diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md new file mode 100644 index 000000000..1cb444df3 --- /dev/null +++ b/docs/maintainers/control-files.md @@ -0,0 +1,51 @@ +## `CONTROL` files +Each port has some static metadata in the form of a `CONTROL` file. This file uses the same rough syntax as and a subset of the fields from [the Debian `control` format][debian]. + +Fields are case-sensitive. + +[debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html + +### Recognized fields + +#### Source +The name of the port. + +#### Version +The port version. + +This field should be an alphanumeric string which may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bitstrings and are only evaluated for equality. + +By convention, if a portfile is modified without incrementing the "upstream" version, a `-#` is appended to create a unique version string. + +Example: +```no-highlight +Version: 1.0.5-2 +``` + +#### Description +A description of the library + +The first sentence of the description should concisely describe the purpose and contents of the library. Then, a larger description including the library's "proper name" should follow. + +#### Maintainer +Reserved for future use. + +#### Build-Depends +The list of dependencies required to build and use this library. + +Example: +```no-highlight +Build-Depends: zlib, libpng, libjpeg-turbo, tiff +``` + +Unlike dpkg, Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified. + +*For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies* + +Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside brackets is substring-compared against the triplet name. __This will change in a future version to not depend on the triplet name.__ + +Example: +```no-highlight +Build-Depends: zlib [windows], openssl [windows], boost [windows], websocketpp [windows] +``` + diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md new file mode 100644 index 000000000..705d65b7e --- /dev/null +++ b/docs/maintainers/portfile-functions.md @@ -0,0 +1,15 @@ + + +# Portfile helper functions +- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md) +- [vcpkg\_apply\_patches](vcpkg_apply_patches.md) +- [vcpkg\_build\_msbuild](vcpkg_build_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) +- [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\_find\_acquire\_program](vcpkg_find_acquire_program.md) +- [vcpkg\_from\_github](vcpkg_from_github.md) +- [vcpkg\_install\_cmake](vcpkg_install_cmake.md) diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/docs/maintainers/vcpkg_acquire_msys.md new file mode 100644 index 000000000..46cda81fd --- /dev/null +++ b/docs/maintainers/vcpkg_acquire_msys.md @@ -0,0 +1,47 @@ +# vcpkg_acquire_msys + +Download and prepare an MSYS2 instance. + +## Usage +```cmake +vcpkg_acquire_msys() +``` + +## Parameters +### MSYS_ROOT_VAR +An out-variable that will be set to the path to MSYS2. + +## Notes +A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`: +```cmake +vcpkg_acquire_msys(MSYS_ROOT) +set(BASH ${MSYS_ROOT}/usr/bin/bash.exe) + +vcpkg_execute_required_process( + COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh" + WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel + LOGNAME build-${TARGET_TRIPLET}-rel +) +``` +To ensure a package is available: +```cmake +vcpkg_acquire_msys(MSYS_ROOT) +set(BASH ${MSYS_ROOT}/usr/bin/bash.exe) + +message(STATUS "Installing MSYS Packages") +vcpkg_execute_required_process( + COMMAND + ${BASH} --noprofile --norc -c + "pacman -Sy --noconfirm --needed make" + WORKING_DIRECTORY ${MSYS_ROOT} + LOGNAME pacman-${TARGET_TRIPLET}) +``` + +## Examples + +* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) +* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake) +* [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_acquire_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake) diff --git a/docs/maintainers/vcpkg_apply_patches.md b/docs/maintainers/vcpkg_apply_patches.md new file mode 100644 index 000000000..d4d8dbfec --- /dev/null +++ b/docs/maintainers/vcpkg_apply_patches.md @@ -0,0 +1,35 @@ +# vcpkg_apply_patches + +Apply a set of patches to a source tree. + +## Usage +```cmake +vcpkg_apply_patches( + SOURCE_PATH <${SOURCE_PATH}> + [QUIET] + PATCHES ... +) +``` + +## Parameters +### SOURCE_PATH +The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. + +### PATCHES +A list of patches that are applied to the source tree. + +Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\\` directory. + +### QUIET +Disables the warning message upon failure. + +This should only be used for edge cases, such as patches that are known to fail even on a clean source tree. + +## Examples + +* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake) +* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake) +* [libpng](https://github.com/Microsoft/vcpkg/blob/master/ports/libpng/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_apply_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake) diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md new file mode 100644 index 000000000..178964fcd --- /dev/null +++ b/docs/maintainers/vcpkg_build_msbuild.md @@ -0,0 +1,59 @@ +# vcpkg_build_msbuild + +Build an msbuild-based project. + +## Usage +```cmake +vcpkg_build_msbuild( + PROJECT_PATH <${SOURCE_PATH}/port.sln> + [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 ...] +) +``` + +## Parameters +### PROJECT_PATH +The path to the solution (`.sln`) or project (`.vcxproj`) file. + +### 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 + +* [libuv](https://github.com/Microsoft/vcpkg/blob/master/ports/libuv/portfile.cmake) +* [zeromq](https://github.com/Microsoft/vcpkg/blob/master/ports/zeromq/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_build_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake) diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md new file mode 100644 index 000000000..93f661767 --- /dev/null +++ b/docs/maintainers/vcpkg_configure_cmake.md @@ -0,0 +1,49 @@ +# vcpkg_configure_cmake + +Configure CMake for Debug and Release builds of a project. + +## Usage +```cmake +vcpkg_configure_cmake( + SOURCE_PATH <${SOURCE_PATH}> + [PREFER_NINJA] + [GENERATOR <"NMake Makefiles">] + [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] + [OPTIONS_RELEASE <-DOPTIMIZE=1>...] + [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] +) +``` + +## Parameters +### SOURCE_PATH +Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. + +### PREFER_NINJA +Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja. + +### GENERATOR +Specifies the precise generator to use. + +This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. If used for this purpose, it should be set to "NMake Makefiles". + +### OPTIONS +Additional options passed to CMake during the configuration. + +### OPTIONS_RELEASE +Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`. + +### OPTIONS_DEBUG +Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`. + +## Notes +This command supplies many common arguments to CMake. To see the full list, examine the source. + +## Examples + +* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) +* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_configure_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake) diff --git a/docs/maintainers/vcpkg_copy_pdbs.md b/docs/maintainers/vcpkg_copy_pdbs.md new file mode 100644 index 000000000..6bfa488db --- /dev/null +++ b/docs/maintainers/vcpkg_copy_pdbs.md @@ -0,0 +1,19 @@ +# vcpkg_copy_pdbs + +Automatically locate pdbs in the build tree and copy them adjacent to all DLLs. + +## Usage +```cmake +vcpkg_copy_pdbs() +``` + +## Notes +This command should always be called by portfiles after they have finished rearranging the binary output. + +## Examples + +* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_copy_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake) diff --git a/docs/maintainers/vcpkg_copy_tool_dependencies.md b/docs/maintainers/vcpkg_copy_tool_dependencies.md new file mode 100644 index 000000000..05d74f0b2 --- /dev/null +++ b/docs/maintainers/vcpkg_copy_tool_dependencies.md @@ -0,0 +1,21 @@ +# vcpkg_copy_tool_dependencies + +Copy all DLL dependencies of built tools into the tool folder. + +## Usage +```cmake +vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>) +``` +## Parameters +The path to the directory containing the tools. + +## Notes +This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools. + +## Examples + +* [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake) +* [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_copy_tool_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake) diff --git a/docs/maintainers/vcpkg_download_distfile.md b/docs/maintainers/vcpkg_download_distfile.md new file mode 100644 index 000000000..7897610e3 --- /dev/null +++ b/docs/maintainers/vcpkg_download_distfile.md @@ -0,0 +1,39 @@ +# vcpkg_download_distfile + +Download and cache a file needed for this port. + +## Usage +```cmake +vcpkg_download_distfile( + + URLS ... + FILENAME + SHA512 <5981de...> +) +``` +## Parameters +### OUT_VARIABLE +This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources. + +### URLS +A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given. + +### FILENAME +The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts. + +### SHA512 +The expected hash for the file. + +If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch. + +## Notes +The command [`vcpkg_from_github`](vcpkg_from_github.md) should be used instead of this for downloading the main archive for GitHub projects. + +## Examples + +* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake) +* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake) +* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_download_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake) diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md new file mode 100644 index 000000000..4b1a7e081 --- /dev/null +++ b/docs/maintainers/vcpkg_execute_required_process.md @@ -0,0 +1,33 @@ +# vcpkg_execute_required_process + +Execute a process with logging and fail the build if the command fails. + +## Usage +```cmake +vcpkg_execute_required_process( + COMMAND <${PERL}> [...] + WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg> + LOGNAME +) +``` +## Parameters +### COMMAND +The command to be executed, along with its arguments. + +### WORKING_DIRECTORY +The directory to execute the command in. + +### LOGNAME +The prefix to use for the log files. + +This should be a unique name for different triplets so that the logs don't conflict when building multiple at once. + +## Examples + +* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) +* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) +* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake) +* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_execute_required_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake) diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md new file mode 100644 index 000000000..104032ffc --- /dev/null +++ b/docs/maintainers/vcpkg_extract_source_archive.md @@ -0,0 +1,32 @@ +# vcpkg_extract_source_archive + +Extract an archive into the source directory. + +## Usage +```cmake +vcpkg_extract_source_archive( + <${ARCHIVE}> [<${TARGET_DIRECTORY}>] +) +``` +## Parameters +### ARCHIVE +The full path to the archive to be extracted. + +This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md). + +### TARGET_DIRECTORY +If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}\src\`. + +This can be used to mimic git submodules, by extracting into a subdirectory of another archive. + +## Notes +This command will also create a tracking file named .extracted in the TARGET_DIRECTORY. This file, when present, will suppress the extraction of the archive. + +## Examples + +* [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake) +* [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake) +* [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_extract_source_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake) diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md new file mode 100644 index 000000000..209b4416e --- /dev/null +++ b/docs/maintainers/vcpkg_find_acquire_program.md @@ -0,0 +1,37 @@ +# vcpkg_find_acquire_program + +Download or find a well-known tool. + +## Usage +```cmake +vcpkg_find_acquire_program() +``` +## Parameters +### VAR +This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable. + +## Notes +The current list of programs includes: + +- 7Z +- BISON +- FLEX +- PERL +- PYTHON2 +- PYTHON3 +- JOM +- MESON +- NASM +- NINJA +- YASM + +Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md). + +## Examples + +* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) +* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) +* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_find_acquire_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake) diff --git a/docs/maintainers/vcpkg_from_github.md b/docs/maintainers/vcpkg_from_github.md new file mode 100644 index 000000000..cb7849fcc --- /dev/null +++ b/docs/maintainers/vcpkg_from_github.md @@ -0,0 +1,52 @@ +# vcpkg_from_github + +Download and extract a project from GitHub. Enables support for `install --head`. + +## Usage: +```cmake +vcpkg_from_github( + OUT_SOURCE_PATH + REPO + [REF ] + [SHA512 <45d0d7f8cc350...>] + [HEAD_REF ] +) +``` + +## Parameters: +### 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 and repository on GitHub. + +### REF +A stable git commit-ish (ideally a tag) that will not change contents. + +If `REF` is specified, `SHA512` must also be specified. + +### SHA512 +The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz). + +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. + +This exports the `VCPKG_HEAD_VERSION` variable during head builds. + +## Examples: + +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake) +* [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_from_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake) diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md new file mode 100644 index 000000000..e199d1292 --- /dev/null +++ b/docs/maintainers/vcpkg_install_cmake.md @@ -0,0 +1,25 @@ +# vcpkg_install_cmake + +Build and install a cmake project. + +## Usage: +```cmake +vcpkg_install_cmake([MSVC_64_TOOLSET]) +``` + +## Parameters: +### MSVC_64_TOOLSET +This adds the `/p:PreferredToolArchitecture=x64` switch if the underlying buildsystem is MSBuild. Some large projects can run out of memory when linking if they use the 32-bit hosted tools. + +## Notes: +This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md). + +## Examples: + +* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) +* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_install_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake) diff --git a/docs/regenerate.ps1 b/docs/regenerate.ps1 new file mode 100644 index 000000000..abb91af61 --- /dev/null +++ b/docs/regenerate.ps1 @@ -0,0 +1,27 @@ +Param([string]$VcpkgRoot = "") + +$ErrorActionPreference = "Stop" + +if (!$VcpkgRoot) { + $VcpkgRoot = ".." +} + +$VcpkgRoot = Resolve-Path $VcpkgRoot + +if (!(Test-Path "$VcpkgRoot\.vcpkg-root")) { + throw "Invalid vcpkg instance, did you forget -VcpkgRoot?" +} + +Set-Content -Path "$PSScriptRoot\maintainers\portfile-functions.md" -Value "`n`n# Portfile helper functions" + +ls "$VcpkgRoot\scripts\cmake\*.cmake" | % { + $contents = Get-Content $_ ` + | ? { $_ -match "^## |^##`$" } ` + | % { $_ -replace "^## ?","" } + + if ($contents) { + Set-Content -Path "$PSScriptRoot\maintainers\$($_.BaseName).md" -Value "$($contents -join "`n")`n`n## Source`n[scripts/cmake/$($_.Name)](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/$($_.Name))" + "- [$($_.BaseName -replace "_","\_")]($($_.BaseName).md)" ` + | Out-File -Enc Ascii -Append -FilePath "$PSScriptRoot\maintainers\portfile-functions.md" + } +} diff --git a/docs/specifications/export-command.md b/docs/specifications/export-command.md new file mode 100644 index 000000000..aaa95cb1c --- /dev/null +++ b/docs/specifications/export-command.md @@ -0,0 +1,172 @@ +# Binary Export (Apr 28, 2017) + +## 1. Motivation + +### A. Build once and share + +Customers want to be able to build their set of required libraries once, and then distribute the resulting binaries to all members of the "group". This has been brought up in +- Enterprise environments, in which there are dedicated teams to acquire libraries and then share them with other team to consume them +- Academic environments, in which the professor/teacher wants to build the required libraries and then provide them to all the students +- CI Systems, in which developers want to quickly distribute their exact set of dependencies to a cloud-based farm of build machines + +Building once and sharing ensures that everyone gets exactly the same binaries, isolates the building effort to a small number of people and minimizes friction to obtain them. Therefore, there is value in enabling users to easily export ready-to-share binaries from `vcpkg`. + +### B. Very large libraries + +Libraries like [Qt][] can take a very long time to build (5+ hours). Therefore, having the ability to build them and then distribute the binaries can save a lot of time. + +### C. Flexibility and uses without `vcpkg` + +`vcpkg` currently handles cases where you have a `vcpkg` enlistment on your machine and use it for acquiring libraries and integrating into Visual Studio, CMake etc. However, users need the ability to build the libraries and then use them outside of and independently of `vcpkg`. For example: +- Use `vcpkg` for the build, then host the binaries in a website (similarly to nuget) +- Use `vcpkg` for the build, then put the binaries in an installer and distribute the installer + +Consuming the libraries outside of `vcpkg` forfeits the ability to install new libraries or update existing ones, but this can be: +- not a concern, like in a short term project or assignment +- explicitly desired, like in the development of a game where libraries and their versions are sealed for a particular release, never to be modified + +### D. Easy consumption in Visual Studio for NuGet users + +Customers have requested C++ NuGet packages to integrate into their project. This has come from: +- Customers than have used NuGet (e.g. in C#) and find it very convenient +- Customers who are working on a C# project that has a few dependencies on C++ and just want those dependencies to be satisfied in the most automatic way possible + +Providing a way to create NuGet packages provides great value to those customers. In an enterprise environment which focuses on C#, the dedicated acquisition team can create the NuGet packages with `vcpkg` and provide them to the other developers. For the "end-developer", this makes the consumption of C++ libraries the same as C# ones. + +[Qt]: https://www.qt.io/ + +## 2. Other design concerns + +- The `vcpkg` root may have a variety of packages built and many of them might be unrelated to the current task. Providing an easy way to export a subset of them will enhance user experience. +- Since binary compatibility is not guaranteed, it is not safe to individually export packages. Therefore, when exporting a particular package, all of the dependencies that it was built against must also be present in the export format (e.g. zip file). When a `vcpkg export` command succeeds, there is a guarantee that all required headers/binaries are available in the target bundle. + +## 3. Proposed solution + +This document proposes the `vcpkg export` command to pack the desired binaries in a convenient format. It is not the goal of this document to discuss binary distribution for C++ in a similar way that NuGet does for C#. It proposes exporting "library sets" instead of individual libraries as a solution to the C++ binary incompatibility problem. + +From a user experience perspective, the user expresses interest in exporting a particular library (e.g. `vcpkg export cpprestsdk`). `vcpkg export` should then make sure that the output contains `cpprestsdk` along with all dependencies it was actually built against. + +## 4. Proposed User experience + +### i. User knows what libraries he needs and wants to export them to an archive format (zip) +Developer Bob needs gtest and cpprestsdk and has been manually building them and their dependencies, then using the binaries in his project via applocal deployment. Bob has been experimenting with `vcpkg` and wants to use `vcpkg` for the building part only. + +Bob tries to export the libraries: +```no-highlight +> vcpkg export gtest cpprestsdk --zip +The following packages are already built and will be exported: + * boost:x86-windows + * bzip2:x86-windows + cpprestsdk:x86-windows + * openssl:x86-windows + * websocketpp:x86-windows + * zlib:x86-windows +The following packages need to be built: + gtest:x86-windows +Additional packages (*) need to be exported to complete this operation. +There are packages that have not been built. +To build them, run: + vcpkg install gtest:x86-windows +``` + +Bob proceeds to install the missing libraries: +```no-highlight +> vcpkg install gtest:x86-windows +// -- omitted build information -- // +Package gtest:x86-windows is installed. +``` + +Bob then returns to export the libraries: +```no-highlight +> vcpkg export gtest cpprestsdk --zip +The following packages are already built and will be exported: + * boost:x86-windows + * bzip2:x86-windows + cpprestsdk:x86-windows + gtest:x86-windows + * openssl:x86-windows + * websocketpp:x86-windows + * zlib:x86-windows +Additional packages (*) need to be exported to complete this operation. +Exporting package zlib:x86-windows... +Exporting package zlib:x86-windows... done +Exporting package openssl:x86-windows... +Exporting package openssl:x86-windows... done +Exporting package bzip2:x86-windows... +Exporting package bzip2:x86-windows... done +Exporting package boost:x86-windows... +Exporting package boost:x86-windows... done +Exporting package websocketpp:x86-windows... +Exporting package websocketpp:x86-windows... done +Exporting package cpprestsdk:x86-windows... +Exporting package cpprestsdk:x86-windows... done +Exporting package gtest:x86-windows... +Exporting package gtest:x86-windows... done +Creating zip archive... +Creating zip archive... done +zip archive exported at: C:/vcpkg/vcpkg-export-20170428-155351.zip +``` + +Bob takes the zip file and extracts the contents next to his other dependencies. Bob can now proceed with building his own project as before. + +### ii. User has a vcpkg root that works and wants to share it +Developer Alice has been using `vcpkg` and has a Visual Studio project that consumes libraries from it (via `vcpkg integrate`). The project is built for both 32-bit and 64-bit architectures. Alice wants to quickly share the dependencies with Bob so he can test the project. +```no-highlight +> vcpkg export gtest zlib gtest:x64-windows zlib:x64-windows --nuget +The following packages are already built and will be exported: + gtest:x86-windows + gtest:x64-windows + zlib:x86-windows + zlib:x64-windows +Exporting package zlib:x86-windows... +Exporting package zlib:x86-windows... done +Exporting package zlib:x64-windows... +Exporting package zlib:x64-windows... done +Exporting package gtest:x86-windows... +Exporting package gtest:x86-windows... done +Exporting package gtest:x64-windows... +Exporting package gtest:x64-windows... done +Creating nuget package... +Creating nuget package... done +Nuget package exported at: C:/vcpkg/scripts/buildsystems/tmp/vcpkg-export-20170428-164312.nupkg +``` + +Alice gives to Bob: a) The link to her project and b) The NuGet package "vcpkg-export-20170428-164312.nupkg". Bob clones the project and then installs the NuGet package. Bob is now ready to build Alice's project. + +### iii. User has a vcpkg root that works and wants to share it #2 +Developer Alice has been using `vcpkg` and has a CMake project that consumes libraries from it (via CMake toolchain file). Alice wants to quickly share the dependencies with Bob so he can test the project. +```no-highlight +> vcpkg export cpprestsdk zlib --zip +The following packages are already built and will be exported: + * boost:x86-windows + * bzip2:x86-windows + cpprestsdk:x86-windows + * openssl:x86-windows + * websocketpp:x86-windows + zlib:x86-windows +Additional packages (*) need to be exported to complete this operation. +Exporting package zlib:x86-windows... +Exporting package zlib:x86-windows... done +Exporting package openssl:x86-windows... +Exporting package openssl:x86-windows... done +Exporting package bzip2:x86-windows... +Exporting package bzip2:x86-windows... done +Exporting package boost:x86-windows... +Exporting package boost:x86-windows... done +Exporting package websocketpp:x86-windows... +Exporting package websocketpp:x86-windows... done +Exporting package cpprestsdk:x86-windows... +Exporting package cpprestsdk:x86-windows... done +Creating zip archive... +Creating zip archive... done +zip archive exported at: C:/vcpkg/vcpkg-export-20170428-155351.zip +``` + +Alice gives to Bob: a) The links to her project and b) The zip file "vcpkg-export-20170428-155351.zip". Bob clones the project, extracts the zip file and uses the provided (in the zip) CMake toolchain file to make the dependencies available to CMake. Bob is now ready to build Alice's project. + +## 5. Technical model + +- Each exported library, must be accompanied with all of its dependencies, even if they are not explicitly specified in the `vcpkg export` command. +- When exporting a library, a dependency graph will be built, similarly to install, to figure out which packages needs to be exported. +- It is allowed to have packages from different triplets, so users can include 32/64-bit and dynamic/static binaries in the same export. +- The exported archives also include the files needed to integrate with MSBuild and/or CMake. \ No newline at end of file diff --git a/docs/users/integration.md b/docs/users/integration.md new file mode 100644 index 000000000..38332f1aa --- /dev/null +++ b/docs/users/integration.md @@ -0,0 +1,85 @@ +## Buildsystem Integration + +Vcpkg offers many ways to integrate into your build so you can do what's right for your project. There are two main categories of integration: + +- [`integrate` command](#integrate) +- [`export` command](#export) + + +### Integrate Command + +These link your project(s) to a specific copy of Vcpkg on your machine so any updates or new package installations will be instantly available for the next build of your project. + +#### User-wide for MSBuild (Recommended for Open Source MSBuild projects) +```no-highlight +vcpkg integrate install +``` +This will implicitly add Include Directories, Link Directories, and Link Libraries for all packages installed with Vcpkg to all VS2015 and VS2017 MSBuild projects. We also add a post-build action for executable projects that will analyze and copy any DLLs you need to the output folder, enabling a seamless F5 experience. + +For the vast majority of libraries, this is all you need to do -- just File -> New Project and write code! However, some libraries perform conflicting behaviors such as redefining `main()`. Since you need to choose per-project which of these conflicting options you want, you will need to add those libraries to your linker inputs manually. + +Here are some examples, though this is not an exhaustive list: +- Gtest provides `gtest`, `gmock`, `gtest_main`, and `gmock_main` +- SDL2 provides `SDL2main` +- SFML provides `sfml-main` +- Boost.Test provides `boost_test_exec_monitor` + +To get a full list for all your installed packages, run `vcpkg owns manual-link`. + +#### CMake toolchain file (Recommended for Open Source CMake projects) +```no-highlight +cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake +``` +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. + +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) +include_directories(${CATCH_INCLUDE_DIR}) +``` + +#### 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. +```no-highlight +PS D:\src\vcpkg> .\vcpkg integrate project +Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg + +With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste: + Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems" +``` +*Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.* + +#### Manual compiler settings + +Libraries are installed into the `installed\` subfolder, partitioned by architecture (e.g. x86-windows): +* The header files are installed to `installed\x86-windows\include` +* Release `.lib` files are installed to `installed\x86-windows\lib` or `installed\x86-windows\lib\manual-link` +* Release `.dll` files are installed to `installed\x86-windows\bin` +* Debug `.lib` files are installed to `installed\x86-windows\debug\lib` or `installed\x86-windows\debug\lib\manual-link` +* Debug `.dll` files are installed to `installed\x86-windows\debug\bin` + +See your build system specific documentation for how to use prebuilt binaries. + +Generally, to run any produced executables you will also need to either copy the needed DLL files to the same folder as your executable or *prepend* the correct `bin\` directory to your path. + + +### Export Command +This command creates a shrinkwrapped archive containing a specific set of libraries (and their dependencies) that can be quickly and reliably shared with build servers or other users in your organization. + +- `--nuget`: NuGet package (Recommended for MSBuild projects) +- `--zip`: Zip archive +- `--7zip`: 7Zip archive (Recommended for CMake projects) +- `--raw`: Raw, uncompressed folder + +Each of these have the same layout, which mimics the layout of a full vcpkg: + +- `installed\` contains the installed package files +- `scripts\buildsystems\vcpkg.cmake` is a toolchain file suitable for use with CMake + +Additionally, NuGet packages will contain a `build\native\vcpkg.targets` that integrates with MSBuild projects. + +Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples. \ No newline at end of file -- cgit v1.2.3 From d8791515cc6f547c7d03637acb27e3eff4ccbe32 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 31 May 2017 16:53:05 -0700 Subject: [vcpkg-specs] Initial commit of Feature Packages draft --- docs/specifications/feature-packages.md | 287 ++++++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 docs/specifications/feature-packages.md (limited to 'docs') diff --git a/docs/specifications/feature-packages.md b/docs/specifications/feature-packages.md new file mode 100644 index 000000000..2c7f60ff9 --- /dev/null +++ b/docs/specifications/feature-packages.md @@ -0,0 +1,287 @@ +# Proposal: Features / Feature packages (Feb 23 2017) + +## 1. Motivation + +### A. OpenCV + CUDA + +[OpenCV][] is a computer vision library that can optionally be built with CUDA support to massively accelerate certain tasks when using computers with NVidia GPUs. For users without NVidia GPUs, building with CUDA support provides no benefit. [CUDA][] is provided only via a 1.3 GB installer (at the time of this authoring), which requires administrator access to install and modifies the global system state. + +Therefore, there is significant value in enabling users to choose whether they find CUDA support valuable for their particular scenario. + +### B. OpenCV + OpenCV\_contrib + +The community around [OpenCV][] has built up a library of extensions called [OpenCV_contrib][]. However, these extensions are a source-level patch onto the main OpenCV codebase and therefore must be applied _during_ the core OpenCV build. Further confounding the problem, it is the author's understanding that these community extensions have only been developed with [CUDA][] enabled and cannot be built without that dependency. + +Therefore, if CUDA is disabled, OpenCV\_contrib must also be disabled. Likewise, when a user requests OpenCV\_contrib, CUDA must be enabled. It would be convienent, but not a requirement, to enable CUDA without enabling the community extensions. + +Finally, these extensions add additional exports and headers which could be depended upon by other libraries. For maintainers, there must be a way to specify this requirement such that `vcpkg install mylib-depends-ocv-contrib` will verify/build/rebuild OpenCV with the community extensions enabled. + +### C. C++ REST SDK + SignalR + +The [C++ REST SDK][cpprestsdk] is a networking library that provides (among other features) HTTP and Websockets clients. To implement the HTTP client functionality on Windows Desktop, only the core Win32 platform APIs are needed (`zlib` is optional). + +However, the websockets client is based on [Websockets++][], which adds mandatory dependencies on `boost`, `openssl`, and `zlib`. Many users of the C++ REST SDK do not use the websockets component, so to minimize their overall dependency footprint it can be disabled at build time. Ideally, these kinds of options would be easily accessible to users in Vcpkg who are concerned about the final size or licensing of their deployment. + +[SignalR-Client-Cpp][SignalR] depends on the websockets functionality provided by the C++ REST SDK. Therefore, the maintainers of the `signalrclient` port would ideally like to express this dependency such that `cpprestsdk` will be automatically correctly built for their needs. Note that `signalrclient` does not _inherently_ care about `boost`, `websocketspp` or `openssl` -- it depends only on the public websocket client APIs provided by `cpprestsdk`. It would be much more maintainable to declare dependencies based on the public APIs rather than the dependencies themselves. + +[OpenCV]: http://opencv.org/ +[CUDA]: http://www.nvidia.com/object/cuda_home_new.html +[OpenCV_contrib]: https://github.com/opencv/opencv_contrib +[cpprestsdk]: https://github.com/Microsoft/cpprestsdk +[Websockets++]: https://www.zaphoyd.com/websocketpp/ +[SignalR]: https://github.com/aspnet/SignalR-Client-Cpp + +## 2. Other design concerns + +- General-purpose Open Source projects must be able to easily and succinctly describe their build dependencies inside Vcpkg. This should be no more verbose than a single `vcpkg install` line and, when that command succeeds, there is a strong expectation that all required functionality/headers/imports are available. + +- The internal state of the Vcpkg enlistment must be either extremely transparent OR managed by version control (git). This enables larger projects to efficiently transfer the entire state of their customized Vcpkg system between machines (and onto build servers) by having the destination clone and then run a single `vcpkg install` line for the subset of dependencies required. The results of this operation should be as repeatable as reasonably achievable given the current limits of the underlying toolchain. + +## 3. Proposed solution + +A key summary of the above motivations is that they are all scenarios surrounding APIs that are not independently buildable from each other. We have an existing solution for APIs that are independently buildable: separate packages. Therefore, we seek to extend the user-facing notion of "packages" to include capabilities and contracts that cannot be made into independent builds. + +This document proposes "features" (also called feature packages). These features are intended to model semi-independently toggleable API sets/contracts such that they can be sanely depended upon by other packages. It is not a goal to model exclusive alternatives (such as implementation choices that are not directly user-observable) through this mechanism. + +- Individual libraries within `boost` may be reasonably represented as features. +- Whether a graphics library is built on DirectX xor OpenGL (where one but not both must be chosen) is not representable as a feature. + +From a user experience perspective (i.e. from `vcpkg install`) feature packages act as much as possible like completely independent packages. However, internally, any change to a package's features will result in a rebuild of the associated "parent" package. This will invoke a package rebuild experience similar to upgrading. + +When using `vcpkg install `, some features will be enabled by default. These default features can be avoided by referring to the packages as `[core]` and features can be added by supplying them on the same installation line. + +### A. Proposed User experience + +#### i. User with no preference about options +Install of a library with default features: +```no-highlight +> vcpkg install cpprestsdk +// -- omitted build information -- // +Package cpprestsdk[core]:x86-windows is installed. +Package cpprestsdk[compression]:x86-windows is installed. +Package cpprestsdk[ws-client]:x86-windows is installed. +``` + +Removal of that library: +```no-highlight +> vcpkg remove cpprestsdk +The following packages will be removed: + cpprestsdk:x86-windows +Removing package cpprestsdk:x86-windows... +Removing package cpprestsdk:x86-windows... done +Purging package cpprestsdk:x86-windows... +Cleaned up D:\src\vcpkg\packages\cpprestsdk_x64-windows +Purging package cpprestsdk:x86-windows... done +``` + +Installation of a library with optional features: +```no-highlight +> vcpkg install opencv +// -- omitted build information -- // +Package opencv[core]:x86-windows is installed. +``` + +#### ii. User desires CUDA support for OpenCV directly, and is unfamiliar with feature packages +Developer Bob knows he wants OpenCV, so he guesses what the package is called +```no-highlight +> vcpkg install opencv +// -- omitted build information -- // +Package opencv[core]:x86-windows is installed. +``` + +Bob attempts to build his application against OpenCV (assuming CUDA), which fails at runtime or compile time indicating that OpenCV wasn't built with CUDA. +Bob comes back to vcpkg, not knowing about the "feature packages" feature. The primary inquiry tools for Vcpkg are `search` and `list`, so he runs `vcpkg search`: +```no-highlight +> vcpkg search opencv +opencv 3.2.0 computer vision library +opencv[cuda] support for NVidia CUDA +opencv[contrib] community supported extensions for OpenCV + +If your library is not listed, please open an issue at: + https://github.com/Microsoft/vcpkg/issues +``` +He isn't immediately sure what the lack of a version number means, but anything in `vcpkg search` can be applied to `vcpkg install`, so he runs: +```no-highlight +> vcpkg install opencv[cuda] +The following packages will be rebuilt: + opencv:x86-windows + +To rebuild with this feature, use: + vcpkg remove opencv:x86-windows + vcpkg install opencv[core,cuda]:x86-windows +``` +Bob follows the instructions... +```no-highlight +> vcpkg remove opencv:x86-windows +// -- omitted results as above -- // +> vcpkg install opencv[core,cuda]:x86-windows +// -- omitted build information -- // +Package opencv[core]:x86-windows is installed. +Package opencv[cuda]:x86-windows is installed. +``` +and he can now use OpenCV's CUDA support in his application. + +#### iii. User is familiar with feature packages, and wants to opt-out of a feature +Developer Alice has used `cpprestsdk`, built it from source, and she knows about the option to disable websockets. She uses `search` to find the complete list of features: +``` +> vcpkg search cpprestsdk +cpprestsdk 2.9.0-2 C++11 JSON, REST, and OAuth library The C++ RES... +cpprestsdk[compression] Gzip compression support in the HTTP client. +cpprestsdk[ws-client] Websocket client support based on websocketspp. + +If your library is not listed, please open an issue at: + https://github.com/Microsoft/vcpkg/issues +``` + +She decided she only wants `cpprestsdk[compression]`, so she installs only that feature: +```no-highlight +> vcpkg install cpprestsdk[compression] +// -- omitted build information -- // +Package cpprestsdk[core]:x86-windows is installed. +Package cpprestsdk[compression]:x86-windows is installed. +``` +She receives a quick recursive build that only depends on `zlib`. + +She's now interested in some additional libraries built on top of cpprestsdk: `azure-storage-cpp` and `signalrclient`. +```no-highlight +> vcpkg install azure-storage-cpp +// -- omitted build information -- // +Package azure-storage-cpp[core]:x86-windows is installed. + +> vcpkg install signalrclient +Package signalrclient:x86-windows depends on cpprestsdk[ws-client]:x86-windows. + +The following packages will be rebuilt: + * azure-storage-cpp:x86-windows + * cpprestsdk:x86-windows + +To rebuild the current package graph with this feature, use: + vcpkg remove cpprestsdk:x86-windows azure-storage-cpp:x86-windows + vcpkg install cpprestsdk[core,compression,ws-client]:x86-windows + vcpkg install azure-storage-cpp[core]:x86-windows + vcpkg install signalrclient[core]:x86-windows +``` +She follows the above script and can use both `azure-storage-cpp` and `signalrclient` in her code. + +Some time has passed, she decided not to use `signalrclient`, and she's interested in shipping her application. She wants to minimize her final install size, so she'd like to remove all unneeded packages like `boost` and `openssl`. +```no-highlight +> vcpkg remove boost openssl +The following packages and features will be removed: + * signalrclient[core]:x86-windows + * cpprestsdk[ws-client]:x86-windows + boost[core]:x86-windows + openssl[core]:x86-windows + +The following packages will be rebuilt: + * azure-storage-cpp:x86-windows + * cpprestsdk:x86-windows + +Removing features requires rebuilding packages. +To rebuild the current package graph without these features, use: + vcpkg remove cpprestsdk:x86-windows azure-storage-cpp:x86-windows signalrclient:x86-windows openssl:x86-windows boost:x86-windows + vcpkg install cpprestsdk[core,compression]:x86-windows + vcpkg install azure-storage-cpp[core]:x86-windows +``` +In the end, her final `vcpkg list` outputs: +```no-highlight +> vcpkg list +zlib[core]:x86-windows 1.2.11 A compression library +azure-storage-cpp[core]:x86-windows 2.6.0 Microsoft Azure Storage Client SDK for ... +cpprestsdk[core]:x86-windows 2.9.0-2 C++11 JSON, REST, and OAuth library +cpprestsdk[compression]:x86-windows Gzip compression support in the HTTP client. +``` + +### B. Technical model + +- Each package can have any number "features". +- Features follow the same naming conventions as packages, but when referenced are always "namespaced" by the parent package. + - `cpprestsdk[ws-client]` is a completely orthogonal feature from `poco[ws-client]`. +- Features are valid dependencies. + - `signalrclient` depends on `cpprestsdk[ws-client]` +- Features can have dependencies (including other features). + - `cpprestsdk[ws-client]` depends on `boost`, `openssl`, and `websocketspp` + - `opencv[cuda]` depends on `cuda` + - `opencv[contrib]` depends on `opencv[cuda]` + - `boost[python]` depends on `libpython` +- Every package has an implicit feature called `core`, which covers the core library with a minimum set of features. All features implicitly depend on the `core` feature of their parent package + - `azure-storage-cpp` depends on `cpprestsdk[core]` + - `cpprestsdk[ws-client]` implicitly depends on `cpprestsdk[core]` +- Each package declares a list of default features that are enabled when the package is referred to by its raw name, and `core` is always a default feature. + - `cpprestsdk` declares `ws-client` and `compression` to be default features. Any unqualified reference `cpprestsdk` implicitly means `cpprestsdk[core]` _and_ `cpprestsdk[ws-client]` _and_ `cpprestsdk[compression]`. + - `opencv` does not declare `cuda` nor `contrib` to be default features. + +As a conclusion of the above, it is expected that all packages will be buildable with all features disabled (just the `core` feature) and with all features enabled. + +### C. Proposed Control File Syntax + +#### OpenCV and CUDA +To add the feature CUDA to OpenCV, we will adopt the following syntax in the CONTROL file: +```no-highlight +# opencv/CONTROL +Source: opencv +Version: 3.2.0-1 +Build-Depends: zlib, libpng, libjpeg-turbo, tiff +Description: computer vision library +Default-Features: + +Feature: cuda +Build-Depends: cuda +Description: parallel computing platform + +Feature: contrib +Build-Depends: opencv[cuda] +Description: library of OpenCV Extensions +``` + +#### Signalrclient +```no-highlight +# signalrclient/CONTROL +Source: signalrclient +Version: 1.0.0-beta1 +Build-Depends: cpprestsdk[ws-client] +Description: C++ client for SignalR. +``` +```no-highlight +# cpprestsdk/CONTROL +Source: cpprestsdk +Version: 2.9.0-2 +Build-Depends: +Description: C++11 JSON, REST, and OAuth library ... +Default-Features: compression, ws-client + +Feature: compression +Build-Depends: zlib (windows) +Description: Gzip compression support in the HTTP client. + +Feature: ws-client +Build-Depends: boost (windows), openssl (windows), websocketpp (windows) +Description: Websocket client support based on websocketspp +``` + +### D. Additional Control File Technical Details + +- If any feature paragraphs exist, the field `Default-Features` must be present. + +## 4. Related Work + +### Cargo's Features (from Rust): +The proposed feature packages are exceedingly similar to Cargo's Features, with the following changes: + +- We avoid any collision problems because features are always namespaced by the owning package +- We do not have a concept of "feature groups", instead we allow dependencies from one feature to another within the same package (Note: This may be how "feature groups" are implemented internally to Cargo -- it was not clear from the documentation). +- Because of the nature of C and C++, it is extremely commonplace that large software packages can have features disabled to remove their dependencies upon other libraries. Changing this configuration requires a rebuild of the package and potentially rippling ABI changes to any downstream dependencies. Therefore, we expect significantly more use of this feature to manage optional API contracts instead of the intended use in Cargo (curation). +- We do not intend feature packages to be used to express the curation relationship, beyond the notion of a "default" set within a package. + +### Gentoo's USE flags: +Gentoo's USE flags can be shortly summarized as a global set of keywords that is used to make cross-cutting changes to the entire package graph's build configuration. This system standardizes many common settings such that they can be simultaneously toggled for the entire graph. + +The most common example of this would be using KDE vs Gnome. A user who knows that, given the choice, they would prefer the KDE/Qt interface can manage the massive space of package configuration efficiently without learning the particular term that each package has decided to call "build using Qt instead of GTK". + +USE flags can be customized hierarchically when needed, including at the per-package level. They can be depended upon by other packages, both positively and negatively. USE flags themselves can be used in any boolean expression to determine the complete set of package dependencies, including removing dependencies when flags are enabled. + +Problems with USE flags: + +- They require coordination from package maintainers to achieve the goal of "portable" flags. This increases the burden of adding a package -- to author a good package, I need to be aware of every uncommon USE flag and evaluate how those could map onto my local configuration space. +- Based on research online, it seems extremely common that users need to tweak flags at a per-package level. This calls into question how valuable the cross-cutting power above is. +- The vast majority of common USE flags are essentially a list of all the common packages and focus on giving the user a view of dependencies (which a package manager is designed to abstract when possible) instead of APIs (which is what users code against). +- Dependency analysis with USE flags becomes a SAT problem with an enormous state space -- P*F bits -- which compounds with any versioning relations. This may work acceptably in practice via heuristics, but it implies that a) there is a looming performance wall which could suddenly create a poor user experience and b) the heuristics may incorrectly model the user's needs, causing a disconnect in desire vs practice, which again leads to a poor user experience. -- cgit v1.2.3 From 76b754e52ddcb2d2a6958e4a913d0371c00279d8 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Tue, 6 Jun 2017 11:40:47 -0700 Subject: [vcpkg-docs] Initial commit of triplets documentation --- docs/index.md | 1 + docs/maintainers/control-files.md | 18 ++++++------- docs/users/triplets.md | 54 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 9 deletions(-) create mode 100644 docs/users/triplets.md (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index 9b279baf0..3fa5784e9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,6 +13,7 @@ Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are ### User Help - [Integration with build systems](users/integration.md) +- [Triplet files](users/triplets.md) ### Maintainer help diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md index 1cb444df3..e446fe6fa 100644 --- a/docs/maintainers/control-files.md +++ b/docs/maintainers/control-files.md @@ -1,16 +1,16 @@ -## `CONTROL` files -Each port has some static metadata in the form of a `CONTROL` file. This file uses the same rough syntax as and a subset of the fields from [the Debian `control` format][debian]. +# CONTROL files +Each port has some static metadata in the form of a `CONTROL` file. This file uses the same syntax and a subset of the fields from [the Debian `control` format][debian]. -Fields are case-sensitive. +Field names are case-sensitive. [debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html -### Recognized fields +## Recognized fields -#### Source +### Source The name of the port. -#### Version +### Version The port version. This field should be an alphanumeric string which may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bitstrings and are only evaluated for equality. @@ -22,15 +22,15 @@ Example: Version: 1.0.5-2 ``` -#### Description +### Description A description of the library The first sentence of the description should concisely describe the purpose and contents of the library. Then, a larger description including the library's "proper name" should follow. -#### Maintainer +### Maintainer Reserved for future use. -#### Build-Depends +### Build-Depends The list of dependencies required to build and use this library. Example: diff --git a/docs/users/triplets.md b/docs/users/triplets.md new file mode 100644 index 000000000..2b0971da3 --- /dev/null +++ b/docs/users/triplets.md @@ -0,0 +1,54 @@ +# Triplet files + +Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name. + +In Vcpkg, we use triplets to describe self-consistent builds of library sets. This means every library will be built using the same target cpu, OS, and compiler toolchain, but also CRT linkage and preferred library type. + +We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily add your own by creating a new file in the `triplets\` directory. The new triplet will immediately be available for use in commands, such as `vcpkg install boost:x86-windows-custom`. + +## Variables +### VCPKG_TARGET_ARCHITECTURE +Specifies the target machine architecture. + +Valid options are `x86`, `x64`, and `arm`. + +### VCPKG_CRT_LINKAGE +Specifies the desired MSVCRT linkage. + +Valid options are `dynamic` and `static`. + +### VCPKG_LIBRARY_LINKAGE +Specifies the preferred library linkage. + +Valid options are `dynamic` and `static`. Note that libraries can ignore this setting if they do not support the preferred linkage type. + +### 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`. + +### VCPKG_PLATFORM_TOOLSET +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. + +## 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 STREQUAL "qt5") + set(VCPKG_LIBRARY_LINKAGE dynamic) +endif() +``` +This will build `qt5` as DLLs against the dynamic CRT, but every other library as a static library (still against the dynamic CRT). + +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. + +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 b90dbbc928d5880de690392f431d12321b337481 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 7 Jun 2017 17:08:13 -0700 Subject: [vcpkg-docs] Document how to change the deduced triplet for cmake and msbuild. Fixes #1185. --- docs/users/integration.md | 38 +++++++++++++++++++++++++++++++++++++- docs/users/triplets.md | 2 ++ 2 files changed, 39 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/users/integration.md b/docs/users/integration.md index 38332f1aa..1e52adb88 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -5,11 +5,14 @@ Vcpkg offers many ways to integrate into your build so you can do what's right f - [`integrate` command](#integrate) - [`export` command](#export) +Each integration style has heuristics to deduce the correct [triplet][]. This can be overridden using [a common method](#triplet-selection) based on your buildsystem. + ### Integrate Command These link your project(s) to a specific copy of Vcpkg on your machine so any updates or new package installations will be instantly available for the next build of your project. + #### User-wide for MSBuild (Recommended for Open Source MSBuild projects) ```no-highlight vcpkg integrate install @@ -82,4 +85,37 @@ Each of these have the same layout, which mimics the layout of a full vcpkg: Additionally, NuGet packages will contain a `build\native\vcpkg.targets` that integrates with MSBuild projects. -Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples. \ No newline at end of file +Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples. + + +### Triplet selection +Every integration mechanism besides manually adding the folders will deduce a [triplet][] for your project as one of: +- x86-windows +- x64-windows +- x86-uwp +- x64-uwp +- arm-uwp + +#### With MSBuild +You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher: + +> *Shortcut: Ctrl+Q "build and run"* +> +> Tools -> Options -> Projects and Solutions -> Build and Run -> MSBuild project build output verbosity + +To override the automatically chosen [triplet][], you can specify the MSBuild property `VcpkgTriplet` in your `.vcxproj`. We recommend adding this to the `Globals` PropertyGroup. +```xml + + + x86-windows-static + x64-windows-static + +``` + +#### With CMake +Simply set `VCPKG_TARGET_TRIPLET` on the configure line. +```no-highlight +cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=... +``` + +[triplet]: triplets.md diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 2b0971da3..06f77e63f 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -6,6 +6,8 @@ In Vcpkg, we use triplets to describe self-consistent builds of library sets. Th We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily add your own by creating a new file in the `triplets\` directory. The new triplet will immediately be available for use in commands, such as `vcpkg install boost:x86-windows-custom`. +To change the triplet used by your project, such as to enable static linking, see our [Integration Document](integration.md#triplet-selection). + ## Variables ### VCPKG_TARGET_ARCHITECTURE Specifies the target machine architecture. -- cgit v1.2.3 From 8085cd34f2f5eef533aaeac6232cde4f073a4bf0 Mon Sep 17 00:00:00 2001 From: Gilles Khouzam Date: Sat, 17 Jun 2017 11:30:03 -0700 Subject: Adding support for FFmpeg in UWP. Adding support to download gas-preprocessor as an acquire_program. Update all packages for msys2 Download perl and gcc for ARM assembly in ffmpeg. --- docs/maintainers/vcpkg_find_acquire_program.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md index 209b4416e..bc50ef4c8 100644 --- a/docs/maintainers/vcpkg_find_acquire_program.md +++ b/docs/maintainers/vcpkg_find_acquire_program.md @@ -24,6 +24,7 @@ The current list of programs includes: - NASM - NINJA - YASM +- GASPREPROCESSOR Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md). -- cgit v1.2.3 From c89b4358156854bd4ef8a4f8a714553b7b14b59e Mon Sep 17 00:00:00 2001 From: Yang Yang Date: Tue, 4 Jul 2017 00:55:46 +0800 Subject: fix the static-linking setting in docs/users/integration.md --- docs/users/integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/users/integration.md b/docs/users/integration.md index 1e52adb88..f1b5014bf 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -107,8 +107,8 @@ To override the automatically chosen [triplet][], you can specify the MSBuild pr ```xml - x86-windows-static - x64-windows-static + x86-windows-static + x64-windows-static ``` -- cgit v1.2.3 From ab78c3b6edc666d81bb4389cea70f8e8779f9e40 Mon Sep 17 00:00:00 2001 From: paercebal Date: Tue, 29 Aug 2017 17:56:11 +0200 Subject: Add doc on Vcpkg integration for custom config --- docs/about/faq.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index 85a0c14db..9178f9b9a 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -46,6 +46,20 @@ Yes. In the current preview, there is not yet a standardized global way to chang 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. +## Can I get Vcpkg integration for custom configurations? + +Yes. While Vcpkg will only produce the standard "Release" and "Debug" configurations when building a library, you can get integration support for your projects' custom configurations, in addition to your project's standard configurations. + +The MSBuild $(VcpkgConfiguration) macro, if not set in your project, will identify either the "Release" or the "Debug" configuration. You only need to override this macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration. + +For example, you can add support for your "MyRelease" configuration by adding in your project file: +``` + + Release + +``` +Of course, this will only produce viable binaries if your custom configuration is compatible with the target configuration (e.g. they should both link with the same runtime library). + ## How is CMake used internally by Vcpkg? Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows, does not require system-wide installation, and legible for unfamiliar users. -- cgit v1.2.3 From 23649f58ec58196ff6e7f0b25f2d13f4b0c27cc9 Mon Sep 17 00:00:00 2001 From: paercebal Date: Tue, 29 Aug 2017 18:21:31 +0200 Subject: Add doc on Vcpkg integration per project --- docs/about/faq.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index 9178f9b9a..43039258f 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -60,6 +60,14 @@ For example, you can add support for your "MyRelease" configuration by adding in ``` Of course, this will only produce viable binaries if your custom configuration is compatible with the target configuration (e.g. they should both link with the same runtime library). +## I can't use user-wide integration. Can I use a per-project integration? + +Yes. The Visual Studio integration is actually enabled by the `\scripts\buildsystems\msbuild\vcpkg.targets` file. So all you need is to import it in your .vcxproj file, replacing `` with the path where you installed vcpkg: + +``` + +``` + ## How is CMake used internally by Vcpkg? Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows, does not require system-wide installation, and legible for unfamiliar users. -- cgit v1.2.3 From b966cdce678461e5497b01a25664ace0e76b51bf Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 30 Aug 2017 21:00:59 -0700 Subject: [vcpkg-docs] Add integrate project to faq section --- docs/about/faq.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index 43039258f..8234216e0 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -62,7 +62,9 @@ Of course, this will only produce viable binaries if your custom configuration i ## I can't use user-wide integration. Can I use a per-project integration? -Yes. The Visual Studio integration is actually enabled by the `\scripts\buildsystems\msbuild\vcpkg.targets` file. So all you need is to import it in your .vcxproj file, replacing `` with the path where you installed vcpkg: +Yes. A NuGet package suitable for per-project use can be generated via either the `vcpkg integrate project` command (lightweight linking) or the `vcpkg export --nuget` command (shrinkwrapped). + +A lower level mechanism to achieve the same as the `vcpkg integrate project` NuGet package is via the `\scripts\buildsystems\msbuild\vcpkg.targets` file. All you need is to import it in your .vcxproj file, replacing `` with the path where you installed vcpkg: ``` -- cgit v1.2.3 From e5861d356bf2b1874b74a321dcec9439a8d11ef5 Mon Sep 17 00:00:00 2001 From: paercebal Date: Thu, 31 Aug 2017 10:59:42 +0200 Subject: Updated the documentation to reflect the greater tolerance on configs --- docs/about/faq.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index 8234216e0..88f88bad0 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -50,7 +50,9 @@ By saving the changes to the portfile (and checking them in), you'll get the sam Yes. While Vcpkg will only produce the standard "Release" and "Debug" configurations when building a library, you can get integration support for your projects' custom configurations, in addition to your project's standard configurations. -The MSBuild $(VcpkgConfiguration) macro, if not set in your project, will identify either the "Release" or the "Debug" configuration. You only need to override this macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration. +First of all, Vcpkg will automatically assume any custom configuration starting with "Release" (resp. "Debug") as a configuration that is compatible with the standard "Release" (resp. "Debug") configuration and will act accordingly. + +For other configurations, you only need to override the MSBuild `$(VcpkgConfiguration)` macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration. For example, you can add support for your "MyRelease" configuration by adding in your project file: ``` -- cgit v1.2.3 From 3af00c8a1e598a38b3376c4dbd96aa10ff766fb8 Mon Sep 17 00:00:00 2001 From: Amin Cheloh Date: Mon, 2 Oct 2017 00:45:00 +0700 Subject: [vcpkg-docs] Update CONTROL file Build-Depends change qualifier from brackets to parentheses. see #1582 --- docs/maintainers/control-files.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md index e446fe6fa..17cb50311 100644 --- a/docs/maintainers/control-files.md +++ b/docs/maintainers/control-files.md @@ -42,10 +42,10 @@ Unlike dpkg, Vcpkg does not distinguish between build-only dependencies and runt *For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies* -Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside brackets is substring-compared against the triplet name. __This will change in a future version to not depend on the triplet name.__ +Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside parentheses is substring-compared against the triplet name. __This will change in a future version to not depend on the triplet name.__ Example: ```no-highlight -Build-Depends: zlib [windows], openssl [windows], boost [windows], websocketpp [windows] +Build-Depends: zlib (windows), openssl (windows), boost (windows), websocketpp (windows) ``` -- cgit v1.2.3 From 2c9ee072da34a925f0faf22596e532d378930582 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Thu, 5 Oct 2017 17:49:28 -0700 Subject: [vcpkg_build_cmake] Refactor _build_ and _install_ into a single cmake script. Regenerate documentation. Remove MSVC_64_TOOLSET option because it's obsolete. --- docs/maintainers/portfile-functions.md | 2 + docs/maintainers/vcpkg_acquire_msys.md | 2 +- docs/maintainers/vcpkg_build_cmake.md | 31 +++++++++++++++ docs/maintainers/vcpkg_find_acquire_program.md | 2 +- docs/maintainers/vcpkg_from_bitbucket.md | 53 ++++++++++++++++++++++++++ docs/maintainers/vcpkg_from_github.md | 6 ++- docs/maintainers/vcpkg_install_cmake.md | 8 ++-- 7 files changed, 96 insertions(+), 8 deletions(-) create mode 100644 docs/maintainers/vcpkg_build_cmake.md create mode 100644 docs/maintainers/vcpkg_from_bitbucket.md (limited to 'docs') diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index 705d65b7e..e16147f7d 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -3,6 +3,7 @@ # Portfile helper functions - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md) - [vcpkg\_apply\_patches](vcpkg_apply_patches.md) +- [vcpkg\_build\_cmake](vcpkg_build_cmake.md) - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md) - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md) @@ -11,5 +12,6 @@ - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md) - [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\_github](vcpkg_from_github.md) - [vcpkg\_install\_cmake](vcpkg_install_cmake.md) diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/docs/maintainers/vcpkg_acquire_msys.md index 46cda81fd..53aa6532e 100644 --- a/docs/maintainers/vcpkg_acquire_msys.md +++ b/docs/maintainers/vcpkg_acquire_msys.md @@ -32,7 +32,7 @@ message(STATUS "Installing MSYS Packages") vcpkg_execute_required_process( COMMAND ${BASH} --noprofile --norc -c - "pacman -Sy --noconfirm --needed make" + 'PATH=/usr/bin:\$PATH pacman -Sy --noconfirm --needed make' WORKING_DIRECTORY ${MSYS_ROOT} LOGNAME pacman-${TARGET_TRIPLET}) ``` diff --git a/docs/maintainers/vcpkg_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md new file mode 100644 index 000000000..ddfa46f6b --- /dev/null +++ b/docs/maintainers/vcpkg_build_cmake.md @@ -0,0 +1,31 @@ +# vcpkg_build_cmake + +Build a cmake project. + +## Usage: +```cmake +vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET ]) +``` + +## Parameters: +### DISABLE_PARALLEL +The underlying buildsystem will be instructed to not parallelize + +### TARGET +The target passed to the cmake build command (`cmake --build . --target `). If not specified, no target will +be passed. + +## 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 +"install" target + +## Examples: + +* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) +* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_build_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake) diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md index bc50ef4c8..8107c8dd2 100644 --- a/docs/maintainers/vcpkg_find_acquire_program.md +++ b/docs/maintainers/vcpkg_find_acquire_program.md @@ -16,6 +16,7 @@ The current list of programs includes: - 7Z - BISON - FLEX +- GASPREPROCESSOR - PERL - PYTHON2 - PYTHON3 @@ -24,7 +25,6 @@ The current list of programs includes: - NASM - NINJA - YASM -- GASPREPROCESSOR Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md). diff --git a/docs/maintainers/vcpkg_from_bitbucket.md b/docs/maintainers/vcpkg_from_bitbucket.md new file mode 100644 index 000000000..c8850b725 --- /dev/null +++ b/docs/maintainers/vcpkg_from_bitbucket.md @@ -0,0 +1,53 @@ +# vcpkg_from_bitbucket + +Download and extract a project from Bitbucket. +Enables support for installing HEAD `vcpkg.exe install --head `. + +## Usage: +```cmake +vcpkg_from_bitbucket( + OUT_SOURCE_PATH + REPO + [REF ] + [SHA512 <45d0d7f8cc350...>] + [HEAD_REF ] +) +``` + +## Parameters: +### 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 and repository on GitHub. + +### 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 (https://bitbucket.com/${REPO}/get/${REF}.tar.gz). + +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. + +## Examples: + +* [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_from_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake) diff --git a/docs/maintainers/vcpkg_from_github.md b/docs/maintainers/vcpkg_from_github.md index cb7849fcc..cf50dc445 100644 --- a/docs/maintainers/vcpkg_from_github.md +++ b/docs/maintainers/vcpkg_from_github.md @@ -23,7 +23,9 @@ 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. +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. @@ -38,7 +40,7 @@ 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. +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. diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md index e199d1292..1b132b4f1 100644 --- a/docs/maintainers/vcpkg_install_cmake.md +++ b/docs/maintainers/vcpkg_install_cmake.md @@ -4,15 +4,15 @@ Build and install a cmake project. ## Usage: ```cmake -vcpkg_install_cmake([MSVC_64_TOOLSET]) +vcpkg_install_cmake(...) ``` ## Parameters: -### MSVC_64_TOOLSET -This adds the `/p:PreferredToolArchitecture=x64` switch if the underlying buildsystem is MSBuild. Some large projects can run out of memory when linking if they use the 32-bit hosted tools. +See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md). ## Notes: -This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md). +This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install` +parameter. ## Examples: -- cgit v1.2.3 From fe842b31d411ed3c14117ca77b65997e671d3a17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dar=C3=ADo=20Here=C3=B1=C3=BA?= Date: Sat, 21 Oct 2017 22:39:01 +0200 Subject: Minor fix --- 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 88f88bad0..cb711e384 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -78,7 +78,7 @@ Vcpkg uses CMake internally as a build scripting language. This is because CMake ## Will Vcpkg support downloading compiled binaries from a public or private server? We would like to eventually support downloading precompiled binaries, similar to other system package managers. -In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See [the `export` command](../users/integration.md#export). +In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See the [`export`](../users/integration.md#export) command. ## What Visual C++ toolsets are supported? We support Visual Studio 2015 Update 3 and above. -- cgit v1.2.3 From 2ece3186ff5cc8b687a22d1a242537a0a6da7420 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 8 Nov 2017 10:41:03 -0800 Subject: [vcpkg-build-msbuild] Update examples. --- docs/maintainers/vcpkg_build_msbuild.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md index 178964fcd..889b07bdc 100644 --- a/docs/maintainers/vcpkg_build_msbuild.md +++ b/docs/maintainers/vcpkg_build_msbuild.md @@ -52,8 +52,8 @@ Additional options passed to msbuild for Debug builds. These are in addition to ## Examples -* [libuv](https://github.com/Microsoft/vcpkg/blob/master/ports/libuv/portfile.cmake) -* [zeromq](https://github.com/Microsoft/vcpkg/blob/master/ports/zeromq/portfile.cmake) +* [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake) +* [cppunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cppunit/portfile.cmake) ## Source [scripts/cmake/vcpkg_build_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake) -- cgit v1.2.3 From 2b30280c222a6970fa74d05b6f7e106b4776318a Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Fri, 5 Jan 2018 16:16:08 -0800 Subject: [vcpkg-download-distfile] Regenerate docs and enable SKIP_SHA512 only in unstable (head) mode --- docs/maintainers/vcpkg_download_distfile.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_download_distfile.md b/docs/maintainers/vcpkg_download_distfile.md index 7897610e3..80ea7559a 100644 --- a/docs/maintainers/vcpkg_download_distfile.md +++ b/docs/maintainers/vcpkg_download_distfile.md @@ -2,6 +2,8 @@ Download and cache a file needed for this port. +This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command. + ## Usage ```cmake vcpkg_download_distfile( @@ -26,12 +28,17 @@ The expected hash for the file. If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch. +### SKIP_SHA512 +Skip SHA512 hash check for file. + +This switch is only valid when building with the `--head` command line flag. + ## Notes -The command [`vcpkg_from_github`](vcpkg_from_github.md) should be used instead of this for downloading the main archive for GitHub projects. +The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects. ## Examples -* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake) +* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake) * [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake) * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) -- cgit v1.2.3 From 77eae92e75c4b0d15c14c1f19c93fb41bc60f25e Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Mon, 22 Jan 2018 22:28:13 -0800 Subject: [vcpkg-docs] Add feature packages to core documentation of CONTROL files --- docs/maintainers/control-files.md | 53 +++++++++++++++++++++++++++++---- docs/specifications/feature-packages.md | 2 ++ 2 files changed, 49 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md index 17cb50311..eb03f1d94 100644 --- a/docs/maintainers/control-files.md +++ b/docs/maintainers/control-files.md @@ -1,16 +1,29 @@ # CONTROL files + Each port has some static metadata in the form of a `CONTROL` file. This file uses the same syntax and a subset of the fields from [the Debian `control` format][debian]. Field names are case-sensitive. [debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html -## Recognized fields +## Source Paragraph + +The first paragraph appearing in a `CONTROL` file is the Source paragraph, which defines the core attributes of the package (name, version, and so on). + +### Example: +```no-highlight +Source: vtk +Version: 8.1.0-1 +Description: Software system for 3D computer graphics, image processing, and visualization +Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype +``` + +### Recognized fields -### Source +#### Source The name of the port. -### Version +#### Version The port version. This field should be an alphanumeric string which may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bitstrings and are only evaluated for equality. @@ -22,15 +35,15 @@ Example: Version: 1.0.5-2 ``` -### Description +#### Description A description of the library The first sentence of the description should concisely describe the purpose and contents of the library. Then, a larger description including the library's "proper name" should follow. -### Maintainer +#### Maintainer Reserved for future use. -### Build-Depends +#### Build-Depends The list of dependencies required to build and use this library. Example: @@ -49,3 +62,31 @@ Example: Build-Depends: zlib (windows), openssl (windows), boost (windows), websocketpp (windows) ``` +## Feature Paragraphs + +After the Source Paragraph, `CONTROL` files can list zero or more Feature Paragraphs which declare features. + +### Example: +```no-highlight +Source: vtk +Version: 8.1.0-1 +Description: Software system for 3D computer graphics, image processing, and visualization +Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype + +Feature: mpi +Description: MPI functionality for VTK +Build-Depends: msmpi, hdf5[parallel] +``` + +### Recognized fields + +#### Feature +The name of the feature. + +#### Description +A description of the feature + +#### Build-Depends +The list of dependencies required to build and use this feature. + +All dependencies from selected features are unioned together to produce the final dependency set for the build. This field follows the same syntax as `Build-Depends` in the Source Paragraph. diff --git a/docs/specifications/feature-packages.md b/docs/specifications/feature-packages.md index 2c7f60ff9..198a602ba 100644 --- a/docs/specifications/feature-packages.md +++ b/docs/specifications/feature-packages.md @@ -1,5 +1,7 @@ # Proposal: Features / Feature packages (Feb 23 2017) +**Note: this is the proposal as it was initially accepted and does not neccessarily reflect the current behavior.** + ## 1. Motivation ### A. OpenCV + CUDA -- cgit v1.2.3 From 53e61d4ab545fa0097cb58ce9818350595322aab Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 31 Jan 2018 12:20:27 -0800 Subject: [docs][packaging-zlib] Fix example doc. --- docs/examples/packaging-zlib.md | 47 ++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 24 deletions(-) (limited to 'docs') diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zlib.md index 81bc58314..ce176d451 100644 --- a/docs/examples/packaging-zlib.md +++ b/docs/examples/packaging-zlib.md @@ -16,7 +16,7 @@ Finally, if the server's name for the archive is not very descriptive (such as d 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/zlib128.zip zlib128.zip +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 ``` @@ -39,29 +39,28 @@ PS D:\src\vcpkg> .\vcpkg build zlib2 -- 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/zlib128.zip --- Extracting source D:/src/vcpkg/downloads/zlib128.zip +-- 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 -CMake Error at scripts/cmake/vcpkg_execute_required_process.cmake:13 (message): - Command failed: C:/Program Files - (x86)/CMake/bin/cmake.exe;D:/src/vcpkg/buildtrees/zlib2/src/zlib128;-G;Ninja;-DCMAKE_VERBOSE_MAKEFILE=ON;-DCMAKE_BUILD_TYPE=Release;-DCMAKE_TOOLCHAIN_FILE=D:/src/vcpkg/triplets/x86-windows.cmake;-DCMAKE_PREFIX_PATH=D:/src/vcpkg/installed/x86-windows;- -DCMAKE_INSTALL_PREFIX=D:/src/vcpkg/packages/zlib2_x86-windows - - - Working Directory: D:/src/vcpkg/buildtrees/zlib2/x86-windows-rel - - See logs for more information: - - D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-out.log - D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-err.log - -Call Stack (most recent call first): - scripts/cmake/vcpkg_configure_cmake.cmake:15 (vcpkg_execute_required_process) - ports/zlib2/portfile.cmake:8 (vcpkg_configure_cmake) - scripts/ports.cmake:105 (include) - scripts/ports.cmake:184 (build) +-- 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. @@ -73,8 +72,8 @@ In the `ports\` directory are many libraries that can be used as examples, inclu - rapidjson - range-v3 - MSBuild-based + - cppunit - mpg123 - - glew - Non-CMake, custom buildsystem - openssl - - boost + - ffmpeg -- cgit v1.2.3 From 995ab094093e5cea8b250f69200406bcc59848ae Mon Sep 17 00:00:00 2001 From: Guillaume Lachance Date: Sat, 17 Feb 2018 05:31:49 -0500 Subject: libmupdf version bump (#2730) * Add libgta Libgta is a portable library that implements the Generic Tagged Array (GTA) file format. Signed-off-by: Hiroshi Miura * [libgta] turn off document build and doxygen dependency Signed-off-by: Hiroshi Miura * [libgta] add build-dependency - bzip2, zlib and liblzma Signed-off-by: Hiroshi Miura * [libgta] remove dlls when static build Signed-off-by: Hiroshi Miura * Fix typo * [libgta] update CONTROL add lf at end of file. * libmupdf version bump * [qt5-base] Use system freetype. * [opencv] Fix UWP and ARM * [hdf5] Always use config mode for HDF5 * [opencv] Fixup -- apply patch added in previous commit * [abseil] Add *.inc files. Fixes #2718 * [abseil] Update to 2018-2-5 * Fix for Issue #2729 Allows PowerShell to change the name of the downloaded directory correctly. * vcpkgRemoveItem: nullcheck * [cpprestsdk] Update to 2.10.2 * Adding Torch's TH library (#2737) Adding Torch's TH library * [flatbuffers] Fixes #2735 * sobjectizer updated to v.5.5.21 * [nghttp2] Enable static builds * [nghttp2]: update to 1.30.0 (#2739) * [nghttp2]: update to 1.30.0 * [nghttp2] Enable static builds * Add epsilon library port Signed-off-by: Hiroshi Miura * [vcpkg-configure-cmake] Use ninja to configure in parallel (#2712) * [curl] Add nghttp2.lib to dependencies of curl * [vtk] Fix breaking change in find_package(HDF5) * Merge findFileRecursivelyUp into VcpkgPowershellUtils * [vcpkgInvokeCommandClean] Don't use -encodedCommand. Instead, use -Command with the appropriate number of escaped quotes (which ended up being 3) * [blosc] Update to 1.13.5 static-install-fix.patch no longer required (upstream contains the patched version). Resolves build error with VS 15.6 in static builds * [cgal] Avoid using absolute paths in cmake config file * Update CHANGELOG and bump version to v0.0.104 * [qt5-base][qtdeploy] Deploy plugin dependencies to the executable's folder. * Add libgeotiff port Signed-off-by: Hiroshi Miura * [libgeotiff] fix install directory for cmake configurations Signed-off-by: Hiroshi Miura * fix tiff detection error when static build * [libgeotiff] remove installed dlls when static build * [libgeotiff] update description * [chipmunk] 7.0.2 initial. * [recast] 1.5.1 initial. * [tinydir] 1.2.3 initial. * [mman] git-f5ff813 initial. * Update Catch to 2.1.2 (#2763) * [vcpkg-ci] Delete intermediate build folders even on unsuccesful builds * [folly] Workaround bug for VS 15.6 * [pcre] fix space issue and add mirror (fix #2751) * [realsense2] Update to v2.10.0 Update realsense2 port to librealsense v2.10.0. * [libevent] Fix generated libevent targets files * fixed typo in warning message (#2773) * [blaze] update to Blaze 3.3 * [lmdb] Fix possible whitespace problem * Fix date issue * add qt5-quickcontrols2 * add qt5-quickcontrols port * add qt5-graphicaleffects * change compile order to debug first, fix #2767 (#2785) * [liblzma] Add usage information * [ffmpeg] Allow static builds of ffmpeg (#2783) ffmpeg creates static .a libraries, so change the suffix to .lib * [ffmpeg] Bump version for PR #2783 * [aubio] Update to handle static FFMPEG * Copy local dependencies for library targets (#2787) * Fix for issue #2786 * [vcpkg-cmake-toolchain] Only applocal dependencies for shared libraries * [uriparser] Update to 0.8.5 * [vcpkg] Implement Default-Features (#2697) * [vcpkg] Add Default-Feature to make_status_pgh utility function Signed-off-by: Squareys * [vcpkg] Parse "Default-Features" as dependencies and add test for parsing Signed-off-by: Squareys * [vcpkg] Document some methods and structures Signed-off-by: Squareys * [vcpkg] Add install_default_features_test Signed-off-by: Squareys * [vcpkg] Change install_default_features_test to not have preinstalled package * [vcpkg] Test install behaviour of default features Signed-off-by: Squareys * [vcpkg] Implement default features Signed-off-by: Squareys * [vcpkg] Test default features upgrade behavior Signed-off-by: Squareys * [vcpkg] Implement upgrade with default features Signed-off-by: Squareys * [vcpkg] Test behaviour of upgrade with default features in dependencies Signed-off-by: Squareys * [vcpkg] Make upgrade install new default features Signed-off-by: Squareys * [vcpkg] Move collecting of packages for which to prevent defaults Further down the line to create_feature_install_plan. Signed-off-by: Squareys * [vcpkg] Fix core missing from default features and potential inf loop Signed-off-by: Squareys * [vcpkg] Rename, fix and move some tests Signed-off-by: Squareys * Updated boost license to 1.66.0 (#2795) I was a bit confused to see a reference to "1.65.1" while I was installing 1.66.0, but it turns out this URL is just not updated. This updates it. * [vcpkg-find-acquire-program] Add mirror for NASM. Fixes #2777. * update cuda requirement to 9.0, fixes #2791 (#2802) * update cuda requirement to 9.0, fixes #2791 * [cuda] Restore sample version blob * [vcpkg] http_proxy and https_proxy should be lowercase (#2815) Pacman of Msys understands only lowercase environment variables http_proxy and https_proxy. * [vcpkg] Add find/find_installed/is_installed for FeatureSpec Signed-off-by: Squareys * [vcpkg] Fix build command for packages that depend of features Signed-off-by: Squareys * [liblo] Initial port (#2821) * [portaudio] Added ASIO support to build * Update libpng to 1.6.34 * [liblo] Initial port * Revert "Update libpng to 1.6.34" This reverts commit ede0bb947b07aea119b7b05e3625c3eec1395af4. * Revert "[liblo] Initial port" This reverts commit bb819eb21841bb8cf4816af5a78e17ef58ec8ce5. * [liblo] Initial port * [liblo] Use vcpkg_from_github() and vcpkg_fixup_cmake_targets() * [liblo] Fix SHA512 * [openvr] update to 1.0.13 (#2809) * [ebml] Initial port. (#2812) * [vcpkg] Fix bug with missing dependencies introduced in #2697 (#2819) When a package dependency was not found (has no source control file), install would exit with "Value was null" when trying to install its default features, as the dependency would be marked erroneously as found in this case. Signed-off-by: Squareys * [vcpkg] Avoid using s::status_known() -- it does not do what you think it does * [jansson] Update to 2.11 (#2820) * [aws-sdk-cpp] update to 1.3.58 (#2810) * [mkl] Add port MKL (#2806) * [corrade,magnum,-plugins,-extras,-integration] Update to latest and support feature packages (#2687) [corrade,magnum,-plugins,-extras,-integration] Update to latest and support feature packages * [jbig2dec][libmupdf] Extract jbig2dec, remove remaining vendored 3rdparty --- docs/maintainers/vcpkg_configure_cmake.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md index 93f661767..200d358ae 100644 --- a/docs/maintainers/vcpkg_configure_cmake.md +++ b/docs/maintainers/vcpkg_configure_cmake.md @@ -21,6 +21,11 @@ Specifies the directory containing the `CMakeLists.txt`. By convention, this is ### PREFER_NINJA Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja. +### DISABLE_PARALLEL_CONFIGURE +Disables running the CMake configure step in parallel. + +This is needed for libraries which write back into their source directory during configure. + ### GENERATOR Specifies the precise generator to use. -- cgit v1.2.3 From 8f20e31e180641f10d6e4e945b39e29991f75db8 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Mon, 19 Feb 2018 10:04:02 -0800 Subject: [vcpkg-docs-triplets.md] Update triplet docs to match the qt modularization --- docs/users/triplets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 06f77e63f..eb83aeb10 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -42,11 +42,11 @@ Example: ```cmake set(VCPKG_LIBRARY_LINKAGE static) set(VCPKG_CRT_LINKAGE dynamic) -if(PORT STREQUAL "qt5") +if(PORT MATCHES "qt5-") set(VCPKG_LIBRARY_LINKAGE dynamic) endif() ``` -This will build `qt5` 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 against the dynamic CRT, but every other library as a static library (still against the dynamic CRT). For an example in a real project, see https://github.com/Intelight/vcpkg/blob/master/triplets/x86-windows-mixed.cmake. -- cgit v1.2.3 From 63901137f66ec90f4a51070bd53a2d7433b4b54a Mon Sep 17 00:00:00 2001 From: Jacob Zhong Date: Sat, 24 Feb 2018 16:00:51 +0800 Subject: Add doxygen and add packages option to vcpkg_require_msys (#2869) * Add doxygen to acquired programs * Add packages option to msys function * Add documentation for PACKAGES in vcpkg_require_msys * [ffmpeg][x264] Update to use `PACKAGES` parameter. Tweak docs. --- docs/maintainers/vcpkg_acquire_msys.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/docs/maintainers/vcpkg_acquire_msys.md index 53aa6532e..4dc8f5391 100644 --- a/docs/maintainers/vcpkg_acquire_msys.md +++ b/docs/maintainers/vcpkg_acquire_msys.md @@ -4,13 +4,18 @@ Download and prepare an MSYS2 instance. ## Usage ```cmake -vcpkg_acquire_msys() +vcpkg_acquire_msys( [PACKAGES ...]) ``` ## Parameters ### MSYS_ROOT_VAR An out-variable that will be set to the path to MSYS2. +### PACKAGES +A list of packages to acquire in msys. + +To ensure a package is available: `vcpkg_acquire_msys(MSYS_ROOT PACKAGES make automake1.15)` + ## Notes A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`: ```cmake @@ -23,19 +28,6 @@ vcpkg_execute_required_process( LOGNAME build-${TARGET_TRIPLET}-rel ) ``` -To ensure a package is available: -```cmake -vcpkg_acquire_msys(MSYS_ROOT) -set(BASH ${MSYS_ROOT}/usr/bin/bash.exe) - -message(STATUS "Installing MSYS Packages") -vcpkg_execute_required_process( - COMMAND - ${BASH} --noprofile --norc -c - 'PATH=/usr/bin:\$PATH pacman -Sy --noconfirm --needed make' - WORKING_DIRECTORY ${MSYS_ROOT} - LOGNAME pacman-${TARGET_TRIPLET}) -``` ## Examples -- cgit v1.2.3 From be0e6434371d200f0ebec3543f73436817cf1e3f Mon Sep 17 00:00:00 2001 From: Mateusz Loskot Date: Sun, 18 Mar 2018 12:36:55 +0100 Subject: Update FAQ about cleaning downloads and build trees (#3044) * Update FAQ about cleaning downloads and build trees Answers #2202 and #2538 * [vcpkg-docs] Add packages folder to list of temporary folders --- docs/about/faq.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/about/faq.md b/docs/about/faq.md index cb711e384..b345b4fd0 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -72,6 +72,10 @@ A lower level mechanism to achieve the same as the `vcpkg integrate project` NuG ``` +## How can I remove temporary files? + +You can save some disk space by completely removing the `packages\`, `buildtrees\`, and `downloads\` folders. + ## How is CMake used internally by Vcpkg? Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows, does not require system-wide installation, and legible for unfamiliar users. -- cgit v1.2.3 From d5e433f03bf5220ef075489c18f5d1522fda1a4d Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Sat, 17 Feb 2018 04:46:38 -0800 Subject: [vcpkg-build-msbuild] Add option to use vcpkg's integration. Fixes #891. Fixes #828. --- docs/maintainers/vcpkg_build_msbuild.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md index 889b07bdc..37f8d8df2 100644 --- a/docs/maintainers/vcpkg_build_msbuild.md +++ b/docs/maintainers/vcpkg_build_msbuild.md @@ -19,6 +19,11 @@ vcpkg_build_msbuild( ``` ## Parameters +### 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_PATH The path to the solution (`.sln`) or project (`.vcxproj`) file. -- cgit v1.2.3 From f51b9d403a5a1bb99aa7c13e6b64f398ff423a40 Mon Sep 17 00:00:00 2001 From: Joel Clay Date: Tue, 24 Apr 2018 18:52:32 -0400 Subject: Add crossplatform announcement to docs --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index 3fa5784e9..1d12b282e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,7 @@ Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are - [Export](specifications/export-command.md) ### 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: 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 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