From 919d894e778c287cb597be248a81c67089e26409 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Mon, 11 Nov 2024 11:07:19 +0100 Subject: [PATCH] [docs] Drop Conan 1.x from CCI documentation (#25875) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Drop Conan 1.x from docs Signed-off-by: Uilian Ries * Revert .c3i folder deletion Signed-off-by: Uilian Ries * Add info about CLA Signed-off-by: Uilian Ries * Restore community resources Signed-off-by: Uilian Ries * Fix markdown reference leftover Signed-off-by: Uilian Ries * Fix first time contribution title Signed-off-by: Uilian Ries * Fix 3 steps Signed-off-by: Uilian Ries * how to write a good recipe Signed-off-by: Uilian Ries * Linter and hooks displayed in Checks Signed-off-by: Uilian Ries * Re-add build() and package() Signed-off-by: Uilian Ries * May accept build scripts based on effort Signed-off-by: Uilian Ries * Clarify patch on source folder Signed-off-by: Uilian Ries * Rephrase adding old versions Signed-off-by: Uilian Ries * Only required patch fields should be included Signed-off-by: Uilian Ries * Remove community tools Signed-off-by: Uilian Ries * Restore supported platforms Signed-off-by: Uilian Ries * How to consume a graph of shared libraries Signed-off-by: Uilian Ries * Fix typo in build_and_package.md Co-authored-by: Abril Rincón Blanco * Fix typo in build_and_package.md Co-authored-by: Abril Rincón Blanco * Grammar fix in conanfile_attributes.md Co-authored-by: Abril Rincón Blanco * Grammar fix in conanfile_attributes.md Co-authored-by: Abril Rincón Blanco * Point correct link to version ranges Co-authored-by: Abril Rincón Blanco * Add note about waiting fresh bump version Co-authored-by: Abril Rincón Blanco --------- Signed-off-by: Uilian Ries Co-authored-by: Abril Rincón Blanco --- README.md | 4 +- docs/README.md | 4 - docs/adding_packages/README.md | 53 +- docs/adding_packages/build_and_package.md | 75 +-- docs/adding_packages/conandata_yml_format.md | 6 +- docs/adding_packages/conanfile_attributes.md | 41 +- docs/adding_packages/dependencies.md | 151 +----- docs/adding_packages/folders_and_files.md | 107 +--- docs/adding_packages/sources_and_patches.md | 62 +-- docs/adding_packages/test_packages.md | 107 ---- docs/bump_version.md | 3 +- docs/changelog.md | 5 + docs/community_resources.md | 9 +- docs/consuming_recipes.md | 20 +- docs/developing_recipes_locally.md | 230 +------- docs/error_knowledge_base.md | 499 ------------------ docs/faqs.md | 145 +---- docs/labels.md | 96 ---- docs/linters.md | 34 -- docs/review_process.md | 106 +--- .../supported_platforms_and_configurations.md | 67 ++- docs/v2_linter.md | 71 --- docs/v2_roadmap.md | 150 ------ 23 files changed, 178 insertions(+), 1867 deletions(-) delete mode 100644 docs/adding_packages/test_packages.md delete mode 100644 docs/error_knowledge_base.md delete mode 100644 docs/labels.md delete mode 100644 docs/linters.md delete mode 100644 docs/v2_linter.md delete mode 100644 docs/v2_roadmap.md diff --git a/README.md b/README.md index 29592345bf8e1..54cfaefe6c2cc 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Any maintenance, outage or important event related to the CI will be informed th ### Configure the Conan Center remote -> [!IMPORTANT] +> [!IMPORTANT] > The Conan Center remote URL changed for **Conan 2** on November 2024 - the new URL is the default on new installations of Conan since version 2.9.2. > > New recipe updates are only published to this remote and are only guaranteed to be compatible with recent versions of Conan 2. @@ -61,10 +61,8 @@ This is a list of shortcuts to some interesting topics: * :rocket: If you want to learn how to **contribute new recipes**, please read [docs/adding_packages/](docs/adding_packages/README.md). * :speech_balloon: **FAQ**: most common questions are listed in [docs/faqs.md](docs/faqs.md). -* :warning: The conan-center **hook errors** reported by CCI Bot can be found in the [docs/error_knowledge_base.md](docs/error_knowledge_base.md). * :hammer_and_wrench: The internal changes related to infrastructure can be checked in [docs/changelog.md](docs/changelog.md). * :world_map: There are various community lead initiatives which are outlined in [docs/community_resources.md](docs/community_resources.md). -* :magic_wand: To start preparing your recipes for **Conan 2.0**, please check [docs/v2_migration.md](docs/v2_migration.md). ### Reporting Issues diff --git a/docs/README.md b/docs/README.md index 566801917e5f3..3305d7c06b030 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,11 +14,7 @@ When pull requests are merged, the CI will upload the generated packages to the + [Developing Recipes Locally](developing_recipes_locally.md) + [Adding Packages to ConanCenter](adding_packages/README.md) :point_left: Best place to learn how to contribute + [Bumping versions to existing packages](bump_version.md) - + [Errors from the conan-center hook (KB-Hxxx)](error_knowledge_base.md) + [Review Process](review_process.md) - + [Labels](labels.md) - + [Supported platforms and configurations](supported_platforms_and_configurations.md) + [Consuming Recipes](consuming_recipes.md) :information_source: Learn how to limit the impact of recipe changes + [Community Resources](community_resources.md) - + [Preparing recipes for Conan 2.0](v2_migration.md) + [FAQs](faqs.md) diff --git a/docs/adding_packages/README.md b/docs/adding_packages/README.md index 409f61c38fc0e..a4d6c0e3a5b4f 100644 --- a/docs/adding_packages/README.md +++ b/docs/adding_packages/README.md @@ -4,44 +4,22 @@ ConanCenterIndex aims to provide the best quality packages of any open source pr Any C/C++ project can be made available by contributing a "recipe". Getting started is easy. Try building an existing package with our [developing recipes](../developing_recipes_locally.md) -tutorial. To deepen you understanding, start with the [How to provide a good recipe](#how-to-provide-a-good-recipe) section. +tutorial. To deepen you understanding, start with the [How to write a good recipe](#how-to-provide-a-good-recipe) section. You can follow the three steps (:one: :two: :three:) described below! :tada: ## Contents - - * [:one: Request access](#one-request-access) - * [Inactivity and user removal](#inactivity-and-user-removal) + * [:one: First time contributors](#one-first-time-contributors) * [:two: Creating a package](#two-creating-a-package) - * [How to provide a good recipe](#how-to-provide-a-good-recipe) + * [How to write a good recipe](#how-to-provide-a-good-recipe) * [:three: Submitting a Package](#three-submitting-a-package) * [The Build Service](#the-build-service) -## :one: Request access - -The first step to add packages to ConanCenter is requesting access. To enroll in ConanCenterIndex repository, please write a comment -requesting access in this GitHub [issue #4](https://github.com/conan-io/conan-center-index/issues/4). Feel free to introduce yourself and -your motivation to join ConanCenter community. - -This process helps ConanCenter against spam and malicious code. The process is not fully automated on purpose and the requests are -generally approved on a weekly basis. Feel free to continue to step :two: while waiting for approval. - -> **Note** The requests are reviewed manually, checking the GitHub profile activity of the requester to avoid any misuse of the service. -> All interactions are subject to the expectations of the [code of conduct](../code_of_conduct.md). Any misuse or inappropriate behavior -> are subject to the same principals. +## :one: First time contributors When submitting a pull request for the first time, you will be prompted to sign the [CLA](https://cla-assistant.io/conan-io/conan-center-index) for your code contributions. You can view your signed CLA's by going to and signing in. -## Inactivity and user removal - -For security reasons related to the CI, when a user no longer contributes for a long period, it will be considered inactive and removed from the authorized user's list. -For now, it's configured for **4 months**, and it's computed based on the latest commit, not comments or opened issues. -After that time, the CI bot will ask to remove the user name from the authorized users' list through the access request PR, which occurs a few times every week. - -When you are interested in contributing again, simply ask again to be included in the [issue #4](https://github.com/conan-io/conan-center-index/issues/4). -The process will be precisely like for newcomers. - ## :two: Creating a package Once you've successfully built an existing recipe following [developing recipes](../developing_recipes_locally.md) tutorial. @@ -66,14 +44,7 @@ In ConanCenter, our belief is recipes should always match upstream, in other wor * Options should [follow these recommendations](conanfile_attributes.md#options) as well as match the default value used by the upstream project. * [Package information](build_and_package.md), libraries, components should match as well. This includes exposing supported build system names. -Where dependencies are involved, there's no shortcuts, inspect the upstream's build scripts for how they are usually consumed. Pick the Conan -generator that matches. The most common example is CMake's `find_package` that can be satisfied by Conan's -[`CMakeDeps`](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmakedeps.html) generator. There are a few -things to be cautious about, many projects like to "vendor" other projects within them. This can be files checked into the repository or -downloaded during the build process. These should be removed, see the [Dependencies section](dependencies.md#handling-internal-dependencies) -for more information. - -### How to provide a good recipe +### How to write a good recipe Take a look at existing [recipes](https://github.com/conan-io/conan-center-index/tree/master/recipes) available in ConanCenterIndex which can be used as good examples, you can use them as the base for your recipe. The GitHub search is very good for matching code snippets, you can see if, @@ -95,7 +66,6 @@ The documents in this folder are written to explain each folder, file, method, a 4. [Dependencies](dependencies.md) 5. [Build and Package](build_and_package.md) 1. [Revisit Patches](sources_and_patches.md#policy-about-patching) -6. [Test Package](test_packages.md) The one place you are certain to find a lot of information is , this has the documentation for everything in Conan. There are helpful tutorials for cross-build, detailed explication for profiles and settings and much much more! @@ -110,8 +80,6 @@ The specific steps to submitting changes are: * Build and test the new recipe in several combinations. Check [developing recipes](../developing_recipes_locally.md) for tips. * [Commit and push to your fork repository](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) then [submit a pull request](https://github.com/conan-io/conan-center-index/compare). -* Our automated [build service](#the-build-service) will build 100+ different configurations, and provide messages that indicate if there - were any issues found during the pull request on GitHub. When the pull request is [reviewed and merged](../review_process.md), those packages are published to [JFrog's ConanCenter](https://conan.io/center/) and are made available for everyone. @@ -120,14 +88,9 @@ and are made available for everyone. The **build service** associated to this repository will generate binary packages automatically for the most common platforms and compilers. See [the Supported Platforms and Configurations page](../supported_platforms_and_configurations.md) for a list of generated configurations. -For a C++ library, the system is currently generating more than 100 binary packages. +For a C++ library, the system is currently generating more than 30 binary packages. > **Note**: This not a testing service, it is a binary building service for **released** packages. Unit tests shouldn't be built nor run in recipes by default, see the [FAQs](../faqs.md#why-conancenter-does-not-build-and-execute-tests-in-recipes) for more. Before submitting a pull request, please ensure that it works locally for some configurations. -* The CI bot will start a new build only [after the author is approved](#one-request-access). Your PR may be reviewed in the mean time, but is not guaranteed. -* The CI system will also report errors and build logs by creating a comment in the pull-request, the message will include links to the logs for inspecting. -* The Actions are used to lint and ensure the latest conventions are being used. You'll see comments from bots letting you know. - -Packages generated and uploaded by this build service do not include any _user_ or _channel_ (we generally recommend using `@user/channel` for private package -repositories as an easy way to distinguish them from public ones). Once the packages are uploaded, you will be able to install them using the reference as -`name/version` so example `conan install fmt/9.1.0@` for 1.x client or `conan install --requires=fmt/9.1.0` for 2.x clients. +- The CI system will report the build logs in the Checks tab, in the pull-request. +- Linter and Hooks are automatically displayed in the Checks tab as well. diff --git a/docs/adding_packages/build_and_package.md b/docs/adding_packages/build_and_package.md index a64769f6e6b52..0235be181c3e4 100644 --- a/docs/adding_packages/build_and_package.md +++ b/docs/adding_packages/build_and_package.md @@ -17,61 +17,15 @@ Both methods often use build helpers to build binaries and install them into the ## Build Method -* `build()` method should focus on build only, not installation. During the build, nothing should be written in `package` folder. Installation step should only occur in `package()` method. - -* The build itself should only rely on local files. Nothing should be downloaded from the internet during this step. If external files are required, they should come from `requirements` or `build_requirements` in addition to source files downloaded in `source()` or coming from the recipe itself through `export()` or `export_sources()`. - -* Except for CMake, a working build toolchain (compiler, linker, archiver, etc.), and a "native generator" (`make` on *nix platforms, `mingw32-make` for MinGW, `MSBuild`/`NMake` for Visual Studio), the recipe should not assume that any other build tool is installed on the user-build machine (like Meson, autotools, or pkg-config). On Windows, the recipe should not assume that a shell is available (like MSYS2). Therefore, if the build method requires additional tools, they should be added to `build_requirements()`. - Tools explicitly marked as available by users through conf like `tools.gnu:make_program`, `tools.gnu:pkg_config`, `tools.microsoft.bash:path`, `tools.microsoft.bash:subsystem` should be taken into account to conditionally inject a build requirement (these conf should have precedence over build requirement equivalent hardcoded in the recipe). - -* It is forbidden to run other conan client commands during build. In other words, if upstream build files call conan under the hood (through `cmake-conan` for example or any other logic), this logic must be removed. - -* Settings from profile should be honored (`build_type`, `compiler.libcxx`, `compiler.cppstd`, `compiler.runtime` etc). - -* Compiler paths from host profile should be honored and properly propagated to underlying build system during the build: - - | compiler type | conf / env var | - |---------------|----------------| - | C compiler | `c` key of `tools.build:compiler_executables`, otherwise `CC` environment variable | - | C++ compiler | `cpp` key of `tools.build:compiler_executables`, otherwise `CXX` environment variable | - | ASM compiler | `asm` key of `tools.build:compiler_executables`, otherwise `CCAS` environment variable | - | CUDA compiler | `cuda` key of `tools.build:compiler_executables` | - | Fortran compiler | `fortran` key of `tools.build:compiler_executables`, otherwise `FC` environment variable | - | Objective-C compiler | `objc` key of `tools.build:compiler_executables` | - | Objective-C++ compiler | `objcpp` key of `tools.build:compiler_executables` | - | Resource files compiler | `rc` key of `tools.build:compiler_executables`, otherwise `RC` environment variable | - | Archiver | `AR` environment variable | - | Linker | `LD` environment variable | - - They should be curated on the fly if underlying build system expects a specific format (no spaces in path, forward slash instead of back slash, etc). - -* These compiler and linker conf from host profile should be honored and propagated to underlying build system during the build: - * `tools.build:cflags` - * `tools.build:cxxflags` - * `tools.build:defines` - * `tools.build:sharedlinklags` - * `tools.build:exelinkflags` - * `tools.apple:enable_bitcode` (only if host OS is `iOS`/`watchOS`/`tvOS`) - -* Multithread build (if supported by underlying build system): - * if some steps are sensitive to race conditions, monothread should be enforced. - * otherwise multithreaded build should be enabled with a number of cores controlled by `tools.build:jobs` conf from host profile if it is set, otherwise to all cores of build machine. +For the `build()` method, the general scope used to build artifacts. Please, read +the official reference to the [build()](https://docs.conan.io/2/reference/conanfile/methods/build.html) method and the +[Build packages: the build() method](https://docs.conan.io/2/tutorial/creating_packages/build_packages.html). ## Package Method -* CMake config files must be removed. They will be generated for consumers by `CMakeDeps` generator (or legacy `cmake_find_package`/`cmake_find_package_multi` generators). - -* pkg-config files must be removed. They will be generated for consumers by `PkgConfigDeps` generator (or legacy `pkg_config` generator). - -* On *nix systems, executables and shared libraries should have empty `RPATH`/`RUNPATH`/`LC_RPATH`. Though, a relative path pointing inside package itself is allowed. - -* On Apple OS family: - * shared libs: name field of `LC_ID_DYLIB` load command must be `@rpath/`. - * shared libs & executables: name field of each `LC_LOAD_DYLIB` load command should be `@rpath/` (except those refering to system libs or frameworks). - -* Installed files must not contain absolute paths specific to build machine. Relative paths to other packages is also forbidden since relative paths of dependencies during build may not be the same for consumers. Hardcoded relative paths pointing to a location in the package itself are allowed. - -* Static and shared flavors of the same library must not be packaged together. +The `package()` method is used to copy the artifacts to the `package_folder`. Please, read the official reference to the +[package()](https://docs.conan.io/2/reference/conanfile/methods/package.html) method and the +[Package files: the package() method](https://docs.conan.io/2/tutorial/creating_packages/package_method.html). ## Build System Examples @@ -82,31 +36,28 @@ General patterns about how they can be used for OSS in ConanCenterIndex can be f ### Header Only If you are looking for header-only projects, you can take a look on [header-only template](../package_templates/header_only). -Also, Conan Docs have a section about [how to package header-only libraries](https://docs.conan.io/1/howtos/header_only.html). +Also, Conan Docs have a section about [how to package header-only libraries](https://docs.conan.io/2/tutorial/creating_packages/other_types_of_packages/header_only_packages.html). ### CMake For C/C++ projects which use CMake for building, you can take a look on [cmake package template](../package_templates/cmake_package). -Another common use case for CMake based projects, both header only and compiled, is _modeling components_ to match the `find_package` and export the correct targets from Conan's generators. A basic examples of this is [cpu_features](https://github.com/conan-io/conan-center-index/blob/master/recipes/cpu_features/all/conanfile.py), a moderate/intermediate example is [cpprestsdk](https://github.com/conan-io/conan-center-index/blob/master/recipes/cpprestsdk/all/conanfile.py), and a very complex example is [OpenCV](https://github.com/conan-io/conan-center-index/blob/master/recipes/opencv/4.x/conanfile.py). - ### Autotools There is an [autotools package template](../package_templates/autotools_package/) amiable to start from. -However, if you need to use autotools for building, you can take a look on [libalsa](https://github.com/conan-io/conan-center-index/blob/master/recipes/libalsa/all/conanfile.py), [kmod](https://github.com/conan-io/conan-center-index/blob/master/recipes/kmod/all/conanfile.py), [libcap](https://github.com/conan-io/conan-center-index/blob/master/recipes/libcap/all/conanfile.py). - -Many projects offer [**pkg-config**'s](https://www.freedesktop.org/wiki/Software/pkg-config/) `*.pc` files which need to be modeled using components. A prime example of this is [Wayland](https://github.com/conan-io/conan-center-index/blob/master/recipes/wayland/all/conanfile.py). - ### No Upstream Build Scripts -For cases where a project only offers source files, but not a build script, you can add CMake support, but first, contact the upstream and open a PR offering building support. If it's rejected because the author doesn't want any kind of build script, or the project is abandoned, CCI can accept your build script. Take a look at [Bzip2](https://github.com/conan-io/conan-center-index/blob/master/recipes/bzip2/all/CMakeLists.txt) and [DirectShowBaseClasses](https://github.com/conan-io/conan-center-index/blob/master/recipes/directshowbaseclasses/all/CMakeLists.txt) as examples. +For cases where a project only offers source files but does not provide a build script, you can add CMake support. +However, it is essential to first contact the upstream maintainers and open a pull request (PR) offering building support. +If your PR is rejected because the author does not want any kind of build script, or if the project is abandoned, Conan Center Index (CCI) will consider accepting your build script based on the effort required to maintain it, as we aim to avoid adding scripts that may require significant ongoing maintenance. +Take a look at [Bzip2](https://github.com/conan-io/conan-center-index/blob/master/recipes/bzip2/all/CMakeLists.txt) as example. ### System Packages > **Note**: For exceptional cases where only system packages can be used and a regular Conan package may result in an incompatible and fragile package, a separated system package may be created. See the [FAQs](../faqs.md#can-i-install-packages-from-the-system-package-manager) for more. -The [SystemPackageTool](https://docs.conan.io/1/reference/conanfile/methods.html#systempackagetool) can easily manage a system package manager (e.g. apt, +The [package_manager](https://docs.conan.io/2/reference/tools/system/package_manager.html#conan-tools-system-package-manager) can easily manage a system package manager (e.g. apt, pacman, brew, choco) and install packages which are missing on Conan Center but available for most distributions. It is key to correctly fill in the `cpp_info` for the consumers of a system package to have access to whatever was installed. -As example there is [xorg](https://github.com/conan-io/conan-center-index/blob/master/recipes/xorg/all/conanfile.py). Also, it will require an exception rule for [conan-center hook](https://github.com/conan-io/hooks#conan-center), a [pull request](https://github.com/conan-io/hooks/pulls) should be open to allow it over the KB-H032. +As example there is [xorg](https://github.com/conan-io/conan-center-index/blob/master/recipes/xorg/all/conanfile.py). \ No newline at end of file diff --git a/docs/adding_packages/conandata_yml_format.md b/docs/adding_packages/conandata_yml_format.md index 142637ae3a99e..943af159a6485 100644 --- a/docs/adding_packages/conandata_yml_format.md +++ b/docs/adding_packages/conandata_yml_format.md @@ -1,6 +1,6 @@ # conandata.yml -[conandata.yml](https://docs.conan.io/1/reference/config_files/conandata.yml.html) is a [YAML](https://yaml.org/) +[conandata.yml](https://docs.conan.io/2/tutorial/creating_packages/handle_sources_in_packages.html#using-the-conandata-yml-file) is a [YAML](https://yaml.org/) file to provide declarative data for the recipe (which is imperative). This is a built-in Conan feature (available since 1.22.0) without a fixed structure, but ConanCenter has a specific format to ensure quality of recipes. @@ -113,7 +113,7 @@ sources: sha256: "f5d48c4b0d558c5d71e8bf6fcdf135b0943210c1ff91f8191dfc447419a6b12e" ``` -This approach requires a special code within [build](https://docs.conan.io/1/reference/conanfile/methods.html#build) method to handle. +This approach requires a special code within [build](https://docs.conan.io/2/reference/conanfile/methods/build.html) method to handle. ### Sources fields @@ -172,7 +172,7 @@ An example of a full patch description could be: `port to Android: update config #### patch_type -_Required_ +_Recommended_ The `patch_type` field specifies the type of the patch. In ConanCenterIndex we currently accept only several kind of patches: diff --git a/docs/adding_packages/conanfile_attributes.md b/docs/adding_packages/conanfile_attributes.md index 2f231bde0079f..f4b962c9c85e1 100644 --- a/docs/adding_packages/conanfile_attributes.md +++ b/docs/adding_packages/conanfile_attributes.md @@ -20,11 +20,11 @@ or are known by ConanCenter's build service and have special meaning. ## Attributes -These are a [key feature](https://docs.conan.io/1/reference/conanfile/attributes.html) which allow the Conan client to understand, +These are a [key feature](https://docs.conan.io/2/reference/conanfile/attributes.html) which allows the Conan client to understand, identify, and expose recipes and which project they expose. In ConanCenter, there are a few conventions that need to be respected to ensure recipes can be discovered there `conan search` command -of through the web UI. Many of which are enforces with the [hooks](../error_knowledge_base.md). +of through the web UI. ### Name @@ -142,61 +142,40 @@ Having the same naming conventions for the options helps consumers. It allows us ### Predefined Options and Known Defaults -ConanCenter supports many combinations, these are outline in the [supported configurations](../supported_platforms_and_configurations.md) document for each platform. -By default recipes should use `shared=False` with `fPIC=True`. If supported, `header_only=False` is the default. +By default recipes should use `*/*:shared=False` with `*/*:fPIC=True`. If supported, `&:header_only=False` is the default. Usage of each option should follow the rules: * `shared` (with values `True` or `False`). The CI inspects the recipe looking for this option. The **default should be `shared=False`** and will generate all the configurations with values `shared=True` and `shared=False`. - > **Note**: The CI applies `shared=True` only to the package being built, while every other requirement will `shared=False`. To consume everything as a shared library you will set `--build=always` and/or `-o *:shared=True`) - > It's important to keep this in mind when trying to consume shared packages from ConanCenter - > as their requirements were linked inside the shared library. See [FAQs](../faqs.md#how-to-consume-a-graph-of-shared-libraries) for more information. - * `fPIC` (with values `True` or `False`). The **default should be `fPIC=True`** and will generate all the configurations with values `fPIC=True` and `fPIC=False`. - This option does not make sense on all the support configurations so it should be removed. + This option does not make sense on all the support configurations, so using `implements` is recommended: ```python - def config_options(self): - if self.settings.os == "Windows": - del self.options.fPIC - - def configure(self): - if self.options.shared: - self.options.rm_safe("fPIC") + implements = ["auto_shared_fpic"] ``` * `header_only` (with values `True` or `False`). The **default should be `header_only=False`**. If the CI detects this option, it will generate all the configurations for the value `header_only=False` and add one more configuration with `header_only=True`. **Only one package** will be generated for `header_only=True`, so it is crucial that the package is actually a _header only_ library, with header files only (no libraries or executables inside). - Recipes with such option should include the following in their `package_id` method + Recipes with such options should include the following in their `implements` attribute: ```python - def package_id(self): - if self.options.header_only: - self.info.clear() + implements = ["auto_header_only"] ``` - ensuring that, when the option is active, the recipe ignores all the settings and only one package ID is generated. - ### Options to Avoid * `build_testing` should not be added, nor any other related unit test option. Options affect the package ID, therefore, testing should not be part of that. - Instead, use Conan config [skip_test](https://docs.conan.io/1/reference/config_files/global_conf.html#tools-configurations) feature: - - ```python - def generate(self): - tc = CMakeToolChain(self) - tc.variables['BUILD_TESTING'] = not self.conf.get("tools.build:skip_test", default=true, check_type=bool) - ``` + Instead, use Conan config [skip_test](https://docs.conan.io/2/reference/config_files/global_conf.html#user-tools-configurations) feature. - The `skip_test` configuration is supported by [CMake](https://docs.conan.io/1/reference/build_helpers/cmake.html#test) and [Meson](https://docs.conan.io/1/reference/build_helpers/meson.html#test). + The `skip_test` configuration is supported by [CMake](https://docs.conan.io/2/reference/tools/cmake/cmake.html) and [Meson](https://docs.conan.io/2/reference/tools/meson/meson.html). ### Removing from `package_id` - By default, options are included in the calculation for the `package_id` ([docs](https://docs.conan.io/1/reference/conanfile/methods.html#package-id)). + By default, options are included in the calculation for the `package_id` ([docs](https://docs.conan.io/2/reference/binary_model/package_id.html)). Options which do not impact the generated packages should be deleted, for instance adding a `#define` for a package. ```python diff --git a/docs/adding_packages/dependencies.md b/docs/adding_packages/dependencies.md index 3a93fcb8bad12..ac1a5c37c6491 100644 --- a/docs/adding_packages/dependencies.md +++ b/docs/adding_packages/dependencies.md @@ -5,90 +5,24 @@ from handling "vendored" dependencies to what versions should be used. ## Contents - - * [List Dependencies](#list-dependencies) - * [Optional Requirements](#optional-requirements) - * [Build Requirements](#build-requirements) - * [Accessing Dependencies](#accessing-dependencies) - * [Handling Requirement's Options](#handling-requirements-options) - * [Verifying Dependency's Version](#verifying-dependencys-version) - * [Passing Requirement's info to `build()`](#passing-requirements-info-to-build) - * [Overriding the provided properties from the consumer](#overriding-the-provided-properties-from-the-consumer) + * [Handling Requirement's Options](#handling-requirements-options) * [Adherence to Build Service](#adherence-to-build-service) * [Version Ranges](#version-ranges) - * [Adding Version Ranges](#adding-version-ranges) + * [Adding Version Ranges](#adding-version-ranges) * [Handling "internal" dependencies](#handling-internal-dependencies) -## List Dependencies - -Since all ConanCenterIndex recipes are to build and/or package projects they are exclusively done in [`conanfile.py`](https://docs.conan.io/1/reference/conanfile.html). This offers a few -ways to add requirements. The most common way is [requirements](https://docs.conan.io/1/reference/conanfile/methods.html#requirements): - -```py - def requirements(self): - self.requires("fmt/9.1.0") -``` - -> **Note**: With Conan 2.0, you'll also need to pay attention to new properties like the `transitive_header` attributed which is -> needed when a project include a dependencies header files in its public headers. - -When a project supports a range of version of a dependency, it's generally advised to pick the **most recent available in ConanCenter**. -This helps ensure there are fewer conflicts with other, up to-date, recipes that share the same requirement. - -### Optional Requirements - -Many projects support enabling certain features by adding dependencies. In ConanCenterIndex this is done by adding an option, see -[naming recommendation](conanfile_attributes.md#recommended-names), which should be set to match the upstream project's by default. - -```py -class ExampleConan(ConanFile): - options = { - "with_zlib": [True, False], # Possible values - } - default_options = { - "with_zlib": True, # Should match upstream's CMakeLists.txt `option(...)` - } - - def requirements(self): - if self.options.with_zlib: - self.requires("zlib/1.2.13") -``` -If a dependency was added (or removed) with a release, then the `if` condition could check [`self.version`](https://docs.conan.io/1/reference/conanfile/attributes.html#version). Another common case is -`self.settings.os` dependant requirements which need to be added for certain plaforms. -### Build Requirements - -In ConanCenter we only assume -[CMake is available](../faqs.md#why-recipes-that-use-build-tools-like-cmake-that-have-packages-in-conan-center-do-not-use-it-as-a-build-require-by-default). -If a project requires any other specific tool, those can be added as well. We like to do this with [build_requirements](https://docs.conan.io/1/reference/conanfile/methods.html#build-requirements): - -```py - def build_requirements(self): - self.tool_requires("ninja/1.1.0") -``` - -## Accessing Dependencies - -It's fairly common to need to pass information from a dependency to the project. This is the job of the [`generate()`](https://docs.conan.io/1/reference/conanfile/methods.html#generate) method. This -is generally covered by the built-in generators like [`CMakeDeps`](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmakedeps.html) -However the [`self.dependencies`](https://docs.conan.io/1/reference/conanfile/dependencies.html?highlight=generate) are available. - -Alternatively, a project may depend on a specific versions or configuration of a dependency. This use case is again covered by the -[`self.dependencies`](https://docs.conan.io/1/reference/conanfile/dependencies.html?highlight=validate) within the -[`validate()`](https://docs.conan.io/1/reference/conanfile/methods.html#validate) method. Additionally it's possible to suggest the option's values while the graph is built through [`configure()`](https://docs.conan.io/1/reference/conanfile/methods.html#configure-config-options) -this is not guaranteed and not a common practice. - -### Handling Requirement's Options +## Handling Requirement's Options Forcing options of dependencies inside a ConanCenter should be avoided, except if it is mandatory for the library to build. Our general belief is the users input should be the most important; it's unexpected for command line arguments to be over ruled by specifc recipes. -You need to use the [`validate()`](https://docs.conan.io/1/reference/conanfile/methods.html#validate) method in order to ensure they check after the Conan graph is completely built. +You need to use the [`validate()`](https://docs.conan.io/2/reference/conanfile/methods/validate.html) method in order to ensure they check after the Conan graph is completely built. Certain projects are dependent on the configuration (also known as options) of a dependency. This can be enforced in a recipe by -accessing the [`options`](https://docs.conan.io/1/reference/conanfile/dependencies.html?highlight=options) field of +accessing the [`options`](https://docs.conan.io/2/reference/conanfile/methods/generate.html#dependencies-interface) field of the dependency. ```py @@ -100,68 +34,6 @@ the dependency. raise ConanInvalidConfiguration(f"{self.ref} requires foobar/*:enable_feature=True.") ``` -### Verifying Dependency's Version - -Some project requirements need to respect a version constraint, this can be done as follows: - -```py -def validate(self): - if Version(self.dependencies["foobar"].ref.version) < "1.2": - raise ConanInvalidConfiguration(f"{self.ref} requires [foobar>=1.2] to build and work.") -``` - -### Passing Requirement's info to `build()` - -The [`self.dependencies`](https://docs.conan.io/1/reference/conanfile/dependencies.html) are limited to [`generate()`](https://docs.conan.io/1/reference/conanfile/methods.html#generate) and [`validate()`](https://docs.conan.io/1/reference/conanfile/methods.html#validate). This means configuring a projects build scripts -is a touch more complicated when working with unsupported build scripts. - -In general, with [CMake](https://cmake.org/) project, this can be very simple with the [`CMakeToolchain`](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmaketoolchain.html), such as: - -```py - def generate(self): - tc = CMakeToolchain(self) - # deps_cpp_info, deps_env_info and deps_user_info are no longer used - if self.dependencies["dependency"].options.foobar: - tc.variables["DEPENDENCY_LIBPATH"] = self.dependencies["dependency"].cpp_info.libdirs -``` - -This pattern can be recreated for less common build system by, generating a script to call configure or capture the -required values in a YAML files for example. - -> **Note**: This needs to be saved to disk because the [`conan install`](https://docs.conan.io/1/reference/commands/consumer/install.html) and [`conan build`](https://docs.conan.io/1/reference/commands/development/build.html) commands can be separated when -> developing packages so for this reason the `class` may not persists the information. This is a very common workflow, -> even used in ConanCenter in other areas such as testing. - -```py -from conan import ConanFile -from conan.tools.files import save, load - - -class ExampleConan(ConanFile): - _optional_build_args = [] - - @property - def _optional_build_args_filename(self): - return os.path.join(self.recipe_folder, self.folders.generators, "build_args.yml") - - def generate(self): - # This is required as `self.dependencies` is not available in `build()` or `test()` - if self.dependencies["foobar"].options.with_compression: - self._optional_build_args.append("--enable-foobar-compression") - - save(self, self._optional_build_args_filename, file) - - def build(self): - opts_args = load(self, self._optional_build_args_filename) - # Some magic setup - self.run(f"./configure.sh {opts_args}") -``` - -### Overriding the provided properties from the consumer - -> **Note**: This was adding in [Conan 1.55](https://github.com/conan-io/conan/pull/12609) to the generators... we need to -> write docs for when that's available - ## Adherence to Build Service It's very rare we layout "rules", most often it's guidelines, however in order to ensure graph and the package generated are usable @@ -169,10 +41,10 @@ for consumer, we do impose some limits on Conan features to provide a smoother f > **Note**: These are very specific to the ConanCenter being the default remote and may not be relevant to your specifc use case. -* [Version ranges](https://docs.conan.io/1/versioning/version_ranges.html) are generally not allowed (see below for exemption). -* Specify explicit [RREV](https://docs.conan.io/1/versioning/revisions.html) (recipe revision) of dependencies is not allowed. +* [Version ranges](https://docs.conan.io/2/tutorial/versioning/version_ranges.html#range-expressions) are generally not allowed ([see below](https://github.com/conan-io/conan-center-index/blob/master/docs/adding_packages/dependencies.md#version-ranges) for exemptions). +* Specify explicit [RREV](https://docs.conan.io/2/tutorial/versioning/revisions.html) (recipe revision) of dependencies is not allowed. * Only ConanCenter recipes are allowed in `requires`/`requirements()` and `build_requires`/`build_requirements()`. -* [`python_requires`](https://docs.conan.io/1/reference/conanfile/other.html#python-requires) are not allowed. +* [`python_requires`](https://docs.conan.io/2/reference/extensions/python_requires.html) are not allowed. ### Version Ranges @@ -202,14 +74,9 @@ version range only when a requirement for a newer version is needed. * pkgconf: `[>=2.2 <3]` * xz_utils: `[>=5.4.5 <6]` -> **Warning**: With Conan 1.x, [version ranges](https://docs.conan.io/1/versioning/version_ranges.html) adhere to a much more strict sematic version spec, -> OpenSSL 1.1.x does not follow this so the client will not resolve to that range and will pick a 3.x version. In order to select a lower version you -> can user the defunct `--require-override openssl/1.1.1t@` from the command line, or override from the recipe with `self.requires(openssl/1.1.1t, override=True)` -> to ensure a lower version is picked. - Conan maintainers may introduce this for other dependencies over time. Outside of the cases outlined above, version ranges are not allowed in ConanCenter recipes. -#### Adding Version Ranges +### Adding Version Ranges You might also see version ranges being added in pull requests by Conan maintainers, that are not in the list above. These are being introduced on a case-by-case basis, and are being rolled out diff --git a/docs/adding_packages/folders_and_files.md b/docs/adding_packages/folders_and_files.md index b5a51c8d60309..4e9d94ec5889a 100644 --- a/docs/adding_packages/folders_and_files.md +++ b/docs/adding_packages/folders_and_files.md @@ -10,7 +10,6 @@ to work most efficiently. * [`config.yml`](#configyml) * [The _recipe folder_](#the-_recipe-folder_) * [`conandata.yml`](#conandatayml) - * [`conanfile.py`](#conanfilepy) * [`test_package`](#test_package) ## Recipe File Structure @@ -21,8 +20,6 @@ folders at a time. This is the canonical structure of one of these folders, where the same `conanfile.py` recipe is suitable to build all the versions of the library: -> **Note**: For updating the structure during the [v2 migration](../v2_migration.md) see the [test package](test_packages.md#cmake-targets) document. - ```txt . +-- recipes @@ -32,7 +29,7 @@ This is the canonical structure of one of these folders, where the same `conanfi | +-- conanfile.py | +-- conandata.yml | +-- patches/ -| +-- add-missing-string-header-2.1.0.patch +| +-- 2.1.0-0001-add-missing-string-header-.patch | +-- test_package/ | +-- conanfile.py | +-- CMakeLists.txt @@ -83,19 +80,7 @@ This contains every needed to build packages. #### `conandata.yml` This file lists **all the sources** that are needed to build the package. The most common examples are -source code, build scripts, license files. - -The file is organized into two sections, `"sources"` and `"patches"`, each one of them contains the files that are required -for each version of the library. Resources which need to be downloaded are listed under `"source"` should include a checksum -to validate that they do not change. This helps to ensure the build is reproducible at a later point in time. Often -modifications are required for a variety of reasons, which ones are associated to which version are listed under the `"patches"`. - -```yml -sources: - "9.0.0": - url: "https://github.com/fmtlib/fmt/archive/9.0.0.tar.gz" - sha256: "9a1e0e9e843a356d65c7604e2c8bf9402b50fe294c355de0095ebd42fb9bd2c5" -``` +source code, build scripts, license files. The Conandata is officially documented in [using the conandata.yml](https://docs.conan.io/2/tutorial/creating_packages/handle_sources_in_packages.html#using-the-conandata-yml-file). For more information about picking source tarballs, adding or removing versions, or what the rules are for patches, continue reading our [Sources and Patches](sources_and_patches.md) guide. @@ -106,87 +91,29 @@ For more information about picking source tarballs, adding or removing versions, A detailed breakdown of all the fields can be found in [conandata_yml_format.md](conandata_yml_format.md). We **strongly** recommend adding the [patch fields](conandata_yml_format.md#patches-fields) to help track where patches come from and what issue they solve. -Inside the `conanfile.py` recipe, this data is available in a `self.conan_data` attribute that can be used as follows: - -```py -def source(self): - get(self, **self.conan_data["sources"][self.version], strip_root=True) -``` - -See the [Export Patches](sources_and_patches.md#exporting-patches) and [Applying Patches](sources_and_patches.md#applying-patches) -for more use cases and examples. - -#### `conanfile.py` - -This file is the recipe, it contains the logic to build the libraries from source for all the configurations. -It's the single most important part of writing a package. Every `conanfile.py` should be accompanied by at least one -[folder to test the generated packages](#test_package). - -Each recipe should derive the `ConanFile` class and implement key attributes and methods. - -* Basic attributes and conversions can be found in [`ConanFile` attributes](conanfile_attributes.md) -* Some of the key methods are outlined in this document and will link to more details - -```python -from conan import ConanFile - -class FmtConan(ConanFile): - name = "fmt" - homepage = "https://github.com/fmtlib/fmt" - # ... -``` - -When a package needs other packages those can be include with the `requirements()` method. - -```python - def requirements(self): - self.requires("fmt/9.0.0") -``` - -For more information see the [Dependencies](dependencies.md) documentation. - -For compiled libraries, the `build()` method is used along side the [build helpers](https://docs.conan.io/1/reference/build_helpers.html). -This allows you to use the official build script from a project, see [build and package](build_and_package.md) instructions. - -```python - def build(self): - cmake = CMake(self) - cmake.configure() - cmake.build() -``` - -Most of the projects with build scripts support installing the important files. Avoid installing documentation or examples. - -```python - def package(self): - cmake = CMake(self) - cmake.configure() - cmake.install() -``` - -For some projects, you will need to manually copy files. -Here's an example for a header only library: - -```python - def package(self): - copy(self, "*.h", src=os.path.join(self.source_folder, "include"), dst=os.path.join(self.package_folder, "include")) -``` +Inside the `conanfile.py` recipe, this data is available in through the [self.conan_data](https://docs.conan.io/2/reference/conanfile/attributes.html#conan-data) attribute. #### `test_package` All the packages in this repository need to be tested before they join ConanCenter. A `test_package` folder with its corresponding `conanfile.py` and a minimal project to test the package is strictly required. You can read about it in the -[Conan documentation](https://docs.conan.io/1/creating_packages/getting_started.html) and learn about ConanCenterIndex -specific conventions in [test package](test_packages.md) section. +[Conan documentation](https://docs.conan.io/2/tutorial/creating_packages/test_conan_packages.html#testing-conan-packages). + +The goal for the test package is to make sure the: -The goal for the test package is to make sure the +* Header files are available +* Libraries are available to link against +* Components are correctly exposed -* header files are available -* libraries are available to link against -* components are correctly exposed +When providing a test package, please: -> **Note** It's required to verify that the old generators are not broken. You can do so by using the pattern, see -> [KB-H073](../error_knowledge_base.md#kb-h078) for details. +* Create a minimal usage for the target project here +* Avoid upstream full examples, or code bigger than 15 lines +* Avoid networking connections +* Avoid background apps or servers +* Avoid GUI apps +* Avoid extra files like images, sounds and other binaries +* The propose is testing the generated artifacts ONLY Remember that the `test_` recipes should **test the package configuration that has just been generated** for the _host_ context, otherwise it will fail in cross-building scenarios. diff --git a/docs/adding_packages/sources_and_patches.md b/docs/adding_packages/sources_and_patches.md index 56ff5130c26e4..a57c7355f6978 100644 --- a/docs/adding_packages/sources_and_patches.md +++ b/docs/adding_packages/sources_and_patches.md @@ -14,8 +14,6 @@ These are a very important aspects and it helps us to establish the quality of t * [Adding old versions](#adding-old-versions) * [Policy about patching](#policy-about-patching) * [Format and Conventions](#format-and-conventions) - * [Exporting Patches](#exporting-patches) - * [Applying Patches](#applying-patches) * [Policy on patches](#policy-on-patches) ## Picking the Sources @@ -32,9 +30,8 @@ Where ever possible, downloading source files and compiling is mandated. Downloa Downloaded source code must have a deterministic results where the exact same archive is download each time. See [Conandata's `"sha"` fields](conandata_yml_format.md#sha256) for how this is achieved in ConanCenterIndex. -The sources stored under `self.source_folder` should not be modified. This will enable local workflows to "keep sources" and avoid extra downloads. -Any patch should be applied to the copy of this source code when a build is executed (basically in `build()` method). See [Applying Patches](#applying-patches) -below for more information. +The sources stored under `self.source_folder` should not apply patches or modifications in the `source()` method conditional to options or settings. +Patches should be applied in the `source()` method - taking special care that the patches are platform agnostic. Patches in the `build()` method can be considered where this is not possible, provided that `no_copy_source` is **not** set to `True`. ### Sources not accessible @@ -52,7 +49,9 @@ as a system recipe (`/system`) and making those binaries availabl In this repository we are building a subset of all the versions for a given library. This set of version changes over time as new versions are released and old ones stop being used. -We always welcome latest releases as soon as they are available, and from time to time we remove old versions mainly due to technical reasons: +We welcome the latest release version for its new features and improvements. However, we recommend exercising caution with fresh releases, as upstream may soon release patches or hotfixes to address any unforeseen issues. We usually wait until releases are a few days old to merge them. + +From time to time we remove old versions mainly due to technical reasons: the more versions we have, the more resources that are needed in the CI and the more time it takes to build each pull-request (also, the more chances of failing because of unexpected errors). @@ -61,18 +60,20 @@ more chances of failing because of unexpected errors). The Conan Team may ask you to remove more if they are taking a lot of resources. When removing old versions, please follow these considerations: * keep one version for every major release -* for the latest major release, at least three versions should be available (latest three minor versions) +* for the latest major release, at least two versions should be available (latest two minor versions) Logic associated with removed revisions implies that entries in the `config.yml` and `conandata.yml` files should also be removed. If anyone needs to recover them in the future, Git contains the full history and changes can be recovered from it. +Removed versions should not affect other recipes available in the repository. If a recipe depends on a removed version, it should be updated to +depend on the latest available version. + Please, note that even if those versions are removed from this repository, **the packages will always be accessible in ConanCenter remote** associated to the recipe revision used to build them. ### Adding old versions -We love to hear why in the opening description of the pull requests you need this exact version. -We usually don't add old versions unless there is a specific request for it. Adding versions that are not used by author of the pull request reduces overall resources and time from [the build services](README.md#the-build-service). +We usually don't add old versions unless there is a specific and well-motivated request for it. Adding versions that are not actively used by the author of the pull request reduces overall resources and time from [the build services](README.md#the-build-service). Take into account that the version might be removed in future pull requests according to the [guidelines above](#removing-old-versions). @@ -86,8 +87,7 @@ reading the changelog of the library, the documentation, or any statement by the Patch files are preferred over programmatic `replace_in_file` statements. This makes it easier to review and prevent unwanted side effects when new versions are added. They will be listed in [`conandata.yml`](conandata_yml_format.md) -file and exported together with the recipe. Patches must always include [patch fields](conandata_yml_format.md#patches-fields) -which are enforced by the [linters](../../linter/conandata_yaml_linter.py). +file and exported together with the recipe. Patches should include the required [patch fields](conandata_yml_format.md#patches-fields). Patches must be located in the recipe folder in a `patches/` sub-directory. @@ -100,50 +100,14 @@ There are a few recommendations about naming patches: By clearly indicating what the patch does, when it's applied, and how it relates to existing patches, you can help make the [review process](../review_process.md) easier for readers and help speed up your pull requests. -### Exporting Patches - -It's ideal to minimize the number of files in a package to exactly what's required. When recipes support multiple -versions with differing patches, it's strongly encouraged to only export the patches used for that given recipe. - -Make sure the `export_sources` attribute is replaced by -[`conan.tools.files.export_conandata_patches`](https://docs.conan.io/1/reference/conanfile/tools/files/patches.html?highlight=export_conandata_patches) -helper. - -```py -def export_sources(self): - export_conandata_patches(self) -``` - -### Applying Patches - -Patches can be applied in a separate method, the pattern name is `_patch_sources`. When applying patch files, -using [`conan.tools.files.apply_conandata_patches`](https://docs.conan.io/1/reference/conanfile/tools/files/patches.html?highlight=apply_conandata_patches) -is the best option. - -```py -def build(self): - apply_conandata_patches(self) -``` - -For more complicated cases, -[`conan.tools.files.rm`](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-rm) -or [`conan.tools.files.replace_in_file`](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-replace-in-file) -are good choices. - -```py -def _patch_sources(self): - # remove bundled libfmt - rmdir(self, os.path.join(self.source_folder, "lib", "fmt")) - replace_in_file(self, os.path.join(self.source_folder, "CMakeLists.txt"), "${CMAKE_SOURCE_DIR}", "${CMAKE_CURRENT_SOURCE_DIR}") -``` ### Policy on patches Conan Center is a package repository, and the aim of the service is to provide the recipes to build libraries from the sources as provided by the library authors, and to provide binaries for Conan Center’s supported platforms and configurations. -In general, patches to source code should be avoided and only done as a last resort. In situations where it is strictly necessary, the aim should be that the patches could be eventually merged upstream so that in the future they are no longer necessary. +In general, patches to source code should be avoided and only done as a last resort. In situations where it is strictly necessary, the aim should be that the patches could be eventually merged upstream so that in the future they are no longer necessary. -Pull Requests that introduce patches will be carefully reviewed by the Conan Team. We recognize that in some instances, patches are necessary in the build system/build scripts. +Pull Requests that introduce patches will be carefully reviewed by the Conan Team. We recognize that in some instances, patches are necessary in the build system/build scripts. Patches that affect C and C++ code are strongly discouraged and will only be accepted at the discretion of the Conan Team, after a strict validation process. Patches are more likely to be accepted if they are first reported and acknowledged by the library authors. For scenarios that require patching source code, we greatly encourage raising a new issue explaining the need and motivation, reproducible steps and complete logs, behind the patch. Please note that for issues that strictly affect C and C++ source code, it is very unlikely that a patch will be accepted if an issue is not first raised with the original library authors, or if the patches are not addressing a known security advisory. diff --git a/docs/adding_packages/test_packages.md b/docs/adding_packages/test_packages.md deleted file mode 100644 index 220ff43cb0e59..0000000000000 --- a/docs/adding_packages/test_packages.md +++ /dev/null @@ -1,107 +0,0 @@ -# Test Packages - -This is the main way that ConanCenter is able to validate the contents of a package are valid. -It is required to provide a [`test_package/`](https://docs.conan.io/1/reference/commands/creator/create.html?highlight=test_package) -sub-directory with every recipe. These are expected to work regardless of the options or settings used as this is what consumer will encounter when doing a `conan create` -themselves. It's possible to have ConanCenter run `conan test` on more then one `test folder` by using the `test_` prefix. - - -## Contents - - * [Files and Structure](#files-and-structure) - * [CMake targets](#cmake-targets) - * [Testing more generators with `test_`](#testing-more-generators-with-test_something) - * [Testing CMake variables from FindModules](#testing-cmake-variables-from-findmodules) - * [How it works](#how-it-works) - * [Minimalist Source Code](#minimalist-source-code) - -### Files and Structure - -See the [recipe files and structures](README.md#recipe-files-structure) for a visual. - -All ConanCenterIndex recipe should have a two [test_folders](https://docs.conan.io/1/reference/commands/creator/create.html?highlight=test_folder) -One for the current CMake generator in `test_package/`. - -Please refer to the [Package Templates](../package_templates/) for the current practices about which files and what their content should be. - -### CMake targets - -When using CMake to test a package, the information should be consumed using the -[`CMakeDeps` generator](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmakedeps.html?highlight=cmakedeps). - -This typically will look like a `CMakeLists.txt` which contain lines similar to - -```cmake -find_package(fmt REQUIRED CONFIG) -# ... -target_link_libraries(test_ranges PRIVATE fmt::fmt) -``` - -Refer to the [package template](https://github.com/conan-io/conan-center-index/blob/master/docs/package_templates/cmake_package/all/test_package/CMakeLists.txt) for more examples. - -In ConanCenterIndex, we try to accurately represent the names of the targets and the information provided by CMake's modules and config files that some libraries -provide. If CMake or the library itself don't enforce any target name, the default ones provided by Conan should be recommended. The minimal project -in the `test_package` folder should serve as an example of the best way to consume the package, and targets are preferred over raw variables. - -This rule applies for the _global_ target and for components ones. The following snippet should serve as example: - -We encourage contributors to check that not only the _global_ target works properly, but also the ones for the components. It can be -done creating and linking different libraries and/or executables. - -### Testing more generators with `test_` - -The CI will explore all the folders and run the tests for the ones matching `test_*/conanfile.py` pattern. You can find the output of all -of them together in the testing logs. - -Sometimes it is useful to test the package using different build systems (CMake, Autotools,...). Instead of adding complex logic to one -`test_package/conanfile.py` file, it is better to add another `test_/conanfile.py` file with a minimal example for that build system. That -way the examples will be short and easy to understand and maintain. In some other situations it could be useful to test different Conan generators -(e.g. `CMakeDeps`) using different folders and `conanfile.py` files. - -When using more than one `test_` folder, create a different project for each of them to keep the content of the `conanfile.py` and the -project files as simple as possible, without the need of extra logic to handle different scenarios. - -``` -. -+-- recipes -| +-- library_name/ -| +-- config.yml -| +-- all/ -| +-- ... -| +-- test_package/ -| +-- ... -| +-- test_cmakedeps/ -| +-- conanfile.py -| +-- CMakeLists.txt -| +-- test_package.cpp -``` - -### Testing CMake variables from FindModules - -Recipes which provide [Find Modules](https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html#find-modules) are strongly encouraged to -module the file name, targets and or variables. - -**We will provide better docs in the near future**, for now here are a few references: - -- Convo: https://github.com/conan-io/conan-center-index/pull/13511 -- early example: https://github.com/conan-io/conan-center-index/tree/master/recipes/libxml2/all/test_cmake_module_package -- Best reference: https://github.com/conan-io/conan-center-index/blob/master/recipes/expat/all/test_package_module/CMakeLists.txt#L9 - -### How it works - -The [build service](README.md#the-build-service) will explore all the folders and run the tests for the ones matching `test_*/conanfile.py` pattern. -You can find the output of all of them together in the testing logs. Only the end of the logs are posted even if an earlier "test folder" may have failed. - -> **Note**: If, for any reason, it is useful to write a test that should only be checked using Conan v1, you can do so by using the pattern -> `test_v1_*/conanfile.py` for the folder. Please, have a look to [linter notes](../v2_linter.md) to know how to prevent the linter from -> checking these files. - -Remember that the `test_` recipes should **test the package configuration that has just been generated** for the _host_ context, otherwise -it will fail in cross-building scenarios; before running executables, recipes should check -[`conan.tools.build.can_run`](https://docs.conan.io/1/reference/conanfile/tools/build.html?highlight=can_run#conan-tools-build-can-run) - -### Minimalist Source Code - -The contents of `test_package.c` or `test_package.cpp` should be as minimal as possible, including a few headers at most with simple -instantiation of objects to ensure linkage and dependencies are correct. Any build system can be used to test the package, but -CMake or Meson are usually preferred. diff --git a/docs/bump_version.md b/docs/bump_version.md index 132d4ff1bf685..895576989afa9 100644 --- a/docs/bump_version.md +++ b/docs/bump_version.md @@ -44,5 +44,4 @@ In case a patch should be re-used, it should be present in `conandata.yml` to th ## Reviewing and merging -Bumping version PRs follow the same regular [review process](review_process.md), except for being merged automatically -as listed on [Labels](labels.md#bump-version) section. +Bumping version PRs follow the same regular [review process](review_process.md). \ No newline at end of file diff --git a/docs/changelog.md b/docs/changelog.md index ecdf3c49ada2f..6ee15d19c592c 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,5 +1,10 @@ # Changelog +### 04-Nov-2024 - 09:15 CET + +- [feature] Conan 1.x end of support and Conan 2.x as default version in the CI +- [feature] New CI infrastructure for Conan 2.x only + ### 12-Sep-2024 - 09:23 CEST - [feature] Add support for Conan 2.7.1 in the CI diff --git a/docs/community_resources.md b/docs/community_resources.md index 4600ca89ac451..f2806f9377afb 100644 --- a/docs/community_resources.md +++ b/docs/community_resources.md @@ -6,8 +6,7 @@ This is a curated list of various bots and helpful tools that aim to making appr ## Contents * [Social Media and More](#social-media-and-more) - * [Bots](#bots) - * [Tools](#tools) + * [Bots](#bots) ## Social Media and More @@ -19,12 +18,6 @@ If you are looking to stay up to date with the last Conan news, follow us on Twi - [Updatable Recipes](https://github.com/qchateau/conan-center-bot): Automatically scans available recipes and checked for new upstream releases and tests one configuration - The results can be found here: https://qchateau.github.io/conan-center-bot/#/updatable -- [Pending Review](https://github.com/prince-chrismc/conan-center-index-pending-review) - - The results can be found here: https://prince-chrismc.github.io/conan-center-index-pending-review/ - [System Package Checks](https://github.com/bincrafters/system-packages-checks): Builds automatically all `system` versions of recipes merged on CCI and being pull requested on a selection of Linux distributions and FreeBSD - The results can be found here: https://bincrafters.github.io/system-packages-checks/ - -## Tools - -- [Bincrafters Conventions](https://github.com/bincrafters/bincrafters-conventions): Automatically updates Conan recipes to the latest conventions and rules diff --git a/docs/consuming_recipes.md b/docs/consuming_recipes.md index c7f4c917b6788..b898282302020 100644 --- a/docs/consuming_recipes.md +++ b/docs/consuming_recipes.md @@ -29,8 +29,8 @@ There can be several causes if a recipe (a new revision) might stopped to work i New recipe revisions can take into account changes that are introduced in new Conan client version, sometimes these changes modify some experimental behavior without modifying recipe syntax. -This use case is covered by the [`required_conan_version`](https://docs.conan.io/1/reference/conanfile/other.html?highlight=required_conan_version#requiring-a-conan-version-for-the-recipe) feature. It will -substitute the syntax error by one nicer error provided by Conan client. +This use case is covered by the [`required_conan_version`](https://docs.conan.io/2/reference/conanfile/attributes.html#required-conan-version) feature. +It will substitute the syntax error by one nicer error provided by Conan client. To be sure that people using these new experimental features are using the required Conan version and testing the actual behavior of those features (feedback about them is very important to Conan). @@ -43,23 +43,19 @@ Conan is very flexible; you can add your own remote or modify your client’s co Here are a few choices: -- [Running your own Conan Server](https://docs.conan.io/1/uploading_packages/running_your_server.html) - great for local ad-hoc setups -- [Cache recipes in your own ArtifactoryCE](https://docs.conan.io/1/uploading_packages/using_artifactory.html) - recommended for production environments +- [Cache recipes in your own ArtifactoryCE](https://docs.conan.io/2/devops/devops_local_recipes_index.html) - recommended for production environments Using your own ArtifactoryCE instance is easy. You can [deploy it on-premise](https://conan.io/downloads.html) or use a -[cloud provided solution](https://jfrog.com/community/start-free) for **free**. Your project should -[use only this remote](https://docs.conan.io/1/reference/commands/misc/remote.html?highlight=add%20new) and new recipe +[cloud provided solution](https://jfrog.com/start-free) for **trial**. +Your project should [use only this remote](https://docs.conan.io/2/reference/commands/remote.html#conan-remote-add) and new recipe revisions are only pushed to your Artifactory after they have been validated in your project. The minimum solution, if still choosing to rely on ConanCenter directly, involves small changes to your client configuration by pinning the revision of every reference you consume in your project using the following: -- [recipe revision (RREV)](https://docs.conan.io/1/versioning/revisions.html) can be added to each requirement. +- [recipe revision (RREV)](https://docs.conan.io/2/tutorial/versioning/revisions.html#using-revisions) can be added to each requirement. Instead of `fmt/9.1.0` you can add a pound (or hashtag) to the end followed by the revision `fmt/9.1.0#c93359fba9fd21359d8db6f875d8a233`. - This feature needs to be enabled in Conan 1.x, see the [Activation Instructions](https://docs.conan.io/1/versioning/revisions.html#how-to-activate-the-revisions) for details. -- [Lockfiles](https://docs.conan.io/1/versioning/lockfiles.html) can be created with the `conan lock create` and read with by - adding `--lockfile=conan.lock` to `conan install` or `conan create` commands. See the [lockfile introduction](https://docs.conan.io/1/versioning/lockfiles/introduction.html#) for more information. - -> **Warning** Please, be aware there are some known bugs related to lockfiles that are not being fixed in Conan v1.x - we are really excited for the 2.0 improvements to be widely used. +- [Lockfiles](https://docs.conan.io/2/tutorial/versioning/lockfiles.html) can be created with the `conan lock create` and read with by + adding `--lockfile=conan.lock` to `conan install` or `conan create` commands. See the [lockfile introduction](https://docs.conan.io/2/tutorial/consuming_packages/intro_to_versioning.html#lockfiles) for more information. Both of these give you better control and will allow you to choose when to upgrade your Conan client. diff --git a/docs/developing_recipes_locally.md b/docs/developing_recipes_locally.md index 6a82d992574ed..3a028a8c6ff61 100644 --- a/docs/developing_recipes_locally.md +++ b/docs/developing_recipes_locally.md @@ -4,15 +4,11 @@ Before you can contribute any code changes, you'll need to make sure you are fam This file is intended to provide all the commands you need to run in order to be an expert ConanCenterIndex contributor. -> **Note**: If you are working with Conan 2.0, the [instructions are below](#using-conan-20) - ## Contents * [Clone your fork](#clone-your-fork) * [Setup your environment](#setup-your-environment) - * [Installing the ConanCenter Hooks](#installing-the-conancenter-hooks) - * [Updating conan hooks on your machine](#updating-conan-hooks-on-your-machine) * [Basic Commands](#basic-commands) * [Try it yourself](#try-it-yourself) * [Debugging Failed Builds](#debugging-failed-builds) @@ -22,10 +18,7 @@ This file is intended to provide all the commands you need to run in order to be * [Yamlschema](#yamlschema) * [Testing the different `test__package`](#testing-the-different-test__package) * [Testing more environments](#testing-more-environments) - * [Docker build images used by ConanCenterIndex](#docker-build-images-used-by-conancenterindex) - * [Using Conan 2.0](#using-conan-20) - * [Installing Conan 2.0 beta](#installing-conan-20-beta) - * [Trying it out](#trying-it-out) + * [Docker build images used by ConanCenterIndex](#docker-build-images-used-by-conancenterindex) ## Clone your fork @@ -35,53 +28,21 @@ This file is intended to provide all the commands you need to run in order to be ## Setup your environment 1. Install a C++ development toolchain - ConanCenter's [build images](#testing-more-environments) are available -2. [Install the Conan client](https://docs.conan.io/1/installation.html) - make sure to keep it up to date! +2. [Install the Conan client](https://docs.conan.io/2/installation.html) - make sure to keep it up to date! 3. Install CMake - this is the only tool which is assumed to be present [see FAQ](faqs.md#why-recipes-that-use-build-tools-like-cmake-that-have-packages-in-conan-center-do-not-use-it-as-a-build-require-by-default) for details. > **Note**: It's recommended to use a dedicated Python virtualenv when installing with `pip`. -### Installing the ConanCenter Hooks - -> **Warning**: This is not yet supported with Conan 2.0. Please, follow the instructions below only in case you are using Conan 1.0. - -The system will use the [conan-center hooks](https://github.com/conan-io/hooks) to perform some quality checks. You can install the hooks by running: - -```sh -conan config install https://github.com/conan-io/hooks.git -sf hooks -tf hooks -conan config set hooks.conan-center -``` - -> **Note**: Hooks are generally for package correctness and the pylinters are for the recipe syntax - -The hooks will show error messages but the `conan create` won’t fail unless you export the environment variable `CONAN_HOOK_ERROR_LEVEL=40`. -All hooks checks will print a similar message: - -```txt -[HOOK - conan-center.py] post_source(): [LIBCXX MANAGEMENT (KB-H011)] OK -[HOOK - conan-center.py] post_package(): ERROR: [PACKAGE LICENSE] No package licenses found -``` - -#### Updating conan hooks on your machine - -The hooks are updated from time to time, so it's worth keeping your own copy of the hooks updated regularly. To do this, simply run: - -```sh -conan config install -``` - ## Basic Commands We recommend working from the `recipes/project` folder itself. You can learn about the [recipe file structure](adding_packages/README.md#recipe-files-structure) to understand the folder and files located there. > **Note**: You can only change one recipe per pull request, and working from the [_recipe folder_](adding_packages/README.md#the-recipe-folder-conanfilepy) will help prevent making a few mistakes. The default for this folder is `all`, follow the link above to learn more. -The [entire workflow of a recipe](https://docs.conan.io/1/developing_packages/package_dev_flow.html) can be executed with the [`conan create`](https://docs.conan.io/1/reference/commands/creator/create.html). This should look like: - -* `conan create all/conanfile.py 0.0.0@ -pr:b=default -pr:h=default` +The [entire workflow of a recipe](https://docs.conan.io/2/tutorial/creating_packages.html) can be executed with the [`conan create`](https://docs.conan.io/2/reference/commands/create.html). This should look like: -ConanCenter also has a few [support settings and options](supported_platforms_and_configurations.md) which highly recommend to test. For example -`conan create all/conanfile.py 0.0.0@ -o project:shared=True -s build_type=Debug` is an easy way to test more configurations ensuring the package is correct. +* `conan create all/conanfile.py --version=0.1.0` ### Try it yourself @@ -89,110 +50,29 @@ For instance you can create packages for `fmt` in various supported configuratio ```sh cd recipes/fmt -conan create all/conanfile.py fmt/9.0.0@ -pr:b=default -pr:h=default -conan create all/conanfile.py fmt/9.0.0@ -o fmt:header_only=True -pr:b=default -pr:h=default -conan create all/conanfile.py fmt/9.0.0@ -s build_type=Debug -o fmt:shared=True -pr:b=default -pr:h=default +conan create all/conanfile.py --version=9.0.0 +conan create all/conanfile.py --version=9.0.0 -o "&:header_only=True" +conan create all/conanfile.py --version=9.0.0 -s build_type=Debug -o "*/*:shared=True" ``` ## Debugging Failed Builds -Some common errors related to Conan can be found on [troubleshooting](https://docs.conan.io/1/faq/troubleshooting.html) section. -For ConanCenter Hook errors, go to the [Error Knowledge Base](error_knowledge_base.md) page to know more about those. +Some common errors related to Conan can be found on [troubleshooting](https://docs.conan.io/2/knowledge/faq.html#troubleshooting) section. -To test with the same environment, the [build images](supported_platforms_and_configurations.md#build-images) are available. Instructions for using these images can be found in [Testing more environments](#testing-more-environments) section. In ConanCenterIndex, the most common failure point is upstream build scripts tailored to their specific use cases. It's not uncommon to [patch build scripts](adding_packages/sources_and_patches.md#rules) but make sure to read the -[patch policy](adding_packages/sources_and_patches.md#policy-about-patching). You are encouraged to submit pull requests upstream. - -## Running the Python Linters - -> **Warning**: This is not yet supported with Conan 2.0 - -Linters are always executed by GitHub Actions to validate parts of your recipe, for instance, if it uses migrated Conan tools imports. - -It is possible to run the linter locally the same way it is being run [using Github actions](../.github/workflows/linter-conan-v2.yml) by: - -* (Recommended) Use a dedicated Python virtualenv. -* Ensure you have required tools installed: `conan` and `pylint` (better to uses fixed versions) - - ```sh - pip install conan~=1.0 pylint==2.14 - ``` - -* Set environment variable `PYTHONPATH` to the root of the repository - - ```sh - export PYTHONPATH=your/path/conan-center-index - ``` - -* Now you just need to execute the `pylint` commands: - - ```sh - # Lint a recipe: - pylint --rcfile=linter/pylintrc_recipe recipes/fmt/all/conanfile.py - - # Lint the test_package - pylint --rcfile=linter/pylintrc_testpackage recipes/fmt/all/test_package/conanfile.py - ``` - -## Running the YAML Linters - -There's two levels of YAML validation, first is syntax and the second is schema. -The style rules are located in [`linter/yamllint_rules.yml`](../linter/yamllint_rules.yml) and are used to ensure consistence. -The [`config.yml`](adding_packages/README.md#configyml) is required for the build infrastructure and the -[`conandata.yml` patch fields](adding_packages/conandata_yml_format.md#patches-fields) have required elements that are enforced with -schema validation. There's are to encourage the best possible quality of recipes and make reviewing faster. - -### Yamllint - -* (Recommended) Use a dedicated Python virtualenv. -* Ensure you have required tools installed: `yamllint` (better to uses fixed versions) - - ```sh - pip install yamllint==1.28 - ``` - -* Now you just need to execute the `yamllint` commands: - - ```sh - # Lint a recipe: - yamllint --config-file linter/yamllint_rules.yml -f standard recipes/config.yml - yamllint --config-file linter/yamllint_rules.yml -f standard recipes/fmt/all/conandata.yml - ``` - -### Yamlschema - -* (Recommended) Use a dedicated Python virtualenv. -* Ensure you have required tools installed: `strictyaml` and `argparse` (better to use fixed versions) - - ```sh - pip install strictyaml==1.16 argparse==1.4 - ``` - -* Now you just need to execute the validation scripts: +[patch policy](adding_packages/sources_and_patches.md#policy-about-patching). You are encouraged first to submit pull requests upstream. - ```sh - # Lint a config.yml: - python3 linter/config_yaml_linter.py recipes/fmt/config.yml - # Lint a conandata.yml - python3 linter/conandata_yaml_linter.py recipes/fmt/all/conandata.yml - ``` - -## Testing the different `test_*_package` +## Testing This can be selected when calling `conan create` or separately with `conan test` -```sh -# By adding the `-tf` argument -conan create recipes/fmt/all/conanfile.py 9.0.0@ -tf test_v1_package/ -pr:b=default -pr:h=default -``` - ```sh # Passing test package's conanfile directly (make sure to export first) -conan test recipes/fmt/all/test_v1_package/conanfile.py fmt/9.0.0@ -pr:h=default -pr:b=default +conan test recipes/fmt/all/test_package/conanfile.py fmt/9.0.0 ``` ## Testing more environments @@ -207,96 +87,12 @@ Assuming you've already tested it locally and it's been successfully exported to * You can also download them from CCI build summary 2. Build missing packages -Example. - -```sh -docker run -v/Users/barbarian/.conan:/home/conan/.conan conanio/gcc8 bash -c "conan profile new --detect gcc8" -docker run -v/Users/barbarian/.conan:/home/conan/.conan conanio/gcc8 bash -c "conan install -pr gcc8 fmt/9.0.0@ --build missing" -``` +Please, read [how to create Conan package using a Docker runner](https://docs.conan.io/2/examples/runners/docker/basic.html). > **Note**: If you are running on Mac M1, the follow Docker argument is required: `--platform=linux/amd64` If you are working with packages that have system dependencies that are managed by Conan -```sh -docker run -e CONAN_SYSREQUIRES_MODE=enabled conanio/gcc11-ubuntu16.04 conan install fmt/9.0.0@ -if build --build missing -c tools.system.package_manager:mode=install -c tools.system.package_manager:sudo=yes -``` - #### Docker build images used by ConanCenterIndex -The Conan Center Index uses [Conan Docker Tools](https://github.com/conan-io/conan-docker-tools/) to build packages in a variety of environments. All images are hosted in [Docker Hub](https://hub.docker.com/u/conanio). The relation of the images with the build configurations is available according to the Conan configuration, as `node_labels.Linux`, for instance: - - -```yaml -node_labels: - Linux: - x86_64: - "gcc": - default: "linux_gcc_${compiler.version}" - "11": "linux_gcc_${compiler.version}_ubuntu16.04" - "clang": - default: "linux_clang_${compiler.version}_ubuntu16.04" - "11": "linux_clang_${compiler.version}" -``` - -The configuration files are located in the folder [../.c3i](../.c3i). Currently are the files [config_v1.yml](../.c3i/config_v1.yml) and [config_v2.yml](../.c3i/config_v2.yml). The configuration file `config_v1.yml` is used by the Conan 1.0 client, while `config_v2.yml` is used by the Conan 2.0 client. - -The label `linux` refers to any Docker image, while `gcc_${compiler.version}` refers to GCC + a compiler version. For example, `linux_gcc_10` refers to the image `conanio/gcc10`. -The suffix `_ubuntu16.04` refers to the base image used by the Docker image, in this case, `ubuntu16.04`. So, `"11": "linux_gcc_${compiler.version}_ubuntu16.04"` means that the image `conanio/gcc11-ubuntu16.04`. Thus, all GCC versions use `conanio/gcc`, except for the GCC 11, which uses `conanio/gcc11-ubuntu16.04`. The same applies to Clang. - - -## Using Conan 2.0 - -Everything you need to know about the methods, commands line, outputs can be found in the -[Conan 2.0 Migrations](https://docs.conan.io/1/conan_v2.html) docs. - -This should be non-intrusive. Conan 2.0 by default has a different `CONAN_USER_HOME` location, which means that it has separate caches, profiles, and settings. -This will leave your Conan 1.0 setup completely intact when using Conan 2.0. - -> **Note**: There are substantial changes to the CLI so very few of the commands will remain the same. -> The new [Unified Command Pattern](https://docs.conan.io/1/migrating_to_2.0/commands.html#unified-patterns-in-command-arguments), -> as an example, changes how settings and options are passed. - -### Installing Conan 2.0 beta - -Simply install Conan 2.0 with `pip install conan --upgrade --pre`. - -You can confirm the installation with: - -```sh -$ conan --version -Conan version 2.0.0-beta3 -$ conan config home -Current Conan home: /Users/barbarian/.conan2 -``` - -> **Note**: You will most likely see -> -> ```sh -> Initialized file: '/Users/barbarian/.conan2/settings.yml' -> Initialized file: '/Users/barbarian/.conan2/extensions/plugins/compatibility/compatibility.py' -> Initialized file: '/Users/barbarian/.conan2/extensions/plugins/compatibility/app_compat.py' -> Initialized file: '/Users/barbarian/.conan2/extensions/plugins/compatibility/cppstd_compat.py' -> Initialized file: '/Users/barbarian/.conan2/extensions/plugins/profile.py' -> ``` -> -> When running the client for the first time. - -You will need to setup profiles. This is one of the changes in 2.0. The default profile is now opt-in and no longer generated automatically. - -```sh -conan profile detect -``` - -> **Warning**: This is a best guess, you need to make sure it's correct. - -### Trying it out - -Try building an existing recipe. We'll repeat the 1.x example with `fmt` to build the same configurations: - -```sh -cd recipes/fmt -conan create all/conanfile.py --version 9.0.0 -conan create all/conanfile.py --version 9.0.0 -o fmt/9.0.0:header_only=True -conan create all/conanfile.py --version 9.0.0 -s build_type=Debug -o fmt/9.0.0:shared=True -``` +The Conan Center Index uses [Conan Docker Tools](https://github.com/conan-io/conan-docker-tools/) to build packages in a variety of environments. All images are hosted in [Docker Hub](https://hub.docker.com/u/conanio). \ No newline at end of file diff --git a/docs/error_knowledge_base.md b/docs/error_knowledge_base.md deleted file mode 100644 index 415d9fd2e98fc..0000000000000 --- a/docs/error_knowledge_base.md +++ /dev/null @@ -1,499 +0,0 @@ -# Errors from the conan-center hook (KB-Hxxx) - -These are located at [conan-io/hooks](https://github.com/conan-io/hooks/blob/master/hooks/conan-center.py). - -#### **#KB-H001: "DEPRECATED GLOBAL CPPSTD"** - -`Conan > 1.15` deprecated the usage of the global ``cppstd`` setting in favor of ``compiler.cppstd`` to [manage C++ standard](https://docs.conan.io/1/howtos/manage_cpp_standard.html). As a subsetting of the compiler, it shouldn't be declared in the `conanfile.py`. - -#### **#KB-H002: "REFERENCE LOWERCASE"** - -The package names in conan-center have to be [lowercase](https://github.com/conan-io/tribe/blob/main/design/017-lowercase-references.md). e.g: ``zlib/1.2.8``. - -#### **#KB-H003: "RECIPE METADATA"** - -The recipe has to declare the following attributes: - -- [url](https://docs.conan.io/1/reference/conanfile/attributes.html#url) -- [license](https://docs.conan.io/1/reference/conanfile/attributes.html#license) -- [description](https://docs.conan.io/1/reference/conanfile/attributes.html#description) -- [homepage](https://docs.conan.io/1/reference/conanfile/attributes.html#homepage). - -Also we recommend adding [topics](https://docs.conan.io/1/reference/conanfile/attributes.html#topics) attribute. - -#### **#KB-H005: "HEADER_ONLY, NO COPY SOURCE"** - -If the recipe calls [self.info.header_only()](https://docs.conan.io/1/howtos/header_only.html) in the [package_id()](https://docs.conan.io/1/reference/conanfile/methods.html#package-id) method and doesn't declare settings, it should use the [no_copy_source](https://docs.conan.io/1/reference/conanfile/attributes.html#no-copy-source) attribute to avoid unnecessary copies of the source code. - -#### **#KB-H006: "FPIC OPTION"** - -The recipe is not for a header-only library and should have an `fPIC` option: - -```python -class SomeRecipe(ConanFile): - ... - - options = {"fPIC": [True, False]} - default_options = {"fPIC": True} -``` - -#### **#KB-H007: "FPIC MANAGEMENT"** - -The recipe declares `fPIC` but doesn't remove the option for Windows (where it doesn't make sense). - -```python -class SomeRecipe(ConanFile): - ... - - def config_options(self): - if self.settings.os == "Windows": - del self.options.fPIC -``` - -Or, a package is built as `shared` library and `fPIC` is declared. The option `fPIC` should be removed: - -```python -class SomeRecipe(ConanFile): - ... - - def configure(self): - if self.options.shared: - del self.options.fPIC -``` - -Here we use [configure()](https://docs.conan.io/1/reference/conanfile/methods.html#configure-config-options) method, because user options are loaded after [config_options()](https://docs.conan.io/1/reference/conanfile/methods.html#configure-config-options) only. - -#### **#KB-H008: "VERSION RANGES"** - -See [Dependencies Version Ranges](adding_packages/dependencies.md#version-ranges) for details. - -#### **#KB-H009: "RECIPE FOLDER SIZE"** - -The recipe folder (including the `test_package` folder) cannot exceed 256KB. - -#### **#KB-H010: "IMMUTABLE SOURCES"** - -Create a file [conandata.yml](https://docs.conan.io/1/reference/config_files/conandata.yml.html) in the recipe folder containing the source code origins: - -**_recipes/lib/1.2.0/conandata.yml_**: - -```yaml -sources: - 1.2.0: - url: "http://downloads.sourceforge.net/project/mylib/1.2.0/sources.tar.gz" - sha256: "36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d" -``` - -Then in the recipe, you can access the data to download the URL and validate the checksum doing: - -```python -class SomeRecipe(ConanFile): - ... - - def source(self): - tools.get(**self.conan_data["sources"][self.version]) -``` - -#### **#KB-H011: "LIBCXX MANAGEMENT"** - -If the library is detected as a pure C library (sources doesn't conatain any file with the following extensions: ["cc", "cpp", "cxx", "c++m", "cppm", "cxxm", "h++", "hh", "hxx", "hpp"]) then it has to remove the [compiler.libcxx](https://docs.conan.io/1/reference/config_files/settings.yml.html#c-standard-libraries-aka-compiler-libcxx) subsetting, because the cpp standard library shouldn't affect the binary ID: - -```python -class SomeRecipe(ConanFile): - ... - - def configure(self): - del self.settings.compiler.libcxx -``` - -#### **#KB-H012: "PACKAGE LICENSE"** - -The binary packages should contain a folder named `licenses` containing the contents (library, tool, etc) license/s. - -#### **#KB-H013: "DEFAULT PACKAGE LAYOUT"** - -The binary packages generally do not need any other files or folder except the following: `["lib", "bin", "include", "res", "licenses"]`. -This closely matches the default [`cpp_info`](https://docs.conan.io/1/reference/conanfile/methods.html#package-info) from the client. -The upstream package layout should be followed as much as possible, if a folder is not in the list (like `"share"`) then an exception -can very easily be added by adding it to [this list of exceptions](https://github.com/conan-io/hooks/blob/d587cfebbf2b31c16e477b79c0c2fd4501f60fc8/hooks/conan-center.py#L1089-L1090). - -> **Note**: We are in the process of evaluating this rule, looking at calculating the size impact for problematic packages - -#### **#KB-H014: "MATCHING CONFIGURATION"** - -The binary package contains some file that not corresponds to the configuration of the package, for example, binary libraries for a header-only library, a DLL file when the `settings.os != Windows` and so on. The error message will contain information about the offending file. - -#### **#KB-H015: "SHARED ARTIFACTS"** - -The binary package is shared (self.options.shared == True) but there is no `dll`, `so` or `dylib` files inside the package. - -#### **#KB-H016: "CMAKE-MODULES-CONFIG-FILES"** - -The binary package cannot contain module or config CMake files ("Find\*.cmake", "\*Config.cmake", "\*-config.cmake"). -The package shouldn't contain specific build-system files to inform to the consumers how to link with it. -In order to make sure that the package will be consumed with any build-system, conan-center repository encourages to declare a [def package_info(self)](https://docs.conan.io/1/reference/conanfile/methods.html#package-info) method with all the needed information about the package. - -The consumers of the package will be able to consume the packages using a specific [generators](https://docs.conan.io/1/using_packages/conanfile_txt.html#generators) for the build system they use. - -See also: [Why are CMake find/config files and pkg-config files not packaged?](faqs.md#why-are-cmake-findconfig-files-and-pkg-config-files-not-packaged). - -#### **#KB-H017: "PDB FILES NOT ALLOWED"** - -Because of the big size of the [PDB](https://github.com/Microsoft/microsoft-pdb) files (Program Databse, a debug information format) and the issues using them changing the original folders, the PDB files are not allowed to be packaged. - -See also: [Why PDB files are not allowed?](faqs.md#why-pdb-files-are-not-allowed). - -#### **#KB-H018: "LIBTOOL FILES PRESENCE"** - -Packaging [libtool files](https://www.linuxfromscratch.org/blfs/view/svn/introduction/la-files.html) (\*.la) instead of library files (\*.a) is not allowed. - -#### **#KB-H019: "CMAKE FILE NOT IN BUILD FOLDERS"** - -Some file with `*.cmake` extension has been found in a folder not declared in [cpp_info.builddirs](https://docs.conan.io/1/reference/conanfile/attributes.html#cpp-info). -It is only allowed to put build files in `builddirs` because the generators might be able to include them when needed, but only if they are located in well known paths. - -#### **#KB-H020: "PC-FILES"** - -For the same reasons explained at [KB-H016](#KB-H016) it is not allowed to package `*.pc` files. - -See also: [Why are CMake find/config files and pkg-config files not packaged?](faqs.md#why-are-cmake-findconfig-files-and-pkg-config-files-not-packaged). - -#### **#KB-H021: "MS RUNTIME FILES"** - -For the legal reasons, and in order to reduce the size of packages, it's not allowed to package Microsoft Visual Studio runtime libraries, such as `msvcr80.dll`, `msvcp80.dll`, `vcruntime140.dll` and so on. - -#### **#KB-H022: "CPPSTD MANAGEMENT"** - -If the library is detected as a pure C library (sources doesn't conatain any file with the following extensions: ["cc", "cpp", "cxx", "c++m", "cppm", "cxxm", "h++", "hh", "hxx", "hpp"]) then it has to remove the [compiler.cppstd](https://docs.conan.io/1/howtos/manage_cpp_standard.html) subsetting, because the cpp standard library shouldn't affect the binary ID: - -```python -class SomeRecipe(ConanFile): - ... - - def configure(self): - del self.settings.compiler.cppstd -``` - -#### **#KB-H023: "EXPORT LICENSE"** - -A recipe should not export any license file, as all recipes are under the same license type (in the root of this repo). - -```python -class SomeRecipe(ConanFile): - ... - - exports = "LICENSE.md" # not allowed -``` - -There is a complete explanation in the [FAQ](faqs.md#should-recipes-export-a-recipes-license). - -#### **#KB-H024: "TEST PACKAGE FOLDER"** - -The [test_package](https://docs.conan.io/1/creating_packages/getting_started.html) folder is required for every recipe in Conan Center Index. - -``` -. conanfile.py -. test_package - |- conanfile.py -``` - -#### **#KB-H025: "META LINES"** - -The following metadata lines (and similiar) are not allowed in recipes: - -- [Shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) to specify Python version: - -```python -#!/usr/bin/env python # not allowed -#!/usr/local/bin/python # not allowed - -class SomeRecipe(ConanFile): - ... -``` - -- [Vim](https://www.vim.org/) configuration: - -```python -# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4 # not allowed - -class SomeRecipe(ConanFile): - ... -``` - -- [Encoding](https://www.python.org/dev/peps/pep-0263/): - -```python -# -*- coding: utf-8 -*- # not allowed -# coding=utf-16 # not allowed - -class SomeRecipe(ConanFile): - ... -``` - -#### **#KB-H027: "CONAN CENTER INDEX URL"** - -The attribute [url](https://docs.conan.io/1/reference/conanfile/attributes.html#url) should point to the address where the recipe is located. -The current Conan Center Index address is - -#### **#KB-H028: "CMAKE MINIMUM VERSION"** - -All CMake files added to recipe package should contain a [minimal version](https://cmake.org/cmake/help/latest/command/cmake_minimum_required.html) (Not necessarily 2.8.11, it can be any version) available in the file: - -```cmake -# CMakeLists.txt -cmake_minimum_required(VERSION 2.8.11) -project(conanwrapper) - -... -``` - -#### **#KB-H029: "TEST PACKAGE - RUN ENVIRONMENT"** - -The [RunEnvironment()](https://docs.conan.io/1/reference/build_helpers/run_environment.html#runenvironment) build helper is no longer needed in the `test_package/conanfile.py`. It has been integrated by [run_environment](https://docs.conan.io/1/devtools/running_packages.html#running-from-packages) parameter. - -```python -# test_package/conanfile.py -class TestConan(ConanFile): - settings = "os", "compiler", "build_type", "arch" - - def test(self): - self.run("bin/test", run_environment=True) -``` - -#### **#KB-H030: "CONANDATA.YML FORMAT"** - -The structure of the [conandata.yml](https://docs.conan.io/1/reference/config_files/conandata.yml.html) file should follow the schema -defined in [Adding Packages - `Conandata.yml` Format](adding_packages/conandata_yml_format.md). - -#### **#KB-H031: "CONANDATA.YML REDUCE"** - -This [hook](https://docs.conan.io/1/extending/hooks.html) re-creates the information of the [conandata.yml](https://docs.conan.io/1/reference/config_files/conandata.yml.html) file, discarding the fields not relevant to the version of the package exported. This avoids creating new recipe revisions for every new change introduced in the file. -Any additional field in the YAML file will raise an error. - -#### **#KB-H032: "SYSTEM REQUIREMENTS"** - -[System requirements](https://docs.conan.io/1/reference/conanfile/methods.html#systempackagetool) can be used as an option when a Conan package is not available ,the same package can be installed by system package manager. However, it can cause reproducibility problems, since the package may vary according the distribution or OS. Conan is not able to track its metadata, so that, installing system packages by recipe is not allowed. - -See also: [Can I install packages from the system package manager?](faqs.md#can-i-install-packages-from-the-system-package-manager). - -#### **#KB-H034: "TEST PACKAGE - NO IMPORTS()"** - -The method [imports](https://docs.conan.io/1/reference/conanfile/methods.html#imports) helps the test package stage copying all dynamic libraries and special resources. However, the [run_environment](https://docs.conan.io/1/reference/conanfile/other.html#running-commands) parameter, used when running commands, is able to solve all paths to the dynamic libraries installed in your cache. - -#### **#KB-H037: "NO AUTHOR"** - -Since the entire community is maintaining all CCI recipes, putting just one name in a recipe is unfair, putting all names is unmanageable. All authors can be found in the Git logs. - -#### **#KB-H040: "NO TARGET NAME"** - -According the Conan issue [#6269](https://github.com/conan-io/conan/issues/6269), the attribute `cpp_info.name` should be avoided for Conan Center Index in favor of `cpp_info.names["cmake_find_package"]` and `cpp_info.names["cmake_find_package_multi"]`. - -See also: [Migrating legacy cpp_info attributes to set_property()](https://docs.conan.io/1/migrating_to_2.0/properties.html). - -#### **#KB-H041: "NO FINAL ENDLINE"** - -Source files should end with a final endline. -This avoids potential warnings/errors like `no new line at the end of file`. - -#### **#KB-H044: "NO REQUIRES.ADD()"** - -Both `self.requires.add()` and `self.build_requires.add()` have been deprecated in favor of [self.requires()](https://docs.conan.io/1/reference/conanfile/methods.html#requirements) and [self.build_requires()](https://docs.conan.io/1/reference/conanfile/methods.html#build-requirements) which were introduced on Conan 1.x. Both `add()` were introduced during Conan 0.x and since Conan 1.23 they no longer follow the original behavior. - -#### **#KB-H045: "DELETE OPTIONS"** - -The method `self.options.remove()` was introduced in Conan 0.x, however, Conan 1.x brings a more pythonic way for removing options from your recipe: `del self.options.` - -See also: [configure(), config_options()](https://docs.conan.io/1/reference/conanfile/methods.html#configure-config-options). - -#### **#KB-H046: "CMAKE VERBOSE MAKEFILE"** - -The CMake definition [CMAKE_VERBOSE_MAKEFILE](https://cmake.org/cmake/help/latest/variable/CMAKE_VERBOSE_MAKEFILE.html) helps for debugging when developing, however, for regular CI build, it increases the log size and it's only required when problems occur and need to be verified. - -#### **#KB-H048: "CMAKE VERSION REQUIRED"** - -> **Warning**: This is a legacy Conan 1.x details from the deprecated generators - -The file test_package/CMakeLists.txt should require CMake 3.15 by default: [cmake_minimum_required(VERSION 3.15)](https://cmake.org/cmake/help/latest/command/cmake_minimum_required.html). The CMake wrapper file can require CMake 2.8, because Conan recipe and the test package are totally separated. However, if [CMAKE_CXX_STANDARD](https://cmake.org/cmake/help/latest/variable/CMAKE_CXX_STANDARD.html) or [CXX_STANDARD](https://cmake.org/cmake/help/latest/prop_tgt/CXX_STANDARD.html#prop_tgt:CXX_STANDARD) is explicit, CMake 3.1 is mandatory. - -#### **#KB-H049: "CMAKE WINDOWS EXPORT ALL SYMBOLS"** - -The CMakeLists.txt definitions [CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS](https://cmake.org/cmake/help/v3.4/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS.html) and [WINDOWS_EXPORT_ALL_SYMBOLS](https://cmake.org/cmake/help/v3.4/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.html) are available since CMake 3.4 only. Any previous version will ignore it. - -#### **#KB-H050: "DEFAULT SHARED OPTION VALUE"** - -By default, all packages should be built as static library (the option ``shared`` is ``False`` in ``default_options``). However, some projects can be restricted to shared library only, for those cases, open a new [issue](https://github.com/conan-io/hooks/issues) to include the package name in the allowlist. - -#### **#KB-H051: "DEFAULT OPTIONS AS DICTIONARY"** - -The attribue [default_options](https://docs.conan.io/1/reference/conanfile/attributes.html#default-options) should be a dictionary, for example `default_options = {'shared': False, 'fPIC': True}`. - -#### **#KB-H052: "CONFIG.YML HAS NEW VERSION"** - -It's important to have new library version defined in both [config.yml](adding_packages/folders_and_files.md#configyml) and -[conandata.yml](adding_packages/folders_and_files.md#conandatayml), otherwise newly added version will not be checked and built -by CI and will not be available for download. - -#### **#KB-H053: "PRIVATE IMPORTS"** - -The recipe imports private Conan API, this is strongly discouraged - private imports are subjects to breaking changes. Avoid usage of private APIs, -request to publicly expose needed methods, if necessary. - -#### **#KB-H054: "LIBRARY DOES NOT EXIST"** - -Libraries which are listed on [Components](https://docs.conan.io/1/creating_packages/package_information.html#package-information-components) must be present in [libdirs](https://docs.conan.io/1/reference/conanfile/attributes.html#cpp-info). Check if the library name is correct, or if a library is only generated for a specific platform. - -#### **#KB-H055: "SINGLE REQUIRES"** - -Do not use [requirements()](https://docs.conan.io/1/reference/conanfile/methods.html#requirements) method and [self.requires](https://docs.conan.io/1/reference/conanfile/attributes.html#requires) attribute together in the same recipe. -The duality creates a heterogeneous way of solving dependencies, making it difficult to review and susceptible to prone errors. - -#### **#KB-H056: "LICENSE PUBLIC DOMAIN"** - -See [License Attribute](adding_packages/conanfile_attributes.md#license-attribute) for details. - -#### **#KB-H057: "TOOLS RENAME"** - -The [rename()](https://docs.conan.io/1/reference/conanfile/tools/files.html#conan-tools-rename) method will be the standard for Conan 2.0, and -also, it uses [robocopy](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy), which is safer on Windows. - -#### **#KB-H058: "ILLEGAL CHARACTERS"** - -Windows [naming conventions](https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions) and [reserved](https://en.wikipedia.org/wiki/Filename#Reserved_characters_and_words) characters must be avoided for file naming, otherwise the will not be supported on Windows. - -#### **#KB-H059: "CLASS NAME"** - -Generic class names can cause review confusion. To keep a better naming, it should use `Conan`. - -#### **#KB-H060: "NO CRLF"** - -Files with [CRLF](https://en.wikipedia.org/wiki/Newline) as endline can cause CI errors when building a package, due the conversion to LF and false detection from CI as changed file. -The [.gitattributes](https://git-scm.com/docs/gitattributes) file lists which files should be converted to LF when commit. However, if you want to enforce it in your local copy, you may run: - - > git config --local core.autocrlf false - > git config --local core.eol lf - -The [core.autocrlf](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) disabled means that git will not convert from CRLF to LF on commit. The [core.eol](https://git-scm.com/docs/git-config) sets the specific line ending to be used for every commit. - -#### **#KB-H062: "TOOLS CROSS BUILDING"** - -Replace all occurrences of `tools.cross_building(self.settings)` with [tools.cross_building(self)](https://docs.conan.io/1/reference/tools.html#tools-cross-building). -When cross building, conan needs to compare [self.settings](https://docs.conan.io/1/reference/conanfile/attributes.html#settings) and [self.settings_build](https://docs.conan.io/1/systems_cross_building/cross_building.html), which are attributes of `self`. - -#### **#KB-H064: "INVALID TOPICS"** - -An invalid [topic](https://docs.conan.io/1/reference/conanfile/attributes.html#topics) has been detected. Remove or rename it. -Right now, topic `conan` is considered redundant and it's not needed to explicitly list it within recipe. - -#### **#KB-H065: "NO REQUIRED_CONAN_VERSION"** - -The recipe misses [required_conan_version](https://docs.conan.io/1/reference/conanfile/other.html#requiring-a-conan-version-for-the-recipe) attribute. -It may happen due to the usage of new features within recipe (such as `strip_root` parameter of the [tools.get](https://docs.conan.io/1/reference/conanfile/tools/files/downloads.html#conan-tools-files-get) helper). -The policy of Conan Center Index to support only the latest version of the Conan Client, so it's safe to put the version Conan Center Index currently runs into the recipe. -Otherwise, it's not an easy task on its own to determine the minimal version that has to be specified: checking the Conan Client [Changelog](https://docs.conan.io/1/changelog.html), one has to know in which Conan Client releases all the attributes, methods, build helpers, etc. used by the recipe were first introduced, and then select the most recent of them. -Consider adding the following code: - -```python -required_conan_version = ">=1.43.0" # use the version that Conan Center Index runs - -class SomeRecipe(ConanFile): - ... - -``` - -See also: [Submitting a Package](adding_packages/README.md#submitting-a-package). - -#### **#KB-H066: "SHORT_PATHS USAGE"** - -The recipe missess [short_paths](https://docs.conan.io/1/reference/conanfile/attributes.html#short-paths) attribute. -It may happen due to the very long paths within source, build or package directories during the package creating. -Consider adding the following code: - -```python -class SomeRecipe(ConanFile): - ... - - short_paths = True -``` - -See also: [Maximum Path Length Limitation](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd). - -#### **#KB-H068: "TEST_TYPE MANAGEMENT"** - -In Conan 2.0, see [migration guide](https://docs.conan.io/1/migrating_to_2.0/recipes.html#changes-in-the-test-package-recipe), -the `test_package/conanfile.py` needs to declare the requirement being tested explicitly. To be prepared you -have to set the attribute `test_type="explicit"` (this will be ignored in 2.0) to make Conan activate the explicit -mode, then declaring the requirement using the `self.tested_reference_str` that contains the reference being tested. - -#### **#KB-H069: "TEST PACKAGE - NO DEFAULT OPTIONS"** - -This is to ensure the exact package that is built and uploaded is tested against. When `options` of `default_options` are modified in a -`test_package` it can possibly result in the graph being modified. The objective is to enforce quality of the packages and to avoid confusing -"missing packages" errors. - -#### **#KB-H070: "MANDATORY SETTINGS"** - -> :information_source: This rule was put in place as it was deemed safe for evaluation however there is room for improvement - -ConanCenter operates is profiles with a predefined list of settings, all of these much be present in the recipe to ensure `package_id`s are -computed correctly. Some libraries, for instance header-only, do not require all the settings and those should be deleted from the `package_id`. -This approach ensure consistency and reduces the learning curve. - -Recipes should include: - -```python -class SomeRecipe(ConanFile): - ... - - settings = "os", "compiler", "build_type", "arch" -``` - -- For header-only recipes ([example](https://github.com/conan-io/conan-center-index/blob/3a773e2d69ada3bd931252c43a48daf636ddfe87/recipes/eigen/all/conanfile.py#L35-L36)): - - ```python - def package_id(self): - self.info.header_only() - ``` - -There is the case when the package is header-only, but the options affects the generated artifact, (e.g. kanguru, pagmo2 ...), so you need to use `self.info.settings.clear()` instead. - -- @prince-chrismc This needs to a better example; For "tool" recipes ([example](https://github.com/conan-io/conan-center-index/blob/e604534bbe0ef56bdb1f8513b83404eff02aebc8/recipes/cmake/3.x.x/conanfile.py#L104-L105)) which only provide binaries, see [our packaging policy](adding_packages/build_and_package.md) for more, should do as follows: - - ```python - def package_id(self): - del self.info.settings.compiler - ``` - -#### **#KB-H071: "INCLUDE PATH DOES NOT EXIST"** - -It's erroneous to leave the default `include` directory when it's not present. Consider adding: - -```python -def package_info(self): - self.cpp_info.includedirs = [] -``` - -#### **#KB-H072: "PYLINT EXECUTION"** - -Pylint is executed by default over all `conanfile.py` files in ConanCenterIndex and it should not be skipped. It's an important tool which helps us keep a standard level of acceptance. Otherwise, it would be incredibly hard to review all recipes and keep them to the same level of standards. - -#### **#KB-H075: "REQUIREMENT OVERRIDE PARAMETER"** - -The [self.requires()](https://docs.conan.io/1/reference/conanfile/methods.html#requirements) allows to override a dependency version, forcing to use that version imposed by the recipe only. As a side-effect, dependencies can use different versions of the same project at the same package, which may cause unpredicted errors, like ABI incompatibility. For that reason, the `override` parameter is forbidden and should not be used. Instead, all dependencies should align their package versions, even when it's necessary to open more pull requests to update dependency versions. - -#### **#KB-H076: "EITHER STATIC OR SHARED OF EACH LIB"** - -It checks whether static & shared artifacts of the same lib are packaged together. Also, if there are tuples of (.a/.dylib) or (.a/.so) files with the same name. -So it works on Unix systems only, not Windows. Putting both same library name as shared and static in the very same package is considered an error, as it should be separated -and managed by the package option `shared`. - -#### **#KB-H077: "APPLE RELOCATABLE SHARED LIBS"** - -It checks whether installed shared libs are relocatable on Linux & macOS. All shared libs on macOS properly have `@rpath/` in install tree (@rpath token is supported since macOS 10.5 Leopard). - -## Deprecated errors - -The following errors from the hooks are deprecated and no longer reported: - -### **#KB-H047: "NO ASCII CHARACTERS"** - -According to PEP [263](https://www.python.org/dev/peps/pep-0263/), Unicode literals should only appear in Python code if the encoding is declared on one of the first two lines of the source file. Without such a declaration, any Unicode literal will cause a syntax error for Python 2 interpreters. diff --git a/docs/faqs.md b/docs/faqs.md index a1714a7a2b37b..d9f87971f7113 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -27,7 +27,6 @@ This section gathers the most common questions from the community related to pac * [What license should I use for Public Domain?](#what-license-should-i-use-for-public-domain) * [What license should I use for a custom project specific license?](#what-license-should-i-use-for-a-custom-project-specific-license) * [How do I flag a problem to a recipe consumer?](#how-do-i-flag-a-problem-to-a-recipe-consumer) - * [Why is a `build.check_min_cppstd` call not enough?](#why-is-a-buildcheck_min_cppstd-call-not-enough) * [What is the policy for adding older versions of a package?](#what-is-the-policy-for-adding-older-versions-of-a-package) * [What is the policy for removing older versions of a package?](#what-is-the-policy-for-removing-older-versions-of-a-package) * [Can I install packages from the system package manager?](#can-i-install-packages-from-the-system-package-manager) @@ -38,14 +37,10 @@ This section gathers the most common questions from the community related to pac * [How to protect my project from breaking changes in recipes?](#how-to-protect-my-project-from-breaking-changes-in-recipes) * [What's the policy on version ranges?](#whats-the-policy-on-version-ranges) * [How to consume a graph of shared libraries?](#how-to-consume-a-graph-of-shared-libraries) - * [How to watch only specific recipes?](#how-to-watch-only-specific-recipes) - * [Is it possible to disable Pylint?](#is-it-possible-to-disable-pylint) - * [How long can I be inactive before being removed from the authorized users list?](#how-long-can-i-be-inactive-before-being-removed-from-the-authorized-users-list) - * [What happens in case I change my user name?](#what-happens-in-case-i-change-my-user-name) * [Can we add package which are parts of bigger projects like Boost?](#can-we-add-package-which-are-parts-of-bigger-projects-like-boost) * [Can I add my project which I will submit to Boost?](#can-i-add-my-project-which-i-will-submit-to-boost) * [Can I add options that do not affect `package_id` or the package contents](#can-i-add-options-that-do-not-affect-package_id-or-the-package-contents) - * [Can I use full_package_mode for a requirement in my recipe?](#can-i-use-full_package_mode-for-a-requirement-in-my-recipe) + ## What is the policy on recipe name collisions? @@ -84,7 +79,7 @@ For libraries with a too generic name, like `variant`, the name of the organizat We know that using `find_package()` and relying on the CMake behavior to find the dependencies is something that should be avoided in favor of the information provided by the package manager. -Conan has an abstraction over the packages build system and description by using [generators](https://docs.conan.io/1/reference/generators.html). Those generators translate the information of the dependency graph and create a suitable file that can be consumed by your build system. +Conan has an abstraction over the packages build system and description by using generators. Those generators translate the information of the dependency graph and create a suitable file that can be consumed by your build system. In the past, we have found that the logic of some of the CMake's find/config or pkg-config files can lead to broken scenarios due to issues with: @@ -94,23 +89,21 @@ In the past, we have found that the logic of some of the CMake's find/config or - Hardcoded versions of dependencies as well as build options that make overriding dependencies from the consumer not possible. We believe that the package manager should be the one responsible to handle this information in order to achieve a deterministic and controlled behavior. -Regarding the integration with CMake, Conan already provides ways to consume those packages in the same way by using generators like [cmake_find_package](https://docs.conan.io/1/reference/generators/cmake_find_package.html)* or [cmake_find_package_multi](https://docs.conan.io/1/reference/generators/cmake_find_package.html) and features like [components](https://docs.conan.io/1/creating_packages/package_information.html#using-components) to define internal libraries of a package and generate proper CMake targets or [build_modules](https://docs.conan.io/1/reference/conanfile/attributes.html) to package build system utilities like CMake macros. +Regarding the integration with CMake, Conan already provides ways to consume those packages in the same way by using generators like [CmakeDeps](https://docs.conan.io/2/reference/tools/cmake/cmakedeps.html) to define internal libraries of a package and generate proper CMake targets or [cmake_build_modules](https://docs.conan.io/2/examples/graph/tool_requires/use_cmake_modules.html) to package build system utilities like CMake macros. -Defining the package information in the recipe is also useful in order to consume those packages from a different build system, for example using pkg-config with the [pkg_config generator](https://docs.conan.io/1/reference/generators/pkg_config.html). +Defining the package information in the recipe is also useful in order to consume those packages from a different build system, for example using pkg-config with the [PkgConfigDeps](https://docs.conan.io/2/reference/tools/gnu/pkgconfigdeps.html). Finally, by not allowing these files we make packages agnostic to the consumer as the logic of those files is not in the package but in the way the consumer wants the information. If you really think this is an issue and there is something missing to cover the use case of a library you want to contribute to ConanCenter, please do not hesitate to open an issue and we will be happy to hear your feedback. -\* Take a look at the integrations section to learn more: https://docs.conan.io/1/integrations/build_system/cmake/cmake_find_package_generator.html - ## Why recipes that use build tools (like CMake) that have packages in Conan Center do not use it as a build require by default? We generally consider tools like CMake as a standard tool to have installed in your system. Having the `cmake` package as a build require in **all** the recipes that use it will be an overkill, as every build requirement is installed like a requirement and takes time to download. However, `cmake` could still be useful to use in your profile: ``` [tool_requires] -cmake/3.17.2 +cmake/[>=3.15 <4] ``` Other packages using more unusual build tools should refer to the [Dependencies - Adding Build Requirements](adding_packages/dependencies.md#build-requirements) section for more information. @@ -121,9 +114,9 @@ The C++ ecosystem has a lot of rare, unique and obscure build systems. Some of t The recipe is expected to encode the specifics of the build system, mapping the `settings`, `options` for the binary configuration, and also mapping `self.dependencies` so the build system can locate the dependencies libraries as required. For these cases, contributors are asked to help reviewers as much as possible as it's likely we will not have expertise. -> TODO: Add a link to docs.conan.io which explains how to write a custom generator in the 2.0 sense +In Conan 2.x is possible to use [custom generatros](https://docs.conan.io/2/reference/extensions/custom_generators.html). But this feature is not allowed in conan-center-index. -For quality assurance the build service is expected to be green and the [hooks](https://github.com/conan-io/hooks) will ensure the package contents match what is expected given the options. These recipes are more likely to have +For quality assurance the build service is expected to be green and the hooks will ensure the package contents match what is expected given the options. These recipes are more likely to have inconsistency with other recipes but make for excellent contributions. ## Are python requires allowed in the `conan-center-index`? @@ -141,12 +134,12 @@ Currently, the Jenkins orchestration library for this build service is not avail ## Why not x86 binaries? -As described in the [Supported platforms and configurations](supported_platforms_and_configurations.md), only the x86_64 architecture is available for download, the rest must be built from sources. The reasons behind this decision are: +Only the x86_64 architecture is available for download, the rest must be built from sources. The reasons behind this decision are: * Few users need different pre-built packages that are not x86_64 packages, this number is less than 10% of total users (data obtained through the download counter from Bintray), and tends to decrease over the years; * Some OS are putting the x86 as obsolete, examples [macOS](https://developer.apple.com/documentation/macos-release-notes/macos-catalina-10_15-release-notes) and Ubuntu 20.04; * For security reasons, most companies build their own packages from sources, even if they already have a pre-built version available, which further reduces the need for extra configurations; -* Each recipe results in around 130 packages, and this is only for x86_64, but not all packages are used, some settings remain with zero downloads throughout their life. So, imagine adding more settings that will rarely be used, but that will consume more resources as time and storage, this leaves us in an impractical situation. +* Each recipe results in several packages, and this is only for x86_64, but not all packages are used, some settings remain with zero downloads throughout their life. So, imagine adding more settings that will rarely be used, but that will consume more resources as time and storage, this leaves us in an impractical situation. ### But if there are no packages available, what will the x86 validation look like? @@ -162,7 +155,7 @@ Yes! You can learn more about default options in [Packaging Policy](adding_packa The project initially decided not to support the PDB files primarily due to the size of the final package, which could add an exaggerated size and not even used by users. In addition, PDB files need the source code to perform the debugging and even follow the path in which it was created and not the one used by the user, which makes it difficult to use when compared to the regular development flow with the IDE. -However, there are ways to get around this, one of them is through the [/Z7](https://docs.microsoft.com/en-us/cpp/build/reference/z7-zi-zi-debug-information-format) compilation flag, which can be passed through [environment variables](https://docs.microsoft.com/en-us/cpp/build/reference/cl-environment-variables). You can use your [profile](https://docs.conan.io/1/reference/profiles.html#package-settings-and-env-vars) to customize your compiler command line. +However, there are ways to get around this, one of them is through the [/Z7](https://docs.microsoft.com/en-us/cpp/build/reference/z7-zi-zi-debug-information-format) compilation flag, which can be passed through [environment variables](https://docs.microsoft.com/en-us/cpp/build/reference/cl-environment-variables). You can use your [profile](https://docs.conan.io/2/reference/config_files/profiles.html) to customize your compiler command line. ### Why is there no option for PDB, as there is for fPIC? @@ -204,7 +197,7 @@ After one month, we will welcome a PR removing the option that was deprecated. ## Can I split a project into an installer and library package? -No. Some projects provide more than a simple library, but also applications. For those projects, both libraries and executables should be kept together under the same Conan package. In the past, we tried to separate popular projects, like Protobuf, and it proved to be a complex and hard task to be maintained, requiring custom patches to disable parts of the building. Also, with the [context](https://docs.conan.io/1/systems_cross_building/cross_building.html#conan-v1-24-and-newer) feature, we can use the same package as build requirement, for the same build platform, and as a regular requirement, for the host platform, when cross-building. It's recommended using 2 profiles in that case, one for build platform (where the compilation tools are being executed) and one for host platform (where the generated binaries will run). +No. Some projects provide more than a simple library, but also applications. For those projects, both libraries and executables should be kept together under the same Conan package. In the past, we tried to separate popular projects, like Protobuf, and it proved to be a complex and hard task to be maintained, requiring custom patches to disable parts of the building. Also, with the [context](https://docs.conan.io/2/reference/commands/install.html#reference-commands-install-composition) feature, we can use the same package as build requirement, for the same build platform, and as a regular requirement, for the host platform, when cross-building. It's recommended using 2 profiles in that case, one for build platform (where the compilation tools are being executed) and one for host platform (where the generated binaries will run). ## Should recipes export a recipe's license? @@ -224,35 +217,17 @@ Regardless of why, if the recipe detects a problem where binaries might not be g incorrect packages which do not work as intended. Use `ConanInvalidConfiguration` which is specially support in ConanCenter. ```py -raise ConanInvalidConfiguration(f"The project {self.ref} requires liba.enable_feature=True.") -``` - -You should not be using the `self.output.warn` and it is not enough to alter consumers or stop the build service. - -## Why is a `build.check_min_cppstd` call not enough? - -Very often C++ projects require a minimum standard version, such as 14 or 17, in order to compile. Conan offers tools which enable checking the relevant setting is enabled and above this support for a certain version is present. Otherwise, it uses the compiler's default. - -```python -def configure(self): - build.check_min_cppstd(self, 14) 👈 Wrong! +raise ConanInvalidConfiguration(f"The project {self.ref} requires liba.enable_feature=True. See ") ``` -This fails to cover the vast number of use cases for the following reasons: +You should not be using the `self.output.warning` and it is not enough to alter consumers or stop the build service. -1. `cppstd` is not configured in the `--detect`ed profiles generated by Conan, the majority of users simply do not have this setting. -2. A shocking number of projects override this setting within their respective build scripts, this setting does not get applied in those cases. -3. Conan-Center-Index does **not** manage the `cppstd` setting for the compilers it supports to generate binaries. +Also, need to point upstream's issue/PR related to the same problem. In case it's a limitation in the recipe, the same should be clear and be merged without full support: -```python -def validate(self): - # 👇 Correct - if self.settings.compiler.cppstd: - build.check_min_cppstd(self, 14) +```py +raise ConanInvalidConfiguration(f"{self.ref} Conan recipe does not support Windows. Contributions are welcome!") ``` -As a result, all calls to `build.check_min_cppstd` must be guarded by a check for the setting and the only way to ensure the C++ standard is to check the compiler's version to know if it offers sufficient support. An example of this can be found [here](https://github.com/conan-io/conan/issues/8002). - ## What is the policy for adding older versions of a package? See [Adding older versions](adding_packages/sources_and_patches.md#adding-old-versions) for details. @@ -264,10 +239,8 @@ See [Removing older versions](adding_packages/sources_and_patches.md#removing-ol ## Can I install packages from the system package manager? It depends. You can not mix both regular projects with system packages, but you can provide package wrappers for system packages. However, Conan can not track system packages, like their version and options, which creates a fragile situation where affects libraries and binaries built in your package but can not be totally reproduced. -Also, system package managers require administrator permission to install packages, which is not always possible and may break limited users. Moreover, more than one Conan package may require the same system package and there is no way to track their mutual usage. -The hook [KB-H032](error_knowledge_base.md#KB-H032) does not allow `system_requirement` nor `SystemPackageTool` in recipes, to avoid mixing both regular projects with -system packages at same recipe. +Also, system package managers require administrator permission to install packages, which is not always possible and may break limited users. Moreover, more than one Conan package may require the same system package and there is no way to track their mutual usage. There are exceptions where some projects are closer to system drivers or hardware and packaging as a regular library could result in an incompatible Conan package. To deal with those cases, you are allowed to provide an exclusive Conan package which only installs system packages, see the [How-to](adding_packages/build_and_package.md#system-packages) for more. @@ -358,7 +331,7 @@ Since these references will be never available in ConanCenter, they will be deac If consumers activate the option explicitly (`with_intel_mkl=True`), Conan will fail because of the unknown reference. -Consumers may use an [override](https://docs.conan.io/1/using_packages/conanfile_txt.html#overriding-requirements) facility in order to use their own private references for Intel MKL, IPP or DNN libraries. +Consumers may use an [override](https://docs.conan.io/2/reference/conanfile/methods/requirements.html#override) facility in order to use their own private references for Intel MKL, IPP or DNN libraries. For instance, if you have a private reference `intel-mkl/2021@mycompany/stable`, then you may use the following override in your `conanfile.txt`: @@ -371,7 +344,7 @@ intel-mkl/2021@mycompany/stable This repository and the CI building recipes is continuously pushing to new Conan versions, sometimes adopting new features as soon as they are released -([Conan client changelog](https://docs.conan.io/1/changelog.html)). +([Conan client changelog](https://docs.conan.io/2/changelog.html)). You should expect that latest revision of recipes can introduce breaking changes and new features that will be broken unless you also upgrade Conan client (and sometimes you will @@ -387,58 +360,12 @@ See [Dependencies Version Ranges](adding_packages/dependencies.md#version-ranges ## How to consume a graph of shared libraries? -When the CI builds packages with `shared=True`, it applies the option only to the package being created, but not to -the requirements. As the default value for the `shared` option is usually `False`, you can expect that the dynamic -library that has just being generated has linked all its requirements as static libraries. - -It is important to remark the default [package id mode](https://docs.conan.io/1/creating_packages/define_abi_compatibility.html#versioning-schema) -used by Conan (which is the same default used by ConanCenter): `semver_direct_mode`. With this default only the major -version of the requirements is encoded in the package ID. - -The two previous behaviors together can lead to unexpected results for a user that want to consume a graph of -dependencies as shared libraries from ConanCenter. They might think that using `*:shared=True` in their profile is -enough, and indeed Conan will retrieve from ConanCenter all the dynamic libraries for all the graph of dependencies, but -**all of them will contain the logic of their respective requirements embedded in the dynamic library**, and this -logic is embedded at the time of building, so it might not match the version of the requirements that was resolved -by Conan, and for sure, the other dynamic libraries won't be used, only the ones linked directly by the consumer -project. See a more detailed [example here](https://github.com/conan-io/conan/issues/9712). - -In order to consume all those libraries as shared ones, building from sources is needed. This can be -easily achievable using `*:shared=True` in the _host_ profile and `--build` in the install command. With these inputs, -Conan will build from sources all the packages and use the shared libraries when linking. - -> **Note**: If you are hosting your own recipes, the proper solution for recipes would be to use something like -> [`shared_library_package_id`](https://docs.conan.io/1/reference/conanfile/methods.html?highlight=shared_library_package_id#self-info-shared-library-package-id), -> that will encode this information in the package ID and ensure that any change in the static libraries that are -> embedded into a shared one is taken into account when computing the package ID. -> -> In this repository we are not using it, because it will lead to many missing packages, making it impossible -> for the CI to actually build consumers in PRs. +When the CI builds packages with the option `*/*:shared=True`, this option is applied not only to the package being created but also to its requirements. +Since the default value for the shared option is typically `False`, you can generally expect that the dependency graph will consist of static libraries, +except for packages specifically defined with `package_type = "shared-library"`. -## How to watch only specific recipes? - -The [Code Owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) feature requires -write permission for any listed user in the file `.github/CODEOWNERS`, which makes it impossible to be accepted by Conan. However, that file is still important as it can be re-used in -a future Github Action to parse and communicate users. Meanwhile, there is the project https://app.github-file-watcher.com/, -which is able to notify users, but only after merging to the master branch. Feel free to contribute to a new Github Action that -implements a file watcher feature. - -## Is it possible to disable Pylint? - -No. The [pylint](v2_linter.md) has an important role of keeping any recipe prepared for [Conan v2 migration](v2_migration.md). In case you are having -difficult to understand [linter errors](linters.md), please comment on your pull request about the problem to receive help from the community. - -## How long can I be inactive before being removed from the authorized users list? - -Please, read [Inactivity and user removal section](adding_packages/README.md#inactivity-and-user-removal). - -## What happens in case I change my user name? - -Your Github user name is used to identify you in the authorized users list. If you change your user name, you will need to communicate or, in the #4, or opening a new issue. -Otherwise, the CI will not be able to find you and will not build your pull requests. -In case you change you user name just after asking for authorization in #4, please, communicate the change in the same issue. -Users are revised before being added to the authorized users list, in case the user name is not found in #4, it will be asked in the pull request `Update authorized users list`. -If the user does not answer, the user will be moved to the `waitlist_users.yml` file, until having further communication. +To work with a graph that includes only shared libraries, you must explicitly set the `-o */*:shared=True` option in your conan install command. +This ensures that the necessary shared libraries are included in your build environment. ## Can we add package which are parts of bigger projects like Boost? @@ -461,27 +388,3 @@ Generally no, these sorts of options can most likely be set from a profile or do and would otherwise dynamically embed this into the CMake config files or generated pkg-config files then it should be allowed. Doing so requires [deleting the option from the `package_id`](adding_packages/conanfile_attributes.md#removing-from-package_id). - -## Can I use full_package_mode for a requirement in my recipe? - -For some irregular projects, they may need to be aligned when being used as a requirement, using the very same version, options, and settings and maybe not mixing shared with static linkage. -Those projects usually break between patch versions and are very sensitive, so we can not use different versions through Conan graph dependencies, -otherwise, it may result in unexpected behavior or even runtime errors. - -A very known project is GLib, which requires the very same configuration to prevent multiple instances when using static linkage. -As a solution, we could consume GLib on full package id mode, like: - -```python -def package_id(self): - self.info.requires["glib"].full_package_mode() -``` - -Perfect solution on the consumer side, but there is a side-effect: CCI will not re-generate all involved packages for any change in the dependencies graph with which glib is associated, which means, users will start to see **MISSING_PACKAGES** error during their pull requests. -As a trade-off, it would be necessary to update all recipes involved, by opening new PRs, -then it should generate new packages, but it takes many days and still is a process that is not supported by CCI internally. - -To have more context about it, please, visit issues #11684 and #11022 - -In summary, we do not recommend `full_package_mode` or any other custom package id mode for requirements on CCI, it will break other PRs soon or later. -Instead, prefer using `shared=True` by default, when needed. -Also, when having a similar situation, do not hesitate in opening an issue explaining your case, and ask for support from the community. diff --git a/docs/labels.md b/docs/labels.md deleted file mode 100644 index b5f3f5d9cf396..0000000000000 --- a/docs/labels.md +++ /dev/null @@ -1,96 +0,0 @@ -# Labels - -We use [GitHub labels](https://github.com/conan-io/conan-center-index/labels) to signal the status -of pull-requests and issues. Here you can find more information about the ones that have some -special meaning: - - -## Contents - - * [Bump dependencies](#bump-dependencies) - * [Bump version](#bump-version) - * [C3I Conan2 Ready](#c3i-conan2-ready) - * [Infrastructure](#infrastructure) - * [Stale](#stale) - * [Unexpected Error](#unexpected-error) - * [User-approval pending](#user-approval-pending) - * [Library Request](#library-request) - * [Question](#question) - * [Upstream Update](#upstream-update) - * [conan.io/center](#conaniocenter) - -## Bump dependencies - -Label [`Bump dependencies`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Bump+dependencies%22+) -is assigned by the bot to pull-requests that are just upgrading the version of the requirements that were already in the -recipe. - -> These pull-requests will be merged right away without requiring any approval (CI and CLA checks must have passed). - -If the pull request modifies anything else, the label won't be assigned, we need to be very careful about false positives. - -## Bump version - -Label [`Bump version`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Bump+version%22) -is assigned by the bot to pull-requests that are just adding a new version of the library. The new version should satisfy -some extra conditions: sources should provide from the same URL domain as previous versions. -For now, only [SEMVER](https://semver.org/#semantic-versioning-200) and `` are acceptable version formats. - -> These pull-requests will be merged right away without requiring any approval (CI and CLA checks must have passed). - -If the pull request modifies anything else, the label won't be assigned, we need to be very careful about false positives. - -## C3I Conan2 Ready - -Label [`c3i-conan2-ready`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22c3i-conan2-ready%22) -is assigned by the bot to pull-requests that are just adding a new package references which passed by Conan v2 and are not listed in `.c3i/conan_v2_ready_references.yml`. -This is a regression test, in case package is working with Conan v2, it can not be merged in a future pull request in case of failure. - -> These pull-requests will be merged right away without requiring any approval (CI and CLA checks must have passed). - -Only team members can open a pull request with these changes. - -## Infrastructure - -Label [`infrastructure`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3Ainfrastructure) is -manually assigned to pull requests that are waiting for something on the infrastructure side. Usually they are blocked and -cannot succeed because they need some tools, more memory,... these pull requests won't be marked as `stale`. - -## Stale - -Label [`stale`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3Astale) is assigned to -pull requests without any activity during a long period of time. These pull requests will be closed if they don't get -any further activity. - -## Unexpected Error - -Label [`Unexpected Error`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Unexpected+Error%22) -is assigned by the CI when the process finishes abnormally. -Usually it is some _random_ internal error and it won't happen next time the CI runs. -The CI will re-start your build automatically, the Github check `continuous-integration/jenkins/pr-merge` -will be changed to the status `Pending — This commit is being built` to signalize as running. - -> **Note**: Manually restarting a new build, by closing/opening the PR, will be added to the end of the CI build queue. - -## User-approval pending - -Label [`User-approval pending`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22User-approval+pending%22) -signals the pull request that have been submitted by an user who is not yet approved in ConanCenter. Once the user is -approved these pull requests will be triggered again automatically. - -## Library Request - -Request a new package to be created. - -## Question - -Further information is requested. Usually these are for issue where help is needed to solve a specific issue. These are a great way -to look for advice or recommendation about making changes to recipes. - -## Upstream Update - -Request a bump of a new package version. - -## conan.io/center - -Issues and features related to Web UI. diff --git a/docs/linters.md b/docs/linters.md deleted file mode 100644 index 075f373f209ef..0000000000000 --- a/docs/linters.md +++ /dev/null @@ -1,34 +0,0 @@ -# ConanCenterIndex Linters - -Some linter configuration files are available in the folder [linter](../linter), which are executed by Github Actions -and are displayed during [code review](https://github.com/features/code-review) as annotations, to improve recipe quality. -They consume python scripts which are executed to fit CCI rules. Those scripts use [astroid](https://github.com/PyCQA/astroid) -and [pylint](https://pylint.pycqa.org/en/latest/) classes to parse Conan recipe files and manage their warnings and errors. - -Pylint by itself is not able to find ConanCenterIndex rules, so astroid is used to iterate over a conanfile's content and -validate CCI requirements. Pylint uses an [rcfile](https://pylint.pycqa.org/en/latest/user_guide/configuration/index.html) -to configure plugins, warnings and errors which should be enabled or disabled. - - -## Contents - - * [Understanding the different linters](#understanding-the-different-linters) - * [Running the linters locally](#running-the-linters-locally) - * [Pylint configuration files](#pylint-configuration-files) - -## Understanding the different linters - -There's a three classes of linters currently in place for ConanCenterIndex - -- ConanCenter Hook - these are responsible for validating the structure of the recipes and packages. -- Pylint Linter - these are used to ensure the code quality and conventions of a recipes (i.e `conanfile.py`) -- Yaml Checks - stylistic guidance and schema validation check for support files and best practices - -## Running the linters locally - -Check the [Developing Recipes](developing_recipes_locally.md) for more information on each of the three linters. - -## Pylint configuration files - -- [Pylint Recipe](../linter/pylintrc_recipe): This `rcfile` lists plugins and rules to be executed over all recipes (not test package) and validate them. -- [Pylint Test Package Recipe](../linter/pylintrc_testpackage): This `rcfile` lists plugins and rules to be executed over all recipes in test package folders only: diff --git a/docs/review_process.md b/docs/review_process.md index b5abea3471d39..bae426df1eaf6 100644 --- a/docs/review_process.md +++ b/docs/review_process.md @@ -1,133 +1,69 @@ # Review process Behind the scenes of conan-center-index, there is a heavily automated process to test and merge pull requests. -As there is a lot of activity from many users and various bots (e.g. bumping versions or updating conventions), many PRs are opened every day. +As there is a lot of activity from many users and many PRs are opened every day. conan-center-index tries to make the process as smooth and simple as possible for the contributors, providing feedback in PRs. In this document will explain the review process in detail. ## Contents - * [conan-center-bot](#conan-center-bot) * [Green build](#green-build) * [Unexpected error](#unexpected-error) * [Avoiding conflicts](#avoiding-conflicts) - * [Draft](#draft) * [Getting your pull request reviewed](#getting-your-pull-request-reviewed) * [Rule of 2 reviews](#rule-of-2-reviews) * [Reviews from others](#reviews-from-others) * [Addressing review comments](#addressing-review-comments) - * [Automatic Merges](#automatic-merges) - * [Merge](#merge) - * [Package available to consume](#package-available-to-consume) - * [Updating web front end](#updating-web-front-end) + * [Package available to consume](#package-available-to-consume) + * [Updating web front end](#updating-web-front-end) * [Stale PRs](#stale-prs) -## [conan-center-bot](https://github.com/conan-center-bot) - -In general, reviews are driven by the automated [bot](https://github.com/conan-center-bot). The bot is responsible for: - -- Adding or removing labels (such as [Bump version](https://github.com/conan-io/conan-center-index/pulls?q=is%3Apr+is%3Aopen+label%3A%22Bump+version%22) or [Docs](https://github.com/conan-io/conan-center-index/pulls?q=is%3Apr+is%3Aopen+label%3ADocs)). -- Writing comments (most of the time, it's a build status, either failure with logs or success). -- Merging pull requests. -- Closing issues (after merging pull requests with GitHub keywords). -- Starting CI builds. -- Assigning CI status (running/failed/successful). - ## Green build The first important prerequisite is ensuring your PR is green (build is successful). It requires a bit of patience, because there are many PRs running and we're building a lot of configurations for a numerous versions of libraries. -Keep attention to the error messages from the bot, and address all the build failures. -The bot tries to provide all the helpful information needed to understand and reproduce an issue, such as: - -- The profile that failed (in other words, the configuration: architecture, operation system, compiler, etc.) -- Failed command line (it might have failed on early stages, like recipe syntax errors, hook errors or later stages, like build or test). -- Logs containing the actual output of the build process (note that some logs like *configure.log* or *CMakeError.log* are not captured, only stdout/stderr). +Keep attention to the error messages from the check tab on your PR, and address all the build failures. +The checks tries to provide all the helpful information needed to understand and reproduce an issue. -If you struggle to fix build errors yourself, you may want to ask for help from other users by mentioning (`@`) individual users in the pull request comments. +If you struggle to fix build errors yourself, you may want to ask for help from other users by mentioning (`@conan-io/barbarians`) group in the pull request comments. ### Unexpected error -Sometimes, build fails with `Unexpected error` message. This indicates an infrastructure problem, and usually it's unrelated to the changes within PR itself. - -To learn more, checkout the [label definition](labels.md#unexpected-error). +Sometimes, build fails with an unexpected error (e.g Pre-Checks hangs forever). This indicates an infrastructure problem, and usually it's unrelated to the changes within PR itself. When this occurs, please, ping `@conan-io/barbarians` in your PR describing your situation. ## Avoiding conflicts -Right now, neither GitHub itself nor conan-center-bot notify about merge conflicts, so it's the contributor's responsibility to periodically check for the conflicts. Pull Requests that have merge conflicts can't be merged, and all the conflicts have to be resolved first. - -Please [synchronize your branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to take into account the latest changes in the main branch. This is important for ConanCenter to ensure it is building the correct recipe revision, see [this comment](https://github.com/conan-io/conan-center-index/pull/8797#discussion_r781993233) for details. One trick is to look out for comments from the [Community's Conflict PR Bot](https://github.com/prince-chrismc/conan-center-index/blob/patch-41/docs/community_resources.md#bots) which can anticipate possible problems. +Right now, the check `Related Pull Requests` shows other PRs that are affecting the recipe and may result in conflicts, so it's the contributor's responsibility to periodically check for the conflicts. Pull Requests that have merge conflicts can't be merged, and all the conflicts have to be resolved first. -## Draft +In case a PR that affects your recipe is merged first, then, you have to [synchronize your branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to take into account the latest changes in the main branch. This is important for ConanCenter to ensure it is building the correct recipe revision. -Draft pull requests are also never merged, and they won't likely be reviewed. -Once you're done with your changes, remember to convert from "Draft" to "Normal" pull request. +One trick is to look the [List of open pull requests broken down by recipe](https://github.com/conan-io/conan-center-index/discussions/24240) which can anticipate possible problems. ## Getting your pull request reviewed -Each PR must be reviewed by several reviewers before it will be merged. It cannot be just reviews from anyone, we have two categories of reviewers: - -- Official reviewers: these are active team members who are responsible for developing Conan, ConanCenter, and ConanCenterIndex. -- Community reviewers: this list includes former Conan team members and ConanCenterIndex contributors who are very active and proven to be trusted - they frequently submit pull requests and provide their own useful reviews - -The list or reviewers, located [here](../.c3i/reviewers.yml), -is not constant and will change periodically based on contribution. -That also means **you can be included in this list** as well - submit PRs and provide reviews, and in time you may be added as a trusted contributor. - -> **Note**: GitHubs user interface does not support such custom rules so you should not rely solely on the message it provides. +Each PR must be reviewed before it will be merged. Extra reviews are welcome and appreciated, but the Conan team reviews are required. ### Rule of 2 reviews -At least 2 approving reviews are required, and at least one of them has to be from the official reviewers. -So, it might be 1 official + 1 community, or 2 official, but it couldn't be just 2 community reviews. -Approvals are only counted if they are associated with the latest commit in the PR, while "Change requested" ones (from the Conan team) will persist even if there are new commits. Don't hesitate to dismiss old reviews if the issues have already been addressed. +At least 2 approving reviews are required from maintainers are mandatory to merge a PR. -Pull requests labelled as [`Bump version`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Bump+version%22) -or [`Bump dependencies`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Bump+dependencies%22+) require **just 1 approving review from an official reviewer**. Community reviewers are not required but are still welcome. +Approvals are only counted if they are associated with the latest commit in the PR, while "Change requested" ones (from the Conan team) will persist even if there are new commits. -### Reviews from others +### Reviews from community -All reviews are still valuable and very helpful. Even if you're not listed as an official or community reviewer, **your reviews are very welcome**, so please do not hesitate to provide them. +All reviews are still valuable and very helpful. ### Addressing review comments Please ensure to address the review comments and respond to them in order to get your PR approved and finally merged. -It doesn't always mean accepting all the suggestions, but at least providing a response, so people can understand your position. - -## Automatic Merges - -The bot runs Automatic Merges every 20 minutes. Currently, it can only merge a single PR in this timeframe, so there is a theoretical limit of ~70 PRs merged per day (in practice, it's even less for reasons listed below). -PR is selected for the merge only if: - -- Author is already [approved](https://github.com/conan-io/conan-center-index/issues/4). -- Author has signed the [CLA](https://cla-assistant.io/conan-io/conan-center-index). -- PR is not a Draft. -- PR has a green status (successful build). -- PR doesn't have merge conflicts with `master` branch. -- PR has approved reviews (as described above). -- PR does not have any [official reviewers](#official-reviewers) requesting changes -- Master build is not running already (see below) - -If these conditions are fulfilled, the PR is merged (associated issues are automatically closed), and then the build of `master` is launched. - -The conan-center-bot will perform a [squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits). You don't need to rebase -your pull request, we ask you not to do it because it will dismiss any reviews and the reviewer will need to restart. - -### Merge - -After merging a pull request, if an actual merge happened (for instance, the recipe changed in PR was already updated in `master` by the time PR merged), -it will introduce a new recipe revision. Therefore, the build should be run one more time, so the `master` build is launched. -In reality this could happen frequently enough if there are multiple PRs aiming to update the same recipe (even if they touch different files in the same recipe). -Such builds can take hours for big packages (like boost), blocking other merges for a while. -So we really appreciate it if changes in `master` to the same recipe are already merged into the proposed PR. +Be polite and open to suggestions. Also, please, read the [code of conduct](code_of_conduct.md) to understand the expected behavior in the community. -### Package available to consume +## Package available to consume -New packages are promoted from the internal repository to ConanCenter. This process is an internal Artifactory promotion that is quite -fast, nevertheless there are some caches and CDNs that need to be invalidated and propagated before the package is finally available for consumption. -The process can take several minutes, so please, consider a *grace period* and understand that the package won't be available immediately. +New packages are promoted from the internal repository to ConanCenter. +The process can take few minutes, so please, consider a *grace period* and understand that the package won't be available immediately. -### Updating web front end +## Updating web front end [ConanCenter](https://conan.io/center/) doesn't directly pull the information from conan-center-index repository. Instead, it's updated by the conan center CI job as its own step. The metadata from the conan repository is @@ -136,4 +72,4 @@ That may explain the fact there are moments when the information showed in the f ## Stale PRs -Conan Center Index uses [stale bot](https://github.com/probot/stale) to close abandoned pull requests. It's configured by [stale.yml](../.github/stale.yml). When a pull request gets stale, we encourage anyone to take ownership of the PR (even submit changes to the author's branch if possible) so existing work doesn't get lost when the pull request is closed without merging. +Conan Center Index uses [stale bot](https://github.com/probot/stale) to close abandoned pull requests. It's configured by [stale.yml](../.github/workflows/stale.yml). When a pull request gets stale, we encourage anyone to take ownership of the PR (even submit changes to the author's branch if possible) so existing work doesn't get lost when the pull request is closed without merging. diff --git a/docs/supported_platforms_and_configurations.md b/docs/supported_platforms_and_configurations.md index 6b1a32e9557cc..d04d4186e6d13 100644 --- a/docs/supported_platforms_and_configurations.md +++ b/docs/supported_platforms_and_configurations.md @@ -4,7 +4,7 @@ ## Contents * [Introduction](#introduction) - * [Build Images](#build-images) + * [Future Steps](#future-steps) * [Windows](#windows) * [Linux](#linux) * [MacOS](#macos) @@ -13,26 +13,28 @@ The pipeline iterates a fixed list of profiles for every Conan reference, it computes the packageID for each profile and discard duplicates. Then it -builds the packages for the remaining profiles and upload them to +builds the packages for the remaining profiles and promoted them to [JFrog ConanCenter](https://conan.io/center/) once the pull-request is merged. -Because duplicated packageIDs are discarded, the pipeline iterates the -profiles always in the same order and the profiles selected to build when -there is a duplicate follow some rules: +Currently, given the following supported platforms and configurations we +are generating **30 different binary packages for a C++ library**. - * Static linkage (option `shared=False`) is preferred over dynamic linking. - * On Windows, `MT/MTd` runtime linkage goes before `MD/MDd` linkage. - * Optimized binaries (`build_type=Release`) are preferred over its _debug_ counterpart. - * Older compiler versions are considered first. - * In Linux, GCC is iterated before Clang. -Currently, given the following supported platforms and configurations we -are generating **136 different binary packages for a C++ library** -and **88 for a C library**. +### Future Steps -### Build Images +With the introduction of our new, more flexible pipeline, +we will be implementing several enhancements to improve our build capabilities and support +a wider range of development environments. The following steps will be taken: -For more information see [conan-io/conan-docker-tools](https://github.com/conan-io/conan-docker-tools) +- Incorporate additional modern GCC versions for Linux builds: + - By adding the latest versions of GCC, we aim to ensure compatibility with the newest C++ standards and features, allowing developers to leverage the latest advancements in the language. +- Integrate more recent Clang versions for Linux builds: + - Clang is known for its fast compilation times and excellent diagnostics. By including more modern versions, we will provide developers with improved performance and better error reporting, enhancing the overall development experience. +- Include updated Apple-Clang versions for macOS builds: + - As macOS continues to evolve, it is crucial to support the latest Apple-Clang versions. This will ensure that our builds are optimized for the latest macOS features and provide a seamless experience for developers working in the Apple ecosystem. +- Add support for Android builds to the pipeline: + - Expanding our pipeline to include Android builds will enable developers to create and test applications for mobile platforms more efficiently. + This addition will help streamline the development process and ensure that our tools are versatile and adaptable to various environments. ## Windows @@ -42,35 +44,28 @@ For more information see [conan-io/conan-docker-tools](https://github.com/conan- > WinSDK version is rolled periodically as [discussed previously](https://github.com/conan-io/conan-center-index/issues/4450). > Please open an issue in case it needs to be updated. - Compilers: Visual Studio: - - - 2019 (19.29.30148) - -- Release (MT/MD) and Debug (MTd, MDd) + - Architectures: x86_64 -- Build types: Release, Debug -- Runtimes: MT/MD (Release), MTd/MDd (Debug) +- Build types: Release +- Runtime: dynamic (MD) - Options: - - Shared, Static (option `"shared": [True, False]` in the recipe when available) - - Header Only (option `"header_only": [True, False]` if available) - -> :warning: The profile with the option `shared=True` and runtime `MT/MTd` is not built. + - Shared, Static (option `"*/*:shared": [True, False]` in the recipe when available) + - Header Only (option `"&:header_only": [True, False]` is only added with the value True) ## Linux - Python: 3.7.17 -- CMake: 3.15.7, 3.18.6 (same version expected after all use [new docker images](https://github.com/conan-io/conan-docker-tools/tree/master/modern)) +- CMake: 3.15.7, 3.18.6 (same version expected after all use [new docker images](https://github.com/conan-io/conan-docker-tools/tree/master/images)) - Compilers: - - GCC versions: 5, 7, 9, 11 - - Clang versions: 13 + - GCC versions: 11 - C++ Standard Library (`libcxx`): - - GCC compiler: `libstdc++`, `libstdc++11` - - Clang compiler: `libstdc++`, `libc++` + - GCC compiler: `libstdc++11` - Architectures: x86_64 -- Build types: Release, Debug +- Build types: Release - Options: - - Shared, Static (option `"shared": [True, False]` in the recipe when available) - - Header Only (option `"header_only": [True, False]` is only added with the value True) + - Shared, Static (option `"*/*:shared": [True, False]` in the recipe when available) + - Header Only (option `"&:header_only": [True, False]` is only added with the value True) ## MacOS @@ -81,7 +76,7 @@ For more information see [conan-io/conan-docker-tools](https://github.com/conan- - Macos deployment target (`minos`): 11.0 - C++ Standard Library (`libcxx`): `libc++` - Architectures: armv8 -- Build types: Release, Debug +- Build types: Release - Options: - - Shared, Static (option ``"shared": [True, False]`` in the recipe when available) - - Header Only (option `"header_only": [True, False]` is only added with the value True) + - Shared, Static (option `"*/*:shared": [True, False]` in the recipe when available) + - Header Only (option `"&:header_only": [True, False]` is only added with the value True) diff --git a/docs/v2_linter.md b/docs/v2_linter.md deleted file mode 100644 index 3d6e3a3f6be33..0000000000000 --- a/docs/v2_linter.md +++ /dev/null @@ -1,71 +0,0 @@ -# Linter to help migration to Conan v2 - - -## Contents - - * [Running the linter locally](#running-the-linter-locally) - * [Import ConanFile from `conan`](#import-conanfile-from-conan) - * [Import tools from `conan`](#import-tools-from-conan) - -We are leveraging on custom Pylint rules. This -linter will run for every pull-request that is submitted to the repository and will -raise some warnings and errors that should be addressed in order to migrate the -recipes to Conan v2. - -It is important to note that these rules are targeting Conan v2 compatibility layer, their -purpose is to fail for v1 syntax that will be no longer available in v2. Even if the syntax -if perfectly valid in Conan v1, the recipe might fail here because it is not v2-compliant. - -> **Note** Some of the errored checks might be just plain Python syntax errors, while -> others might be related to the custom rules added by us. - -Here you can find some examples of the extra rules we are adding: - -## Running the linter locally - -Check the [Developing Recipes](developing_recipes_locally.md#running-the-python-linters) for details. - -## Import ConanFile from `conan` - -The module `conans` is deprecated in Conan v2. Now all the imports should be done from -module `conan`: - -```python -from conan import ConanFile -``` - -## Import tools from `conan` - -All v2-compatible tools are available in module `conan.tools` under different submodules. Recipes -should start to import their tools from this new module. Some of the new tools accept new -argument, please, check the [Conan documentation](https://docs.conan.io/1/reference/conanfile/tools.html). - -Here is a list of different imports and their new equivalent (note that the interface for most of this functions changed, see their respective link to the documentation): - -| **Conan v1** | **Conan v2** | **Required Conan Version** | -|---|---|---| -| conans.tools.get | [conan.tools.files.get](https://docs.conan.io/1/reference/conanfile/tools/files/downloads.html#conan-tools-files-get) | 1.41.0 | -| conans.tools.download | [conan.tools.files.download](https://docs.conan.io/1/reference/conanfile/tools/files/downloads.html#conan-tools-files-download) | 1.41.0 | -| conans.tools.rmdir | [conan.tools.files.rmdir](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-rmdir) | 1.47.0 | -| conans.tools.patch | [conan.tools.files.patch](https://docs.conan.io/1/reference/tools.html#tools-patch) | 1.35.0 | -| conans.tools.remove_files_by_mask | [conan.tools.files.rm](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-rm) | 1.50.0 | -| conans.copy | [conan.tools.files.copy](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-copy) | 1.46.0 | -| conans.tools.load | [conan.tools.files.load](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-load) | 1.35.0 | -| conans.tools.save | [conan.tools.files.save](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-save) | 1.35.0 | -| conans.tools.rename | [conan.tools.files.rename](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-rename) | 1.37.0 | -| conans.tools.replace_in_file | [conan.tools.files.replace_in_file](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-replace-in-file) | 1.46.0 | -| conans.tools.mkdir | [conan.tools.files.mkdir](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-mkdir) | 1.35.0 | -| conans.tools.chdir | [conan.tools.files.chdir](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-chdir) | 1.40.0 | -| conans.tools.unzip | [conan.tools.files.unzip](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-unzip) | 1.46.0 | -| conans.tools.collect_libs | [conan.tools.files.collect_libs](https://docs.conan.io/1/reference/conanfile/tools/files/basic.html#conan-tools-files-collect-libs) | 1.46.0 | -| conans.tools.Version | [conan.tools.scm.Version](https://docs.conan.io/1/reference/conanfile/tools/scm/other.html#version) | 1.46.0 | -| conans.tools.sha256sum | [conan.tools.files.check_sha256](https://docs.conan.io/1/reference/conanfile/tools/files/checksum.html#conan-tools-files-check-sha256) | 1.46.0 | -| conans.tools.unix_path | [conan.tools.microsoft.unix_path](https://docs.conan.io/1/reference/conanfile/tools/microsoft.html#conan-tools-microsoft-unix-path) | 1.47.0 | -| conans.tools.is_apple_os | [conan.tools.apple.is_apple_os](https://docs.conan.io/1/reference/conanfile/tools/apple.html#is-apple-os) | 1.51.3 | -| conans.tools.cpu_count | [conan.tools.build.build_jobs](https://docs.conan.io/1/reference/conanfile/tools/build.html#conan-tools-build-build-jobs) | 1.43.0 | -| conans.tools.check_min_cppstd | [conan.tools.build.check_min_cppstd](https://docs.conan.io/1/reference/conanfile/tools/build.html#conan-tools-build-check-min-cppstd) | 1.50.0 | -| conans.tools.cross_building | [conan.tools.build.cross_building](https://docs.conan.io/1/reference/conanfile/tools/build.html#conan-tools-build-cross-building) | 1.46.0 | -| conans.errors.ConanInvalidConfiguration | [conan.errors.ConanInvalidConfiguration](https://docs.conan.io/1/migrating_to_2.0/recipes.html#migrating-the-recipes) | 1.47.0 | -| conans.errors.ConanException | [conan.errors.ConanException](https://docs.conan.io/1/migrating_to_2.0/recipes.html#migrating-the-recipes) | 1.47.0 | - ---- diff --git a/docs/v2_roadmap.md b/docs/v2_roadmap.md deleted file mode 100644 index 324ec01c47527..0000000000000 --- a/docs/v2_roadmap.md +++ /dev/null @@ -1,150 +0,0 @@ -# Road to Conan v2 - - -## Contents - - * [Short term](#short-term) - * [Prepare the CI infrastructure](#prepare-the-ci-infrastructure) - * [Export recipes using Conan v2 (warning)](#export-recipes-using-conan-v2-warning) - * [Prepare a syntax linter (CCI specific)](#prepare-a-syntax-linter-cci-specific) - * [Run an scheduled job exporting all recipes](#run-an-scheduled-job-exporting-all-recipes) - * [Mid term](#mid-term) - * [Add CI running Conan v2 (hidden)](#add-ci-running-conan-v2-hidden) - * [Show CI results to contributors (info)](#show-ci-results-to-contributors-info) - * [Linter - turn more warnings to errors](#linter---turn-more-warnings-to-errors) - * [Export using Conan v2 becomes an error](#export-using-conan-v2-becomes-an-error) - * [Long term](#long-term) - * [CI running v2 is reported (and required)](#ci-running-v2-is-reported-and-required) - * [Conan v2 remote](#conan-v2-remote) - * [Webpage with v2 information](#webpage-with-v2-information) - * [Future](#future) - * [CI running Conan v1 dropping configuration support](#ci-running-conan-v1-dropping-configuration-support) - -> **Note** This document is not a [guide about how to migrate recipes to Conan v2](v2_migration.md). - -> **Note** This is a working document that will be updated as we walk -> this path. There are no dates intentionally, and if any they should be -> considered as an estimation, there are still some unknowns to provide -> certain steps and dates. - -Conan v2 is under heavy development and it will be released in the -following months. It comes with many improvements that will benefit -recipes and users, and we are willing to adopt it. - -It is a new major version that will come with many breaking changes. Lot -of the features and syntax that we were used to in Conan v1 will no longer -be available and will be supersedes by improved alternatives. All these -alternatives should be backported to v1.x releases, so **there will be a -subset of features that will work using Conan v1 and v2**. - -**Our main goal in ConanCenter during this migration process is to ensure -that recipes work with v1 and v2** and to make the transition as smooth as -possible for contributors and users. In the end we will be providing -working recipes and binaries for both versions. - -This process will require a lot of work also in the internals, we will keep -communicating those changes and the relevant updates in the -[changelog](changelog.md). Here there are the main steps that we are -planning for the following months. - -## Short term - -### Prepare the CI infrastructure - -Workers for Conan v2 will be ready for Windows, Macos and Linux alternatives. -[Modern docker images](https://github.com/conan-io/conan-docker-tools/tree/master/modern) with Conan v2 are already -available to use, for example `conanio/gcc11-ubuntu16.04:2.0.0-pre`. -Note that we will be using tag name `2.0.0-pre` until there is an -actual Conan v2 release, this tag will use the latest pre-release -available (alpha, beta or release candidate). - -### Export recipes using Conan v2 (warning) - -We will start to run `conan export` using Conan v2 and the result will be -added to the comments by the bot. Failing this command won't make the -pull-request fail at this moment, but we expect contributors to start -gaining awareness about changes in Conan v2. - -### Prepare a syntax linter (CCI specific) - -We want to provide a Conan recipe's linter in this repository. We will add -warnings and errors to it following the pace dictated by the community. -The purpose is that this linter will fail pull-requests if there is any -error and, this way, we can start to migrate small (and easy) bits of -recipes... and ensure that future pull-requests don't introduce -regressions. - -This linter can (and surely will) implement some of the checks that are -being currently done by [hooks](https://github.com/conan-io/hooks), but -the purpose is not replace them: - -* hooks are really useful from the CLI, and are easier to install and run. -* linter provides much better output in GitHub interface. - -### Run an scheduled job exporting all recipes - -The same way we [export all the recipes every night using Conan v1](https://github.com/conan-io/conan-center-index/issues/2232), we will -run something similar using Conan v2 and report the results to an issue in -this repository. - -It will help us to know how many recipes are fixed at a given time and -think about efforts and impact of next steps. - -## Mid term - -### Add CI running Conan v2 (hidden) - -We will start working on a CI running Conan v2. Once recipes start to be -exported successfully, next step is to start building the packages. - -We are going to prepare the CI and start running it behind the scenes -(sorry, at this moment hidden to users) in order to understand and -experiment ourself some challenges that will come with Conan v2: syntax, -configuration defaults,... - -### Show CI results to contributors (info) - -Once the errors start to make sense, we will start to provide these outputs -in pull-requests (although successful builds using v2 won't be required to -merge). Again, we expect some contributors to be aware of these errors, -maybe try to fix those builds, and for sure report feedback. - -### Linter - turn more warnings to errors - -During all this time, the plan is to move linter warnings to errors, one -by one and taking into account the effort required to fix them. With the -help of the linter more recipes should start to work (just `conan export`) -using Conan v2. - -### Export using Conan v2 becomes an error - -When a significant number (TBD) of recipes start to be exported -successfully, we will turn those export warnings into actual errors and -they will be become required to merge the pull-requests - -## Long term - -### CI running v2 is reported (and required) - -Next step is to start running and reporting the results of the builds using -v2 for all the configurations, like we do for Conan v1. At this time all -pull-requests need to work with v1 and v2 to be merged. - -### Conan v2 remote - -Packages built using Conan v2 are available for users on ``conancenter`` remote. - -### Webpage with v2 information - -ConanCenter webpage will start to show relevant information related to v2 -packages and, eventually, v2 information will be the only available. - -## Future - -After this process in completed, we will consider the deprecation and -decommission of the infrastructure to generate v1 packages. - -### CI running Conan v1 dropping configuration support - -The change should occur by steps, less used configurations, like older compiler versions, will be dropped first. -Any changed will notified before to occur, so users can be prepared.