diff options
Diffstat (limited to 'docs')
27 files changed, 1598 insertions, 24 deletions
diff --git a/docs/about/faq.md b/docs/about/faq.md index 504738479..6517774cf 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -52,11 +52,12 @@ Yes. While Vcpkg will only produce the standard "Release" and "Debug" configurat 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 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. Unfortunately, due to the sequential nature of MSBuild, you'll need to add those settings much higher in your vcxproj so that it is declared before the Vcpk integration is loaded. It is recommend that the `$(VcpkgConfiguration)` macro is added to the "Globals" PropertyGroup. For example, you can add support for your "MyRelease" configuration by adding in your project file: ``` -<PropertyGroup> +<PropertyGroup Label="Globals"> + ... <VcpkgConfiguration Condition="'$(Configuration)' == 'MyRelease'">Release</VcpkgConfiguration> </PropertyGroup> ``` diff --git a/docs/examples/overlay-triplets-linux-dynamic.md b/docs/examples/overlay-triplets-linux-dynamic.md new file mode 100644 index 000000000..b2868e2fd --- /dev/null +++ b/docs/examples/overlay-triplets-linux-dynamic.md @@ -0,0 +1,126 @@ +# Overlay triplets example
+
+## Building dynamic libraries on Linux
+
+Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS.
+
+This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux.
+
+### Step 1: Create the custom triplet files
+
+To save time, copy the existing `x64-linux.cmake` triplet file.
+
+```sh
+~/git$ mkdir custom-triplets
+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake
+```
+
+And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below:
+```cmake
+# ~/git/custom-triplets/x64-linux-dynamic.cmake
+set(VCPKG_TARGET_ARCHITECTURE x64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic
+
+set(VCPKG_CMAKE_SYSTEM_NAME Linux)
+```
+
+### Step 2: Use `--overlay-triplets` to build dynamic libraries
+
+Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.
+
+```
+~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets
+The following packages will be built and installed:
+ sqlite3[core]:x64-linux-dynamic
+Starting package 1/1: sqlite3:x64-linux-dynamic
+Building package sqlite3[core]:x64-linux-dynamic...
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux-dynamic.cmake
+-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
+-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
+-- Applying patch fix-arm-uwp.patch
+-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92
+-- Configuring x64-linux-dynamic-dbg
+-- Configuring x64-linux-dynamic-rel
+-- Building x64-linux-dynamic-dbg
+-- Building x64-linux-dynamic-rel
+-- Performing post-build validation
+-- Performing post-build validation done
+Building package sqlite3[core]:x64-linux-dynamic... done
+Installing package sqlite3[core]:x64-linux-dynamic...
+Installing package sqlite3[core]:x64-linux-dynamic... done
+Elapsed time for package sqlite3:x64-linux-dynamic: 44.82 s
+
+Total elapsed time: 44.82 s
+
+The package sqlite3:x64-linux-dynamic provides CMake targets:
+
+ find_package(sqlite3 CONFIG REQUIRED)
+ target_link_libraries(main PRIVATE sqlite3)
+```
+
+Overlay triplets enables your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.
+
+When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used:
+
+```
+-- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake
+```
+
+## Overriding default triplets
+
+As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is different with Linux and Mac OS where static libraries are built by `x64-linux` and `x64-osx`.
+
+Using `--overlay-ports` it is possible to override the default triplets to accomplish the same behavior on Linux:
+
+* `x64-linux`: Builds dynamic libraries,
+* `x64-linux-static`: Builds static libraries.
+
+### Step 1: Create the overlay triplets
+
+Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. Then, copy the default `x64-linux` triplet (which builds static libraries) in your `custom-triplets` folder and rename it to `x64-linux-static.cmake`.
+
+```sh
+~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake
+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.cmake
+```
+
+### Step 2: Use `--overlay-ports` to override default triplets
+
+Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.
+
+```
+~/git$ vcpkg/vcpkg install sqlite3:x64-linux --overlay-triplets=custom-triplets
+The following packages will be built and installed:
+ sqlite3[core]:x64-linux
+Starting package 1/1: sqlite3:x64-linux
+Building package sqlite3[core]:x64-linux...
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
+-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
+-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
+-- Applying patch fix-arm-uwp.patch
+-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92
+-- Configuring x64-linux-dbg
+-- Configuring x64-linux-rel
+-- Building x64-linux-dbg
+-- Building x64-linux-rel
+-- Performing post-build validation
+-- Performing post-build validation done
+Building package sqlite3[core]:x64-linux... done
+Installing package sqlite3[core]:x64-linux...
+Installing package sqlite3[core]:x64-linux... done
+Elapsed time for package sqlite3:x64-linux: 44.82 s
+
+Total elapsed time: 44.82 s
+
+The package sqlite3:x64-linux provides CMake targets:
+
+ find_package(sqlite3 CONFIG REQUIRED)
+ target_link_libraries(main PRIVATE sqlite3)
+```
+
+Note that the default triplet is masked by your custom triplet:
+
+```
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
+```
diff --git a/docs/index.md b/docs/index.md index cde241e92..579b0e4c8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,6 +19,14 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too - [Control files](maintainers/control-files.md) - [Portfile functions](maintainers/portfile-functions.md) +- [Maintainer Guidelines](maintainers/maintainer-guide.md) + +### Tool Maintainer Help + +- [Testing](tool-maintainers/testing.md) +- [Benchmarking](tool-maintainers/benchmarking.md) +- [Layout of the vcpkg source tree](tool-maintainers/layout.md) +- [Maintainer Guidelines](maintainers/maintainer-guide.md) ### Specifications diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md index ac4afa265..03bfa113a 100644 --- a/docs/maintainers/control-files.md +++ b/docs/maintainers/control-files.md @@ -43,16 +43,27 @@ The port version. This field is an alphanumeric string that may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bit strings 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. +For tagged-release ports, we follow the following convention: -Some projects do not have named releases. In these cases use the date of the version do not have labeled releases, in these cases use the date of the last commit in `YYYY-MM-DD` format. See the `abseil` port as an example. +1. If the port follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`. +2. If the port includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1` +3. If the port has been modified, we append a `-N` to distinguish the versions: `1.2.1-4` + +For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master. + +For example, given: +1. The latest commit was made on 2019-04-19 +2. The current version string is `2019-02-14-1` +3. Today's date is 2019-06-01. + +Then if you update the source version today, you should give it version `2019-06-01`. If you need to make a change which doesn't adjust the source version, you should give it version `2019-02-14-2`. Example: ```no-highlight Version: 1.0.5-2 ``` ```no-highlight -Version: 2019-3-21 +Version: 2019-03-21 ``` #### Description diff --git a/docs/maintainers/execute_process.md b/docs/maintainers/execute_process.md new file mode 100644 index 000000000..cbb339509 --- /dev/null +++ b/docs/maintainers/execute_process.md @@ -0,0 +1,10 @@ +# execute_process + +Intercepts all calls to execute_process() inside portfiles and fails when Download Mode +is enabled. + +In order to execute a process in Download Mode call `_execute_process()` instead. + + +## Source +[scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)
diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md new file mode 100644 index 000000000..624aa46d3 --- /dev/null +++ b/docs/maintainers/maintainer-guide.md @@ -0,0 +1,236 @@ +# Maintainer Guidelines and Policies
+
+This document lists a set of policies that you should apply when adding or updating a port recipe.
+It is intended to serve the role of
+[Debian's Policy Manual](https://www.debian.org/doc/debian-policy/),
+[Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and
+[Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).
+
+## PR Structure
+
+### Make separate Pull Requests per port
+
+Whenever possible, separate changes into multiple PRs.
+This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.
+
+### Avoid trivial changes in untouched files
+
+For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand.
+However, if you need to modify the file for the primary purpose of the PR (updating the library),
+then obviously beneficial changes like fixing typos are appreciated!
+
+### Check names against other repositories
+
+A good service to check many at once is [Repology](https://repology.org/).
+If the library you are adding could be confused with another one,
+consider renaming to make it clear.
+
+### Use GitHub Draft PRs
+
+GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge.
+Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.
+
+More information about GitHub Draft PRs:
+https://github.blog/2019-02-14-introducing-draft-pull-requests/
+
+## Portfiles
+
+### Avoid deprecated helper functions
+
+At this time, the following helpers are deprecated:
+
+1. `vcpkg_extract_source_archive()` should be replaced by [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md)
+2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
+3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
+
+### Avoid excessive comments in portfiles
+
+Ideally, portfiles should be short, simple, and as declarative as possible.
+Remove any boiler plate comments introduced by the `create` command before submitting a PR.
+
+## Build Techniques
+
+### Do not use vendored dependencies
+
+Do not use embedded copies of libraries.
+All dependencies should be split out and packaged separately so they can be updated and maintained.
+
+### Prefer using CMake
+
+When multiple buildsystems are available, prefer using CMake.
+Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.
+
+Examples: [abseil](../../ports/abseil/portfile.cmake)
+
+### Choose either static or shared binaries
+
+By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`,
+however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:
+
+```cmake
+string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
+string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)
+
+vcpkg_configure_cmake(
+ SOURCE_PATH ${SOURCE_PATH}
+ PREFER_NINJA
+ OPTIONS
+ -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
+ -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
+)
+```
+
+### When defining features, explicitly control dependencies
+
+When defining a feature that captures an optional dependency,
+ensure that the dependency will not be used accidentally when the feature is not explicitly enabled.
+
+```cmake
+if ("zlib" IN_LIST FEATURES)
+ set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
+else()
+ set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
+endif()
+
+vcpkg_configure_cmake(
+ SOURCE_PATH ${SOURCE_PATH}
+ PREFER_NINJA
+ OPTIONS
+ -CMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
+)
+```
+
+The snippet below using `vcpkg_check_features()` is equivalent, [see the documentation](vcpkg_check_features.md).
+
+```cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+ INVERTED_FEATURES
+ "zlib" CMAKE_DISABLE_FIND_PACKAGE_ZLIB
+)
+
+vcpkg_configure_cmake(
+ SOURCE_PATH ${SOURCE_PATH}
+ PREFER_NINJA
+ OPTIONS
+ ${FEATURE_OPTIONS}
+)
+```
+
+Note that `ZLIB` in the above is case-sensitive. See the [cmake documentation](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) for more details.
+
+### Place conflicting libs in a `manual-link` directory
+
+A lib is considered conflicting if it does any of the following:
++ Define `main`
++ Define malloc
++ Define symbols that are also declared in other libraries
+
+Conflicting libs are typically by design and not considered a defect. Because some build systems link against everything in the lib directory, these should be moved into a subdirectory named `manual-link`.
+
+## Versioning
+
+### Follow common conventions for the `Version:` field
+
+See our [CONTROL files document](control-files.md#version) for a full explanation of our conventions.
+
+### Update the `Version:` field in the `CONTROL` file of any modified ports
+
+Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes.
+
+Our convention for this field is to append a `-N` to the upstream version when changes need to be made.
+
+For Example:
+
+- Zlib's package version is currently `1.2.1`.
+- You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile.
+- You should update the `Version:` field in the control file to `1.2.1-1`.
+
+See our [CONTROL files document](control-files.md#version) for a full explanation of our conventions.
+
+## Patching
+
+### Prefer options over patching
+
+It is preferable to set options in a call to `vcpkg_configure_xyz()` over patching the settings directly.
+
+Common options that allow avoiding patching:
+1. [MSBUILD] `<PropertyGroup>` settings inside the project file can be overridden via `/p:` parameters
+2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
+3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overridden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
+
+### Prefer patching over overriding `VCPKG_<VARIABLE>` values
+
+Some variables prefixed with `VCPKG_<VARIABLE>` have an equivalent `CMAKE_<VARIABLE>`.
+However, not all of them are passed to the internal package build [(see implementation: Windows toolchain)](../../scripts/toolchains/windows.cmake).
+
+Consider the following example:
+
+```cmake
+set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
+set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")
+```
+
+Using `vcpkg`'s built-in toolchains this works, because the value of `VCPKG_<LANG>_FLAGS` is forwarded to the appropriate `CMAKE_LANG_FLAGS` variable. But, a custom toolchain that is not aware of `vcpkg`'s variables will not forward them.
+
+Because of this, it is preferable to patch the buildsystem directly when setting `CMAKE_<LANG>_FLAGS`.
+
+### Minimize patches
+
+When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional.
+
+This helps to keep the size of the vcpkg repository down as well as improves the likelihood that the patch will apply to future code versions.
+
+### Do not implement features in patches
+
+The purpose of patching in vcpkg is to enable compatibility with compilers, libraries, and platforms. It is not to implement new features in lieu of following proper Open Source procedure (submitting an Issue/PR/etc).
+
+## Do not build tests/docs/examples by default
+
+When submitting a new port, check for any options like `BUILD_TESTS` or `WITH_TESTS` or `POCO_ENABLE_SAMPLES` and ensure the additional binaries are disabled. This minimizes build times and dependencies for the average user.
+
+Optionally, you can add a `test` feature which enables building the tests, however this should not be in the `Default-Features` list.
+
+## Enable existing users of the library to switch to vcpkg
+
+### Do not add `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`
+
+Unless the author of the library is already using it, we should not use this CMake functionality because it interacts poorly with C++ templates and breaks certain compiler features. Libraries that don't provide a .def file and do not use __declspec() declarations simply do not support shared builds for Windows and should be marked as such with `vcpkg_check_linkage(ONLY_STATIC_LIBRARY)`.
+
+### Do not rename binaries outside the names given by upstream
+
+This means that if the upstream library has different names in release and debug (libx versus libxd), then the debug library should not be renamed to `libx`. Vice versa, if the upstream library has the same name in release and debug, we should not introduce a new name.
+
+Important caveat:
+- Static and shared variants often should be renamed to a common scheme. This enables consumers to use a common name and be ignorant of the downstream linkage. This is safe because we only make one at a time available.
+
+Note that if a library generates CMake integration files (`foo-config.cmake`), renaming must be done through patching the CMake build itself instead of simply calling `file(RENAME)` on the output archives/LIBs.
+
+Finally, DLL files on Windows should never be renamed post-build because it breaks the generated LIBs.
+
+## Useful implementation notes
+
+### Portfiles are run in Script Mode
+
+While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core CMake language constructs, portfiles run in "Script Mode", whereas `CMakeLists.txt` files run in "Build Mode" (unofficial term). The most important difference between these two modes is that "Script Mode" does not have a concept of "Target" -- any behaviors that depend on the "target" machine (`CMAKE_CXX_COMPILER`, `CMAKE_EXECUTABLE_SUFFIX`, `CMAKE_SYSTEM_NAME`, etc) will not be correct.
+
+Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`).
+
+Portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:
+
+```no-highlight
++----------------------------+ +------------------------------------+
+| CMake.exe | | CMake.exe |
++----------------------------+ +------------------------------------+
+| Triplet file | ====> | Toolchain file |
+| (x64-windows.cmake) | | (scripts/buildsystems/vcpkg.cmake) |
++----------------------------+ +------------------------------------+
+| Portfile | ====> | CMakeLists.txt |
+| (ports/foo/portfile.cmake) | | (buildtrees/../CMakeLists.txt) |
++----------------------------+ +------------------------------------+
+```
+
+To determine the host in a portfile, the standard CMake variables are fine (`CMAKE_HOST_WIN32`).
+
+To determine the target in a portfile, the vcpkg triplet variables should be used (`VCPKG_CMAKE_SYSTEM_NAME`).
+
+See also our [triplet documentation](../users/triplets.md) for a full enumeration of possible settings.
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index f159f7f64..dac417acf 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -1,25 +1,36 @@ <!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake --> # Portfile helper functions
+- [execute\_process](execute_process.md)
- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
- [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
- [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
-- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
+- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md) +- [vcpkg\_build\_make](vcpkg_build_make.md) +- [vcpkg\_build\_nmake](vcpkg_build_nmake.md)
+- [vcpkg\_check\_features](vcpkg_check_features.md)
- [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
-- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
+- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
+- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) +- [vcpkg\_configure\_make](vcpkg_configure_make.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\_build\_process](vcpkg_execute_build_process.md)
- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
- [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)
- [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)
+- [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md)
- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
- [vcpkg\_from\_git](vcpkg_from_git.md)
- [vcpkg\_from\_github](vcpkg_from_github.md)
- [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)
- [vcpkg\_install\_cmake](vcpkg_install_cmake.md)
-- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)
+- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md) +- [vcpkg\_install\_make](vcpkg_install_make.md) +- [vcpkg\_install\_nmake](vcpkg_install_nmake.md)
+- [vcpkg\_prettify\_command](vcpkg_prettify_command.md)
- [vcpkg\_test\_cmake](vcpkg_test_cmake.md)
diff --git a/docs/maintainers/vcpkg_build_make.md b/docs/maintainers/vcpkg_build_make.md new file mode 100644 index 000000000..5161ba3ce --- /dev/null +++ b/docs/maintainers/vcpkg_build_make.md @@ -0,0 +1,30 @@ +# vcpkg_build_make + +Build a linux makefile project. + +## Usage: +```cmake +vcpkg_build_make([TARGET <target>]) +``` + +### TARGET +The target passed to the configure/make build command (`./configure/make/make install`). 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_make()`](vcpkg_configure_make.md). +You can use the alias [`vcpkg_install_make()`](vcpkg_configure_make.md) function if your CMake script supports the +"install" target + +## Examples + +* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake) +* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) +* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake) +* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_build_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)
diff --git a/docs/maintainers/vcpkg_build_nmake.md b/docs/maintainers/vcpkg_build_nmake.md new file mode 100644 index 000000000..e5c177b1b --- /dev/null +++ b/docs/maintainers/vcpkg_build_nmake.md @@ -0,0 +1,75 @@ +# vcpkg_build_nmake + +Build a msvc makefile project. + +## Usage: +```cmake +vcpkg_build_nmake( + SOURCE_PATH <${SOURCE_PATH}> + [NO_DEBUG] + PROJECT_SUBPATH <${SUBPATH}> + PROJECT_NAME <${MAKEFILE_NAME}> + [PRERUN_SHELL <${SHELL_PATH}>] + [PRERUN_SHELL_DEBUG <${SHELL_PATH}>] + [PRERUN_SHELL_RELEASE <${SHELL_PATH}>] + [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] + [OPTIONS_RELEASE <-DOPTIMIZE=1>...] + [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] + [TARGET <target>]) +``` + +## Parameters +### SOURCE_PATH +Specifies the directory containing the source files. +By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. + +### PROJECT_SUBPATH +Specifies the sub directory containing the `makefile.vc`/`makefile.mak`/`makefile.msvc` or other msvc makefile. + +### PROJECT_NAME +Specifies the name of msvc makefile name. +Default is `makefile.vc` + +### NO_DEBUG +This port doesn't support debug mode. + +### ENABLE_INSTALL +Install binaries after build. + +### PRERUN_SHELL +Script that needs to be called before build + +### PRERUN_SHELL_DEBUG +Script that needs to be called before debug build + +### PRERUN_SHELL_RELEASE +Script that needs to be called before release build + +### OPTIONS +Additional options passed to generate during the generation. + +### OPTIONS_RELEASE +Additional options passed to generate during the Release generation. These are in addition to `OPTIONS`. + +### OPTIONS_DEBUG +Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`. + +### TARGET +The target passed to the nmake build command (`nmake/nmake install`). 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_nmake()`](vcpkg_configure_nmake.md). +You can use the alias [`vcpkg_install_nmake()`](vcpkg_configure_nmake.md) function if your CMake script supports the +"install" target + +## Examples + +* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) +* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_build_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)
diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md new file mode 100644 index 000000000..cec01dde2 --- /dev/null +++ b/docs/maintainers/vcpkg_check_features.md @@ -0,0 +1,148 @@ +# vcpkg_check_features +Check if one or more features are a part of a package installation. + +## Usage +```cmake +vcpkg_check_features( + OUT_FEATURE_OPTIONS <FEATURE_OPTIONS> + [FEATURES + <cuda> <WITH_CUDA> + [<opencv> <WITH_OPENCV>] + ...] + [INVERTED_FEATURES + <cuda> <IGNORE_PACKAGE_CUDA> + [<opencv> <IGNORE_PACKAGE_OPENCV>] + ...] +) +``` +`vcpkg_check_features()` accepts these parameters: + +* `OUT_FEATURE_OPTIONS`: + An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS` + and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`). + + This should be set to `FEATURE_OPTIONS` by convention. + +* `FEATURES`: + A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs. + For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of: + + * `-D<OPTION_NAME>=ON`, if a feature is specified for installation, + * `-D<OPTION_NAME>=OFF`, otherwise. + +* `INVERTED_FEATURES`: + A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`. + For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of: + + * `-D<OPTION_NAME>=OFF`, if a feature is specified for installation, + * `-D<OPTION_NAME>=ON`, otherwise. + + +## Notes + +The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used. + +At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call. + +Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication. +If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists, +two conflicting definitions are added to `OUT_FEATURE_OPTIONS`. + + +## Examples + +### Example 1: Regular features + +```cmake +$ ./vcpkg install mimalloc[asm,secure] + +# ports/mimalloc/portfile.cmake +vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS + # Keyword FEATURES is optional if INVERTED_FEATURES are not used + asm MI_SEE_ASM + override MI_OVERRIDE + secure MI_SECURE +) + +vcpkg_configure_cmake( + SOURCE_PATH ${SOURCE_PATH} + PREFER_NINJA + OPTIONS + # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON" + ${FEATURE_OPTIONS} +) +``` + +### Example 2: Inverted features + +```cmake +$ ./vcpkg install cpprestsdk[websockets] + +# ports/cpprestsdk/portfile.cmake +vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS + INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required + brotli CPPREST_EXCLUDE_BROTLI + websockets CPPREST_EXCLUDE_WEBSOCKETS +) + +vcpkg_configure_cmake( + SOURCE_PATH ${SOURCE_PATH} + PREFER_NINJA + OPTIONS + # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF" + ${FEATURE_OPTIONS} +) +``` + +### Example 3: Set multiple options for same feature + +```cmake +$ ./vcpkg install pcl[cuda] + +# ports/pcl/portfile.cmake +vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS + cuda WITH_CUDA + cuda BUILD_CUDA + cuda BUILD_GPU +) + +vcpkg_configure_cmake( + SOURCE_PATH ${SOURCE_PATH} + PREFER_NINJA + OPTIONS + # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON" + ${FEATURE_OPTIONS} +) +``` + +### Example 4: Use regular and inverted features + +```cmake +$ ./vcpkg install rocksdb[tbb] + +# ports/rocksdb/portfile.cmake +vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS + FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used + tbb WITH_TBB + INVERTED_FEATURES + tbb ROCKSDB_IGNORE_PACKAGE_TBB +) + +vcpkg_configure_cmake( + SOURCE_PATH ${SOURCE_PATH} + PREFER_NINJA + OPTIONS + # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF" + ${FEATURE_OPTIONS} +) +``` + +## Examples in portfiles + +* [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake) +* [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake) + + +## Source +[scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)
diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md new file mode 100644 index 000000000..3bb922b17 --- /dev/null +++ b/docs/maintainers/vcpkg_common_definitions.md @@ -0,0 +1,19 @@ +# vcpkg_common_definitions + +File contains helpful variabls for portfiles which are commonly needed or used. + +## The following variables are available: +```cmake +VCPKG_TARGET_IS_<target> with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD. only defined if <target> +VCPKG_TARGET_STATIC_LIBRARY_PREFIX static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX) +VCPKG_TARGET_STATIC_LIBRARY_SUFFIX static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX) +VCPKG_TARGET_SHARED_LIBRARY_PREFIX shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX) +VCPKG_TARGET_SHARED_LIBRARY_SUFFIX shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX) +``` + +CMAKE_STATIC_LIBRARY_PREFIX, CMAKE_STATIC_LIBRARY_SUFFIX, CMAKE_SHARED_LIBRARY_PREFIX, CMAKE_SHARED_LIBRARY_SUFFIX are defined for the target so that +portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports. + + +## Source +[scripts/cmake/vcpkg_common_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)
diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md index 200d358ae..ebbd92ed1 100644 --- a/docs/maintainers/vcpkg_configure_cmake.md +++ b/docs/maintainers/vcpkg_configure_cmake.md @@ -7,6 +7,8 @@ Configure CMake for Debug and Release builds of a project. vcpkg_configure_cmake( SOURCE_PATH <${SOURCE_PATH}> [PREFER_NINJA] + [DISABLE_PARALLEL_CONFIGURE] + [NO_CHARSET_FLAG] [GENERATOR <"NMake Makefiles">] [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] [OPTIONS_RELEASE <-DOPTIMIZE=1>...] @@ -16,20 +18,27 @@ vcpkg_configure_cmake( ## Parameters ### SOURCE_PATH -Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `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. +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. +### NO_CHARSET_FLAG +Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`. + +This is needed for libraries that set their own source code's character set. + ### 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". +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. diff --git a/docs/maintainers/vcpkg_configure_make.md b/docs/maintainers/vcpkg_configure_make.md new file mode 100644 index 000000000..73b46bafc --- /dev/null +++ b/docs/maintainers/vcpkg_configure_make.md @@ -0,0 +1,78 @@ +# vcpkg_configure_make + +Configure `configure` for Debug and Release builds of a project. + +## Usage +```cmake +vcpkg_configure_make( + SOURCE_PATH <${SOURCE_PATH}> + [AUTOCONFIG] + [DISABLE_AUTO_HOST] + [DISABLE_AUTO_DST] + [GENERATOR] + [NO_DEBUG] + [SKIP_CONFIGURE] + [PROJECT_SUBPATH <${PROJ_SUBPATH}>] + [PRERUN_SHELL <${SHELL_PATH}>] + [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] + [OPTIONS_RELEASE <-DOPTIMIZE=1>...] + [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] +) +``` + +## Parameters +### SOURCE_PATH +Specifies the directory containing the `configure`/`configure.ac`. +By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. + +### PROJECT_SUBPATH +Specifies the directory containing the ``configure`/`configure.ac`. +By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. +Should use `GENERATOR NMake` first. + +### NO_DEBUG +This port doesn't support debug mode. + +### SKIP_CONFIGURE +Skip configure process + +### AUTOCONFIG +Need to use autoconfig to generate configure file. + +### DISABLE_AUTO_HOST +Don't set host automatically, the default value is `i686`. +If use this option, you will need to set host manually. + +### DISABLE_AUTO_DST +Don't set installation path automatically, the default value is `${CURRENT_PACKAGES_DIR}` and `${CURRENT_PACKAGES_DIR}/debug` +If use this option, you will need to set dst path manually. + +### GENERATOR +Specifies the precise generator to use. +NMake: nmake(windows) make(unix) +MAKE: make(windows) make(unix) + +### PRERUN_SHELL +Script that needs to be called before configuration + +### OPTIONS +Additional options passed to configure during the configuration. + +### OPTIONS_RELEASE +Additional options passed to configure during the Release configuration. These are in addition to `OPTIONS`. + +### OPTIONS_DEBUG +Additional options passed to configure during the Debug configuration. These are in addition to `OPTIONS`. + +## Notes +This command supplies many common arguments to configure. To see the full list, examine the source. + +## Examples + +* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake) +* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) +* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake) +* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_configure_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
diff --git a/docs/maintainers/vcpkg_execute_build_process.md b/docs/maintainers/vcpkg_execute_build_process.md new file mode 100644 index 000000000..d5b3593d9 --- /dev/null +++ b/docs/maintainers/vcpkg_execute_build_process.md @@ -0,0 +1,36 @@ +# vcpkg_execute_build_process + +Execute a required build process + +## Usage +```cmake +vcpkg_execute_build_process( + COMMAND <cmd> [<args>...] + [NO_PARALLEL_COMMAND <cmd> [<args>...]] + WORKING_DIRECTORY </path/to/dir> + LOGNAME <log_name>) +) +``` +## Parameters +### COMMAND +The command to be executed, along with its arguments. + +### NO_PARALLEL_COMMAND +Optional parameter which specifies a non-parallel command to attempt if a +failure potentially due to parallelism is detected. + +### 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 + +* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_execute_build_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)
diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md index 4b1a7e081..26a116782 100644 --- a/docs/maintainers/vcpkg_execute_required_process.md +++ b/docs/maintainers/vcpkg_execute_required_process.md @@ -11,6 +11,10 @@ vcpkg_execute_required_process( ) ``` ## Parameters +### ALLOW_IN_DOWNLOAD_MODE +Allows the command to execute in Download Mode. +[See execute_process() override](../../scripts/cmake/execute_process.cmake). + ### COMMAND The command to be executed, along with its arguments. diff --git a/docs/maintainers/vcpkg_extract_source_archive_ex.md b/docs/maintainers/vcpkg_extract_source_archive_ex.md index 92c90b296..8f525c3ce 100644 --- a/docs/maintainers/vcpkg_extract_source_archive_ex.md +++ b/docs/maintainers/vcpkg_extract_source_archive_ex.md @@ -25,7 +25,7 @@ The full path to the archive to be extracted. This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md). ### REF -A friendly name that will be used instead of the filename of the archive. +A friendly name that will be used instead of the filename of the archive. If more than 10 characters it will be truncated. By convention, this is set to the version number or tag fetched diff --git a/docs/maintainers/vcpkg_fail_port_install.md b/docs/maintainers/vcpkg_fail_port_install.md new file mode 100644 index 000000000..b3b48ad5e --- /dev/null +++ b/docs/maintainers/vcpkg_fail_port_install.md @@ -0,0 +1,34 @@ +# vcpkg_fail_port_install + +Fails the current portfile with a (default) error message + +## Usage +```cmake +vcpkg_fail_port_install([MESSAGE <message>] [ON_TARGET <target1> [<target2> ...]] +``` + +## Parameters +### MESSAGE +Additional failure message. If non is given a default message will be displayed depending on the failure condition + +### ALWAYS +will always fail early + +### ON_TARGET +targets for which the build should fail early. Valid targets are <target> from VCPKG_IS_TARGET_<target> (see vcpkg_common_definitions.cmake) + +### ON_ARCH +architecture for which the build should fail early. + +### ON_CRT_LINKAGE +CRT linkage for which the build should fail early. + +### ON_LIBRARY_LINKAGE +library linkage for which the build should fail early. + +## Examples + +* [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_fail_port_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)
diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md index 57a2bf75a..b868ea418 100644 --- a/docs/maintainers/vcpkg_find_acquire_program.md +++ b/docs/maintainers/vcpkg_find_acquire_program.md @@ -24,6 +24,7 @@ The current list of programs includes: - MESON - NASM - NINJA +- NUGET - YASM - ARIA2 (Downloader) diff --git a/docs/maintainers/vcpkg_fixup_cmake_targets.md b/docs/maintainers/vcpkg_fixup_cmake_targets.md new file mode 100644 index 000000000..5bad80656 --- /dev/null +++ b/docs/maintainers/vcpkg_fixup_cmake_targets.md @@ -0,0 +1,30 @@ +# vcpkg_fixup_cmake_targets
+
+Transforms all `/debug/share/\<port\>/\*targets-debug.cmake` files and move them to `/share/\<port\>`.
+Removes all `/debug/share/\<port\>/\*targets.cmake and /debug/share/\<port\>/\*config.cmake`.
+
+Transforms all references matching `/bin/\*.exe tools/\<port\>/\*.exe` on Windows.
+Transforms all references matching `/bin/\* to /tools/\<port\>/\*` on other platforms.
+
+Fixups *${_IMPORT_PREFIX}* in auto generated targets to be one folder deeper.
+Replaces *${CURRENT_INSTALLED_DIR}* with *${_IMPORT_PREFIX}* in config files and targets.
+
+
+## Usage
+```cmake
+vcpkg_fixup_cmake_targets(CONFIG_PATH <config_path>)
+```
+
+## Parameters:
+### CONFIG_PATH
+*.cmake files subdirectory (e.g. "lib/cmake/${PORT}" or "cmake/${PORT}).
+### TARGET_PATH
+Optional location to place fixup'd files. Unecessary if target is "share/${PORT}".
+
+## Examples:
+ - [Azure-uamqp-c](https://github.com/microsoft/vcpkg/blob/master/ports/azure-uamqp-c/portfile.cmake)
+ - [Brigand](https://github.com/microsoft/vcpkg/blob/master/ports/brigand/portfile.cmake)
+ - [cctz](https://github.com/microsoft/vcpkg/blob/master/ports/cctz/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_fixup_cmake_targets.cmake](https://github.com/microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)
diff --git a/docs/maintainers/vcpkg_from_git.md b/docs/maintainers/vcpkg_from_git.md index 6b24a558d..4b9a26c62 100644 --- a/docs/maintainers/vcpkg_from_git.md +++ b/docs/maintainers/vcpkg_from_git.md @@ -8,7 +8,6 @@ vcpkg_from_git( OUT_SOURCE_PATH <SOURCE_PATH> URL <https://android.googlesource.com/platform/external/fdlibm> REF <59f7335e4d...> - SHA512 <abcdef123...> [PATCHES <patch1.patch> <patch2.patch>...] ) ``` @@ -20,17 +19,10 @@ Specifies the out-variable that will contain the extracted location. This should be set to `SOURCE_PATH` by convention. ### URL -The url of the git repository. - -### SHA512 -The SHA512 hash that should match the archive form of the commit. - -This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile. +The url of the git repository. Must start with `https`. ### REF -A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.** - -For repositories without official releases, this can be set to the full commit id of the current latest master. +The git sha of the commit to download. ### PATCHES A list of patches to be applied to the extracted sources. @@ -38,7 +30,7 @@ A list of patches to be applied to the extracted sources. Relative paths are based on the port directory. ## Notes: -`OUT_SOURCE_PATH`, `REF`, `SHA512`, and `URL` must be specified. +`OUT_SOURCE_PATH`, `REF`, and `URL` must be specified. ## Examples: diff --git a/docs/maintainers/vcpkg_install_make.md b/docs/maintainers/vcpkg_install_make.md new file mode 100644 index 000000000..3460778cc --- /dev/null +++ b/docs/maintainers/vcpkg_install_make.md @@ -0,0 +1,24 @@ +# vcpkg_install_make + +Build and install a make project. + +## Usage: +```cmake +vcpkg_install_make(...) +``` + +## Parameters: +See [`vcpkg_build_make()`](vcpkg_build_make.md). + +## Notes: +This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.md), adding `ENABLE_INSTALL` + +## Examples + +* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake) +* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) +* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake) +* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_install_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)
diff --git a/docs/maintainers/vcpkg_install_nmake.md b/docs/maintainers/vcpkg_install_nmake.md new file mode 100644 index 000000000..3f397c195 --- /dev/null +++ b/docs/maintainers/vcpkg_install_nmake.md @@ -0,0 +1,60 @@ +# vcpkg_install_nmake + +Build and install a msvc makefile project. + +## Usage: +```cmake +vcpkg_install_nmake( + SOURCE_PATH <${SOURCE_PATH}> + [NO_DEBUG] + PROJECT_SUBPATH <${SUBPATH}> + PROJECT_NAME <${MAKEFILE_NAME}> + [PRERUN_SHELL <${SHELL_PATH}>] + [PRERUN_SHELL_DEBUG <${SHELL_PATH}>] + [PRERUN_SHELL_RELEASE <${SHELL_PATH}>] + [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] + [OPTIONS_RELEASE <-DOPTIMIZE=1>...] + [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] +``` + +## Parameters +### SOURCE_PATH +Specifies the directory containing the source files. +By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. + +### PROJECT_SUBPATH +Specifies the sub directory containing the `makefile.vc`/`makefile.mak`/`makefile.msvc` or other msvc makefile. + +### PROJECT_NAME +Specifies the name of msvc makefile name. +Default is makefile.vc + +### NO_DEBUG +This port doesn't support debug mode. + +### PRERUN_SHELL +Script that needs to be called before build + +### PRERUN_SHELL_DEBUG +Script that needs to be called before debug build + +### PRERUN_SHELL_RELEASE +Script that needs to be called before release build + +### OPTIONS +Additional options passed to generate during the generation. + +### OPTIONS_RELEASE +Additional options passed to generate during the Release generation. These are in addition to `OPTIONS`. + +### OPTIONS_DEBUG +Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`. + +## Parameters: +See [`vcpkg_build_nmake()`](vcpkg_build_nmake.md). + +## Notes: +This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL` + +## Source +[scripts/cmake/vcpkg_install_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)
diff --git a/docs/maintainers/vcpkg_prettify_command.md b/docs/maintainers/vcpkg_prettify_command.md new file mode 100644 index 000000000..1856e06b4 --- /dev/null +++ b/docs/maintainers/vcpkg_prettify_command.md @@ -0,0 +1,17 @@ +# vcpkg_prettify_command + +Turns list of command arguments into a formatted string. + +## Usage +```cmake +vcpkg_prettify_command() +``` + +## Examples + +* `scripts/cmake/vcpkg_execute_build_process.cmake` +* `scripts/cmake/vcpkg_execute_required_process.cmake` +* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake` + +## Source +[scripts/cmake/vcpkg_prettify_command.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_prettify_command.cmake)
diff --git a/docs/specifications/ports-overlay.md b/docs/specifications/ports-overlay.md new file mode 100644 index 000000000..d486cfe19 --- /dev/null +++ b/docs/specifications/ports-overlay.md @@ -0,0 +1,182 @@ +# Ports Overlay (Jun 19, 2019)
+
+
+## 1. Motivation
+
+### A. Allow users to override ports with alternate versions
+
+It's a common scenario for `vcpkg` users to keep specific versions of libraries to use in their own projects. The current recommendation for users is to fork `vcpkg`'s repository and create tags for commits containing the specific versions of the ports they want to use.
+
+This proposal adds an alternative to solve this problem. By allowing `vcpkg` users to specify additional locations in their file system containing ports for:
+
+ * older or newer versions of libraries,
+ * modified libraries, or
+ * libraries not available in `vcpkg`.
+
+These locations will be searched when resolving port names during package installation, and override ports in `<vcpkg-root>/ports`.
+
+### B. Allow users to keep unmodified upstream ports
+
+Users will be able to keep unmodified versions of the ports shipped with `vcpkg` and update them via `vcpkg update` and `vcpkg upgrade` without having to solve merge conflicts.
+
+
+## 2. Other design concerns
+
+* Allow a set of `vcpkg` commands to optionally accept additional paths to be used when searching for ports.
+* Additional paths must take precedence when resolving names of ports to install.
+* Allow users to specify multiple additional paths.
+* Provide a simple disambiguation mechanism to resolve ambiguous port names.
+* After resolving a port name, the installation process has to work the same as for ports shipped by `vcpkg`.
+* This **DOES NOT ENABLE MULTIPLE VERSIONS** of a same library to be **INSTALLED SIDE-BY-SIDE**.
+
+
+## 3. Proposed solution
+
+This document proposes allowing additional locations to search for ports during package installation that will override and complement the set of ports provided by `vcpkg` (ports under the `<vcpkg_root>/ports` directory).`
+
+A new option `--overlay-ports` will be added to the `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, `vcpkg export`, and `vcpkg depend-info` commands to specify additional paths containing ports.
+
+From a user experience perspective, a user expresses interest in adding additional lookup locations by passing the `--overlay-ports` option followed by a path to:
+
+* an individual port (directory containing a `CONTROL` file),
+ * `vcpkg install sqlite3 --overlay-ports="C:\custom-ports\sqlite3"`
+
+* a directory containing ports,
+ * `vcpkg install sqlite3 --overlay-ports=\\share\org\custom-ports`
+
+* a file listing paths to the former two.
+ > NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
+
+ * `vcpkg install sqlite3 --overlay-ports=..\port-repos.txt`
+
+ _port-repos.txt_
+
+ ```
+ .\experimental-ports\sqlite3
+ C:\custom-ports
+ \\share\team\custom-ports
+ \\share\org\custom-ports
+ ```
+ *Relative paths inside this file are resolved relatively to the file's location. In this case a `experimental-ports` directory should exist at the same level as the `port-repos.txt` file.*
+
+_NOTE: It is not the goal of this document to discuss library versioning or project dependency management solutions, which require the ability to install multiple versions of a same library side-by-side._
+
+### Multiple additional paths
+
+Users can provide multiple additional paths by repeating the `--overlay-ports` option.
+
+```
+vcpkg install sqlite3
+ --overlay-ports="..\experimental-ports\sqlite3"
+ --overlay-ports="C:\custom-ports"
+ --overlay-ports="\\share\team\custom-ports
+```
+
+### Overlaying ports
+
+Port name resolution follows the order in which additional paths are specified, with the first match being selected for installation, and falling back to `<vcpkg-root>/ports` if the port is not found in any of the additional paths.
+
+No effort is made to compare version numbers inside the `CONTROL` files, or to determine which port contains newer or older files.
+
+### Examples
+
+Given the following directory structure:
+
+ ```
+ team-ports/
+ |-- sqlite3/
+ |---- CONTROL
+ |-- rapidjson/
+ |---- CONTROL
+ |-- curl/
+ |---- CONTROL
+
+ my-ports/
+ |-- sqlite3/
+ |---- CONTROL
+ |-- rapidjson/
+ |---- CONTROL
+
+ vcpkg
+ |-- ports/
+ |---- <upstream ports>
+ |-- vcpkg.exe
+ |-- preferred-ports.txt
+ ```
+* #### Example #1:
+
+ Running:
+
+ ```
+ vcpkg/vcpkg.exe install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports
+ ```
+
+ Results in `my-ports/sqlite3` getting installed as that location appears first in the command line arguments.
+
+* #### Example #2:
+
+ A specific version of a port can be given priority by adding its path first in the list of arguments:
+
+ ```
+ vcpkg/vcpkg.exe install sqlite3 rapidjson curl
+ --overlay-ports=my-ports/rapidjson
+ --overlay-ports=vcpkg/ports/curl
+ --overlay-ports=team-ports
+ ```
+
+ Installs:
+ * `sqlite3` from `team-ports/sqlite3`
+ * `rapidjson` from `my-ports/rapidjson`
+ * `curl` from `vcpkg/ports/curl`
+
+* #### Example #3:
+
+ > NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
+
+ Given the content of `preferred-ports.txt` as:
+
+ ```
+ ./ports/curl
+ /my-ports/rapidjson
+ /team-ports
+ ```
+
+ A location can be appended or prepended to those included in `preferred-ports.txt` via the command line, like this:
+
+ ```
+ vcpkg/vcpkg.exe install sqlite3 curl --overlay-ports=my-ports --overlay-ports=vcpkg/preferred-ports.txt
+ ```
+
+ Which results in `my-ports/sqlite3` and `vcpkg/ports/curl` getting installed.
+
+
+## 4. Proposed User experience
+
+### i. User wants to preserve an older version of a port
+
+Developer Alice and her team use `vcpkg` to acquire **OpenCV** and some other packages. She has even contributed many patches to add features to the **OpenCV 3** port in `vcpkg`. But, one day, she notices that a PR to update **OpenCV** to the next major version has been merged.
+
+Alice wants to update some packages available in `vcpkg`. Unfortunately, updating her project to use the latest **OpenCV** is not immediately possible.
+
+Alice creates a private GitHub repository and checks in the set of ports that she wants to preserve. Then provides her teammates with the link to clone her private ports repository.
+
+```
+mkdir vcpkg-custom-ports
+cd vcpkg-custom-ports
+git init
+cp -r %VCPKG_ROOT%/ports/opencv .
+git add .
+git commit -m "[opencv] Add OpenCV 3 port"
+git remote add origin https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
+git push -u origin master
+```
+
+Now her team is able to use:
+
+```
+git clone https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
+vcpkg update --overlay-ports=./vcpkg-custom-ports
+vcpkg upgrade --no-dry-run --overlay-ports=./vcpkg-custom-ports
+```
+
+to upgrade their packages and preserve the old version of **OpenCV** they require.
diff --git a/docs/tool-maintainers/benchmarking.md b/docs/tool-maintainers/benchmarking.md new file mode 100644 index 000000000..e0295be50 --- /dev/null +++ b/docs/tool-maintainers/benchmarking.md @@ -0,0 +1,195 @@ +# Benchmarking + +Benchmarking new code against old code is extremely important whenever making +large changes to how something works. If you are attempting to make something +faster, and you end up slowing it down, you'll never know if you don't +benchmark! We have benchmarks in the `toolsrc/src/vcpkg-test` directory, just +like the tests -- they're treated as a special kind of test. + +## Running Benchmarks + +Unlike normal tests, benchmarks are hidden behind a special define -- `CATCH_CONFIG_ENABLE_BENCHMARKING` -- so that you never try to run benchmarks +unless you specifically want to. This is because benchmarks actually take quite +a long time! However, if you want to run benchmarks (and I recommend running +only specific benchmarks at a time), you can do so by passing the +`VCPKG_ENABLE_BENCHMARKING` option at cmake configure time. + +```sh +$ cmake -B toolsrc/out -S toolsrc -G Ninja \ + -DCMAKE_BUILD_TYPE=Release \ + -DVCPKG_BUILD_BENCHMARKING=On + +-- The C compiler identification is MSVC 19.22.27905.0 +-- The CXX compiler identification is MSVC 19.22.27905.0 +-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe +-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe -- works +-- Detecting C compiler ABI info +-- Detecting C compiler ABI info - done +-- Detecting C compile features +-- Detecting C compile features - done +-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe +-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe -- works +-- Detecting CXX compiler ABI info +-- Detecting CXX compiler ABI info - done +-- Detecting CXX compile features +-- Detecting CXX compile features - done +-- Looking for pthread.h +-- Looking for pthread.h - not found +-- Found Threads: TRUE +-- Configuring done +-- Generating done +-- Build files have been written to: C:/Users/t-nimaz/src/vcpkg/toolsrc/out + +$ cmake --build toolsrc/out + +[0/2] Re-checking globbed directories... +[80/80] Linking CXX executable vcpkg-test.exe +``` + +You can then run benchmarks easily with the following command (which run the +files benchmarks): + +```sh +$ ./toolsrc/out/vcpkg-test [!benchmark][file] +``` + +You can switch out `[file]` for a different set -- `[hash]`, for example. + +## Writing Benchmarks + +First, before anything else, I recommend reading the +[benchmarking documentation] at Catch2's repository. + +Now, after that, let's say that you wanted to benchmark, say, our ASCII +case-insensitive string compare against your new implementation. We place +benchmarks for code in the same file as their tests, so open +`vcpkg-test/strings.cpp`, and add the following at the bottom: + +```cpp +#if defined(CATCH_CONFIG_ENABLE_BENCHMARKING) +TEST_CASE ("case insensitive ascii equals: benchmark", "[strings][!benchmark]") +{ + BENCHMARK("qwertyuiop") { + return vcpkg::Strings::case_insensitive_ascii_equals("qwertyuiop", "QWERTYUIOP"); + }; +} +#endif +``` + +Remember the `;` at the end of the benchmark -- it's not required for +`TEST_CASE`s, but is for `BENCHMARK`s. + +Now, let's rebuild and run: + +```sh +$ cmake --build toolsrc/out +[0/2] Re-checking globbed directories... +[2/2] Linking CXX executable vcpkg-test.exe +$ ./toolsrc/out/vcpkg-test [strings][!benchmark] +Filters: [strings][!benchmark] + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +vcpkg-test.exe is a Catch v2.9.1 host application. +Run with -? for options + +------------------------------------------------------------------------------- +case insensitive ascii equals: benchmark +------------------------------------------------------------------------------- +C:\Users\t-nimaz\src\vcpkg\toolsrc\src\vcpkg-test\strings.cpp(36) +............................................................................... + +benchmark name samples iterations estimated + mean low mean high mean + std dev low std dev high std dev +------------------------------------------------------------------------------- +qwertyuiop 100 2088 3.9672 ms + 25 ns 24 ns 26 ns + 6 ns 5 ns 8 ns + + +=============================================================================== +test cases: 1 | 1 passed +assertions: - none - +``` + +You've now written your first benchmark! + +But wait. This seems kind of silly. Benchmarking the comparison of literal +strings is great and all, but could we make it a little more realistic? + +This is where `BENCHMARK_ADVANCED` comes in. `BENCHMARK_ADVANCED` allows one to +write a benchmark that has a little setup to it without screwing up the numbers. +Let's try it now: + +```cpp +TEST_CASE ("case insensitive ascii equals: benchmark", "[strings][!benchmark]") +{ + BENCHMARK_ADVANCED("equal strings")(Catch::Benchmark::Chronometer meter) + { + std::vector<std::string> strings; + strings.resize(meter.runs()); + std::mt19937_64 urbg; + std::uniform_int_distribution<std::uint64_t> data_generator; + + std::generate(strings.begin(), strings.end(), [&] { + std::string result; + for (std::size_t i = 0; i < 1000; ++i) + { + result += vcpkg::Strings::b32_encode(data_generator(urbg)); + } + + return result; + }); + + meter.measure( + [&](int run) { return vcpkg::Strings::case_insensitive_ascii_equals(strings[run], strings[run]); }); + }; +} +``` + +Then, run it again! + +```sh +$ cmake --build toolsrc/out +[0/2] Re-checking globbed directories... +[2/2] Linking CXX executable vcpkg-test.exe +$ toolsrc/out/vcpkg-test [strings][!benchmark] +Filters: [strings][!benchmark] + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +vcpkg-test.exe is a Catch v2.9.1 host application. +Run with -? for options + +------------------------------------------------------------------------------- +case insensitive ascii equals: benchmark +------------------------------------------------------------------------------- +C:\Users\t-nimaz\src\vcpkg\toolsrc\src\vcpkg-test\strings.cpp(36) +............................................................................... + +benchmark name samples iterations estimated + mean low mean high mean + std dev low std dev high std dev +------------------------------------------------------------------------------- +equal strings 100 2 5.4806 ms + 22.098 us 21.569 us 23.295 us + 3.842 us 2.115 us 7.41 us + + +=============================================================================== +test cases: 1 | 1 passed +assertions: - none - +``` + +And now you have a working benchmark to test the speed of the existing code, and +of new code! + +If you're writing a lot of benchmarks that follow the same sort of pattern, with +some differences in constants, look into `vcpkg-test/files.cpp`'s benchmarks -- +there are a lot of things one can do to make writing new benchmarks really easy. + +If you wish to add a benchmark for a piece of code that has not yet been tested, +please read the [testing documentation], and please write some unit tests. +The speed of your code isn't very important if it doesn't work at all! + +[benchmarking documentation]: https://github.com/catchorg/Catch2/blob/master/docs/benchmarks.md#top +[testing documentation]: ./testing.md#adding-new-test-files diff --git a/docs/tool-maintainers/layout.md b/docs/tool-maintainers/layout.md new file mode 100644 index 000000000..9779b0434 --- /dev/null +++ b/docs/tool-maintainers/layout.md @@ -0,0 +1,85 @@ +# Layout of the vcpkg source tree + +All vcpkg sources and build systems are in `toolsrc`. If you'd like to +contribute to the vcpkg tool itself, most of your time will be spent in here. + +## Build Files + +These are the files used to build and configure the project. In order to build +with CMake, the only files you should be interested in are `CMakeLists.txt`, and +`.clang-format`; in order to build with msbuild or the Visual Studio IDE, you +will be interested in `dirs.proj` or `vcpkg.sln`. However, if you add or remove +files, you will need to edit the MSBuild project files in the `vcpkg*` +directories no matter what system you use. + +### Top Level + +We have six files in this directory -- one `.clang-format` file, one +`CMakeLists.txt` file, three Visual Studio files, and `VERSION.txt`. + + - `.clang-format`: This is where we store the formatting settings of the + project. If you want to format the project, you can use the `format` target + with the CMake build system. + - `CMakeLists.txt`: This is where the CMake build system definition lives. If + you want to modify how one builds the project, or add a target, you can do + it here. + - `VERSION.txt`: This is a file which tells `vcpkg` to tell the user to + rebuild. If this version is different from the version when the user built + the binary (for example, after a `git pull` or a `vcpkg update`), then + `vcpkg` will print a message to re-bootstrap. This is updated whenever major + changes are made to the `vcpkg` tool. + - The Visual Studio files: + - `vcpkg.natvis`: NATVIS files allow one to visualize objects of user + defined type in the debugger -- this one contains the definitions for + `vcpkg`'s types. + - `dirs.proj`: This is how one builds with `msbuild` without calling into + the IDE. + - `vcpkg.sln`: The solution file is how one opens the project in the VS IDE. + +### `vcpkg`, `vcpkglib`, `vcpkgmetricsuploader`, and `vcpkgtest` + +These four contain exactly one `<name>.vcxproj` and one +`<name>.vcxproj.filters`. The `<name>.vcxproj` file contains the source files +and the `<name>.vcxproj.filters` contains information on how Visual Studio +should lay out the project's source files in the IDE's project view. + +`vcpkgtest` should not be touched. It's likely that it will be deleted soon. If +you want to test your code, use the cmake build system. + +## Source Files + +If you're modifying the project, it's likely that these are the directories that +you're going to deal with. + +### `include` + +There's one file in here -- `pch.h`. This contains most of the C++ standard +library, and acts as a [precompiled header]. You can read more at the link. + +There are three directories: + + - `catch2` -- This contains the single-header library [catch2]. We use this + library for both [testing] and [benchmarking]. + - `vcpkg` -- This contains the header files for the `vcpkg` project. All of + the interfaces for building, installing, and generally "port stuff" live + here. + - `vcpkg/base` -- This contains the interfaces for the + "vcpkg standard library" -- file handling, hashing, strings, + `Span<T>`, printing, etc. + - `vcpkg-test` -- This contains the interfaces for any common utilities + required by the tests. + +### `src` + +The source files live here. `pch.cpp` is the source file for the +[precompiled header]; `vcpkg.cpp` is where the `vcpkg` binary lives; and +`vcpkgmetricsuploader.cpp` is where the metrics uploader lives. + +The interesting files live in the `vcpkg` and `vcpkg-test` directories. In +`vcpkg`, you have the implementation for the interfaces that live in +`include/vcpkg`; and in `vcpkg-test`, you have the tests and benchmarks. + +[precompiled header]: https://en.wikipedia.org/wiki/Precompiled_header +[catch2]: https://github.com/catchorg/Catch2 +[testing]: ./testing.md +[benchmarking]: ./benchmarking.md diff --git a/docs/tool-maintainers/testing.md b/docs/tool-maintainers/testing.md new file mode 100644 index 000000000..0284a2650 --- /dev/null +++ b/docs/tool-maintainers/testing.md @@ -0,0 +1,152 @@ +# Testing + +Testing vcpkg is important whenever one makes changes to the tool itself, and +writing new tests and keeping them up to date is also very important. If one's +code is subtly broken, we'd rather find it out right away than a few weeks down +the line when someone complains! + +## Running Tests + +Before anything else, we should know whether you can actually run the tests! +All you should need is a way to build vcpkg -- anything will do! All you have to +do is follow the guide 😄 + +With `$VCPKG_DIRECTORY` being the directory where you have cloned vcpkg, create +a build directory in `$VCPKG_DIRECTORY/toolsrc` (commonly named `out`), and +`cd` into it. Make sure to clean it out if it already exists! + +```sh +$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja +$ cmake --build . +$ ./vcpkg-test # ./vcpkg-test [$SPECIFIC_TEST] for a specific set of tests +$ # i.e., ./vcpkg-test [arguments] +``` + +If you make any modifications to `vcpkg`, you'll have to do the +`cmake --build .` step again. + +## Writing Tests + +In your journey to write new tests, and to modify existing tests, reading the +[Catch2 documentation] will be very helpful! Come back after reading those 😀 + +You'll want to place your tests in one of the existing files, or, if it doesn't +belong in any of those, in a [new file](#adding-new-test-files). + +The layout of these tests is as follows: + +```cpp +// ... includes + +TEST_CASE("Name of test", "[filename without the .cpp]") { + // setup and the like + REQUIRE(some boolean expression); +} + +// etc. +``` + +You want to give these test cases good, descriptive, unique names, like +`SourceParagraph construct minimum` -- it doesn't need to be extremely clear +english, and shorthand is good, but make sure it's clear what the test is from +the name. For the latter parameter, known as "tags", you should at least put the +name of the file which the test case is in -- e.g., in `arguments.cpp`, you'd +tag all of the test cases with `[arguments]`. + +If you wish to add helper functions, make sure to place them in an anonymous +namespace -- this will ensure that they don't trample over anybody else's +space. Additionally, there are a few helper functions that live in +`<vcpkg-test/util.h>` and `src/vcpkg-test/util.cpp` -- make sure to look into +them so that you're not rewriting functionality. + +That should be all you need to know to start writing your own tests! +Remember to check out the [Catch2 documentation] +if you'd like to get more advanced with your tests, +and good luck on your testing journey! + +## Adding New Test Files + +Adding new test files should be easy and straightforward. All it requires is +creating a new source file in `toolsrc/src/vcpkg-test`. + +### Example + +Let's try writing a new test file called `example` (very creative, I know). + +First, we should create a file, `example.cpp`, in `toolsrc/src/vcpkg-test`: + +```cpp +// vcpkg-test/example.cpp +#include <vcpkg-test/catch.h> +``` + +This is the minimum file needed for tests; let's rebuild! + +```sh +$ cmake --build . +[80/80] Linking CXX executable vcpkg.exe +``` + +Okay, now let's make sure this worked; add a test case to `example.cpp`: + +```cpp +TEST_CASE("Example 1 - fail", "[example]") { + REQUIRE(false); +} +``` + +Now build the tests again, and run them: + +```sh +$ cmake --build . +[2/2] Linking CXX executable vcpkg-test.exe +$ ./vcpkg-test + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +vcpkg-test.exe is a Catch v2.9.1 host application. +Run with -? for options + +------------------------------------------------------------------------------- +Example 1 - fail +------------------------------------------------------------------------------- +$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(3) +............................................................................... + +$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(14): FAILED: + REQUIRE( false ) + +=============================================================================== +test cases: 102 | 101 passed | 1 failed +assertions: 3611 | 3610 passed | 1 failed +``` + +Hopefully, that worked! It should compile correctly, and have one failing test. +Now let's try a more complex test, after deleting the old one; + +```cpp +// add #include <vcpkg/base/strings.h> to the top of the file +namespace Strings = vcpkg::Strings; + +TEST_CASE("Example 2 - success", "[example]") { + std::string hello = "Hello"; + REQUIRE(Strings::case_insensitive_ascii_equals(hello, "hELLo")); + REQUIRE_FALSE(Strings::case_insensitive_ascii_starts_with(hello, "E")); +} +``` + +Now compile and build the tests, and this time let's only run our example tests: + +```sh +$ cmake --build . +[2/2] Linking CXX executable vcpkg-test.exe +$ ./vcpkg-test [example] +Filters: [example] +=============================================================================== +All tests passed (2 assertions in 1 test case) +``` + +Hopefully you have one test running and succeeding! If you have that, you have +succeeded at adding a new file to vcpkg's tests. Congratulations! Have fun on +the rest of your journey 🐱👤😁 + +[Catch2 documentation]: https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md#top |