--- stage: Package group: Package 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/#designated-technical-writers --- # Conan packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. Publish Conan packages in your project’s Package Registry. Then install the packages whenever you need to use them as a dependency. To publish Conan packages to the Package Registry, add the Package Registry as a remote and authenticate with it. Then you can run `conan` commands and publish your package to the Package Registry. ## Build a Conan package This section explains how to install Conan and build a package for your C/C++ project. 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). ### Install Conan Download the Conan package manager to your local development environment by following the instructions at [conan.io](https://conan.io/downloads.html). When installation is complete, verify you can use Conan in your terminal by running: ```shell conan --version ``` The Conan version is printed in the output: ```plaintext Conan version 1.20.5 ``` ### Install CMake When you develop with C++ and Conan, you can select from many available compilers. This example uses the CMake compiler. To install CMake: - For Mac, use [homebrew](https://brew.sh/) and run `brew install cmake`. - For other operating systems, follow the instructions at [cmake.org](https://cmake.org/install/). When installation is complete, verify you can use CMake in your terminal by running: ```shell cmake --version ``` The CMake version is printed in the output. ### Create a project 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). ### Build a package To build a package: 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: ```shell conan new Hello/0.1 -t ``` 1. Create a package for the recipe by running `conan create` with the Conan user and channel: ```shell conan create . mycompany/beta ``` NOTE: **Note:** 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). A package with the recipe `Hello/0.1@mycompany/beta` is created. For more details about creating and managing Conan packages, see the [Conan documentation](https://docs.conan.io/en/latest/creating_packages.html). ## Add the Package Registry as a Conan remote To run `conan` commands, you must add the Package Registry as a Conan remote for your project or instance. ### Add a remote for your project > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) in GitLab 13.4. 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`. To add the remote: 1. In your terminal, run this command: ```shell conan remote add gitlab https://gitlab.example.com/api/v4/projects//packages/conan ``` 1. Use the remote by adding `--remote=gitlab` to the end of your Conan command. For example: ```shell conan search Hello* --all --remote=gitlab ``` ### Add a remote for your instance Use a single remote to access packages across your entire GitLab instance. However, when using this remote, you must follow these [package naming restrictions](#package-recipe-naming-convention-for-instance-remotes). To add the remote: 1. In your terminal, run this command: ```shell conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan ``` 1. Use the remote by adding `--remote=gitlab` to the end of your Conan command. For example: ```shell conan search 'Hello*' --remote=gitlab ``` #### Package recipe naming convention for instance remotes 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. Example recipe names: | 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 | [Project remotes](#add-a-remote-for-your-project) have a more flexible naming convention. ## Authenticate to the Package Registry To authenticate to the Package Registry, you need either a personal access token or deploy token. - If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. - If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. ### Add your credentials to the GitLab remote Associate your token with the GitLab remote, so that you don't have to explicitly add a token to every Conan command. Prerequisites: - You must have an authentication token. - The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). In a terminal, run this command. In this example, the remote name is `gitlab`. Use the name of your remote. ```shell conan user -r gitlab -p ``` Now when you run commands with `--remote=gitlab`, your username and password are included in the requests. Alternatively, you can explicitly include your credentials in any given command. For example: ```shell CONAN_LOGIN_USERNAME= CONAN_PASSWORD= conan upload Hello/0.1@mycompany/beta --all --remote=gitlab ``` NOTE: **Note:** Because your authentication with GitLab expires on a regular basis, you may occasionally need to re-enter your personal access token. ### Set a default remote for your project (optional) 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. In a terminal, run this command: ```shell conan remote add_ref Hello/0.1@mycompany/beta gitlab ``` NOTE: **Note:** 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`. If you don't set a default user or remote, you can still include the user and remote in your commands: ```shell `CONAN_LOGIN_USERNAME= CONAN_PASSWORD= --remote=gitlab ``` ## Publish a Conan package Publish a Conan package to the Package Registry, so that anyone who can access the project can use the package as a dependency. Prerequisites: - 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. - For an instance remote, the package must meet the [naming convention](#package-recipe-naming-convention-for-instance-remotes). - You must have the project ID, which is on the project's homepage. To publish the package, use the `conan upload` command: ```shell conan upload Hello/0.1@mycompany/beta --all ``` ## Publish a Conan package by using CI/CD > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. To work with Conan commands in [GitLab CI/CD](../../../ci/README.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each Conan command in your `.gitlab-ci.yml` file. For example: ```yaml image: conanio/gcc7 create_package: stage: deploy script: - conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan - conan new /0.1 -t - conan create . +/stable - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload /0.1@+/stable --all --remote=gitlab ``` 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). ## Install a Conan package Install a Conan package from the Package Registry so you can use it as a dependency. Conan packages are often installed as dependencies by using the `conanfile.txt` file. Prerequisites: - 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. 1. In the project where you want to install the package as a dependency, open `conanfile.txt`. Or, in the root of your project, create a file called `conanfile.txt`. 1. Add the Conan recipe to the `[requires]` section of the file: ```plaintext [requires] Hello/0.1@mycompany/beta [generators] cmake ``` 1. At the root of your project, create a `build` directory and change to that directory: ```shell mkdir build && cd build ``` 1. Install the dependencies listed in `conanfile.txt`: ```shell conan install ``` NOTE: **Note:** If you try to install the package you just created in this tutorial, the package already exists on your local computer, so this command has no effect. ## Remove a Conan package There are two ways to remove a Conan package from the GitLab Package Registry. - From the command line, using the Conan client: ```shell conan remove Hello/0.2@user/channel --remote=gitlab ``` You must explicitly include the remote in this command, otherwise the package is removed only from your local system cache. NOTE: **Note:** This command removes all recipe and binary package files from the Package Registry. - From the GitLab user interface: Go to your project's **Packages & Registries > Package Registry**. Remove the package by clicking the red trash icon. ## Search for Conan packages in the Package Registry To search by full or partial package name, or by exact recipe, run the `conan search` command. - To search for all packages with a specific package name: ```shell conan search Hello --remote=gitlab ``` - To search for a partial name, like all packages starting with `He`: ```shell conan search He* --remote=gitlab ``` The scope of your search includes all projects you have permission to access. This includes your private projects as well as all public projects. ## Fetch Conan package information from the Package Registry The `conan info` command returns information about a package: ```shell conan info Hello/0.1@mycompany/beta ``` ## Supported CLI commands The GitLab Conan repository supports the following Conan CLI commands: - `conan upload`: Upload your recipe and package files to the Package Registry. - `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. - `conan info`: View the information on a given package from the Package Registry. - `conan remove`: Delete the package from the Package Registry.