2020-06-23 00:09:42 +05:30
---
stage: Package
group: Package
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-23 00:09:42 +05:30
---
2021-03-11 19:13:27 +05:30
# Conan packages in the Package Registry **(FREE)**
2019-12-21 20:55:43 +05:30
2021-03-11 19:13:27 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab Premium 12.6.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3.
2019-12-21 20:55:43 +05:30
2021-03-11 19:13:27 +05:30
Publish Conan packages in your project's Package Registry. Then install the
2021-01-03 14:25:43 +05:30
packages whenever you need to use them as a dependency.
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
To publish Conan packages to the Package Registry, add the Package Registry as a
remote and authenticate with it.
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
Then you can run `conan` commands and publish your package to the
Package Registry.
2019-12-21 20:55:43 +05:30
2021-04-29 21:17:54 +05:30
For documentation of the specific API endpoints that the Conan package manager
client uses, see the [Conan API documentation ](../../../api/packages/conan.md ).
2021-01-03 14:25:43 +05:30
## Build a Conan package
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
This section explains how to install Conan and build a package for your C/C++
project.
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
If you already use Conan and know how to build your own packages, go to the
[next section ](#add-the-package-registry-as-a-conan-remote ).
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
### Install Conan
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
Download the Conan package manager to your local development environment by
following the instructions at [conan.io ](https://conan.io/downloads.html ).
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
When installation is complete, verify you can use Conan in your terminal by
running:
2020-03-13 15:44:24 +05:30
```shell
conan --version
```
2021-01-03 14:25:43 +05:30
The Conan version is printed in the output:
2020-03-13 15:44:24 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2020-03-13 15:44:24 +05:30
Conan version 1.20.5
```
2021-01-03 14:25:43 +05:30
### Install CMake
2021-01-29 00:20:46 +05:30
When you develop with C++ and Conan, you can select from many available
2021-03-08 18:12:59 +05:30
compilers. This example uses the CMake build system generator.
2021-01-03 14:25:43 +05:30
To install CMake:
2021-02-22 17:27:13 +05:30
- For Mac, use [Homebrew ](https://brew.sh/ ) and run `brew install cmake` .
2021-01-03 14:25:43 +05:30
- For other operating systems, follow the instructions at [cmake.org ](https://cmake.org/install/ ).
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
When installation is complete, verify you can use CMake in your terminal by
running:
2020-03-13 15:44:24 +05:30
```shell
cmake --version
```
2021-01-03 14:25:43 +05:30
The CMake version is printed in the output.
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
### Create a project
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
To test the Package Registry, you need a C++ project. If you don't already have
one, you can clone the Conan [hello world starter project ](https://github.com/conan-io/hello ).
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
### Build a package
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
To build a package:
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
1. Open a terminal and navigate to your project's root folder.
1. Generate a new recipe by running `conan new` with a package name and version:
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
```shell
conan new Hello/0.1 -t
```
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
1. Create a package for the recipe by running `conan create` with the Conan user
and channel:
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
```shell
conan create . mycompany/beta
```
2020-03-13 15:44:24 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-01-29 00:20:46 +05:30
If you use an [instance remote ](#add-a-remote-for-your-instance ), you must
follow a specific [naming convention ](#package-recipe-naming-convention-for-instance-remotes ).
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
A package with the recipe `Hello/0.1@mycompany/beta` is created.
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
For more details about creating and managing Conan packages, see the
[Conan documentation ](https://docs.conan.io/en/latest/creating_packages.html ).
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
## Add the Package Registry as a Conan remote
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
To run `conan` commands, you must add the Package Registry as a Conan remote for
2021-03-11 19:13:27 +05:30
your project or instance. Then you can publish packages to
and install packages from the Package Registry.
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
### Add a remote for your project
2020-11-24 15:15:51 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) in GitLab 13.4.
2021-01-03 14:25:43 +05:30
Set a remote so you can work with packages in a project without
having to specify the remote name in every command.
When you set a remote for a project, there are no restrictions to your package names.
However, your commands must include the full recipe, including the user and channel,
for example, `package_name/version@user/channel` .
2020-11-24 15:15:51 +05:30
To add the remote:
2021-01-03 14:25:43 +05:30
1. In your terminal, run this command:
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
```shell
conan remote add gitlab https://gitlab.example.com/api/v4/projects/< project_id > /packages/conan
```
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
1. Use the remote by adding `--remote=gitlab` to the end of your Conan command.
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
For example:
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
```shell
2021-04-29 21:17:54 +05:30
conan search Hello* --remote=gitlab
2021-01-03 14:25:43 +05:30
```
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
### Add a remote for your instance
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
Use a single remote to access packages across your entire GitLab instance.
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
However, when using this remote, you must follow these
[package naming restrictions ](#package-recipe-naming-convention-for-instance-remotes ).
To add the remote:
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
1. In your terminal, run this command:
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
```shell
conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan
```
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
1. Use the remote by adding `--remote=gitlab` to the end of your Conan command.
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
For example:
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
```shell
conan search 'Hello*' --remote=gitlab
```
#### Package recipe naming convention for instance remotes
2021-01-29 00:20:46 +05:30
The standard Conan recipe convention is `package_name/version@user/channel` , but
if you're using an [instance remote ](#add-a-remote-for-your-instance ), the
recipe `user` must be the plus sign (`+`) separated project path.
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
Example recipe names:
2020-11-24 15:15:51 +05:30
| Project | Package | Supported |
| ---------------------------------- | ----------------------------------------------- | --------- |
| `foo/bar` | `my-package/1.0.0@foo+bar/stable` | Yes |
| `foo/bar-baz/buz` | `my-package/1.0.0@foo+bar-baz+buz/stable` | Yes |
| `gitlab-org/gitlab-ce` | `my-package/1.0.0@gitlab-org+gitlab-ce/stable` | Yes |
| `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No |
2021-01-29 00:20:46 +05:30
[Project remotes ](#add-a-remote-for-your-project ) have a more flexible naming
convention.
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
## Authenticate to the Package Registry
2019-12-21 20:55:43 +05:30
2021-04-17 20:07:23 +05:30
GitLab requires authentication to upload packages, and to install packages
from private and internal projects. (You can, however, install packages
from public projects without authentication.)
2021-03-11 19:13:27 +05:30
To authenticate to the Package Registry, you need one of the following:
2020-05-24 23:13:21 +05:30
2021-03-11 19:13:27 +05:30
- A [personal access token ](../../../user/profile/personal_access_tokens.md )
with the scope set to `api` .
- A [deploy token ](../../project/deploy_tokens/index.md ) with the
scope set to `read_package_registry` , `write_package_registry` , or both.
- A [CI job token ](#publish-a-conan-package-by-using-cicd ).
2020-05-24 23:13:21 +05:30
2021-06-08 01:23:25 +05:30
NOTE:
Packages from private and internal projects are hidden if you are not
authenticated. If you try to search or download a package from a private or internal project without authenticating, you will receive the error `unable to find the package in remote` in the Conan client.
2021-01-03 14:25:43 +05:30
### Add your credentials to the GitLab remote
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
Associate your token with the GitLab remote, so that you don't have to
explicitly add a token to every Conan command.
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
Prerequisites:
- You must have an authentication token.
2021-01-29 00:20:46 +05:30
- The Conan remote [must be configured ](#add-the-package-registry-as-a-conan-remote ).
2021-01-03 14:25:43 +05:30
2021-01-29 00:20:46 +05:30
In a terminal, run this command. In this example, the remote name is `gitlab` .
Use the name of your remote.
2020-03-13 15:44:24 +05:30
```shell
2020-05-24 23:13:21 +05:30
conan user < gitlab_username or deploy_token_username > -r gitlab -p < personal_access_token or deploy_token >
2020-03-13 15:44:24 +05:30
```
2021-01-29 00:20:46 +05:30
Now when you run commands with `--remote=gitlab` , your username and password are
included in the requests.
2020-03-13 15:44:24 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-01-29 00:20:46 +05:30
Because your authentication with GitLab expires on a regular basis, you may
occasionally need to re-enter your personal access token.
2021-01-03 14:25:43 +05:30
### Set a default remote for your project (optional)
2021-01-29 00:20:46 +05:30
If you want to interact with the GitLab Package Registry without having to
specify a remote, you can tell Conan to always use the Package Registry for your
packages.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
In a terminal, run this command:
2020-03-13 15:44:24 +05:30
```shell
2020-11-24 15:15:51 +05:30
conan remote add_ref Hello/0.1@mycompany/beta gitlab
2020-03-13 15:44:24 +05:30
```
2021-02-22 17:27:13 +05:30
NOTE:
2021-01-29 00:20:46 +05:30
The package recipe includes the version, so the default remote for
`Hello/0.1@user/channel` doesn't work for `Hello/0.2@user/channel` .
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
If you don't set a default user or remote, you can still include the user and
remote in your commands:
2020-03-13 15:44:24 +05:30
```shell
2020-05-24 23:13:21 +05:30
`CONAN_LOGIN_USERNAME=< gitlab_username or deploy_token_username > CONAN_PASSWORD=< personal_access_token or deploy_token > < conan command > --remote=gitlab
2020-03-13 15:44:24 +05:30
```
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
## Publish a Conan package
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
Publish a Conan package to the Package Registry, so that anyone who can access
the project can use the package as a dependency.
2020-11-24 15:15:51 +05:30
2021-01-03 14:25:43 +05:30
Prerequisites:
2021-01-29 00:20:46 +05:30
- The Conan remote [must be configured ](#add-the-package-registry-as-a-conan-remote ).
- [Authentication ](#authenticate-to-the-package-registry ) with the
Package Registry must be configured.
- A local [Conan package ](https://docs.conan.io/en/latest/creating_packages/getting_started.html )
must exist.
2021-01-03 14:25:43 +05:30
- For an instance remote, the package must meet the [naming convention ](#package-recipe-naming-convention-for-instance-remotes ).
2021-01-29 00:20:46 +05:30
- You must have the project ID, which is on the project's homepage.
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
To publish the package, use the `conan upload` command:
2019-12-21 20:55:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-11-24 15:15:51 +05:30
conan upload Hello/0.1@mycompany/beta --all
2019-12-21 20:55:43 +05:30
```
2021-01-03 14:25:43 +05:30
## Publish a Conan package by using CI/CD
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7.
2020-03-13 15:44:24 +05:30
2021-09-30 23:02:18 +05:30
To work with Conan commands in [GitLab CI/CD ](../../../ci/index.md ), you can
2021-01-29 00:20:46 +05:30
use `CI_JOB_TOKEN` in place of the personal access token in your commands.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each Conan
command in your `.gitlab-ci.yml` file. For example:
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
```yaml
image: conanio/gcc7
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
create_package:
stage: deploy
script:
2021-09-04 01:27:46 +05:30
- conan remote add gitlab ${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/conan
2021-01-03 14:25:43 +05:30
- conan new < package-name > /0.1 -t
- conan create . < group-name > +< project-name > /stable
- CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload < package-name > /0.1@< group-name > +< project-name > /stable --all --remote=gitlab
2020-03-13 15:44:24 +05:30
```
2021-01-29 00:20:46 +05:30
Additional Conan images to use as the basis of your CI file are available in the
[Conan docs ](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images ).
2020-03-13 15:44:24 +05:30
2021-03-11 19:13:27 +05:30
### Re-publishing a package with the same recipe
When you publish a package that has the same recipe (`package-name/version@user/channel`)
as an existing package, the duplicate files are uploaded successfully and
are accessible through the UI. However, when the package is installed,
only the most recently-published package is returned.
2021-01-03 14:25:43 +05:30
## Install a Conan package
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
Install a Conan package from the Package Registry so you can use it as a
2021-03-11 19:13:27 +05:30
dependency. You can install a package from the scope of your instance or your project.
If multiple packages have the same recipe, when you install
a package, the most recently-published package is retrieved.
2020-03-13 15:44:24 +05:30
2021-03-08 18:12:59 +05:30
WARNING:
Project-level packages [cannot be downloaded currently ](https://gitlab.com/gitlab-org/gitlab/-/issues/270129 ).
2021-01-29 00:20:46 +05:30
Conan packages are often installed as dependencies by using the `conanfile.txt`
file.
2021-01-03 14:25:43 +05:30
Prerequisites:
2021-01-29 00:20:46 +05:30
- The Conan remote [must be configured ](#add-the-package-registry-as-a-conan-remote ).
2021-04-17 20:07:23 +05:30
- For private and internal projects, you must configure
[Authentication ](#authenticate-to-the-package-registry )
with the Package Registry.
2021-01-03 14:25:43 +05:30
2021-02-22 17:27:13 +05:30
1. In the project where you want to install the package as a dependency, open
2021-01-29 00:20:46 +05:30
`conanfile.txt` . Or, in the root of your project, create a file called
`conanfile.txt` .
2021-01-03 14:25:43 +05:30
1. Add the Conan recipe to the `[requires]` section of the file:
```plaintext
[requires]
Hello/0.1@mycompany/beta
[generators]
cmake
```
2021-01-29 00:20:46 +05:30
1. At the root of your project, create a `build` directory and change to that
directory:
2021-01-03 14:25:43 +05:30
```shell
mkdir build & & cd build
```
1. Install the dependencies listed in `conanfile.txt` :
```shell
2021-02-22 17:27:13 +05:30
conan install .. < options >
2021-01-03 14:25:43 +05:30
```
2020-03-13 15:44:24 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-01-03 14:25:43 +05:30
If you try to install the package you just created in this tutorial, the package
2021-01-29 00:20:46 +05:30
already exists on your local computer, so this command has no effect.
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
## Remove a Conan package
2019-12-21 20:55:43 +05:30
There are two ways to remove a Conan package from the GitLab Package Registry.
2021-01-03 14:25:43 +05:30
- From the command line, using the Conan client:
2019-12-21 20:55:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
conan remove Hello/0.2@user/channel --remote=gitlab
2019-12-21 20:55:43 +05:30
```
2021-01-29 00:20:46 +05:30
You must explicitly include the remote in this command, otherwise the package
is removed only from your local system cache.
2020-03-13 15:44:24 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-01-29 00:20:46 +05:30
This command removes all recipe and binary package files from the
Package Registry.
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
- From the GitLab user interface:
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
Go to your project's **Packages & Registries > Package Registry** . Remove the
package by clicking the red trash icon.
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
## Search for Conan packages in the Package Registry
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
To search by full or partial package name, or by exact recipe, run the
`conan search` command.
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
- To search for all packages with a specific package name:
```shell
conan search Hello --remote=gitlab
```
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
- To search for a partial name, like all packages starting with `He` :
2019-12-21 20:55:43 +05:30
2021-01-03 14:25:43 +05:30
```shell
conan search He* --remote=gitlab
```
2019-12-21 20:55:43 +05:30
2021-01-29 00:20:46 +05:30
The scope of your search includes all projects you have permission to access.
This includes your private projects as well as all public projects.
2021-01-03 14:25:43 +05:30
## Fetch Conan package information from the Package Registry
The `conan info` command returns information about a package:
2019-12-21 20:55:43 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-11-24 15:15:51 +05:30
conan info Hello/0.1@mycompany/beta
2019-12-21 20:55:43 +05:30
```
2020-03-13 15:44:24 +05:30
2021-01-03 14:25:43 +05:30
## Supported CLI commands
2020-03-13 15:44:24 +05:30
The GitLab Conan repository supports the following Conan CLI commands:
2021-01-03 14:25:43 +05:30
- `conan upload` : Upload your recipe and package files to the Package Registry.
2021-01-29 00:20:46 +05:30
- `conan install` : Install a Conan package from the Package Registry, which
includes using the `conanfile.txt` file.
- `conan search` : Search the Package Registry for public packages, and private
packages you have permission to view.
2021-01-03 14:25:43 +05:30
- `conan info` : View the information on a given package from the Package Registry.
- `conan remove` : Delete the package from the Package Registry.