Local Recipes Index Repository

The local_recipes_index repository is an experimental special type of repository to which you cannot upload packages or store binaries. The purpose of this remote is:

  • Enable contributors to share package recipes with the community, particularly for libraries that might not be suitable for ConanCenter.

  • It also simplifies the process of building binaries from a private conan-center-index fork, allowing absolute control over recipes, customization, and maintaining a stable repository snapshot. This ensures robustness against upstream changes in ConanCenter. For detailed setup and usage instructions, see the dedicated section in the Conan DevOps Guide Local Recipes Index Repository.

Setup

To set up a local recipes index repository to share your own recipes, you need to organize your recipes in a folder structure that mimics that of conan-center-index. To start you can use the local_recipes_index template for the conan new command. For demonstration purposes, let’s create a local-recipes-index repository for a hypothetical hello library, with a license incompatible with Conan Center, using the local_recipes_index template for the conan new command:

  1. $ mkdir repo && cd repo
  2. $ conan new local_recipes_index -d name=hello -d version=0.1 \
  3.     -d url=https://github.com/conan-io/libhello/archive/refs/tags/0.0.1.zip \
  4.     -d sha256=1dfb66cfd1e2fb7640c88cc4798fe25853a51b628ed9372ffc0ca285fe5be16b
  5. $ cd ..

The conan new local_recipes_index command creates a template that assumes CMake as the build system alongside other heavy assumptions. In practice, it will require customizing it, but for this demo, it works as-is. It will create a folder layout equal to the conan-center-index GitHub repository:

  1. .
  2. └── repo
  3.     └── recipes
  4.         └── hello
  5.             ├── all
  6.             │   ├── conandata.yml
  7.             │   ├── conanfile.py
  8.             │   └── test_package
  9.             │       ├── CMakeLists.txt
  10.             │       ├── conanfile.py
  11.             │       └── src
  12.             │           └── example.cpp
  13.             └── config.yml

After setting up the repository, we add it as a local remote to Conan:

  1. $ conan remote add mylocalrepo ./repo --allowed-packages="hello/*"

Please pay special attention to the –allowed-packages argument. This argument ensures that all packages other than hello are discarded by Conan. This can be used to minimize the surface area for a potential supply chain attack.

Now you can list and install packages from this new repository:

  1. $ conan list "*" -r=mylocalrepo
  2. $ conan install --requires=hello/0.1 -r=mylocalrepo --build=missing

At this point, you could push this repository to your GitHub account and share it with the community. Now, users simply need to clone the GitHub repository and add the cloned folder as a local repository themselves.

Note

Please be aware that, as we commented earlier, this feature is specifically tailored for scenarios where certain libraries are not suitable for ConanCenter. Remember, a “local-recipes-index” repository has limitations: it is not fully reproducible as it models only versions and not revisions, and it does not provide binaries. Therefore, outside of these cases, it is advised to use a remote package server such as Artifactory.

See also