update ceph source to reef 18.1.2

[ceph.git] / ceph / src / jaegertracing / opentelemetry-cpp / tools / vcpkg / docs / maintainers / maintainer-guide.md

# Maintainer Guidelines and Policies\r
\r
This document lists a set of policies that you should apply when adding or updating a port recipe.\r
It is intended to serve the role of\r
[Debian's Policy Manual](https://www.debian.org/doc/debian-policy/),\r
[Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and\r
[Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).\r
\r
## PR Structure\r
\r
### Make separate Pull Requests per port\r
\r
Whenever possible, separate changes into multiple PRs.\r
This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.\r
\r
### Avoid trivial changes in untouched files\r
\r
For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand.\r
However, if you need to modify the file for the primary purpose of the PR (updating the library),\r
then obviously beneficial changes like fixing typos are appreciated!\r
\r
### Check names against other repositories\r
\r
A good service to check many at once is [Repology](https://repology.org/).\r
If the library you are adding could be confused with another one,\r
consider renaming to make it clear.\r
\r
### Use GitHub Draft PRs\r
\r
GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge.\r
Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.\r
\r
More information about GitHub Draft PRs:\r
https://github.blog/2019-02-14-introducing-draft-pull-requests/\r
\r
## Portfiles\r
\r
### Avoid deprecated helper functions\r
\r
At this time, the following helpers are deprecated:\r
\r
1. `vcpkg_extract_source_archive()` should be replaced by [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md)\r
2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))\r
3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)\r
4. `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md)\r
\r
### Avoid excessive comments in portfiles\r
\r
Ideally, portfiles should be short, simple, and as declarative as possible.\r
Remove any boiler plate comments introduced by the `create` command before submitting a PR.\r
\r
## Features\r
\r
### Do not use features to implement alternatives\r
\r
Features must be treated as additive functionality. If port[featureA] installs and port[featureB] installs, then port[featureA,featureB] must install. Moreover, if a second port depends on [featureA] and a third port depends on [featureB], installing both the second and third ports should have their dependencies satisfied.\r
\r
Libraries in this situation must choose one of the available options as expressed in vcpkg, and users who want a different setting must use overlay ports at this time.\r
\r
Existing examples we would not accept today retained for backwards compatibility:\r
  * `libgit2`, `libzip`, `open62541` all have features for selecting a TLS or crypto backend. Note that `curl` has different crypto backend options but allows selecting between them at runtime, meaning the above tenet is maintained.\r
  * `darknet` has `opencv2`, `opencv3`, features to control which version of opencv to use for its dependencies.\r
\r
### A feature may engage preview or beta functionality\r
\r
Notwithstanding the above, if there is a preview branch or similar where the preview functionality has a high probability of not disrupting the non-preview functionality (for example, no API removals), a feature is acceptable to model this setting.\r
\r
Examples:\r
  * The Azure SDKs (of the form `azure-Xxx`) have a `public-preview` feature.\r
  * `imgui` has an `experimental-docking` feature which engages their preview docking branch which uses a merge commit attached to each of their public numbered releases.\r
\r
### Default features should enable behaviors, not APIs\r
\r
If a consumer is depending directly upon a library, they can list out any desired features easily (`library[feature1,feature2]`). However, if a consumer _does not know_ they are using a library, they cannot list out those features. If that hidden library is like `libarchive` where features are adding additional compression algorithms (and thus behaviors) to an existing generic interface, default features offer a way to ensure a reasonably functional transitive library is built even if the final consumer doesn't name it directly.\r
\r
If the feature adds additional APIs (or executables, or library binaries) and doesn't modify the behavior of existing APIs, it should be left off by default. This is because any consumer which might want to use those APIs can easily require it via their direct reference.\r
\r
If in doubt, do not mark a feature as default.\r
\r
### Do not use features to control alternatives in published interfaces\r
\r
If a consumer of a port depends on only the core functionality of that port, with high probability they must not be broken by turning on the feature. This is even more important when the alternative is not directly controlled by the consumer, but by compiler settings like `/std:c++17` / `-std=c++17`.\r
\r
Existing examples we would not accept today retained for backwards compatibility:\r
  * `redis-plus-plus[cxx17]` controls a polyfill but does not bake the setting into the installed tree.\r
  * `ace[wchar]` changes all APIs to accept `const wchar_t*` rather than `const char*`.\r
\r
### A feature may replace polyfills with aliases provided that replacement is baked into the installed tree\r
\r
Notwithstanding the above, ports may remove polyfills with a feature, as long as:\r
  1. Turning on the feature changes the polyfills to aliases of the polyfilled entity\r
  2. The state of the polyfill is baked into the installed headers, such that ABI mismatch "impossible" runtime errors are unlikely\r
  3. It is possible for a consumer of the port to write code which works in both modes, for example by using a typedef which is either polyfilled or not\r
\r
Example:\r
  * `abseil[cxx17]` changes `absl::string_view` to a replacement or `std::string_view`; the patch\r
https://github.com/microsoft/vcpkg/blob/981e65ce0ac1f6c86e5a5ded7824db8780173c76/ports/abseil/fix-cxx-standard.patch implements the baking requirement\r
\r
### Recommended solutions\r
\r
If it's critical to expose the underlying alternatives, we recommend providing messages at build time to instruct the user on how to copy the port into a private overlay:\r
```cmake\r
set(USING_DOG 0)\r
message(STATUS "This version of LibContosoFrobnicate uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")\r
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")\r
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")\r
```\r
\r
## Build Techniques\r
\r
### Do not use vendored dependencies\r
\r
Do not use embedded copies of libraries.\r
All dependencies should be split out and packaged separately so they can be updated and maintained.\r
\r
### Prefer using CMake\r
\r
When multiple buildsystems are available, prefer using CMake.\r
Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.\r
\r
Examples: [abseil](../../ports/abseil/portfile.cmake)\r
\r
### Choose either static or shared binaries\r
\r
By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`,\r
however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:\r
\r
```cmake\r
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)\r
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)\r
\r
vcpkg_configure_cmake(\r
    SOURCE_PATH ${SOURCE_PATH}\r
    PREFER_NINJA\r
    OPTIONS\r
        -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}\r
        -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}\r
)\r
```\r
\r
### When defining features, explicitly control dependencies\r
\r
When defining a feature that captures an optional dependency,\r
ensure that the dependency will not be used accidentally when the feature is not explicitly enabled.\r
\r
```cmake\r
if ("zlib" IN_LIST FEATURES)\r
  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)\r
else()\r
  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)\r
endif()\r
\r
vcpkg_configure_cmake(\r
  SOURCE_PATH ${SOURCE_PATH}\r
  PREFER_NINJA\r
  OPTIONS\r
    -CMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}\r
)\r
```\r
\r
The snippet below using `vcpkg_check_features()` is equivalent,  [see the documentation](vcpkg_check_features.md).\r
\r
```cmake\r
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS\r
  INVERTED_FEATURES\r
    "zlib"    CMAKE_DISABLE_FIND_PACKAGE_ZLIB\r
)\r
\r
vcpkg_configure_cmake(\r
    SOURCE_PATH ${SOURCE_PATH}\r
    PREFER_NINJA\r
    OPTIONS\r
      ${FEATURE_OPTIONS}\r
)\r
```\r
\r
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.\r
\r
### Place conflicting libs in a `manual-link` directory\r
\r
A lib is considered conflicting if it does any of the following:\r
+ Define `main`\r
+ Define malloc\r
+ Define symbols that are also declared in other libraries\r
\r
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`.\r
\r
## Manifests and CONTROL files\r
\r
When adding a new port, use the new manifest syntax for defining a port;\r
you may also change over to manifests when modifying an existing port.\r
You may do so easily by running the `vcpkg format-manifest` command, which will convert existing CONTROL\r
files into manifest files. Do not convert CONTROL files that have not been modified.\r
\r
## Versioning\r
\r
### Follow common conventions for the `"version"` field\r
\r
See our [versioning documentation](../users/versioning.md#version-schemes) for a full explanation of our conventions.\r
\r
### Update the `"port-version"` field in the manifest file of any modified ports\r
\r
Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes.\r
\r
Our convention is to use the `"port-version"` field for changes to the port that don't change the upstream version, and to reset the `"port-version"` back to zero when an update to the upstream version is made.\r
\r
For Example:\r
\r
- Zlib's package version is currently `1.2.1`, with no explicit `"port-version"` (equivalent to a `"port-version"` of `0`).\r
- You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile.\r
- You should update the `"port-version"` field in the manifest file to `1`.\r
\r
See our [manifest files document](manifest-files.md#port-version) for a full explanation of our conventions.\r
\r
### Update the version files in `versions/` of any modified ports\r
\r
Vcpkg uses a set of metadata files to power its versioning feature.\r
These files are located in the following locations:\r
* `${VCPKG_ROOT}/versions/baseline.json`, (this file is common to all ports) and\r
* `${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json` (one per port).\r
\r
For example, for `zlib` the relevant files are:\r
* `${VCPKG_ROOT}/versions/baseline.json`\r
* `${VCPKG_ROOT}/versions/z-/zlib.json`\r
\r
We expect that each time you update a port, you also update its version files.\r
\r
**The recommended method to update these files is to run the `x-add-version` command, e.g.:**\r
\r
```\r
vcpkg x-add-version zlib\r
```\r
\r
If you're updating multiple ports at the same time, instead you can run:\r
\r
```\r
vcpkg x-add-version --all\r
```\r
\r
To update the files for all modified ports at once.\r
\r
_NOTE: These commands require you to have committed your changes to the ports before running them. The reason is that the Git SHA of the port directory is required in these version files. But don't worry, the `x-add-version` command will warn you if you have local changes that haven't been committed._\r
\r
See our [versioning specification](../specifications/versioning.md) and [registries specification](../specifications/registries-2.md) to learn how vcpkg interacts with these files.\r
\r
## Patching\r
\r
### Prefer options over patching\r
\r
It is preferable to set options in a call to `vcpkg_configure_xyz()` over patching the settings directly.\r
\r
Common options that allow avoiding patching:\r
1. [MSBUILD] `<PropertyGroup>` settings inside the project file can be overridden via `/p:` parameters\r
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)\r
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)\r
\r
### Prefer patching over overriding `VCPKG_<VARIABLE>` values\r
\r
Some variables prefixed with `VCPKG_<VARIABLE>` have an equivalent `CMAKE_<VARIABLE>`.\r
However, not all of them are passed to the internal package build [(see implementation: Windows toolchain)](../../scripts/toolchains/windows.cmake).\r
\r
Consider the following example:\r
\r
```cmake\r
set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")\r
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")\r
```\r
\r
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.\r
\r
Because of this, it is preferable to patch the buildsystem directly when setting `CMAKE_<LANG>_FLAGS`.\r
\r
### Minimize patches\r
\r
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.\r
\r
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.\r
\r
### Do not implement features in patches\r
\r
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).\r
\r
## Do not build tests/docs/examples by default\r
\r
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.\r
\r
Optionally, you can add a `test` feature which enables building the tests, however this should not be in the `Default-Features` list.\r
\r
## Enable existing users of the library to switch to vcpkg\r
\r
### Do not add `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`\r
\r
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)`.\r
\r
### Do not rename binaries outside the names given by upstream\r
\r
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.\r
\r
Important caveat:\r
- 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.\r
\r
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.\r
\r
Finally, DLL files on Windows should never be renamed post-build because it breaks the generated LIBs.\r
\r
## Code format\r
\r
### Vcpkg internal code\r
\r
We require the C++ code inside vcpkg to follow the clang-format, if you change them. Please perform the following steps after modification:\r
\r
- Use Visual Studio:\r
1. Configure your [clang-format tools](https://devblogs.microsoft.com/cppblog/clangformat-support-in-visual-studio-2017-15-7-preview-1/).\r
2. Open the modified file.\r
3. Use shortcut keys Ctrl+K, Ctrl+D to format the current file.\r
\r
- Use tools:\r
1. Install [llvm clang-format](https://releases.llvm.org/download.html#10.0.0)\r
2. Run command:\r
```cmd\r
> LLVM_PATH/bin/clang-format.exe -style=file -i changed_file.cpp\r
```\r
\r
### Manifests\r
\r
We require that the manifest file be formatted. Use the following command to format all manifest files:\r
\r
```cmd\r
> vcpkg format-manifest --all\r
```\r
\r
## Useful implementation notes\r
\r
### Portfiles are run in Script Mode\r
\r
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.\r
\r
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`).\r
\r
Portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:\r
\r
```no-highlight\r
+----------------------------+       +------------------------------------+\r
| CMake.exe                  |       | CMake.exe                          |\r
+----------------------------+       +------------------------------------+\r
| Triplet file               | ====> | Toolchain file                     |\r
| (x64-windows.cmake)        |       | (scripts/buildsystems/vcpkg.cmake) |\r
+----------------------------+       +------------------------------------+\r
| Portfile                   | ====> | CMakeLists.txt                     |\r
| (ports/foo/portfile.cmake) |       | (buildtrees/../CMakeLists.txt)     |\r
+----------------------------+       +------------------------------------+\r
```\r
\r
To determine the host in a portfile, the standard CMake variables are fine (`CMAKE_HOST_WIN32`).\r
\r
To determine the target in a portfile, the vcpkg triplet variables should be used (`VCPKG_CMAKE_SYSTEM_NAME`).\r
\r
See also our [triplet documentation](../users/triplets.md) for a full enumeration of possible settings.\r