Conan Repository

Cloudsmith provides public & private repositories for Conan (C & C++)

Conan is a dependency and package manager for C and C++. It is designed to help manage the development and Continuous Integration of C and C++ projects. Cloudsmith supports both Conan v1 and v2.

Conan Compatibility
Conan v1 and v2 packages are not compatible with each other. If you have v1 packages uploaded in our platform these won't be visible when using the Conan v2 CLI and have to be re-uploaded with the proper recipe changes. Please refer to the Conan v2 Migration Guide on how to.

For more information please see:

Conan: The official Conan website
Conan Documentation: The official docs for Conan

In the following examples:

Identifier	Description
OWNER	Your Cloudsmith account name or organization name (namespace)
REPOSITORY	Your Cloudsmith Repository name (also called "slug")
TOKEN	Your Cloudsmith Entitlement Token (see Entitlements for more details)
USERNAME	Your Cloudsmith username
PASSWORD	Your Cloudsmith password
API-KEY	Your Cloudsmith API Key
PACKAGE_NAME	The name of your package
PACKAGE_VERSION	The version number of your package

Upload a Package

Upload via Conan

The endpoint for the native Conan API is:

https://conan.cloudsmith.io/OWNER/REPOSITORY/

First, you need to set up the Repository as a Conan remote, with your Cloudsmith API-Key and Username for authentication:

shell

# Shell - Conan v1
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan user -p API-KEY -r OWNER-REPOSITORY USERNAME

shell

# Shell - Conan v2
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan remote login -p API-KEY OWNER-REPOSITORY USERNAME

You can then upload natively using Conan with the command:

shell

# Shell - Conan v1
conan upload PACKAGE_NAME/PACKAGE_VERSION --all -r OWNER-REPOSITORY

shell

# Shell - Conan v2
conan upload PACKAGE_NAME/PACKAGE_VERSION -r OWNER-REPOSITORY

An optional USER/CHANNEL can also be provided when uploading a package; this enables multiple versions of the same package to coexist using the user/channel to create a unique version of the package version:

shell

# Shell - Conan v1
conan upload PACKAGE_NAME/PACKAGE_VERSION@USER/CHANNEL --all -r OWNER-REPOSITORY

shell

# Shell - Conan v2
conan upload PACKAGE_NAME/PACKAGE_VERSION@USER/CHANNEL -r OWNER-REPOSITORY

The user/channel will also be used as a tag on the package which will allow for filtering within the UI.

Upload via the Cloudsmith CLI or Website

Note
Uploading using the Cloudsmith CLI or Website is only supported for Conan v1 packages. For v2 packages please use the Conan CLI tooling.

Create a Package

To upload via the Cloudsmith API/CLI, you'll need to generate a package first. The following commands can be used to produce a package and collect the additional files required for upload (otherwise handled by conan upload).

Note
Please see the Conan documentation on creating packages for more information on building your own packages.

You can build a package with Conan by creating a new example project using new, create, and export:

shell

# Shell - Conan v1
conan new PACKAGE_NAME/PACKAGE_VERSION -t
conan create .
conan install .
conan build .
conan package .
conan export .

To create a package, files need to be extracted from the Conan home directory:

shell

export CLOUDSMITH_REPOSITORY=OWNER/REPOSITORY

use _ when user/channel is treated

shell

path=/home/circleci/.conan/data/example-conan-package/0.0.1/_/_

List files in build directory (using wildcard to skip over autogenerated id):

shell

