Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Drop Conan 1.x from CCI documentation #25875

Merged
merged 23 commits into from
Nov 11, 2024
Merged
Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Any maintenance, outage or important event related to the CI will be informed th

### Configure the Conan Center remote

> [!IMPORTANT]
> [!IMPORTANT]
> The Conan Center remote URL changed for **Conan 2** on November 2024 - the new URL is the default on new installations of Conan since version 2.9.2.
>
> New recipe updates are only published to this remote and are only guaranteed to be compatible with recent versions of Conan 2.
Expand Down Expand Up @@ -61,10 +61,8 @@ This is a list of shortcuts to some interesting topics:

* :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).
AbrilRBS marked this conversation as resolved.
Show resolved Hide resolved
* :hammer_and_wrench: The internal changes related to infrastructure can be checked in [docs/changelog.md](docs/changelog.md).
* :world_map: There are various community lead initiatives which are outlined in [docs/community_resources.md](docs/community_resources.md).
* :magic_wand: To start preparing your recipes for **Conan 2.0**, please check [docs/v2_migration.md](docs/v2_migration.md).

### Reporting Issues

Expand Down
4 changes: 0 additions & 4 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,7 @@ When pull requests are merged, the CI will upload the generated packages to the
+ [Developing Recipes Locally](developing_recipes_locally.md)
+ [Adding Packages to ConanCenter](adding_packages/README.md) :point_left: Best place to learn how to contribute
+ [Bumping versions to existing packages](bump_version.md)
+ [Errors from the conan-center hook (KB-Hxxx)](error_knowledge_base.md)
+ [Review Process](review_process.md)
+ [Labels](labels.md)
+ [Supported platforms and configurations](supported_platforms_and_configurations.md)
danimtb marked this conversation as resolved.
Show resolved Hide resolved
+ [Consuming Recipes](consuming_recipes.md) :information_source: Learn how to limit the impact of recipe changes
+ [Community Resources](community_resources.md)
+ [Preparing recipes for Conan 2.0](v2_migration.md)
+ [FAQs](faqs.md)
53 changes: 8 additions & 45 deletions docs/adding_packages/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,44 +4,22 @@ ConanCenterIndex aims to provide the best quality packages of any open source pr
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.
tutorial. To deepen you understanding, start with the [How to write a good recipe](#how-to-provide-a-good-recipe) section.
You can follow the three steps (:one: :two: :three:) described below! :tada:

<!-- toc -->
## Contents

* [:one: Request access](#one-request-access)
* [Inactivity and user removal](#inactivity-and-user-removal)
* [:one: First time contributors](#one-first-time-contributors)
* [:two: Creating a package](#two-creating-a-package)
* [How to provide a good recipe](#how-to-provide-a-good-recipe)
* [How to write a good recipe](#how-to-provide-a-good-recipe)
* [:three: Submitting a Package](#three-submitting-a-package)
* [The Build Service](#the-build-service)<!-- endToc -->

## :one: Request access

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 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.
## :one: First time contributors
AbrilRBS marked this conversation as resolved.
Show resolved Hide resolved

When submitting a pull request for the first time, you will be prompted to sign the [CLA](https://cla-assistant.io/conan-io/conan-center-index) 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

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.

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: Creating a package

Once you've successfully built an existing recipe following [developing recipes](../developing_recipes_locally.md) tutorial.
Expand All @@ -66,14 +44,7 @@ In ConanCenter, our belief is recipes should always match upstream, in other wor
* 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 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/1/reference/conanfile/tools/cmake/cmakedeps.html) generator. There are a few
things to be cautious about, many projects like to "vendor" other projects within them. This can be files checked into the repository or
downloaded during the build process. These should be removed, see the [Dependencies section](dependencies.md#handling-internal-dependencies)
for more information.

### How to provide a good recipe
### How to write a good recipe

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,
Expand All @@ -95,7 +66,6 @@ The documents in this folder are written to explain each folder, file, method, a
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)

The one place you are certain to find a lot of information is <https://docs.conan.io>, 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!
Expand All @@ -110,8 +80,6 @@ The specific steps to submitting changes are:
* 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.

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.
Expand All @@ -120,14 +88,9 @@ and are made available for everyone.

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.
For a C++ library, the system is currently generating more than 30 binary packages.
jcar87 marked this conversation as resolved.
Show resolved Hide resolved

> **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 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
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.
- The CI system will report the build logs in the Checks tab, in the pull-request.
- Linter and Hooks are automatically displayed in the Checks tab as well.
75 changes: 13 additions & 62 deletions docs/adding_packages/build_and_package.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,61 +17,15 @@ Both methods often use build helpers to build binaries and install them into the

## Build Method
AbrilRBS marked this conversation as resolved.
Show resolved Hide resolved

* `build()` method should focus on build only, not installation. During the build, nothing should be written in `package` folder. Installation step should only occur in `package()` method.

* The build itself should only rely on local files. Nothing should be downloaded from the internet during this step. If external files are required, they should come from `requirements` or `build_requirements` in addition to source files downloaded in `source()` or coming from the recipe itself through `export()` or `export_sources()`.

* Except for CMake, a working build toolchain (compiler, linker, archiver, etc.), and a "native generator" (`make` on *nix platforms, `mingw32-make` for MinGW, `MSBuild`/`NMake` for Visual Studio), the recipe should not assume that any other build tool is installed on the user-build machine (like Meson, autotools, or pkg-config). On Windows, the recipe should not assume that a shell is available (like MSYS2). Therefore, if the build method requires additional tools, they should be added to `build_requirements()`.
Tools explicitly marked as available by users through conf like `tools.gnu:make_program`, `tools.gnu:pkg_config`, `tools.microsoft.bash:path`, `tools.microsoft.bash:subsystem` should be taken into account to conditionally inject a build requirement (these conf should have precedence over build requirement equivalent hardcoded in the recipe).

* It is forbidden to run other conan client commands during build. In other words, if upstream build files call conan under the hood (through `cmake-conan` for example or any other logic), this logic must be removed.

* Settings from profile should be honored (`build_type`, `compiler.libcxx`, `compiler.cppstd`, `compiler.runtime` etc).

* Compiler paths from host profile should be honored and properly propagated to underlying build system during the build:

| compiler type | conf / env var |
|---------------|----------------|
| C compiler | `c` key of `tools.build:compiler_executables`, otherwise `CC` environment variable |
| C++ compiler | `cpp` key of `tools.build:compiler_executables`, otherwise `CXX` environment variable |
| ASM compiler | `asm` key of `tools.build:compiler_executables`, otherwise `CCAS` environment variable |
| CUDA compiler | `cuda` key of `tools.build:compiler_executables` |
| Fortran compiler | `fortran` key of `tools.build:compiler_executables`, otherwise `FC` environment variable |
| Objective-C compiler | `objc` key of `tools.build:compiler_executables` |
| Objective-C++ compiler | `objcpp` key of `tools.build:compiler_executables` |
| Resource files compiler | `rc` key of `tools.build:compiler_executables`, otherwise `RC` environment variable |
| Archiver | `AR` environment variable |
| Linker | `LD` environment variable |

They should be curated on the fly if underlying build system expects a specific format (no spaces in path, forward slash instead of back slash, etc).

* These compiler and linker conf from host profile should be honored and propagated to underlying build system during the build:
* `tools.build:cflags`
* `tools.build:cxxflags`
* `tools.build:defines`
* `tools.build:sharedlinklags`
* `tools.build:exelinkflags`
* `tools.apple:enable_bitcode` (only if host OS is `iOS`/`watchOS`/`tvOS`)

* Multithread build (if supported by underlying build system):
* if some steps are sensitive to race conditions, monothread should be enforced.
* otherwise multithreaded build should be enabled with a number of cores controlled by `tools.build:jobs` conf from host profile if it is set, otherwise to all cores of build machine.
For the `build()` method, the general scope used to build artifacts. Please, read
the official reference to [build()](https://docs.conan.io/2/reference/conanfile/methods/build.html) method.and the
uilianries marked this conversation as resolved.
Show resolved Hide resolved
[Build packages: the build() method](https://docs.conan.io/2/tutorial/creating_packages/build_packages.html).

## Package Method
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


* CMake config files must be removed. They will be generated for consumers by `CMakeDeps` generator (or legacy `cmake_find_package`/`cmake_find_package_multi` generators).

* pkg-config files must be removed. They will be generated for consumers by `PkgConfigDeps` generator (or legacy `pkg_config` generator).

* On *nix systems, executables and shared libraries should have empty `RPATH`/`RUNPATH`/`LC_RPATH`. Though, a relative path pointing inside package itself is allowed.

* On Apple OS family:
* shared libs: name field of `LC_ID_DYLIB` load command must be `@rpath/<libfilename>`.
* shared libs & executables: name field of each `LC_LOAD_DYLIB` load command should be `@rpath/<libdependencyfilename>` (except those refering to system libs or frameworks).

* Installed files must not contain absolute paths specific to build machine. Relative paths to other packages is also forbidden since relative paths of dependencies during build may not be the same for consumers. Hardcoded relative paths pointing to a location in the package itself are allowed.

* Static and shared flavors of the same library must not be packaged together.
The `package()` method is used to copy the artifacts to the `package_folder`. Please, read the official reference to
uilianries marked this conversation as resolved.
Show resolved Hide resolved
[package()](https://docs.conan.io/2/reference/conanfile/methods/package.html) method and the
[Package files: the package() method](https://docs.conan.io/2/tutorial/creating_packages/package_method.html).

## Build System Examples

Expand All @@ -82,31 +36,28 @@ General patterns about how they can be used for OSS in ConanCenterIndex can be f
### Header Only

If you are looking for header-only projects, you can take a look on [header-only template](../package_templates/header_only).
Also, Conan Docs have a section about [how to package header-only libraries](https://docs.conan.io/1/howtos/header_only.html).
Also, Conan Docs have a section about [how to package header-only libraries](https://docs.conan.io/2/tutorial/creating_packages/other_types_of_packages/header_only_packages.html).

### CMake

For C/C++ projects which use CMake for building, you can take a look on [cmake package template](../package_templates/cmake_package).

Another common use case for CMake based projects, both header only and compiled, is _modeling components_ to match the `find_package` and export the correct targets from Conan's generators. A basic examples of this is [cpu_features](https://github.com/conan-io/conan-center-index/blob/master/recipes/cpu_features/all/conanfile.py), a moderate/intermediate example is [cpprestsdk](https://github.com/conan-io/conan-center-index/blob/master/recipes/cpprestsdk/all/conanfile.py), and a very complex example is [OpenCV](https://github.com/conan-io/conan-center-index/blob/master/recipes/opencv/4.x/conanfile.py).

### Autotools

There is an [autotools package template](../package_templates/autotools_package/) amiable to start from.

However, if you need to use autotools for building, you can take a look on [libalsa](https://github.com/conan-io/conan-center-index/blob/master/recipes/libalsa/all/conanfile.py), [kmod](https://github.com/conan-io/conan-center-index/blob/master/recipes/kmod/all/conanfile.py), [libcap](https://github.com/conan-io/conan-center-index/blob/master/recipes/libcap/all/conanfile.py).

Many projects offer [**pkg-config**'s](https://www.freedesktop.org/wiki/Software/pkg-config/) `*.pc` files which need to be modeled using components. A prime example of this is [Wayland](https://github.com/conan-io/conan-center-index/blob/master/recipes/wayland/all/conanfile.py).

### No Upstream Build Scripts

For cases where a project only offers source files, but not a build script, you can add CMake support, but first, contact the upstream and open a PR offering building support. If it's rejected because the author doesn't want any kind of build script, or the project is abandoned, CCI can accept your build script. Take a look at [Bzip2](https://github.com/conan-io/conan-center-index/blob/master/recipes/bzip2/all/CMakeLists.txt) and [DirectShowBaseClasses](https://github.com/conan-io/conan-center-index/blob/master/recipes/directshowbaseclasses/all/CMakeLists.txt) as examples.
For cases where a project only offers source files but does not provide a build script, you can add CMake support.
However, it is essential to first contact the upstream maintainers and open a pull request (PR) offering building support.
If your PR is rejected because the author does not want any kind of build script, or if the project is abandoned, Conan Center Index (CCI) will consider accepting your build script based on the effort required to maintain it, as we aim to avoid adding scripts that may require significant ongoing maintenance.
Take a look at [Bzip2](https://github.com/conan-io/conan-center-index/blob/master/recipes/bzip2/all/CMakeLists.txt) as example.

### System Packages

> **Note**: For exceptional cases where only system packages can be used and a regular Conan package may result in an incompatible and fragile package, a separated system package may be created. See the [FAQs](../faqs.md#can-i-install-packages-from-the-system-package-manager) for more.

The [SystemPackageTool](https://docs.conan.io/1/reference/conanfile/methods.html#systempackagetool) can easily manage a system package manager (e.g. apt,
The [package_manager](https://docs.conan.io/2/reference/tools/system/package_manager.html#conan-tools-system-package-manager) can easily manage a system package manager (e.g. apt,
pacman, brew, choco) and install packages which are missing on Conan Center but available for most distributions. It is key to correctly fill in the `cpp_info` for the consumers of a system package to have access to whatever was installed.

As example there is [xorg](https://github.com/conan-io/conan-center-index/blob/master/recipes/xorg/all/conanfile.py). Also, it will require an exception rule for [conan-center hook](https://github.com/conan-io/hooks#conan-center), a [pull request](https://github.com/conan-io/hooks/pulls) should be open to allow it over the KB-H032.
As example there is [xorg](https://github.com/conan-io/conan-center-index/blob/master/recipes/xorg/all/conanfile.py).
Loading