diff --git a/docs/adding_packages/README.md b/docs/adding_packages/README.md index 92c0dbc799..3f310562fd 100644 --- a/docs/adding_packages/README.md +++ b/docs/adding_packages/README.md @@ -68,7 +68,7 @@ In ConanCenter, our belief is recipes should always match upstream, in other wor 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/en/latest/reference/conanfile/tools/cmake/cmakedeps.html) generator. There are a few +[`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. diff --git a/docs/adding_packages/build_and_package.md b/docs/adding_packages/build_and_package.md index b247b29d9f..a64769f6e6 100644 --- a/docs/adding_packages/build_and_package.md +++ b/docs/adding_packages/build_and_package.md @@ -82,7 +82,7 @@ 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/en/latest/howtos/header_only.html). +Also, Conan Docs have a section about [how to package header-only libraries](https://docs.conan.io/1/howtos/header_only.html). ### CMake @@ -106,7 +106,7 @@ For cases where a project only offers source files, but not a build script, you > **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/en/latest/reference/conanfile/methods.html#systempackagetool) can easily manage a system package manager (e.g. apt, +The [SystemPackageTool](https://docs.conan.io/1/reference/conanfile/methods.html#systempackagetool) 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. diff --git a/docs/adding_packages/conandata_yml_format.md b/docs/adding_packages/conandata_yml_format.md index 84338094c3..e1b7f89ee3 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/en/latest/reference/config_files/conandata.yml.html) is a [YAML](https://yaml.org/) +[conandata.yml](https://docs.conan.io/1/reference/config_files/conandata.yml.html) 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. @@ -114,7 +114,7 @@ sources: sha256: "f5d48c4b0d558c5d71e8bf6fcdf135b0943210c1ff91f8191dfc447419a6b12e" ``` -This approach requires a special code within [build](https://docs.conan.io/en/latest/reference/conanfile/methods.html#build) method to handle. +This approach requires a special code within [build](https://docs.conan.io/1/reference/conanfile/methods.html#build) method to handle. ### Sources fields @@ -240,4 +240,4 @@ For the `patch_type: conan`, it doesn't make sense to submit patch upstream, so _Optional_ -Specifies a sub-directory in project's sources to apply patch. This directory is relative to the [source_folder](https://docs.conan.io/en/latest/reference/conanfile/attributes.html?highlight=source_folder#source-folder). Usually, it would be a `source_subfolder`, but could be a lower-level sub-directory (e.g. if it's a patch for a submodule). +Specifies a sub-directory in project's sources to apply patch. This directory is relative to the [source_folder](https://docs.conan.io/1/reference/conanfile/attributes.html?highlight=source_folder#source-folder). Usually, it would be a `source_subfolder`, but could be a lower-level sub-directory (e.g. if it's a patch for a submodule). diff --git a/docs/adding_packages/conanfile_attributes.md b/docs/adding_packages/conanfile_attributes.md index be94297dfa..37395fdd86 100644 --- a/docs/adding_packages/conanfile_attributes.md +++ b/docs/adding_packages/conanfile_attributes.md @@ -20,7 +20,7 @@ or are known by ConanCenter's build service and have special meaning. ## Attributes -These are a [key feature](https://docs.conan.io/en/latest/reference/conanfile/attributes.html) which allow the Conan client to understand, +These are a [key feature](https://docs.conan.io/1/reference/conanfile/attributes.html) which allow 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 @@ -60,7 +60,7 @@ Where the SPDX guidelines do not apply, packages should do the following: Prefer the following order of documented methods in python code (`conanfile.py`, `test_package/conanfile.py`): -For `conan create` the order is listed [here](https://docs.conan.io/en/latest/reference/commands/creator/create.html#methods-execution-order) +For `conan create` the order is listed [here](https://docs.conan.io/1/reference/commands/creator/create.html#methods-execution-order) test packages recipes should append the following methods: * deploy @@ -168,7 +168,7 @@ Usage of each option should follow the rules: ### 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/en/latest/reference/config_files/global_conf.html#tools-configurations) feature: + Instead, use Conan config [skip_test](https://docs.conan.io/1/reference/config_files/global_conf.html#tools-configurations) feature: ```python def generate(self): @@ -176,17 +176,17 @@ Usage of each option should follow the rules: tc.variables['BUILD_TESTING'] = not self.conf.get("tools.build:skip_test", default=true, check_type=bool) ``` - The `skip_test` configuration is supported by [CMake](https://docs.conan.io/en/latest/reference/build_helpers/cmake.html#test) and [Meson](https://docs.conan.io/en/latest/reference/build_helpers/meson.html#test). - + 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). + ### Removing from `package_id` - - By default, options are included in the calculation for the `package_id` ([docs](https://docs.conan.io/en/latest/reference/conanfile/methods.html#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)). Options which do not impact the generated packages should be deleted, for instance adding a `#define` for a package. - + ```python def package_id(self): del self.info.options.enable_feature - + def package_info(self): if self.options.enable_feature: self.cpp_info.defines.append("FOBAR_FEATURE=1") diff --git a/docs/adding_packages/dependencies.md b/docs/adding_packages/dependencies.md index ec2c265059..b04ca6fc57 100644 --- a/docs/adding_packages/dependencies.md +++ b/docs/adding_packages/dependencies.md @@ -20,8 +20,8 @@ from handling "vendored" dependencies to what versions should be used. ## List Dependencies -Since all ConanCenterIndex recipes are to build and/or package projects they are exclusively done in [`conanfile.py`](https://docs.conan.io/en/latest/reference/conanfile.html). This offers a few -ways to add requirements. The most common way is [requirements](https://docs.conan.io/en/latest/reference/conanfile/methods.html#requirements): +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): @@ -53,14 +53,14 @@ class ExampleConan(ConanFile): 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/en/latest/reference/conanfile/attributes.html#version). Another common case is +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/en/latest/reference/conanfile/methods.html#build-requirements): +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): @@ -69,13 +69,13 @@ If a project requires any other specific tool, those can be added as well. We li ## 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/en/latest/reference/conanfile/methods.html#generate) method. This -is generally covered by the built-in generators like [`CMakeDeps`](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmakedeps.html) -However the [`self.dependencies`](https://docs.conan.io/en/latest/reference/conanfile/dependencies.html?highlight=generate) are available. +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/en/latest/reference/conanfile/dependencies.html?highlight=validate) within the -[`validate()`](https://docs.conan.io/en/latest/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/en/latest/reference/conanfile/methods.html#configure-config-options) +[`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 @@ -84,10 +84,10 @@ Forcing options of dependencies inside a ConanCenter should be avoided, except i 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/en/latest/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/1/reference/conanfile/methods.html#validate) 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/en/latest/reference/conanfile/dependencies.html?highlight=options) field of +accessing the [`options`](https://docs.conan.io/1/reference/conanfile/dependencies.html?highlight=options) field of the dependency. ```py @@ -111,10 +111,10 @@ def validate(self): ### Passing Requirement's info to `build()` -The [`self.dependencies`](https://docs.conan.io/en/latest/reference/conanfile/dependencies.html) are limited to [`generate()`](https://docs.conan.io/en/latest/reference/conanfile/methods.html#generate) and [`validate()`](https://docs.conan.io/en/latest/reference/conanfile/methods.html#validate). This means configuring a projects build scripts +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/en/latest/reference/conanfile/tools/cmake/cmaketoolchain.html), such as: +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): @@ -127,7 +127,7 @@ In general, with [CMake](https://cmake.org/) project, this can be very simple wi 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/en/latest/reference/commands/consumer/install.html) and [`conan build`](https://docs.conan.io/en/latest/reference/commands/development/build.html) commands can be separated when +> **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. @@ -168,14 +168,14 @@ 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/en/latest/versioning/version_ranges.html) are not allowed. -* Specify explicit [RREV](https://docs.conan.io/en/latest/versioning/revisions.html) (recipe revision) of dependencies is not allowed. +* [Version ranges](https://docs.conan.io/1/versioning/version_ranges.html) are not allowed. +* Specify explicit [RREV](https://docs.conan.io/1/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/en/latest/reference/conanfile/other.html#python-requires) are not allowed. +* [`python_requires`](https://docs.conan.io/1/reference/conanfile/other.html#python-requires) are not allowed. ### Version Ranges -Version ranges are a useful Conan feature, [documentation here](https://docs.conan.io/en/latest/versioning/version_ranges.html). However, +Version ranges are a useful Conan feature, [documentation here](https://docs.conan.io/1/versioning/version_ranges.html). However, in the context of ConanCenter they pose a few key challenges when being used generally to consume packages, most notably: * Non-Deterministic `package-id`: With version ranges the newest compatible package may yield a different `package_id` than the one built diff --git a/docs/adding_packages/folders_and_files.md b/docs/adding_packages/folders_and_files.md index 2149e21f0e..0136f36792 100644 --- a/docs/adding_packages/folders_and_files.md +++ b/docs/adding_packages/folders_and_files.md @@ -145,7 +145,7 @@ When a package needs other packages those can be include with the `requirements( 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/en/latest/reference/build_helpers.html). +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 @@ -176,7 +176,7 @@ Here's an example for a header only library: 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/en/latest/creating_packages/getting_started.html) and learn about ConanCenterIndex +[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. The goal for the test package is to make sure the diff --git a/docs/adding_packages/sources_and_patches.md b/docs/adding_packages/sources_and_patches.md index 5032bc50a5..66f10a1232 100644 --- a/docs/adding_packages/sources_and_patches.md +++ b/docs/adding_packages/sources_and_patches.md @@ -107,7 +107,7 @@ It's ideal to minimize the number of files in a package to exactly what's requir 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/en/latest/reference/conanfile/tools/files/patches.html?highlight=export_conandata_patches) +[`conan.tools.files.export_conandata_patches`](https://docs.conan.io/1/reference/conanfile/tools/files/patches.html?highlight=export_conandata_patches) helper. ```py @@ -118,7 +118,7 @@ def export_sources(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/en/latest/reference/conanfile/tools/files/patches.html?highlight=apply_conandata_patches) +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 @@ -127,8 +127,8 @@ def build(self): ``` For more complicated cases, -[`conan.tools.files.rm`](https://docs.conan.io/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-rm) -or [`conan.tools.files.replace_in_file`](https://docs.conan.io/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-replace-in-file) +[`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 diff --git a/docs/adding_packages/test_packages.md b/docs/adding_packages/test_packages.md index c37f824816..5870221fbc 100644 --- a/docs/adding_packages/test_packages.md +++ b/docs/adding_packages/test_packages.md @@ -1,7 +1,7 @@ # 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/en/latest/reference/commands/creator/create.html?highlight=test_package) +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. @@ -19,7 +19,7 @@ themselves. It's possible to have ConanCenter run `conan test` on more then one 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/en/latest/reference/commands/creator/create.html?highlight=test_folder) +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/` and on for the deprecated generators in `test_v1_package/`. Please refer to the [Package Templates](../package_templates/) for the current practices about which files and what their content should be. @@ -27,7 +27,7 @@ Please refer to the [Package Templates](../package_templates/) for the current p ### CMake targets When using CMake to test a package, the information should be consumed using the -[`CMakeDeps` generator](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmakedeps.html?highlight=cmakedeps). +[`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 @@ -102,7 +102,7 @@ You can find the output of all of them together in the testing logs. Only the en 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/en/latest/reference/conanfile/tools/build.html?highlight=can_run#conan-tools-build-can-run) +[`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 diff --git a/docs/consuming_recipes.md b/docs/consuming_recipes.md index ee80883fc7..b0a653026d 100644 --- a/docs/consuming_recipes.md +++ b/docs/consuming_recipes.md @@ -30,7 +30,7 @@ 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/en/latest/reference/conanfile/other.html?highlight=required_conan_version#requiring-a-conan-version-for-the-recipe) feature. It will +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. To be sure that people using these new experimental features are using the required Conan version and testing the actual behavior @@ -44,21 +44,21 @@ 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/en/latest/uploading_packages/running_your_server.html) - great for local ad-hoc setups -- [Cache recipes in your own ArtifactoryCE](https://docs.conan.io/en/latest/uploading_packages/using_artifactory.html) - recommended for production environments +- [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 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/en/latest/reference/commands/misc/remote.html?highlight=add%20new) and new recipe +[use only this remote](https://docs.conan.io/1/reference/commands/misc/remote.html?highlight=add%20new) 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 using: -- [recipe revision (RREV)](https://docs.conan.io/en/latest/versioning/revisions.html) can be added to each requirement. +- [recipe revision (RREV)](https://docs.conan.io/1/versioning/revisions.html) 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/en/latest/versioning/revisions.html#how-to-activate-the-revisions) for details. -- [Lockfiles](https://docs.conan.io/en/latest/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/en/latest/versioning/lockfiles/introduction.html#) for more information. + 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. diff --git a/docs/developing_recipes_locally.md b/docs/developing_recipes_locally.md index c12b9d8486..e34902537f 100644 --- a/docs/developing_recipes_locally.md +++ b/docs/developing_recipes_locally.md @@ -75,7 +75,7 @@ We recommend working from the `recipes/project` folder itself. You can learn abo > **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/en/latest/developing_packages/package_dev_flow.html) can be execute with the [`conan create`](https://docs.conan.io/en/latest/reference/commands/creator/create.html). This should look like: +The [entire workflow of a recipe](https://docs.conan.io/1/developing_packages/package_dev_flow.html) can be execute 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` @@ -95,7 +95,7 @@ conan create all/conanfile.py fmt/9.0.0@ -s build_type=Debug -o fmt:shared=True ## Debugging Failed Builds -Some common errors related to Conan can be found on [troubleshooting](https://docs.conan.io/en/latest/faq/troubleshooting.html) section. +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. To test with the same environment, the [build images](supported_platforms_and_configurations.md#build-images) are available. diff --git a/docs/error_knowledge_base.md b/docs/error_knowledge_base.md index 9e81657888..f9d83f1247 100644 --- a/docs/error_knowledge_base.md +++ b/docs/error_knowledge_base.md @@ -4,7 +4,7 @@ These are located at [conan-io/hooks](https://github.com/conan-io/hooks/blob/mas #### **#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/en/latest/howtos/manage_cpp_standard.html). As a subsetting of the compiler, it shouldn't be declared in the `conanfile.py`. +`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"** @@ -14,16 +14,16 @@ The package names in conan-center have to be [lowercase](https://github.com/cona The recipe has to declare the following attributes: -- [url](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#url) -- [license](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#license) -- [description](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#description) -- [homepage](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#homepage). +- [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/en/latest/reference/conanfile/attributes.html#topics) attribute. +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/en/latest/howtos/header_only.html) in the [package_id()](https://docs.conan.io/en/latest/reference/conanfile/methods.html#package-id) method and doesn't declare settings, it should use the [no_copy_source](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#no-copy-source) attribute to avoid unnecessary copies of the source code. +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"** @@ -61,7 +61,7 @@ class SomeRecipe(ConanFile): del self.options.fPIC ``` -Here we use [configure()](https://docs.conan.io/en/latest/reference/conanfile/methods.html#configure-config-options) method, because user options are loaded after [config_options()](https://docs.conan.io/en/latest/reference/conanfile/methods.html#configure-config-options) only. +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"** @@ -73,7 +73,7 @@ The recipe folder (including the `test_package` folder) cannot exceed 256KB. #### **#KB-H010: "IMMUTABLE SOURCES"** -Create a file [conandata.yml](https://docs.conan.io/en/latest/reference/config_files/conandata.yml.html) in the recipe folder containing the source code origins: +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_**: @@ -96,7 +96,7 @@ class SomeRecipe(ConanFile): #### **#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/en/latest/reference/config_files/settings.yml.html#c-standard-libraries-aka-compiler-libcxx) subsetting, because the cpp standard library shouldn't affect the binary ID: +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): @@ -113,7 +113,7 @@ The binary packages should contain a folder named `licenses` containing the cont #### **#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/en/latest/reference/conanfile/methods.html#package-info) from the client. +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). @@ -131,9 +131,9 @@ The binary package is shared (self.options.shared == True) but there is no `dll` 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/en/latest/reference/conanfile/methods.html#package-info) method with all the needed information about the package. +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/en/latest/using_packages/conanfile_txt.html#generators) for the build system they use. +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). @@ -149,7 +149,7 @@ Packaging [libtool files](https://www.linuxfromscratch.org/blfs/view/svn/introdu #### **#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/en/latest/reference/conanfile/attributes.html#cpp-info). +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"** @@ -164,7 +164,7 @@ For the legal reasons, and in order to reduce the size of packages, it's not all #### **#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/en/latest/howtos/manage_cpp_standard.html) subsetting, because the cpp standard library shouldn't affect the binary ID: +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): @@ -189,7 +189,7 @@ There is a complete explanation in the [FAQ](faqs.md#should-recipes-export-a-rec #### **#KB-H024: "TEST PACKAGE FOLDER"** -The [test_package](https://docs.conan.io/en/latest/creating_packages/getting_started.html) folder is required for every recipe in Conan Center Index. +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 @@ -232,7 +232,7 @@ class SomeRecipe(ConanFile): #### **#KB-H027: "CONAN CENTER INDEX URL"** -The attribute [url](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#url) should point to the address where the recipe is located. +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"** @@ -249,7 +249,7 @@ project(conanwrapper) #### **#KB-H029: "TEST PACKAGE - RUN ENVIRONMENT"** -The [RunEnvironment()](https://docs.conan.io/en/latest/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/en/latest/devtools/running_packages.html#running-from-packages) parameter. +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 @@ -262,23 +262,23 @@ class TestConan(ConanFile): #### **#KB-H030: "CONANDATA.YML FORMAT"** -The structure of the [conandata.yml](https://docs.conan.io/en/latest/reference/config_files/conandata.yml.html) file should follow the schema +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/en/latest/extending/hooks.html) re-creates the information of the [conandata.yml](https://docs.conan.io/en/latest/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. +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/en/latest/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. +[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/en/latest/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/en/latest/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. +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"** @@ -288,7 +288,7 @@ Since the entire community is maintaining all CCI recipes, putting just one 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/en/latest/migrating_to_2.0/properties.html). +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"** @@ -297,13 +297,13 @@ 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/en/latest/reference/conanfile/methods.html#requirements) and [self.build_requires()](https://docs.conan.io/en/latest/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. +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/en/latest/reference/conanfile/methods.html#configure-config-options). +See also: [configure(), config_options()](https://docs.conan.io/1/reference/conanfile/methods.html#configure-config-options). #### **#KB-H046: "CMAKE VERBOSE MAKEFILE"** @@ -323,7 +323,7 @@ By default, all packages should be built as static library (the option ``shared` #### **#KB-H051: "DEFAULT OPTIONS AS DICTIONARY"** -The attribue [default_options](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#default-options) should be a dictionary, for example `default_options = {'shared': False, 'fPIC': True}`. +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"** @@ -338,11 +338,11 @@ request to publicly expose needed methods, if necessary. #### **#KB-H054: "LIBRARY DOES NOT EXIST"** -Libraries which are listed on [Components](https://docs.conan.io/en/latest/creating_packages/package_information.html#package-information-components) must be present in [libdirs](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#cpp-info). Check if the library name is correct, or if a library is only generated for a specific platform. +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/en/latest/reference/conanfile/methods.html#requirements) method and [self.requires](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#requires) attribute together in the same recipe. +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"** @@ -351,7 +351,7 @@ See [License Attribute](adding_packages/conanfile_attributes.md#license-attribut #### **#KB-H057: "TOOLS RENAME"** -The [rename()](https://docs.conan.io/en/latest/reference/conanfile/tools/files.html#conan-tools-rename) method will be the standard for Conan 2.0, and +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"** @@ -374,20 +374,20 @@ The [core.autocrlf](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configura #### **#KB-H062: "TOOLS CROSS BUILDING"** -Replace all occurrences of `tools.cross_building(self.settings)` with [tools.cross_building(self)](https://docs.conan.io/en/latest/reference/tools.html#tools-cross-building). -When cross building, conan needs to compare [self.settings](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#settings) and [self.settings_build](https://docs.conan.io/en/latest/systems_cross_building/cross_building.html), which are attributes of `self`. +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/en/latest/reference/conanfile/attributes.html#topics) has been detected. Remove or rename it. +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/en/latest/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/en/latest/reference/conanfile/tools/files/downloads.html#conan-tools-files-get) helper). +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/en/latest/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. +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 @@ -402,7 +402,7 @@ 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/en/latest/reference/conanfile/attributes.html#short-paths) attribute. +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: @@ -417,7 +417,7 @@ See also: [Maximum Path Length Limitation](https://docs.microsoft.com/en-us/wind #### **#KB-H068: "TEST_TYPE MANAGEMENT"** -In Conan 2.0, see [migration guide](https://docs.conan.io/en/latest/migrating_to_2.0/recipes.html#changes-in-the-test-package-recipe), +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. @@ -480,7 +480,7 @@ The legacy content in test_package should not be removed. Instead, rename that f #### **#KB-H075: "REQUIREMENT OVERRIDE PARAMETER"** -The [self.requires()](https://docs.conan.io/en/latest/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. +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"** diff --git a/docs/faqs.md b/docs/faqs.md index d13145432a..d4755d154c 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -73,7 +73,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/en/latest/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](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. 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: @@ -83,15 +83,15 @@ 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/en/latest/reference/generators/cmake_find_package.html)* or [cmake_find_package_multi](https://docs.conan.io/en/latest/reference/generators/cmake_find_package.html) and features like [components](https://docs.conan.io/en/latest/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/en/latest/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 [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. -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/en/latest/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 [pkg_config generator](https://docs.conan.io/1/reference/generators/pkg_config.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/en/latest/integrations/build_system/cmake/cmake_find_package_generator.html +\* Take a look at the integrations section to learn more: https://docs.conan.io/1/integrations/build_system/cmake/cmake_find_package_generator.html ## Should recipes export a recipe's license? @@ -155,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/en/latest/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/1/reference/profiles.html#package-settings-and-env-vars) to customize your compiler command line. ### Why is there no option for PDB, as there is for fPIC? @@ -197,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/en/latest/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/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). ## What license should I use for Public Domain? @@ -347,7 +347,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/en/latest/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/1/using_packages/conanfile_txt.html#overriding-requirements) 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`: @@ -360,7 +360,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/en/latest/changelog.html)). +([Conan client changelog](https://docs.conan.io/1/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 @@ -379,7 +379,7 @@ When the CI builds packages with `shared=True`, it applies the option only to th 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/en/latest/creating_packages/define_abi_compatibility.html#versioning-schema) +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. @@ -396,7 +396,7 @@ easily achievable using `*:shared=True` in the _host_ profile and `--build` in t 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/en/latest/reference/conanfile/methods.html?highlight=shared_library_package_id#self-info-shared-library-package-id), +> [`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. > diff --git a/docs/linters.md b/docs/linters.md index b93f645337..0a2bc915e2 100644 --- a/docs/linters.md +++ b/docs/linters.md @@ -136,7 +136,7 @@ Only the namespace `conans` has been replaced by `conan`. ### E9011 - conan-import-tools: Importing conan.tools or conan.tools.xxx.zzz.yyy should be considered as private -Documented on [conanfile.tools](https://docs.conan.io/en/latest/reference/conanfile/tools.html): +Documented on [conanfile.tools](https://docs.conan.io/1/reference/conanfile/tools.html): It's not allowed to use `tools.xxx` directly: ```python diff --git a/docs/v2_linter.md b/docs/v2_linter.md index a2358f657f..1b6930d1a3 100644 --- a/docs/v2_linter.md +++ b/docs/v2_linter.md @@ -38,34 +38,34 @@ from conan import ConanFile 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/en/latest/reference/conanfile/tools.html). +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/en/latest/reference/conanfile/tools/files/downloads.html#conan-tools-files-get) | 1.41.0 | -| conans.tools.download | [conan.tools.files.download](https://docs.conan.io/en/latest/reference/conanfile/tools/files/downloads.html#conan-tools-files-download) | 1.41.0 | -| conans.tools.rmdir | [conan.tools.files.rmdir](https://docs.conan.io/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-rmdir) | 1.47.0 | -| conans.tools.patch | [conan.tools.files.patch](https://docs.conan.io/en/latest/reference/tools.html#tools-patch) | 1.35.0 | -| conans.tools.remove_files_by_mask | [conan.tools.files.rm](https://docs.conan.io/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-rm) | 1.50.0 | -| conans.copy | [conan.tools.files.copy](https://docs.conan.io/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-copy) | 1.46.0 | -| conans.tools.load | [conan.tools.files.load](https://docs.conan.io/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-load) | 1.35.0 | -| conans.tools.save | [conan.tools.files.save](https://docs.conan.io/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-save) | 1.35.0 | -| conans.tools.rename | [conan.tools.files.rename](https://docs.conan.io/en/latest/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/en/latest/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/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-mkdir) | 1.35.0 | -| conans.tools.chdir | [conan.tools.files.chdir](https://docs.conan.io/en/latest/reference/conanfile/tools/files/basic.html#conan-tools-files-chdir) | 1.40.0 | -| conans.tools.unzip | [conan.tools.files.unzip](https://docs.conan.io/en/latest/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/en/latest/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/en/latest/reference/conanfile/tools/scm/other.html#version) | 1.46.0 | -| conans.tools.sha256sum | [conan.tools.files.check_sha256](https://docs.conan.io/en/latest/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/en/latest/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/en/latest/reference/conanfile/tools/apple.html#is-apple-os) | 1.51.3 | -| conans.tools.cpu_count | [conan.tools.build.build_jobs](https://docs.conan.io/en/latest/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/en/latest/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/en/latest/reference/conanfile/tools/build.html#conan-tools-build-cross-building) | 1.46.0 | -| conans.errors.ConanInvalidConfiguration | [conan.errors.ConanInvalidConfiguration](https://docs.conan.io/en/latest/migrating_to_2.0/recipes.html#migrating-the-recipes) | 1.47.0 | -| conans.errors.ConanException | [conan.errors.ConanException](https://docs.conan.io/en/latest/migrating_to_2.0/recipes.html#migrating-the-recipes) | 1.47.0 | +| 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_migration.md b/docs/v2_migration.md index 3a8ebff66e..0e2bfb0608 100644 --- a/docs/v2_migration.md +++ b/docs/v2_migration.md @@ -26,7 +26,7 @@ Conan v2 in pull requests. It's time to start thinking seriously about Conan v2 and prepare recipes for the incoming changes. Conan v2 comes with many changes and improvements, you can read about them in the -[Conan documentation](https://docs.conan.io/en/latest/conan_v2.html). +[Conan documentation](https://docs.conan.io/1/conan_v2.html). This document is a practical guide, offering extended information particular to Conan Center Index recipes to get them ready to upgrade to Conan 2.0. @@ -60,7 +60,7 @@ not depend on settings or options. The old `CMake.definition` should be replaced by `CMakeToolchain.variables` and moved to the `generate` method. However, certain options need to be passed as `cache_variables`. You'll need to check project's `CMakeLists.txt` -as there are a few cases to look out for: +as there are a few cases to look out for: - When an `option` is configured before `project()` is called. @@ -78,18 +78,18 @@ as there are a few cases to look out for: set(USE_JPEG ON CACHE BOOL "include jpeg support?") ``` -For more information refere to the [CMakeToolchain docs](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmaketoolchain.html) +For more information refere to the [CMakeToolchain docs](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmaketoolchain.html) or check out the converstaion in conan-io/conan#11937 for the brave. ## New conf_info properties As described in the documentation `self.user_info` has been depreated and you are now required to use `self.conf_info` to define individual properties to expose to downstream recipes. -The [2.0 migrations docs](https://docs.conan.io/en/latest/migrating_to_2.0/recipes.html#removed-self-user-info) +The [2.0 migrations docs](https://docs.conan.io/1/migrating_to_2.0/recipes.html#removed-self-user-info) should cover the technical details, however for ConanCenterIndex we need to make sure there are no collisions `conf_info` must be named `user.:`. -For usage options of `conf_info`, the [documenation](https://docs.conan.io/en/latest/reference/config_files/global_conf.html?highlight=conf_info#configuration-in-your-recipes) +For usage options of `conf_info`, the [documenation](https://docs.conan.io/1/reference/config_files/global_conf.html?highlight=conf_info#configuration-in-your-recipes) In ConanCenterIndex this will typically looks like: @@ -111,15 +111,15 @@ In ConanCenterIndex this will typically looks like: self.run(f"{tool_path} --build") ``` > **Note**: This should only be used when absolutely required. In the vast majority of cases, the new -> ["Environments"](https://docs.conan.io/en/latest/reference/conanfile/tools/env/environment.html?highlight=Virtual) +> ["Environments"](https://docs.conan.io/1/reference/conanfile/tools/env/environment.html?highlight=Virtual) > will include the `self.cpp_info.bindirs` which will provide access to the tools in the correct scopes. ## New cpp_info set_property model New Conan generators like -[CMakeDeps](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmakedeps.html) +[CMakeDeps](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmakedeps.html) and -[PkgConfigDeps](https://docs.conan.io/en/latest/reference/conanfile/tools/gnu/pkgconfigdeps.html), +[PkgConfigDeps](https://docs.conan.io/1/reference/conanfile/tools/gnu/pkgconfigdeps.html), don't listen to *cpp_info* ``.names``, ``.filenames`` or ``.build_modules`` attributes. There is a new way of setting the *cpp_info* information with these generators using the ``set_property(property_name, value)`` method. @@ -134,7 +134,7 @@ stay. We will cover some cases of porting all the information set with the current model to the new one. To read more about the properties available for each generator and how the -properties model work, please check the [Conan documentation](https://docs.conan.io/en/latest/conan_v2.html#editables-don-t-use-external-templates-any-more-new-layout-model). +properties model work, please check the [Conan documentation](https://docs.conan.io/1/conan_v2.html#editables-don-t-use-external-templates-any-more-new-layout-model). > **Note**: Please, remember that the **new** ``set_property`` and the **current** attributes > model are *completely independent since Conan 1.43*. Setting ``set_property`` in recipes will @@ -259,7 +259,7 @@ class ExpatConan(ConanFile): Should translate to the code above. Please note we have added the ``cmake_find_mode`` property for the -[CMakeDeps](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmakedeps.html#properties) +[CMakeDeps](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmakedeps.html#properties) generator with value ``both``. ```python @@ -311,7 +311,7 @@ class GlewConan(ConanFile): ``` In this case we have to set the ``cmake_find_mode`` property for the -[CMakeDeps](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmakedeps.html#properties) +[CMakeDeps](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmakedeps.html#properties) generator with value ``both``. That will make CMakeDeps generator create both module and config files for consumers (by default it generates just config files). @@ -480,7 +480,7 @@ class PyBind11Conan(ConanFile): The case of ``PkgConfigDeps`` is much more straight forward than the ``CMakeDeps`` case. This is because the current -[pkg_config](https://docs.conan.io/en/latest/reference/generators/pkg_config.html) +[pkg_config](https://docs.conan.io/1/reference/generators/pkg_config.html) generator suports the new ``set_property`` model for most of the properties. Then, the current model can be translated to the new one without having to leave the old attributes in the recipes. Let's see an example: @@ -506,4 +506,4 @@ class AprConan(ConanFile): ``` For more information about properties supported by ``PkgConfigDeps`` generator, please check the [Conan -documentation](https://docs.conan.io/en/latest/reference/conanfile/tools/gnu/pkgconfigdeps.html#properties). +documentation](https://docs.conan.io/1/reference/conanfile/tools/gnu/pkgconfigdeps.html#properties).