mirror of
https://github.com/conan-io/conan-center-index.git
synced 2025-08-09 07:48:56 +00:00
(#13736) docs: Create a subfolder for "adding packages"
* docs: group files about "adding packages" * fixing links * fixing links * rename file * minor changes * fix merge conflicts * touch ups * fix order * fix links * Clean up notes * Update docs/error_knowledge_base.md * Update docs/developing_recipes_locally.md * merge conflicts * Apply suggestions from code review
This commit is contained in:
Chris Mc
@@ -23,12 +23,12 @@ To contribute follow the next steps:
|
||||
|
||||
1. Comment in the corresponding issue that you want to contribute the package/fix proposed. If there is no open issue, we strongly suggest
|
||||
opening one to gather feedback.
|
||||
2. Make sure to [request access](docs/how_to_add_packages.md#request-access) and be aware there is a [CLA](docs/CONTRIBUTOR_LICENSE_AGREEMENT.md).
|
||||
2. Make sure to [request access](docs/adding_packages/README.md#request-access) and be aware there is a [CLA](docs/CONTRIBUTOR_LICENSE_AGREEMENT.md).
|
||||
3. Get setup by following the [Developing Recipes](docs/developing_recipes_locally.md) guide and learn the basic commands.
|
||||
4. Check the [How To Add Packages](docs/how_to_add_packages.md) page for the break down of ConanCenterIndex specific conventions and practices.
|
||||
4. Check the [How To Add Packages](docs/adding_packages/README.md) page for the break down of ConanCenterIndex specific conventions and practices.
|
||||
5. In your fork create a `package/xxx` branch from the `master` branch and develop
|
||||
your fix/packages as discussed in previous step.
|
||||
6. [Submit a pull request](docs/how_to_add_packages.md#submitting-a-package) once you are ready. This can be when you
|
||||
6. [Submit a pull request](docs/adding_packages/README.md#submitting-a-package) once you are ready. This can be when you
|
||||
got everything working or even if you need help. Add the text to the issue body (besides other comments): "fixes #IssueNumber"
|
||||
in the body of the PR, referring to the issue of step 1.
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@ All the documentation is available in this same repository in the [`docs/` subfo
|
||||
|
||||
This is a list of shortcuts to some interesting topics:
|
||||
|
||||
* :rocket: If you want to learn how to **contribute new recipes**, please read [docs/how_to_add_packages.md](docs/how_to_add_packages.md).
|
||||
* :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).
|
||||
|
||||
@@ -12,7 +12,7 @@ When pull requests are merged, the CI will upload the generated packages to the
|
||||
* User documentation
|
||||
+ [Contributing to Conan Center Index](../CONTRIBUTING.md)
|
||||
+ [Developing Recipes Locally](developing_recipes_locally.md)
|
||||
+ [Adding Packages to ConanCenter](how_to_add_packages.md) :point_left: Best place to learn how to contribute
|
||||
+ [Adding Packages to ConanCenter](adding_packages/README.md) :point_left: Best place to learn how to contribute
|
||||
+ [Errors from the conan-center hook (KB-Hxxx)](error_knowledge_base.md)
|
||||
+ [Review Process](review_process.md)
|
||||
+ [Labels](labels.md)
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
ConanCenterIndex aims to provide the best quality packages of any open source project.
|
||||
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.
|
||||
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.
|
||||
You can follow the three steps (:one: :two: :three:) described below! :tada:
|
||||
|
||||
@@ -37,14 +37,16 @@ You can follow the three steps (:one: :two: :three:) described below! :tada:
|
||||
|
||||
:one: The first step to add packages to ConanCenter is requesting access. To enroll in ConanCenter repository, please write a comment
|
||||
requesting access in this GitHub [issue](https://github.com/conan-io/conan-center-index/issues/4). Feel free to introduce yourself and
|
||||
your motivation to join ConanCenter.
|
||||
your motivation to join ConanCenter community.
|
||||
|
||||
This process helps conan-center-index against spam and malicious code. The process is not not automated on purpose and the requests are generally approved on a weekly basis.
|
||||
This process helps ConanCenter against spam and malicious code. The process is not not automated on purpose and the requests are generally approved
|
||||
on a weekly basis.
|
||||
|
||||
> :warning: The requests are reviewed manually, checking the GitHub profile activity of the requester to avoid a misuse of the service. In case of detecting a misuse or inappropriate behavior, the requester will be dropped from the authorized users list and at last instance even banned from the repository.
|
||||
> **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.
|
||||
|
||||
When submitting a pull request for the first time, you will be prompted to sign the [CLA](CONTRIBUTOR_LICENSE_AGREEMENT.md) for your code contributions.
|
||||
You can view your signed CLA's by going to <https://cla-assistant.io/> and signing in.
|
||||
When submitting a pull request for the first time, you will be prompted to sign the [CLA](../CONTRIBUTOR_LICENSE_AGREEMENT.md) for your code contributions. You can view your signed CLA's by going to <https://cla-assistant.io/> and signing in.
|
||||
|
||||
|
||||
## Inactivity and user removal
|
||||
@@ -61,18 +63,18 @@ In case you are interested in coming back, please, ask again to be included in t
|
||||
The specific steps to add new packages are:
|
||||
|
||||
* Fork the [conan-center-index](https://github.com/conan-io/conan-center-index) git repository, and then clone it locally.
|
||||
* Copy a template from [package_templates](package_templates) folder in the recipes/ folder and rename it to the project name (it should be lower-case). Read templates [documentation](package_templates/README.md) to find more information.
|
||||
* Copy a template from [package_templates](../package_templates) folder in the recipes/ folder and rename it to the project name (it should be lower-case). Read templates [documentation](../package_templates/README.md) to find more information.
|
||||
* Make sure you are using the latest [Conan client](https://conan.io/downloads) version, as recipes might evolve introducing features of the newer Conan releases.
|
||||
* Commit and Push to GitHub then submit a pull request.
|
||||
* Our automated build service will build 100+ different configurations, and provide messages that indicate if there were any issues found during the pull request on GitHub.
|
||||
|
||||
:three: When the pull request is [reviewed and merged](review_process.md), those packages are published to [JFrog ConanCenter](https://conan.io/center/) and available for everyone.
|
||||
:three: When the pull request is [reviewed and merged](../review_process.md), those packages are published to [JFrog ConanCenter](https://conan.io/center/) and available for everyone.
|
||||
|
||||
### The Build Service
|
||||
|
||||
The **build service** associated to this repo 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.
|
||||
The **build service** associated to this repo 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.
|
||||
|
||||
> ⚠️ **Note**: This not a testing service, it is a binary building service for package **released**. 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.
|
||||
> ⚠️ **Note**: This not a testing service, it is a binary building service for package **released**. 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. Your PR may be reviewed in the mean time, but is not guaranteed.
|
||||
- The CI system will also report with messages in the PR any error in the process, even linking to the logs to see more details and debug.
|
||||
@@ -202,7 +204,7 @@ The CI will explore all the folders and run the tests for the ones matching `tes
|
||||
of them together in the testing logs.
|
||||
|
||||
> **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
|
||||
> `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_<package>` recipes should **test the package configuration that has just been generated** for the _host_ context, otherwise
|
||||
@@ -215,12 +217,12 @@ The [recipes](https://github.com/conan-io/conan-center-index/tree/master/recipes
|
||||
|
||||
### Header Only
|
||||
|
||||
If you are looking for header-only projects, you can take a look on [header-only template](package_templates/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 has a section about [how to package header-only libraries](https://docs.conan.io/en/latest/howtos/header_only.html).
|
||||
|
||||
### CMake
|
||||
|
||||
For C/C++ projects which use CMake for building, you can take a look on [cmake package template](package_templates/cmake_package).
|
||||
For C/C++ projects which use CMake for building, you can take a look on [cmake package template](../package_templates/cmake_package).
|
||||
|
||||
#### Components
|
||||
|
||||
@@ -240,7 +242,7 @@ For cases where a project only offers source files, but not a build script, you
|
||||
|
||||
### System Packages
|
||||
|
||||
> :information_source: 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.
|
||||
> :information_source: 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,
|
||||
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.
|
||||
@@ -278,14 +280,13 @@ An example of this can be found in the [sdl_image recipe](https://github.com/con
|
||||
The system will use the [conan-center hook](https://github.com/conan-io/hooks) to perform some quality checks. These are required for the
|
||||
the CI to merge any pull request.
|
||||
|
||||
Follow the [Developing Recipes Locally](developing_recipes_locally.md#installing-the-conancenter-hooks) guide for instructions.
|
||||
Follow the [Developing Recipes Locally](../developing_recipes_locally.md#installing-the-conancenter-hooks) guide for instructions.
|
||||
|
||||
Go to the [Error Knowledge Base](error_knowledge_base.md) page to know more about Conan Center hook errors.
|
||||
Go to the [Error Knowledge Base](../error_knowledge_base.md) page to know more about Conan Center hook errors.
|
||||
Some common errors related to Conan can be found on the [troubleshooting](https://docs.conan.io/en/latest/faq/troubleshooting.html) section.
|
||||
|
||||
### Linters
|
||||
|
||||
Linters are always executed by Github actions to validate parts of your recipe, for instance, if it uses migrated Conan tools imports.
|
||||
All executed linters are documented in [linters.md](linters.md).
|
||||
Check the [Developing Recipes](developing_recipes_locally.md#running-the-python-linters) page for running them locally.
|
||||
Check the [Developing Recipes](developing_recipes_locally.md#running-the-python-linters) for running them locally.
|
||||
All executed linters are documented in [linters.md](../linters.md).
|
||||
Check the [Developing Recipes](../developing_recipes_locally.md#running-the-python-linters) page for running them locally.
|
||||
@@ -1,8 +1,11 @@
|
||||
# conandata.yml
|
||||
|
||||
[conandata.yml](https://docs.conan.io/en/latest/reference/config_files/conandata.yml.html) is a [YAML](https://yaml.org/) file to provide declarative data for the recipe (which is imperative). `conandata.yml` is a built-in Conan feature (available since 1.22.0) without a fixed structure, but ConanCenterIndex uses it for its own purposes and imposes some requirements.
|
||||
[conandata.yml](https://docs.conan.io/en/latest/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.
|
||||
|
||||
In the context of ConanCenterIndex, this file is mandatory and consists of two main sections that we will explain in the next sections with more detail:
|
||||
In the context of ConanCenterIndex, this file is _mandatory_ and consists of two main sections that will be explained in the
|
||||
next sections with more detail:
|
||||
|
||||
* `sources`: Library sources origin with their verification checksums. Freeform structure specific to a recipe.
|
||||
* `patches`: Details about the different patches the library needs along with details for traceability.
|
||||
@@ -128,7 +131,10 @@ Also, you may use [sha256sum](https://linux.die.net/man/1/sha256sum) command ([w
|
||||
|
||||
Sometimes sources provided by project require patching for various reasons. The `conandata.yml` file is the right place to indicate this information as well.
|
||||
|
||||
This section follows the same pattern as the `sources` above: one entry per version with a list of patches to apply.
|
||||
> **Note**: Under our mission to ensure quality, patches undergo extra scrutiny. **Make sure to review** our
|
||||
> [Patching Policy](policy_patching.md) to understand the requirements before adding any.
|
||||
|
||||
This section follows the same pattern as the `sources` above - one entry per version with a list of patches to apply.
|
||||
|
||||
```yaml
|
||||
patches:
|
||||
@@ -215,7 +221,7 @@ As sources with backports don't act exactly the same as the version officially r
|
||||
|
||||
#### patch_source
|
||||
|
||||
_Optional_
|
||||
_Recommended_
|
||||
|
||||
`patch_source` is the URL from where patch was taken from. https scheme is preferred, but other URLs (e.g. git/svn/hg) are also accepted if there is no alternative. Types of patch sources are:
|
||||
|
||||
@@ -84,11 +84,11 @@ release/download webpage.
|
||||
All recipes should list the four settings `os`, `arch`, `compiler` and `build_type` so Conan will compute a different package ID
|
||||
for each combination. There are some particular cases for this general rule:
|
||||
|
||||
* **Recipes for _header only_ libraries** might omit the `settings` attibute, but in any case they should add
|
||||
* **Recipes for _header only_ libraries** might omit the `settings` attribute, but in any case they should add
|
||||
|
||||
```python
|
||||
def package_id(self):
|
||||
self.info.header_only()
|
||||
self.info.clear()
|
||||
```
|
||||
|
||||
* **Recipes that provide applications** (`b2`, `cmake`, `make`,...) that are generally used as a _build requires_, must list all
|
||||
@@ -103,7 +103,7 @@ for each combination. There are some particular cases for this general rule:
|
||||
Removing the `compiler` setting reduces the number of configurations generated by the CI, reducing the time and workload and, at the
|
||||
same time, demonstrates the power of Conan behind the package ID logic.
|
||||
|
||||
> Note.- Intentionally, the `build_type` setting should not be removed from the package ID in this case. Preserving this
|
||||
> **Note** Intentionally, the `build_type` setting should not be removed from the package ID in this case. Preserving this
|
||||
> setting will ensure that the package ID for Debug and Release configurations will be different and both binaries can be
|
||||
> available in the Conan cache at the same time. This enable consumers to switch from one configuration to the other in the case
|
||||
> they want to run or to debug those executables.
|
||||
@@ -113,9 +113,36 @@ for each combination. There are some particular cases for this general rule:
|
||||
Recipes can list any number of options with any meaning, and defaults are up to the recipe itself. The CI cannot enforce anything
|
||||
in this direction. However, there are a couple of options that have a special meaning for the CI.
|
||||
|
||||
### Recommended Names
|
||||
|
||||
Adding options is often needed to toggle specific library features on/off. Regardless of the default, there is a strong preference for using positive naming for options. In order to avoid the fragmentation, we recommend using the following naming conventions for such options:
|
||||
|
||||
- enable_<feature> / disable_<feature>
|
||||
- with_<dependency> / without_<dependency>
|
||||
- use_<feature>
|
||||
|
||||
The actual recipe code then may look like:
|
||||
|
||||
```py
|
||||
options = {"enable_locales": [True, False]} # Changes which files are compiled in to the library
|
||||
default_options = {"enable_locales": True}
|
||||
```
|
||||
|
||||
```py
|
||||
options = {"with_zlib": [True, False]} # Will add a `self.requires` with more deps to link against
|
||||
default_options = {"with_zlib": True}
|
||||
```
|
||||
|
||||
```py
|
||||
options = {"use_tzdb": [True, False]} # Might install more headers to expose more features
|
||||
default_options = {"use_tzdb": True}
|
||||
```
|
||||
|
||||
Having the same naming conventions for the options helps consumers. It allows users to specify options with wildcards: `-o *:with_threads=True`. Therefore, the `with_threads` options will be enabled for all packages in the graph that support it.
|
||||
|
||||
### 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.
|
||||
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 support, `header_only=False` is the default.
|
||||
|
||||
Usage of each option should follow the rules:
|
||||
@@ -125,7 +152,7 @@ Usage of each option should follow the rules:
|
||||
|
||||
> **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.
|
||||
> 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.
|
||||
@@ -160,36 +187,9 @@ Usage of each option should follow the rules:
|
||||
Instead, use Conan config [skip_test](https://docs.conan.io/en/latest/reference/config_files/global_conf.html#tools-configurations) feature:
|
||||
|
||||
```python
|
||||
def _configure_cmake(self):
|
||||
cmake = CMake(self)
|
||||
cmake.definitions['BUILD_TESTING'] = not self.conf.get("tools.build:skip_test", default=true, check_type=bool)
|
||||
def generate(self):
|
||||
tc = CMakeToolChain(self)
|
||||
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).
|
||||
|
||||
### Recommended feature options names
|
||||
|
||||
It's often needed to add options to toggle specific library features on/off. Regardless of the default, there is a strong preference for using positive naming for options. In order to avoid fragmentation, we recommend using the following naming conventions for such options:
|
||||
|
||||
- enable_<feature> / disable_<feature>
|
||||
- with_<dependency> / without_<dependency>
|
||||
- use_<feature>
|
||||
|
||||
the actual recipe code then may look like:
|
||||
|
||||
```py
|
||||
options = {"use_tzdb": [True, False]}
|
||||
default_options = {"use_tzdb": True}
|
||||
```
|
||||
|
||||
```py
|
||||
options = {"enable_locales": [True, False]}
|
||||
default_options = {"enable_locales": True}
|
||||
```
|
||||
|
||||
```py
|
||||
options = {"with_zlib": [True, False]}
|
||||
default_options = {"with_zlib": True}
|
||||
```
|
||||
|
||||
having the same naming conventions for the options may help consumers, e.g. they will be able to specify options with wildcards: `-o *:with_threads=True`, therefore, `with_threads` options will be enabled for all packages in the graph that support it.
|
||||
@@ -36,7 +36,7 @@ If possible, try to avoid mixing single quotes (`'`) and double quotes (`"`) in
|
||||
When extracting sources or performing out-of-source builds, it is preferable to use a _subfolder_ attribute, `_source_subfolder` and `_build_subfolder` respectively.
|
||||
|
||||
> **Note**: These are only required when using the legacy generator such as `cmake`. For the new generators like `CMakeToolchain` see
|
||||
> the [2.0 Migration Guide](v2_migration.md#using-layout-with-new-generators) for more information.
|
||||
> the [2.0 Migration Guide](../v2_migration.md#using-layout-with-new-generators) for more information.
|
||||
|
||||
For example doing this with property attributes for these variables:
|
||||
|
||||
@@ -69,7 +69,7 @@ The mandatory license attribute of each recipe **should** be a [SPDX license](ht
|
||||
|
||||
Where the SPDX guidelines do not apply, packages should do the following:
|
||||
|
||||
- When no license is provided or when it's given to the "public domain", the value should be set to [Unlicense](https://spdx.org/licenses/Unlicense) as per [KB-H056](error_knowledge_base.md#kb-h056-license-public-domain) and [FAQ](faqs.md#what-license-should-i-use-for-public-domain).
|
||||
- When no license is provided or when it's given to the "public domain", the value should be set to [Unlicense](https://spdx.org/licenses/Unlicense) as per [KB-H056](../error_knowledge_base.md#kb-h056-license-public-domain) and [FAQ](../faqs.md#what-license-should-i-use-for-public-domain).
|
||||
- When a custom (e.g. project specific) license is given, the value should be set to `LicenseRef-` as a prefix, followed by the name of the file which contains a custom license. See [this example](https://github.com/conan-io/conan-center-index/blob/e604534bbe0ef56bdb1f8513b83404eff02aebc8/recipes/fft/all/conanfile.py#L8). For more details, [read this conversation](https://github.com/conan-io/conan-center-index/pull/4928/files#r596216206)
|
||||
|
||||
## Exporting Patches
|
||||
@@ -47,6 +47,8 @@ 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:
|
||||
|
||||
@@ -65,9 +67,9 @@ conan config install
|
||||
|
||||
## Basic Commands
|
||||
|
||||
We recommend working from the `recipes/project` folder itself. You can learn about the [recipe file structure](how_to_add_packages.md#recipe-files-structure) to understand the folder and files located there.
|
||||
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_](how_to_add_packages.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.
|
||||
> **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:
|
||||
|
||||
@@ -96,11 +98,11 @@ To test with the same environment, the [build images](supported_platforms_and_co
|
||||
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 script that are tailored to their specific use cases. It's not uncommon to [patch build scripts](policy_patching.md#policy-about-patching) but make sure to read the [patch policy](policy_patching.md). You are encouraged to submit pull requests upstream.
|
||||
build script that are tailored to their specific use cases. It's not uncommon to [patch build scripts](adding_packages/policy_patching.md#policy-about-patching) but make sure to read the [patch policy](adding_packages/policy_patching.md). You are encouraged to submit pull requests upstream.
|
||||
|
||||
## Running the Python Linters
|
||||
|
||||
Linters are always executed by Github actions to validate parts of your recipe, for instance, if it uses migrated Conan tools imports.
|
||||
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:
|
||||
|
||||
|
||||
@@ -182,7 +182,7 @@ There is a complete explanation in the [FAQ](faqs.md#should-recipes-export-a-rec
|
||||
|
||||
#### **<a name="KB-H024">#KB-H024</a>: "TEST PACKAGE FOLDER"**
|
||||
|
||||
The [test_package](https://docs.conan.io/en/latest/creating_packages/getting_started.html#the-test-package-folder) folder is required for every recipe in Conan Center Index.
|
||||
The [test_package](https://docs.conan.io/en/latest/creating_packages/getting_started.html) folder is required for every recipe in Conan Center Index.
|
||||
|
||||
```
|
||||
. conanfile.py
|
||||
@@ -226,7 +226,7 @@ class SomeRecipe(ConanFile):
|
||||
#### **<a name="KB-H027">#KB-H027</a>: "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 current Conan Center Index address is https://github.com/conan-io/conan-center-index
|
||||
The current Conan Center Index address is <https://github.com/conan-io/conan-center-index>
|
||||
|
||||
#### **<a name="KB-H028">#KB-H028</a>: "CMAKE MINIMUM VERSION"**
|
||||
|
||||
@@ -242,7 +242,7 @@ project(conanwrapper)
|
||||
|
||||
#### **<a name="KB-H029">#KB-H029</a>: "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/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.
|
||||
|
||||
```python
|
||||
# test_package/conanfile.py
|
||||
@@ -256,7 +256,7 @@ class TestConan(ConanFile):
|
||||
#### **<a name="KB-H030">#KB-H030</a>: "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
|
||||
defined in [Adding Packages - `Conandata.yml` Format](conandata_yml_format.md).
|
||||
defined in [Adding Packages - `Conandata.yml` Format](adding_packages/conandata_yml_format.md).
|
||||
|
||||
#### **<a name="KB-H031">#KB-H031</a>: "CONANDATA.YML REDUCE"**
|
||||
|
||||
@@ -320,7 +320,7 @@ The attribue [default_options](https://docs.conan.io/en/latest/reference/conanfi
|
||||
|
||||
#### **<a name="KB-H052">#KB-H052</a>: "CONFIG.YML HAS NEW VERSION"**
|
||||
|
||||
It's important to have new library version defined in both [config.yml](how_to_add_packages.md#the-version-folders) and [conandata.yml](https://docs.conan.io/en/latest/reference/config_files/conandata.yml.html), otherwise newly added version will not be checked and built by CI and will not be available for download.
|
||||
It's important to have new library version defined in both [config.yml](adding_packages/README.md#the-version-folders) and [conandata.yml](https://docs.conan.io/en/latest/reference/config_files/conandata.yml.html), otherwise newly added version will not be checked and built by CI and will not be available for download.
|
||||
|
||||
#### **<a name="KB-H053">#KB-H053</a>: "PRIVATE IMPORTS"**
|
||||
|
||||
@@ -391,7 +391,7 @@ class SomeRecipe(ConanFile):
|
||||
|
||||
```
|
||||
|
||||
See also: [Submitting a Package](how_to_add_packages.md#submitting-a-package).
|
||||
See also: [Submitting a Package](adding_packages/README.md#submitting-a-package).
|
||||
|
||||
#### **<a name="KB-H066">#KB-H066</a>: "SHORT_PATHS USAGE"**
|
||||
|
||||
@@ -447,7 +447,7 @@ class SomeRecipe(ConanFile):
|
||||
|
||||
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.
|
||||
|
||||
- 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 packing policy](packaging_policy.md#settings) for more, should do as follows:
|
||||
- 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 packing policy](adding_packages/packaging_policy.md#settings) for more, should do as follows:
|
||||
|
||||
```python
|
||||
def package_id(self):
|
||||
@@ -469,7 +469,7 @@ Pylint is executed by default over all `conanfile.py` files in ConanCenterIndex
|
||||
|
||||
#### **<a name="KB-H073">#KB-H073</a>: "TEST V1 PACKAGE FOLDER"**
|
||||
|
||||
The legacy content in test_package should not be removed. Instead, rename that folder to `test_v1_package` and create a new `test_package` folder following the [file structure](https://github.com/conan-io/conan-center-index/blob/master/docs/how_to_add_packages.md#recipe-files-structure) related to Conan v2 and v1 compatibility. Also, you can obtain good examples of Conan v2 test packages from the [template packages](https://github.com/conan-io/conan-center-index/tree/master/docs/package_templates) folder.
|
||||
The legacy content in test_package should not be removed. Instead, rename that folder to `test_v1_package` and create a new `test_package` folder following the [file structure](adding_packages/README.md#recipe-files-structure) related to Conan v2 and v1 compatibility. Also, you can obtain good examples of Conan v2 test packages from the [template packages](package_templates/README.md) folder.
|
||||
|
||||
## Deprecated errors
|
||||
|
||||
|
||||
17
docs/faqs.md
17
docs/faqs.md
@@ -52,7 +52,7 @@ For example, `GSL` is the name of `Guidelines Support Library` from Microsoft an
|
||||
|
||||
## What is the policy on creating packages from pre-compiled binaries?
|
||||
|
||||
The policy is that in the general case [recipes should build packages from sources](packaging_policy.md), because of reproducibility and security concerns. The implication is that the sources must be publicly available, and in a format that can be consumed programmatically.
|
||||
The policy is that in the general case [recipes should build packages from sources](adding_packages/packaging_policy.md), because of reproducibility and security concerns. The implication is that the sources must be publicly available, and in a format that can be consumed programmatically.
|
||||
|
||||
Check the link for further details.
|
||||
|
||||
@@ -132,7 +132,7 @@ We often receive new fixes and improvements to the recipes already available for
|
||||
|
||||
## Do static libraries tend to be compiled as PIC by default?
|
||||
|
||||
Yes! You can learn more about default options in [Packaging Policy](packaging_policy.md#options).
|
||||
Yes! You can learn more about default options in [Packaging Policy](adding_packages/packaging_policy.md#options).
|
||||
|
||||
## Why PDB files are not allowed?
|
||||
|
||||
@@ -189,7 +189,7 @@ No. Some projects provide more than a simple library, but also applications. For
|
||||
## What license should I use for a custom project specific license?
|
||||
|
||||
When a non standard open-source license is used, we have decided to use `LicenseRef-` as a prefix, followed by the name of the file which contains a custom license.
|
||||
See [the reviewing guidlines](reviewing.md#license-attribute) for more details.
|
||||
See [the reviewing guidlines](adding_packages/reviewing.md#license-attribute) for more details.
|
||||
|
||||
## How do I flag a problem to a recipe consumer?
|
||||
|
||||
@@ -237,7 +237,7 @@ Older versions can be removed from packages given the considerations below. When
|
||||
that is specific to them: logic from the recipe and references in `config.yml` and `conandata.yml`. In any case, packages
|
||||
are never removed from ConanCenter remote.
|
||||
|
||||
When removing older versions, please take into account [these considerations](reviewing.md#supported-versions).
|
||||
When removing older versions, please take into account [these considerations](adding_packages/reviewing.md#supported-versions).
|
||||
|
||||
## Can I install packages from the system package manager?
|
||||
|
||||
@@ -248,7 +248,7 @@ The hook [KB-H032](error_knowledge_base.md#KB-H032) does not allow `system_requi
|
||||
system packages at same recipe.
|
||||
|
||||
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](how_to_add_packages.md#system-packages) for more.
|
||||
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/README.md#system-packages) for more.
|
||||
|
||||
## Why ConanCenter does **not** build and execute tests in recipes
|
||||
|
||||
@@ -261,7 +261,7 @@ There are different motivations
|
||||
## Why not add an option to build unit tests
|
||||
|
||||
- Adding a testing option will change the package ID, but will not provide different packaged binaries
|
||||
- Use the configuration [skip_test](packaging_policy.md#options-to-avoid) to define the testing behavior.
|
||||
- Use the configuration [skip_test](adding_packages/packaging_policy.md#options-to-avoid) to define the testing behavior.
|
||||
|
||||
## What is the policy for supported python versions?
|
||||
|
||||
@@ -403,8 +403,9 @@ Conan will build from sources all the packages and use the shared libraries when
|
||||
|
||||
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.
|
||||
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?
|
||||
|
||||
|
||||
@@ -38,7 +38,7 @@ and package structure will be required.
|
||||
### With New Generators
|
||||
|
||||
When doing this there is no need to manually define `self._subfolder_[...]` in a recipe.
|
||||
Simply use `self.source_folder` and `self.build_folder` instead of [subfolder properties](reviewing.md#subfolder-properties)
|
||||
Simply use `self.source_folder` and `self.build_folder` instead of "subfolder properties" that used to be the norm.
|
||||
|
||||
### With Multiple Build Helpers
|
||||
|
||||
@@ -76,7 +76,7 @@ In ConanCenterIndex this will typically looks like:
|
||||
- using a value
|
||||
```py
|
||||
#generators = "VirtualBuildEnv", "VirtualRunEnv"
|
||||
|
||||
|
||||
def build_requirements(self):
|
||||
self.tool_requires("tool/0.1")
|
||||
|
||||
|
||||
Reference in New Issue
Block a user