diff options
Diffstat (limited to 'docs')
30 files changed, 1713 insertions, 380 deletions
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 -- <a href="#example-1">Example 1: Using Sqlite</a> - - <a href="#example-1-1">Step 1: Build</a> - - <a href="#example-1-2">Step 2: Use</a> - - <a href="#example-1-2-a">Option A: VS Project (User-wide integration)</a> - - <a href="#example-1-2-b">Option B: CMake (Toolchain file)</a> - - <a href="#example-1-2-c">Option C: Other buildsystems</a> - - <a href="#example-1-2-d">Option D: VS Project (Individual Project integration)</a> -- <a href="#example-2">Example 2: Package a remote project (zlib)</a> -- <a href="example-3-patch-libpng.md">Example 3: Patching libpng to work for uwp-x86</a> - -<a name="example-1"></a> -## Example 1: Using Sqlite -<a name="example-1-1"></a> -### 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 `:<target>`. -``` -PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows -``` - -See `.\vcpkg help triplet` for all supported targets. - -<a name="example-1-2"></a> -### Step 2: Use -<a name="example-1-2-a"></a> -#### 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`. - -<a name="example-1-2-b"></a> -#### 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 <sqlite3.h> -#include <stdio.h> - -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 - -<a name="example-1-2-c"></a> -#### 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 -``` -<a name="example-1-2-d"></a> -#### 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.* - -<a name="example-2"></a> -## 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 `<packagename>-<version>.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\<packagename>`. - -``` -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\<package>\portfile.cmake`, We also need a `ports\<package>\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/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/FAQ.md b/docs/about/faq.md index 0a82d320e..87496da44 100644 --- a/docs/FAQ.md +++ b/docs/about/faq.md @@ -1,46 +1,42 @@ -# Frequently Asked Questions: Vcpkg - -Vcpkg is a tool to acquire C++ open source library and rebuild them on Windows. +# Frequently Asked Questions ## Can I contribute a new library? -Yes! Start out by reading our [contribution guidelines](../CONTRIBUTING.md). +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? -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). +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\`](../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)). +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 [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. +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`](../ports/opengl/portfile.cmake) package which simply copies files out of the Windows SDK. +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.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). +## Does Vcpkg run on Linux/OSX? +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!). This is because a package in Vcpkg corresponds to the `X-dev` or `X-devel` packages in other system package managers. +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](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\`. +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\<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`. +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. +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(<vcpkg_root>\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. @@ -50,25 +46,50 @@ 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. + +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: +``` +<PropertyGroup> + <VcpkgConfiguration Condition="'$(Configuration)' == 'MyRelease'">Release</VcpkgConfiguration> +</PropertyGroup> +``` +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. 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 `<vcpkg_root>\scripts\buildsystems\msbuild\vcpkg.targets` file. All you need is to import it in your .vcxproj file, replacing `<vcpkg_root>` with the path where you installed vcpkg: + +``` +<Import Project="<vcpkg_root>\scripts\buildsystems\msbuild\vcpkg.targets" /> +``` + +## 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 reasonably legible for unfamiliar users. +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 do plan to eventually support downloading precompiled binaries, similar to other system package managers. +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. +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 plan to only support Visual Studio 2015 and above. +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. -## 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. @@ -83,11 +104,11 @@ Conan.io is a publicly-federated, project-centric, cross-platform, C++ package m - **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). +- **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 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!). +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/PRIVACY.md b/docs/about/privacy.md index ad345c809..9ff0e7a47 100644 --- a/docs/PRIVACY.md +++ b/docs/about/privacy.md @@ -1,48 +1,44 @@ -# Privacy document for vcpkg +# Privacy and Vcpkg +## Do you collect telemetry data? What is it used for? -## 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. -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? +## 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 } - } - } -}] + "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? -## 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. +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/examples/packaging-zlib.md b/docs/examples/packaging-zlib.md new file mode 100644 index 000000000..ce176d451 --- /dev/null +++ b/docs/examples/packaging-zlib.md @@ -0,0 +1,79 @@ +## 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 `<packagename>-<version>.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\<packagename>`. + +```no-highlight +PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib-1.2.11.zip +-- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake +``` + +### Create the CONTROL file +In addition to the generated `ports\<package>\portfile.cmake`, we also need a `ports\<package>\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/zlib-1.2.11.tar.gz +-- Testing integrity of cached file... +-- Testing integrity of cached file... OK +-- Extracting source D:/src/vcpkg/downloads/zlib-1.2.11.tar.gz +-- Extracting done +-- Configuring x86-windows-rel +-- Configuring x86-windows-rel done +-- Configuring x86-windows-dbg +-- Configuring x86-windows-dbg done +-- Build x86-windows-rel +-- Build x86-windows-rel done +-- Build x86-windows-dbg +-- Build x86-windows-dbg done +-- Performing post-build validation +Include files should not be duplicated into the /debug/include directory. If this cannot be disabled in the project cmake, use + file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include) +/debug/share should not exist. Please reorganize any important files, then use + file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share) +The software license must be available at ${CURRENT_PACKAGES_DIR}/share/zlib2/copyright +Found 3 error(s). Please correct the portfile: + D:\src\vcpkg\ports\zlib2\portfile.cmake +``` + +At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed. + +### Suggested example portfiles +In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake. + +- Header only libraries + - rapidjson + - range-v3 +- MSBuild-based + - cppunit + - mpg123 +- Non-CMake, custom buildsystem + - openssl + - ffmpeg diff --git a/docs/example-3-patch-libpng.md b/docs/examples/patching-libpng.md index a47a2626a..2337b73da 100644 --- a/docs/example-3-patch-libpng.md +++ b/docs/examples/patching-libpng.md @@ -1,9 +1,9 @@ -## Example 3: Patching libpng to work for uwp-x86 +## 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 @@ -39,7 +39,7 @@ 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) -> @@ -76,7 +76,7 @@ Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop ``` 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(). @@ -114,8 +114,8 @@ This already gives us some great clues, but the full definition tells the comple ### Patching the code to improve compatibility -I recommend using git to create the patch file, since you'll already have it installed. -``` +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/ @@ -139,7 +139,7 @@ Now we can modify `pngpriv.h` to use `abort()` everywhere. ``` 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 ``` @@ -162,14 +162,14 @@ vcpkg_configure_cmake( 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 delete the building directory: D:\src\vcpkg\buildtrees\libpng +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 @@ -194,9 +194,9 @@ PS D:\src\vcpkg> vcpkg install libpng:x86-uwp 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. +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 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) + +--- +<a name="install"></a> +## 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 `:<target>`. +```no-highlight +PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows +``` + +See `.\vcpkg help triplet` for all supported targets. + +--- +<a name="use"></a> +## Step 2: Use +<a name="msbuild"></a> +#### 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`. + +<a name="cmake"></a> +#### 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 <sqlite3.h> +#include <stdio.h> + +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..c34715a27 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,40 @@ +### 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) +- [Triplet files](users/triplets.md) + +### Maintainer help + +- [Control files](maintainers/control-files.md) +- [Portfile functions](maintainers/portfile-functions.md) + +### Specifications + +- [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: 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/) +- [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..eb03f1d94 --- /dev/null +++ b/docs/maintainers/control-files.md @@ -0,0 +1,92 @@ +# 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 + +## 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 +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 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) +``` + +## 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/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md new file mode 100644 index 000000000..e16147f7d --- /dev/null +++ b/docs/maintainers/portfile-functions.md @@ -0,0 +1,17 @@ +<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake --> + +# 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)
+- [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\_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 new file mode 100644 index 000000000..4dc8f5391 --- /dev/null +++ b/docs/maintainers/vcpkg_acquire_msys.md @@ -0,0 +1,39 @@ +# vcpkg_acquire_msys + +Download and prepare an MSYS2 instance. + +## Usage +```cmake +vcpkg_acquire_msys(<MSYS_ROOT_VAR> [PACKAGES <package>...]) +``` + +## 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 +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 +) +``` + +## 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 <patch1.patch>... +) +``` + +## 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\<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_cmake.md b/docs/maintainers/vcpkg_build_cmake.md new file mode 100644 index 000000000..1e17eb975 --- /dev/null +++ b/docs/maintainers/vcpkg_build_cmake.md @@ -0,0 +1,34 @@ +# vcpkg_build_cmake + +Build a cmake project. + +## Usage: +```cmake +vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <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 <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 +"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_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md new file mode 100644 index 000000000..37f8d8df2 --- /dev/null +++ b/docs/maintainers/vcpkg_build_msbuild.md @@ -0,0 +1,64 @@ +# vcpkg_build_msbuild + +Build an msbuild-based project. + +## Usage +```cmake +vcpkg_build_msbuild( + PROJECT_PATH <${SOURCE_PATH}/port.sln> + [RELEASE_CONFIGURATION <Release>] + [DEBUG_CONFIGURATION <Debug>] + [TARGET <Build>] + [TARGET_PLATFORM_VERSION <10.0.15063.0>] + [PLATFORM <${TRIPLET_SYSTEM_ARCH}>] + [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>] + [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...] + [OPTIONS_RELEASE </p:ZLIB_LIB=X>...] + [OPTIONS_DEBUG </p:ZLIB_LIB=X>...] +) +``` + +## 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. + +### 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:<TARGET>``) + +### 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 + +* [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)
diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md new file mode 100644 index 000000000..200d358ae --- /dev/null +++ b/docs/maintainers/vcpkg_configure_cmake.md @@ -0,0 +1,54 @@ +# 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. + +### 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. + +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..80ea7559a --- /dev/null +++ b/docs/maintainers/vcpkg_download_distfile.md @@ -0,0 +1,46 @@ +# vcpkg_download_distfile + +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( + <OUT_VARIABLE> + URLS <http://mainUrl> <http://mirror1>... + FILENAME <output.zip> + 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. + +### SKIP_SHA512 +Skip SHA512 hash check for file. + +This switch is only valid when building with the `--head` command line flag. + +## Notes +The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects. + +## Examples + +* [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) + +## 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}> [<arguments>...] + WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg> + LOGNAME <build-${TARGET_TRIPLET}-dbg> +) +``` +## 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 <FILENAME>.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..57a2bf75a --- /dev/null +++ b/docs/maintainers/vcpkg_find_acquire_program.md @@ -0,0 +1,39 @@ +# vcpkg_find_acquire_program + +Download or find a well-known tool. + +## Usage +```cmake +vcpkg_find_acquire_program(<VAR>) +``` +## 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 +- GASPREPROCESSOR +- PERL +- PYTHON2 +- PYTHON3 +- JOM +- MESON +- NASM +- NINJA +- YASM +- ARIA2 (Downloader) + +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_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 <port>`. + +## Usage: +```cmake +vcpkg_from_bitbucket( + OUT_SOURCE_PATH <SOURCE_PATH> + REPO <Microsoft/cpprestsdk> + [REF <v2.0.0>] + [SHA512 <45d0d7f8cc350...>] + [HEAD_REF <master>] +) +``` + +## 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 new file mode 100644 index 000000000..cf50dc445 --- /dev/null +++ b/docs/maintainers/vcpkg_from_github.md @@ -0,0 +1,54 @@ +# vcpkg_from_github + +Download and extract a project from GitHub. Enables support for `install --head`. + +## Usage: +```cmake +vcpkg_from_github( + OUT_SOURCE_PATH <SOURCE_PATH> + REPO <Microsoft/cpprestsdk> + [REF <v2.0.0>] + [SHA512 <45d0d7f8cc350...>] + [HEAD_REF <master>] +) +``` + +## 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://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, however it is preferable for both to be present. + +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..1b132b4f1 --- /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(...) +``` + +## Parameters: +See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md). + +## Notes: +This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install` +parameter. + +## 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 "<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->`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/specifications/feature-packages.md b/docs/specifications/feature-packages.md new file mode 100644 index 000000000..198a602ba --- /dev/null +++ b/docs/specifications/feature-packages.md @@ -0,0 +1,289 @@ +# 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
+
+[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 <package>`, some features will be enabled by default. These default features can be avoided by referring to the packages as `<package>[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): <http://doc.crates.io/manifest.html#the-features-section>
+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: <https://wiki.gentoo.org/wiki/Handbook:X86/Working/USE>
+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.
diff --git a/docs/users/integration.md b/docs/users/integration.md new file mode 100644 index 000000000..f1b5014bf --- /dev/null +++ b/docs/users/integration.md @@ -0,0 +1,121 @@ +## 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) + +Each integration style has heuristics to deduce the correct [triplet][]. This can be overridden using [a common method](#triplet-selection) based on your buildsystem. + +<a name="integrate"></a> +### 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. + +<a name="user-wide-msbuild"></a> +#### 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. + +<a name="export"></a> +### 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. + +<a name="triplet-selection"></a> +### 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 +<PropertyGroup Label="Globals"> + <!-- .... --> + <VcpkgTriplet Condition="'$(Platform)'=='Win32'">x86-windows-static</VcpkgTriplet> + <VcpkgTriplet Condition="'$(Platform)'=='x64'">x64-windows-static</VcpkgTriplet> +</PropertyGroup> +``` + +#### 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 new file mode 100644 index 000000000..911ab5469 --- /dev/null +++ b/docs/users/triplets.md @@ -0,0 +1,59 @@ +# 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`. + +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. + +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. + +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. + +Example: +```cmake +set(VCPKG_LIBRARY_LINKAGE static) +set(VCPKG_CRT_LINKAGE dynamic) +if(PORT MATCHES "qt5-") + set(VCPKG_LIBRARY_LINKAGE dynamic) +endif() +``` +This will build all the `qt5-*` libraries as DLLs against the dynamic CRT, but every other library as a static library (still against the dynamic CRT). + +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. |