From 7129c016cb311c8b1aad07c001b3a7b5d8af8bce Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Wed, 25 Jan 2023 01:07:45 -0800 Subject: [PATCH] (#15004) docs: split out files and folders and the last few attributes * docs: organize "adding packages" by files and methods * typo * modernize the main readme + second pass to improve language * [docs] Regenerate tables of contents Co-authored-by: prince-chrismc * update the folder and files to match other recent changes * Apply suggestions from code review Co-authored-by: SSE4 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: prince-chrismc Co-authored-by: SSE4 --- docs/adding_packages/README.md | 211 +++++++------------ docs/adding_packages/conanfile_attributes.md | 65 ++++-- docs/adding_packages/folders_and_files.md | 192 +++++++++++++++++ docs/error_knowledge_base.md | 4 +- docs/faqs.md | 3 +- 5 files changed, 326 insertions(+), 149 deletions(-) create mode 100644 docs/adding_packages/folders_and_files.md diff --git a/docs/adding_packages/README.md b/docs/adding_packages/README.md index 19f9f5b8d9..92c0dbc799 100644 --- a/docs/adding_packages/README.md +++ b/docs/adding_packages/README.md @@ -3,180 +3,131 @@ 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. -To deepen you understanding, start with the [How to provide a good recipe](#how-to-provide-a-good-recipe) section. +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: ## Contents - * [Request access](#request-access) + * [:one: Request access](#one-request-access) * [Inactivity and user removal](#inactivity-and-user-removal) - * [Submitting a Package](#submitting-a-package) - * [The Build Service](#the-build-service) - * [Recipe files structure](#recipe-files-structure) - * [`config.yml`](#configyml) - * [`conandata.yml`](#conandatayml) - * [The _recipe folder_: `conanfile.py`](#the-_recipe-folder_-conanfilepy) - * [Test Folders](#test-folders) - * [Test the recipe locally](#test-the-recipe-locally) - * [Hooks](#hooks) - * [Linters](#linters) + * [:two: Creating a package](#two-creating-a-package) + * [How to provide a good recipe](#how-to-provide-a-good-recipe) + * [:three: Submitting a Package](#three-submitting-a-package) + * [The Build Service](#the-build-service) -## Request access +## :one: Request access -: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 +The first step to add packages to ConanCenter is requesting access. To enroll in ConanCenterIndex repository, please write a comment +requesting access in this GitHub [issue #4](https://github.com/conan-io/conan-center-index/issues/4). Feel free to introduce yourself and your motivation to join ConanCenter community. -This process helps ConanCenter against spam and malicious code. The process is not 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 fully automated on purpose and the requests are +generally approved on a weekly basis. Feel free to continue to step :two: while waiting for approval. > **Note** The requests are reviewed manually, checking the GitHub profile activity of the requester to avoid any misuse of the service. -> All interactions are subject to the expectations of the [code of conduct](../code_of_conduct.md). Any misuse or inappropriate behavior are subject -> to the same principals. +> 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 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 and signing in. ## Inactivity and user removal For security reasons related to the CI, when a user no longer contributes for a long period, it will be considered inactive and removed from the authorized user's list. For now, it's configured for **4 months**, and it's computed based on the latest commit, not comments or opened issues. After that time, the CI bot will ask to remove the user name from the authorized users' list through the access request PR, which occurs a few times every week. -In case you are interested in coming back, please, ask again to be included in the issue [#4](https://github.com/conan-io/conan-center-index/issues/4), the process will be precise like for newcomers. -## Submitting a Package +When you are interested in contributing again, simply ask again to be included in the [issue #4](https://github.com/conan-io/conan-center-index/issues/4). +The process will be precisely like for newcomers. -:two: To contribute a package, you can submit a [Pull Request](https://github.com/conan-io/conan-center-index/pulls) to this GitHub repository https://github.com/conan-io/conan-center-index. +## :two: Creating a package -The specific steps to add new packages are: +Once you've successfully built an existing recipe following [developing recipes](../developing_recipes_locally.md) tutorial. +You are set to being adding a new package. -* 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. -* Make sure you are using a recent [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. +Make sure you have: -: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. +* Forked and then cloned the [conan-center-index](https://github.com/conan-io/conan-center-index) git repository. +* Make sure you are using a recent [Conan client](https://conan.io/downloads) version, as recipes improve by introducing features of the newer Conan releases. -### The Build Service +The easiest way to start is copying a template from our [`package_templates/`](../package_templates) folder to the [`recipes/`](../../recipes/) folder. +Rename the new folder following the [project name](conanfile_attributes.md#name) guidelines. Read templates [documentation](../package_templates/README.md) +to find more information. -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. +Quickly, there's a few items to look at: -> ⚠️ **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. +* Add _only_ the latest version in the [`config.yml`](folders_and_files.md#configyml) and [`conandata.yml`](folders_and_files.md#conandatayml) +* Make sure to update the [`ConanFile` attributes](conanfile_attributes.md) like `license`, `description`, etc... -- 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. +In ConanCenter, our belief is recipes should always match upstream, in other words, what the original author(s) intended. -The pipeline will report errors and build logs by creating a comment in the pull-request after every commit. The message will include links to the logs for inspecting. +* Options should [follow these recommendations](conanfile_attributes.md#options) as well as match the default value used by the upstream project. +* [Package information](build_and_package.md), libraries, components should match as well. This includes exposing supported build system names. -Packages generated and uploaded by this build service don't include any _user_ or _channel_ (existing references with any `@user/channel` should be considered as deprecated in favor of packages without it). Once the packages are uploaded, you will be able to install them using the reference as `name/version` (requires Conan >= 1.21): `conan install cmake/3.18.2@`. +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 +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. -## Recipe files structure +### How to provide a good recipe -Every entry in the `recipes` folder contains all the files required by Conan to create the binaries for all the versions of one library. Those -files don't depend on any other file in the repository (we are not using `python_requires`) and every pull-request can modify only one of those -folders at a time. +Take a look at existing [recipes](https://github.com/conan-io/conan-center-index/tree/master/recipes) available in ConanCenterIndex which can be +used as good examples, you can use them as the base for your recipe. The GitHub search is very good for matching code snippets, you can see if, +how or when a function is used in other recipes. -This is the canonical structure of one of these folders, where the same `conanfile.py` recipe is suitable to build all the versions of the library: +> **Note**: Conan features change over time and our best practices evolve so some minor details may be out of date due to the vast number of recipes. -``` -. -+-- recipes -| +-- library_name/ -| +-- config.yml -| +-- all/ -| +-- conanfile.py -| +-- conandata.yml -| +-- patches/ -| +-- add-missing-string-header-2.0.0.patch -| +-- test_package/ -| +-- conanfile.py -| +-- CMakeLists.txt -| +-- test_package.cpp -| +-- test_v1_package/ -| +-- conanfile.py -| +-- CMakeLists.txt -``` +More often than not, ConanCenter recipes are built in more configuration than the upstream project. This means some edge cases need minor tweaks. +We **strongly encourage** everyone to contribute back to the upstream project. This reduces the burden of re-applying patches and overall makes the +the code more accessible. -If it becomes too complex to maintain the logic for all the versions in a single `conanfile.py`, it is possible to split the folder `all` into -two or more folders, dedicated to different versions, each one with its own `conanfile.py` recipe. In any case, those folders should replicate the -same structure. +Read the docs! The [FAQs](../faqs.md) are a great place to find short answers. +The documents in this folder are written to explain each folder, file, method, and attribute. -### `config.yml` +1. [Folders and Files](folders_and_files.md) +2. [Sources and Patches](sources_and_patches.md) + 1. [`conandata.yml` format](conandata_yml_format.md) +3. [`ConanFile` Attributes](conanfile_attributes.md) +4. [Dependencies](dependencies.md) +5. [Build and Package](build_and_package.md) + 1. [Revisit Patches](sources_and_patches.md#policy-about-patching) +6. [Test Package](test_packages.md) -This file lists the versions and the folders where they are located: +The one place you are certain to find a lot of information is , this has the documentation for everything in Conan. +There are helpful tutorials for cross-build, detailed explication for profiles and settings and much much more! -```yml -versions: - "1.1.0": - folder: 1.x.x - "1.1.1": - folder: 1.x.x - "2.0.0": - folder: all - "2.1.0": - folder: all -``` +## :three: Submitting a Package +To contribute a package, you can submit a [Pull Request](https://github.com/conan-io/conan-center-index/pulls) to this GitHub +repository . -### `conandata.yml` +The specific steps to submitting changes are: -This file lists **all the sources that are needed to build the package**: source code, patch files, license files,... any file that will be used by the recipe -should be listed here. The file is organized into two sections, `sources` and `patches`, each one of them contains the files that are required -for each version of the library. All the files that are downloaded from the internet should include a checksum, so we can validate that -they are not changed. +* Build and test the new recipe in several combinations. Check [developing recipes](../developing_recipes_locally.md) for tips. +* [Commit and push to your fork repository](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) then + [submit a pull request](https://github.com/conan-io/conan-center-index/compare). +* Our automated [build service](#the-build-service) will build 100+ different configurations, and provide messages that indicate if there + were any issues found during the pull request on GitHub. -A detailed breakdown of all the fields can be found in [conandata_yml_format.md](conandata_yml_format.md). We **strongly** encourage adding the [patch fields](conandata_yml_format.md#patches-fields) to help track where patches come from and what issue they solve. +When the pull request is [reviewed and merged](../review_process.md), those packages are published to [JFrog's ConanCenter](https://conan.io/center/) +and are made available for everyone. -Inside the `conanfile.py` recipe, this data is available in a `self.conan_data` attribute that can be used as follows: +## The Build Service -```py -def export_sources(self): - export_conandata_patches(self) +The **build service** associated to this repository will generate binary packages automatically for the most common platforms and compilers. +See [the Supported Platforms and Configurations page](../supported_platforms_and_configurations.md) for a list of generated configurations. +For a C++ library, the system is currently generating more than 100 binary packages. -def source(self): - files.get(self, **self.conan_data["sources"][self.version], destination=self.source_folder, strip_root=True) +> **Note**: This not a testing service, it is a binary building service for **released** packages. Unit tests shouldn't be built nor run in recipes by default, see the [FAQs](../faqs.md#why-conancenter-does-not-build-and-execute-tests-in-recipes) for more. Before submitting a pull request, please ensure that it works locally for some configurations. -def build(self): - files.apply_conandata_patches(self) - [...] -``` +* The CI bot will start a new build only [after the author is approved](#one-request-access). Your PR may be reviewed in the mean time, but is not guaranteed. +* The CI system will also report errors and build logs by creating a comment in the pull-request, the message will include links to the logs for inspecting. +* The Actions are used to lint and ensure the latest conventions are being used. You'll see comments from bots letting you know. -### The _recipe folder_: `conanfile.py` - -The main files in this repository are the `conanfile.py` ones that contain the logic to build the libraries from sources for all the configurations, -as we said before there can be one single recipe suitable for all the versions inside the `all` folder, or there can be several recipes targeting -different versions in different folders. For maintenance reasons, we prefer to have only one recipe, but sometimes the extra effort doesn't worth -it and it makes sense to split and duplicate it, there is no common rule for it. - -Together with the recipe, there can be other files that are needed to build the library: patches, other files related to build systems, -... all these files will usually be listed in `exports_sources` and used during the build process. - -Also, **every `conanfile.py` should be accompanied by one or several folder to test the generated packages** as we will see below. - -### Test Folders - -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). - -Learn more about the ConanCenterIndex requirements in the [test packages](test_packages.md) document. - -## Test the recipe locally - -### Hooks - -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. - -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. +Packages generated and uploaded by this build service do not include any _user_ or _channel_ (we generally recommend using `@user/channel` for private package +repositories as an easy way to distinguish them from public ones). Once the packages are uploaded, you will be able to install them using the reference as +`name/version` so example `conan install fmt/9.1.0@` for 1.x client or `conan install --requires=fmt/9.1.0` for 2.x clients. diff --git a/docs/adding_packages/conanfile_attributes.md b/docs/adding_packages/conanfile_attributes.md index c420841db7..1bc6affbdd 100644 --- a/docs/adding_packages/conanfile_attributes.md +++ b/docs/adding_packages/conanfile_attributes.md @@ -6,14 +6,55 @@ or are known by ConanCenter's build service and have special meaning. ## Contents - * [Order of methods and attributes](#order-of-methods-and-attributes) - * [License Attribute](#license-attribute) + * [Attributes](#attributes) + * [Name](#name) + * [Version](#version) + * [ConanCenter specific releases format](#conancenter-specific-releases-format) + * [License Attribute](#license) * [Settings](#settings) * [Options](#options) * [Recommended Names](#recommended-names) * [Predefined Options and Known Defaults](#predefined-options-and-known-defaults) * [Options to Avoid](#options-to-avoid) +## Attributes + +These are a [key feature](https://docs.conan.io/en/latest/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 +of through the web UI. Many of which are enforces with the [hooks](../error_knowledge_base.md). + +### Name + +Same as the _recipe folder_ and always lowercase. + +Please see the FAQs for: + +* [name collisions](../faqs.md#what-is-the-policy-on-recipe-name-collisions) +* [space and symbols](../faqs.md#should-reference-names-use---or-_) + +### Version + +ConanCenter is geared towards quickly added new release, the build service always pass the version it is currently building to the recipe. +The `version` attribute MUST NOT be added to any recipe - with exception to "system packages". + +#### ConanCenter specific releases format + +The notation shown below is used for publishing packages which do not match the original library's official releases. This format which includes the "datestamp" corresponding to the date of a commit: `cci.`. + +In order to create reproducible builds, we also "commit-lock" to the latest commit on that day. Otherwise, users would get inconsistent results over time when rebuilding the package. An example of this is the [RapidJSON](https://github.com/Tencent/rapidjson) library, where its package reference is `rapidjson/cci.20200410` and its sources are locked the latest commit on that date in [config.yml](https://github.com/conan-io/conan-center-index/blob/master/recipes/rapidjson/config.yml#L4). The prefix `cci.` is mandatory to distinguish as a virtual version provided by CCI. If you are interested to know about the origin, please, read [here](https://github.com/conan-io/conan-center-index/pull/1464). + +### License Attribute + +The mandatory license attribute of each recipe **should** be a [SPDX license](https://spdx.org/licenses/) [short Identifiers](https://spdx.dev/ids/) when applicable. + +Where the SPDX guidelines do not apply, packages should do the following: + +* When no license is provided or it's under the ["public domain"](https://fairuse.stanford.edu/overview/public-domain/welcome/) - these are not a license by itself. Thus, we have [equivalent licenses](https://en.wikipedia.org/wiki/Public-domain-equivalent_license) that should be used instead. If a project falls under these criteria it should be identified as the [Unlicense](https://spdx.org/licenses/Unlicense) license. +* 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 the 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). + + ## Order of methods and attributes Prefer the following order of documented methods in python code (`conanfile.py`, `test_package/conanfile.py`): @@ -21,22 +62,12 @@ Prefer the following order of documented methods in python code (`conanfile.py`, For `conan create` the order is listed [here](https://docs.conan.io/en/latest/reference/commands/creator/create.html#methods-execution-order) test packages recipes should append the following methods: -- deploy -- test +* deploy +* test the order above resembles the execution order of methods on CI. therefore, for instance, `build` is always executed before `package` method, so `build` should appear before the `package` in `conanfile.py`. -## License Attribute - -The mandatory license attribute of each recipe **should** be a [SPDX license](https://spdx.org/licenses/) [short Identifiers](https://spdx.dev/ids/) when applicable. - -Where the SPDX guidelines do not apply, packages should do the following: - -- When no license is provided or it's under the ["public domain"](https://fairuse.stanford.edu/overview/public-domain/welcome/) - these are not a license by itself. Thus, we have [equivalent licenses](https://en.wikipedia.org/wiki/Public-domain-equivalent_license) that should be used instead. If a project fall under these criteria it should be identified as the [Unlicense](https://spdx.org/licenses/Unlicense) license. -- 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 the 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). - - ## Settings As a general rule, recipes should set the `settings` attribute to: `os`, `arch`, `compiler` and `build_type`, and let Conan compute the package ID based on the settings. Some exceptions apply, as detailed below. For cases not covered here, please reach out to the Conan Center maintainers team for assistance. The following list is not exhaustive: @@ -69,9 +100,9 @@ in this direction. However, there are a couple of options that have a special me 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_ / disable_ -- with_ / without_ -- use_ +* enable_ / disable_ +* with_ / without_ +* use_ The actual recipe code then may look like: diff --git a/docs/adding_packages/folders_and_files.md b/docs/adding_packages/folders_and_files.md new file mode 100644 index 0000000000..2149e21f0e --- /dev/null +++ b/docs/adding_packages/folders_and_files.md @@ -0,0 +1,192 @@ +# Folder and Files Structure + +ConanCenterIndex has a specific structure for its recipes, this allows the [build service](../README.md#the-build-service) +to work most efficiently. + + +## Contents + + * [Recipe File Structure](#recipe-file-structure) + * [`config.yml`](#configyml) + * [The _recipe folder_](#the-_recipe-folder_) + * [`conandata.yml`](#conandatayml) + * [`conanfile.py`](#conanfilepy) + * [`test_package`](#test_package) + +## Recipe File Structure + +Every entry in the `recipes` folder contains all the files required by Conan to create the binaries for all the versions of one library. Those +files don't depend on any other file in the repository (we are not using `python_requires`) and every pull-request can modify only one of those +folders at a time. + +This is the canonical structure of one of these folders, where the same `conanfile.py` recipe is suitable to build all the versions of the library: + +> **Note**: For updating the structure during the [v2 migration](../v2_migration.md) see the [test package](test_packages.md#cmake-targets) document. + +```txt +. ++-- recipes +| +-- library_name/ +| +-- config.yml +| +-- all/ +| +-- conanfile.py +| +-- conandata.yml +| +-- patches/ +| +-- add-missing-string-header-2.1.0.patch +| +-- test_package/ +| +-- conanfile.py +| +-- CMakeLists.txt +| +-- test_pacakge.cpp +``` + +If it becomes too complex to maintain the logic for all the versions in a single `conanfile.py`, it is possible to split the folder `all/` into +more folders, dedicated to different versions, each one with its own `conanfile.py` recipe. In any case, those folders should replicate the +same structure. + +### `config.yml` + +This file lists the versions that should be built along with the corresponding [recipe folder](#the-recipe-folder) that will be used to package the project. + +> **Note**: It's strongly preferred to only have one recipe which should be in the `all/` folder. + +```yml +versions: + # It's encouraged to add new versions on the top + "2.1.0": + folder: all + "2.0.0": + folder: all +``` + +This simple file has the following format: + +* `versions` is a top level dictionary, containing a list of known versions. +* `folder` is a string entry providing the name of the folder, relative to the current directory where the `conanfile.py` that +can package that given folder. + +If it's not possible to maintain one recipe for all version, older version maybe moved to a separate folder. + +```yml +versions: + "2.1.0": + folder: all + "2.0.0": + folder: all + "1.1.1": + folder: 1.x.x # Older version with different build system and options that are not compatible with newer version +``` + +### The _recipe folder_ + +This contains every needed to build packages. + +#### `conandata.yml` + +This file lists **all the sources** that are needed to build the package. The most common examples are +source code, build scripts, license files. + +The file is organized into two sections, `"sources"` and `"patches"`, each one of them contains the files that are required +for each version of the library. Resources which need to be downloaded are listed under `"source"` should include a checksum +to validate that they do not change. This helps to ensure the build is reproducible at a later point in time. Often +modifications are required for a variety of reasons, which ones are associated to which version are listed under the `"patches"`. + +```yml +sources: + "9.0.0": + url: "https://github.com/fmtlib/fmt/archive/9.0.0.tar.gz" + sha256: "9a1e0e9e843a356d65c7604e2c8bf9402b50fe294c355de0095ebd42fb9bd2c5" +``` + +For more information about picking source tarballs, adding or removing versions, or what the rules are for patches, continue reading our +[Sources and Patches](sources_and_patches.md) guide. + +> **Note**: Under our mission to ensure quality, patches undergo extra scrutiny. **Make sure to review** our +> [modifying sources policy](sources_and_patches.md#policy-about-patching) before making changes. + +A detailed breakdown of all the fields can be found in [conandata_yml_format.md](conandata_yml_format.md). We **strongly** recommend adding the +[patch fields](conandata_yml_format.md#patches-fields) to help track where patches come from and what issue they solve. + +Inside the `conanfile.py` recipe, this data is available in a `self.conan_data` attribute that can be used as follows: + +```py +def source(self): + get(self, **self.conan_data["sources"][self.version], strip_root=True) +``` + +See the [Export Patches](sources_and_patches.md#exporting-patches) and [Applying Patches](sources_and_patches.md#applying-patches) +for more use cases and examples. + +#### `conanfile.py` + +This file is the recipe, it contains the logic to build the libraries from source for all the configurations. +It's the single most important part of writing a package. Every `conanfile.py` should be accompanied by at least one +[folder to test the generated packages](#test_package). + +Each recipe should derive the `ConanFile` class and implement key attributes and methods. + +* Basic attributes and conversions can be found in [`ConanFile` attributes](conanfile_attributes.md) +* Some of the key methods are outlined in this document and will link to more details + +```python +from conan import ConanFile + +class FmtConan(ConanFile): + name = "fmt" + homepage = "https://github.com/fmtlib/fmt" + # ... +``` + +When a package needs other packages those can be include with the `requirements()` method. + +```python + def requirements(self): + self.require("fmt/9.0.0") +``` + +For more information see the [Dependencies](dependencies.md) documentation. + +For compiled libraries, the `build()` method is used along side the [build helpers](https://docs.conan.io/en/latest/reference/build_helpers.html). +This allows you to use the official build script from a project, see [build and package](build_and_package.md) instructions. + +```python + def build(self): + cmake = CMake(self) + cmake.configure() + cmake.build() +``` + +Most of the projects with build scripts support installing the important files. Avoid installing documentation or examples. + +```python + def package(self): + cmake = CMake(self) + cmake.configure() + cmake.install() +``` + +For some projects, you will need to manually copy files. +Here's an example for a header only library: + +```python + def package(self): + copy(self, "*.h", src=os.path.join(self.source_folder, "include"), dst=os.path.join(self.package_folder, "include")) +``` + +#### `test_package` + +All the packages in this repository need to be tested before they join ConanCenter. A `test_package` folder with its +corresponding `conanfile.py` and a minimal project to test the package is strictly required. You can read about it in the +[Conan documentation](https://docs.conan.io/en/latest/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 + +* header files are available +* libraries are available to link against +* components are correctly exposed + +> **Note** It's required to verify that the old generators are not broken. You can do so by using the pattern, see +> [KB-H073](../error_knowledge_base.md#kb-h078) for details. + +Remember that the `test_` recipes should **test the package configuration that has just been generated** for the +_host_ context, otherwise it will fail in cross-building scenarios. diff --git a/docs/error_knowledge_base.md b/docs/error_knowledge_base.md index 655573acf7..7bbe54ac88 100644 --- a/docs/error_knowledge_base.md +++ b/docs/error_knowledge_base.md @@ -327,7 +327,9 @@ The attribue [default_options](https://docs.conan.io/en/latest/reference/conanfi #### **#KB-H052: "CONFIG.YML HAS NEW VERSION"** -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. +It's important to have new library version defined in both [config.yml](adding_packages/folders_and_files.md#configyml) and +[conandata.yml](adding_packages/folders_and_files.md#conandatayml), otherwise newly added version will not be checked and built +by CI and will not be available for download. #### **#KB-H053: "PRIVATE IMPORTS"** diff --git a/docs/faqs.md b/docs/faqs.md index 6b255f7001..93e154df52 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -123,7 +123,8 @@ Unless they are a general and extended utility in recipes (in which case, we sho ## What version should packages use for libraries without official releases? -The notation shown below is used for publishing packages where the original library does not make official releases. Thus, we use a format which includes the datestamp corresponding to the date of a commit: `cci.`. In order to create reproducible builds, we also "commit-lock" to the latest commit on that day (use UTC+00). Otherwise, users would get inconsistent results over time when rebuilding the package. An example of this is the [RapidJSON](https://github.com/Tencent/rapidjson) library, where its package reference is `rapidjson/cci.20200410` and its sources are locked the latest commit on that date in [conandata.yml](https://github.com/conan-io/conan-center-index/blob/master/recipes/rapidjson/all/conandata.yml#L5). The prefix `cci.` is mandatory to distinguish as a virtual version provided by CCI. If you are interested to know about the origin, please, read [here](https://github.com/conan-io/conan-center-index/pull/1464). +This happens for a number of reasons, some projects have a "live on main" others are less maintained but still merge pull requests. +Read about the [ConanCenter specific version format](adding_packages/conanfile_attributes.md#conancenter-specific-releases-format) for more information. ## Is the Jenkins orchestration library publicly available?