diff --git a/docs/adding_packages/README.md b/docs/adding_packages/README.md index b5b26e465ff01..92c0dbc7994a0 100644 --- a/docs/adding_packages/README.md +++ b/docs/adding_packages/README.md @@ -45,11 +45,11 @@ The process will be precisely like for newcomers. ## :two: Creating a package Once you've successfully built an existing recipe following [developing recipes](../developing_recipes_locally.md) tutorial. -You are set to being. +You are set to being adding a new package. Make sure you have: -* Fork and then clone the [conan-center-index](https://github.com/conan-io/conan-center-index) git repository. +* 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 easiest way to start is copying a template from our [`package_templates/`](../package_templates) folder to the [`recipes/`](../../recipes/) folder. @@ -59,14 +59,14 @@ to find more information. Quickly, there's a few items to look at: * 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`, ect... +* Make sure to update the [`ConanFile` attributes](conanfile_attributes.md) like `license`, `description`, etc... In ConanCenter, our belief is recipes should always match upstream, in other words, what the original author(s) intended. * Options should [follow these recommendations](conanfile_attributes.md#options) as well as match the default value used by the upstream project. * [Package information](build_and_package.md), libraries, components should match as well. This includes exposing supported build system names. -Where dependencies are involved, there's no shortcuts, inspect the upstream's build scripts for how they usually consume them. Pick the Conan +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 @@ -81,12 +81,12 @@ how or when a function is used in other recipes. > **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. -More often then not, ConanCenter recipes are built in more configuration then the upstream project. This means some edge cases need minor tweaks. -We **strongly encourage** everyone to contribute back to the upstream project. This reduce the burden of re-applying patches and overall makes the +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. 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 and specific conventions. +The documents in this folder are written to explain each folder, file, method, and attribute. 1. [Folders and Files](folders_and_files.md) 2. [Sources and Patches](sources_and_patches.md) @@ -125,7 +125,7 @@ For a C++ library, the system is currently generating more than 100 binary packa > **Note**: This not a testing service, it is a binary building service for **released** packages. Unit tests shouldn't be built nor run in recipes by default, see the [FAQs](../faqs.md#why-conancenter-does-not-build-and-execute-tests-in-recipes) for more. Before submitting a pull request, please ensure that it works locally for some configurations. * The CI bot will start a new build only [after the author is approved](#one-request-access). Your PR may be reviewed in the mean time, but is not guaranteed. -* The CI system will also report errors and build logs by creating a comment in the pull-request, The message will include links to the logs for inspecting. +* The CI system will also report errors and build logs by creating a comment in the pull-request, the message will include links to the logs for inspecting. * The Actions are used to lint and ensure the latest conventions are being used. You'll see comments from bots letting you know. Packages generated and uploaded by this build service do not include any _user_ or _channel_ (we generally recommend using `@user/channel` for private package diff --git a/docs/adding_packages/conanfile_attributes.md b/docs/adding_packages/conanfile_attributes.md index c343fc84531d8..1bc6affbddc93 100644 --- a/docs/adding_packages/conanfile_attributes.md +++ b/docs/adding_packages/conanfile_attributes.md @@ -19,7 +19,7 @@ or are known by ConanCenter's build service and have special meaning. ## Attributes -There's are a [key features](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/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 @@ -36,8 +36,8 @@ Please see the FAQs for: ### Version -ConanCenter is geared towards quickly added new release, the build service always pass the version it it currently building to the recipe. -The `version` attribute MUST NOT be added to any recipe - with except to "system packages". +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 @@ -51,7 +51,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 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 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). diff --git a/docs/adding_packages/folders_and_files.md b/docs/adding_packages/folders_and_files.md index ea17543534444..2149e21f0e4c7 100644 --- a/docs/adding_packages/folders_and_files.md +++ b/docs/adding_packages/folders_and_files.md @@ -1,6 +1,6 @@ # Folder and Files Structure -ConanCenterIndex has a specific structure for it's recipes, this allows the [build service](../README.md#the-build-service) +ConanCenterIndex has a specific structure for its recipes, this allows the [build service](../README.md#the-build-service) to work most efficiently. @@ -58,13 +58,13 @@ versions: folder: all ``` -This simply files has the following format: +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 no possible to maintain one recipe for all version, older version maybe moved to a separate folder. +If it's not possible to maintain one recipe for all version, older version maybe moved to a separate folder. ```yml versions: @@ -83,12 +83,12 @@ 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 . +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 are reproducible at a later point in time. Often -modifications are requires for a variety of reasons, which ones are associated to which version are listed under the `"patches"`. +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: @@ -114,7 +114,7 @@ def source(self): ``` See the [Export Patches](sources_and_patches.md#exporting-patches) and [Applying Patches](sources_and_patches.md#applying-patches) -for more use case and examples. +for more use cases and examples. #### `conanfile.py` @@ -125,7 +125,7 @@ It's the single most important part of writing a package. Every `conanfile.py` s 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 outline in this document and will link to more details +* Some of the key methods are outlined in this document and will link to more details ```python from conan import ConanFile @@ -136,17 +136,17 @@ class FmtConan(ConanFile): # ... ``` -When a package needs other packages those are can be include with the `requirements()` methods. +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 more use cases. +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). -List allows you to use the official build script from a project, see [build and package](build_and_package.md) instructions. +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): @@ -155,7 +155,7 @@ List allows you to use the official build script from a project, see [build and cmake.build() ``` -Most project's with build scripts support installing the important files. Avoid installing documentation or examples. +Most of the projects with build scripts support installing the important files. Avoid installing documentation or examples. ```python def package(self): @@ -185,7 +185,7 @@ The goal for the test package is to make sure the * libraries are available to link against * components are correctly exposed -> **Note** It's required to verify that the old generator are not broken. You can do so by using the pattern, see +> **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 diff --git a/docs/faqs.md b/docs/faqs.md index 2ba3356b7051b..93e154df52821 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -123,7 +123,7 @@ 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? -This happens for a number of reasons, some have a "live on main" others are less maintained but still merge pull requests. +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?