ericLemanissier/conan-center-index
1
0
Fork 1
mirror of https://github.com/conan-io/conan-center-index.git synced 2025-08-14 02:35:37 +00:00
Code Issues 6 Packages Projects Releases Wiki Activity

(#3328) Document _installers_ and packageID decisions AND rewrite some sections.

Browse Source 
* add docs about installers

* use MacOS

* Update docs/how_to_add_packages.md

Co-authored-by: Michael Keck <git@cr0ydon.com>

* Update docs/faqs.md

Co-authored-by: Chris Mc <prince.chrismc@gmail.com>

* Update docs/faqs.md

Co-authored-by: Chris Mc <prince.chrismc@gmail.com>

* Update docs/how_to_add_packages.md

Co-authored-by: Chris Mc <prince.chrismc@gmail.com>

* Update docs/supported_platforms_and_configurations.md

Co-authored-by: Chris Mc <prince.chrismc@gmail.com>

* other minor fixes

* concrete number of profiles

Co-authored-by: Michael Keck <git@cr0ydon.com>
Co-authored-by: Chris Mc <prince.chrismc@gmail.com>
This commit is contained in:
Javier G. Sogo
2020-10-30 10:01:32 +01:00
committed by GitHub
parent cb52072b4c
commit 0f9791f97c
3 changed files with 43 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/faqs.md
View File

@@ -51,7 +51,7 @@ No, recipes do not need to export a recipe license. Recipes and all files contri
## Why recipes that use build tools (like CMake) that have packages in Conan Center do not use it as a build require by default?
We generally consider tools like CMake as a standard tool to have installed in your system. Having the `cmake` package as a build require in all the recipes that use it will be an overkill, as every build required is installed like a requirement and takes time to download. However, `cmake` could be useful to use in your profile:
We generally consider tools like CMake as a standard tool to have installed in your system. Having the `cmake` package as a build require in **all** the recipes that use it will be an overkill, as every build requirement is installed like a requirement and takes time to download. However, `cmake` could still be useful to use in your profile:
```
[build_requires]
@@ -60,9 +60,9 @@ cmake/3.17.2
Other packages using more unusual build tools, like `OpenSSL` using `strawberryperl`, will have the build require in the recipe as it is likely that the user that want to build it from sources will not have it installed in their system
## Are python requires allowed in the conan-center-index?
## Are python requires allowed in the `conan-center-index`?
Unless they are a general and extended utility in recipes (in which case, we should study its inclusion in the Conan tools module), python requires are not allowed in conan-center-index.
Unless they are a general and extended utility in recipes (in which case, we should study its inclusion in the Conan tools module), python requires are not allowed in `conan-center-index` repository.
## What version should packages use for libraries without official releases?
@@ -96,3 +96,13 @@ However, there are ways to get around this, one of them is through the [/Z7](htt
#### Why is there no option for PDB, as there is for fPIC?
Adding one more common option, it seems the most simple and obvious solution, but it contains a side effect already seen with fPIC. It is necessary to manage the entire recipe, it has become a Boilerplate. So, adding PDB would be one more point to be reviewed for each recipe. In addition, in the future new options could arise, such as sanity or benchmark, further inflating the recipes. For this reason, a new option will not be added. However, the inclusion of the PDB files is discussed in issue [#1982](https://github.com/conan-io/conan-center-index/issues/1982) and there are some ideas for making this possible through a new feature. If you want to comment on the subject, please visit issue.
## Why _installer_ packages remove some settings from their package ID?
There are some recipes in `conan-center-index` that provide packages that contain only executables (some examples are `b2`, `cmake` or `make`), these packages are used in
`conan-center-index` itself as `build_require` and they are consumed as utilities or tools by other users. In these contexts, the expectations are to consume an optimized binary (`build_type=Release`) and it is not important the compiler used to build it.
We decided that these packages (as long as they match the premises) should list all the settings needed to build, so building from sources will generate the expected binary, but they will **remove `compiler` setting inside the `package_id()` method**. As a consequence, the CI will generate packages only for one compiler reducing the workload in the pipeline and the number of possible package IDs.
Note about `build_type`.- We retain the `build_type` setting to make it possible for the users to _debug_ these installer packages. We considered removing this settings and it would be possible to compile these packages in _debug_ mode, but if we remove it from the packageID, the compiled package would override the existing _release_ binary, and it'd be quite inconvenient for the users to compile the binary every time they need to switch from _debug_ to _release_.

23
docs/how_to_add_packages.md
View File

@@ -12,24 +12,24 @@ The specific steps to add new packages are:
* Push to GitHub, and 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.
When the pull request is reviewed and merged, those packages are published to center.conan.io.
When the pull request is reviewed and merged, those packages are published to [JFrog ConanCenter](https://conan.io/center/).
## More Information about Recipes
The [conan-center-index](https://github.com/conan-io/conan-center-index) (this repository) contains recipes for the [conan-center](https://bintray.com/conan/conan-center) repository.
The [conan-center-index](https://github.com/conan-io/conan-center-index) (this repository) contains recipes for the remote [conan-center](https://conan.io/center/) repository. This remote is added by default to a clean installation of the Conan client.
To contribute with a Conan recipe into the `conan-center` repository you can submit a [Pull Request](https://github.com/conan-io/conan-center-index/pulls) to the **master branch** of this repository. The connected **continuous integration system** will generate binary packages automatically for the most common platforms and compilers. See [the Supported Platforms and Configurations page](supported_platforms_and_configurations.md) to know the generated configurations. For a C++ library, the system is currently generating more than 100 binary packages.
Recipes are contributed by opening pull-requests to this `conan-center-index` repository as it is explained in the section below.
> ⚠️ **Note**: This CI service is not a testing service, it is a binary building service for package **releases**. Unit tests shouldn't be built nor ran in recipes by default. Before submitting a PR it is mandatory to run at least a local package creation.
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.
When pull requests are merged, the CI generated package binaries will be uploaded to ConanCenter. These packages won't contain the `@user/channel` part. You will be able to install them specifying only `library_name/version` as a requirement, omitting the `@user/channel` part. (Conan >= 1.21).
Previously existing packages in ConanCenter, with the full reference including `@user/channel` will still be available, but the previous process of “inclusion request” for getting them into Conan-center is now deprecated, and new contributions should follow this guide. Those packages will be gradually contributed to this repo to generate new binaries without the `@user/channel`.
When pull requests are merged, the CI will upload the generated packages to [JFrog ConanCenter](https://conan.io/center/). Packages generated and uploaded by this CI process 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@`.
## How to submit a Pull Request
To contribute a Conan recipe into the `conan-center` repository you can submit a [Pull Request](https://github.com/conan-io/conan-center-index/pulls). The connected **continuous integration system** 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 CI service is not a testing service, it is a binary building service for package **releases**. Unit tests shouldn't be built nor run in recipes by default. Please, before submitting a PR ensure that it works locally for some configurations.
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.
### Before start
Make sure you are using the latest [Conan client](https://conan.io/downloads) version, the recipes might evolve introducing features of the newer Conan releases.
@@ -133,7 +133,6 @@ Then in your `conanfile.py` method, it has to be used to download the sources:
```
### Test the recipe locally
The system will use the [conan-center hook](https://github.com/conan-io/hooks.git) to perform some quality checks. You can install the hook running:
@@ -149,4 +148,4 @@ Call `conan create . lib/1.0@` in the folder of the recipe using the profile you
### Debugging failed builds
Go to the [Error Knowledge Base](error_knowledge_base.md) page to know more.
Go to the [Error Knowledge Base](error_knowledge_base.md) page to know more.

23
docs/supported_platforms_and_configurations.md
View File

@@ -1,9 +1,24 @@
# Supported platforms and configurations
The pipeline iterates a fixed list of profiles for every Conan reference,
it computes the packageID for each profile and discard duplicates. Then it
builds the packages for the remaining profiles and upload them to
[JFrog ConanCenter](https://conan.io/center/) once the pull-request is merged.
Because duplicated packageIDs are discarded, the pipeline iterates the
profiles always in the same order and the profiles selected to build when
there is a duplicate follow some rules:
* Static linkage (option `shared=False`) is preferred over dynamic linking.
* On Windows, `MT/MTd` runtime linkage goes before `MD/MDd` linkage.
* Optimized binaries (`build_type=Release`) are preferred over its _debug_ counterpart.
* Older compiler versions are considered first.
* In Linux, GCC is iterated before Clang.
Currently, given the following supported platforms and configurations we
are generating **136 different binary packages for a C++ library**
and **88 for a C library**.
- For a **C++** library (with ``"shared"`` option) the system is generating **136** binary packages.
- For a **pure C** library (with ``"shared"`` option but without ``compiler.libcxx``) the system generates **88** binary packages.
- A package is also generated for those recipes with the `"header_only"` option.
## Windows
@@ -33,7 +48,7 @@
- Shared, Static (option `"shared": [True, False]` in the recipe when available)
- Header Only (option `"header_only": [True, False]` is only added with the value True)
## OSX
## MacOS
- Compilers: Apple-clang versions 9.1, 10.0, 11.0 (three latest versions, we will rotate the older when a new compiler version is released)
- C++ Standard Library (`libcxx`): `libc++`