diff options
| author | Robert Schumacher <roschuma@microsoft.com> | 2019-11-22 09:47:40 -0800 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2019-11-22 09:47:40 -0800 |
| commit | 45f4b820e5743b89bca3508ba2028cdd5d8bbd17 (patch) | |
| tree | f874a8c4a7392309bdbb86447288597ec0a4a281 /docs/maintainers | |
| parent | 62d67d3bf8eeff1afa8009041fd08b8822676b7b (diff) | |
| parent | 8831e8f25f1ff6546ee4a5291b91d599421637b3 (diff) | |
| download | vcpkg-45f4b820e5743b89bca3508ba2028cdd5d8bbd17.tar.gz vcpkg-45f4b820e5743b89bca3508ba2028cdd5d8bbd17.zip | |
Merge branch 'master' into vcpkg_nuget
Diffstat (limited to 'docs/maintainers')
20 files changed, 847 insertions, 22 deletions
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)
|