info_file=$(ls -d $path/package/*/conaninfo.txt)
metadata_file=( "$path/export/conanfile.py" )
manifest_file=( "$path/export/conanmanifest.txt" )
package_directory=( "$path/export" )

Create an archive in the current directory for upload (metadata only):

shell

tar -czf conan_package.tgz --absolute-names "$package_directory"

External network requests in conanfile.py
When extracting metadata from the conanfile.py, Cloudsmith restricts all network access, meaning that any attempt to reach external services from within your conanfile.py will fail, potentially leading package synchronization to fail.
Cloudsmith recommends keeping your conanfile.py as simple as possible to ensure your upload does not encounter any issues.

Upload via Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The package and additional files can then be uploaded via the Cloudsmith CLI. The following example shows an upload via the CLI.:

shell

cloudsmith push conan "$CLOUDSMITH_REPOSITORY" conan_package.tgz \
    --metadata-file "$metadata_file" \
    --info-file "$info_file"  \
    --manifest-file "$manifest_file"

Upload via Cloudsmith web app

Please see Upload a Package for details of how to upload via the Cloudsmith web app.

Download / Install a Package

First, the remote repository must be created and then credentials can be added for a user as follows:

Public Repositories

shell

# Shell - Conan v1
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan user -p API-KEY -r OWNER-REPOSITORY USERNAME

shell

# Shell - Conan v2
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan remote login -p API-KEY OWNER-REPOSITORY USERNAME

Private Repositories

Private Repositories
Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use.

Warning
Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code, or expose them in any logs.

shell

# Entitlement Token Auth - Conan v1
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan user -p TOKEN -r OWNER-REPOSITORY OWNER/REPOSITORY

shell

# HTTP Basic Auth (User & Pass) - Conan v1
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan user -p PASSWORD -r OWNER-REPOSITORY USERNAME

shell

# HTTP Basic Auth (API Key) - Conan v1
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan user -p API-KEY -r OWNER-REPOSITORY USERNAME

shell

# HTTP Basic Auth (Token) - Conan v1
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan user -p TOKEN -r OWNER-REPOSITORY token

shell

# Entitlement Token Auth - Conan v2
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan remote login -p TOKEN OWNER-REPOSITORY OWNER/REPOSITORY

shell

# HTTP Basic Auth (User & Pass) - Conan v2
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan remote login -p PASSWORD OWNER-REPOSITORY USERNAME

shell

# HTTP Basic Auth (API Key) - Conan v2
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan remote login -p API-KEY OWNER-REPOSITORY USERNAME

shell

# HTTP Basic Auth (Token) - Conan v2
conan remote add OWNER-REPOSITORY https://conan.cloudsmith.io/OWNER/REPOSITORY/
conan remote login -p TOKEN OWNER-REPOSITORY token

Install a Package

Once set up, Conan can download the package by running:

shell

# Shell - Conan v1/v2
conan download PACKAGE_NAME/PACKAGE_VERSION@ -r OWNER-REPOSITORY

Conan Revisions

Note
Package revisions uploads are only supported using Conan CLI. Uploading a v1 package with the Cloudsmith CLI or Website doesn't create a revision.

Cloudsmith Conan repositores support Package Revisions. By default all Conan v2 uploads use revisions.

Enable revisions in Conan v1

When using the Conan v1 CLI you have to explicitly enable revisions by either:

Adding revisions_enabled=1 in the [general] section of your conan.conf file (preferred)
Setting the CONAN_REVISIONS_ENABLED=1 environment variable.

After enabling revisions, the conan upload command will upload revisions instead.

Upstream Proxying / Caching

Not Supported

Key Signing Support

Not Supported by Format

Troubleshooting

Q. Why can my conanfile not access external services?

When extracting metadata from the conanfile.py, Cloudsmith restricts all network access, meaning that any attempt to reach external services from within your conanfile.py will fail, potentially leading to package synchronization to fail.

We recommend keeping your conanfile.py as simple as possible to ensure your upload has no issues.

Q. Why is my recipe failing to synchronize?

Similar to the previous point, when extracting metadata from the conanfile.py, Cloudsmith runs your recipe in an isolated secure environment. Things like:

Reading or writing files to the local filesystem
Reaching out to external services (with the exception of Conan Central), like GitHub.
Utilization of third-party python libraries
Dynamically setting metadata values like version, license, description, url, author, topics from external sources to the recipe file.

Will potentially lead to a synchronization failure. We recommend keeping your conanfile.py as simple as possible to ensure the upload has no issues.

If you or your organization have a use-case for any of the previous points please reach out to us.