conan-center-index/docs/adding_packages/folders_and_files.md

Folder and Files Structure

ConanCenterIndex has a specific structure for its recipes, this allows the build service to work most efficiently.

Contents

• Recipe File Structure
  • config.yml
  • The recipe folder
    • conandata.yml
    • 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:

.
+-- recipes
|   +-- library_name/
|       +-- config.yml
|       +-- all/
|           +-- conanfile.py
|           +-- conandata.yml
|           +-- patches/
|               +-- 2.1.0-0001-add-missing-string-header-.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 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.

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.

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 Conandata is officially documented in using the conandata.yml.

For more information about picking source tarballs, adding or removing versions, or what the rules are for patches, continue reading our Sources and Patches guide.

Note

: Under our mission to ensure quality, patches undergo extra scrutiny. Make sure to review our modifying sources policy before making changes.

A detailed breakdown of all the fields can be found in conandata_yml_format.md. We strongly recommend adding the patch fields to help track where patches come from and what issue they solve.

Inside the conanfile.py recipe, this data is available in through the self.conan_data attribute.

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.

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

When providing a test package, please:

• Create a minimal usage for the target project here
• Avoid upstream full examples, or code bigger than 15 lines
• Avoid networking connections
• Avoid background apps or servers
• Avoid GUI apps
• Avoid extra files like images, sounds and other binaries
• The propose is testing the generated artifacts ONLY

Remember that the test_<package> recipes should test the package configuration that has just been generated for the host context, otherwise it will fail in cross-building scenarios.