/doc/user/packages/conan_repository/index.md
Markdown | 430 lines | 293 code | 137 blank | 0 comment | 0 complexity | fb9b40b79a89978a7a166a5067806ae8 MD5 | raw file
1---
2stage: Package
3group: Package
4info: 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
5---
6
7# Conan packages in the Package Registry **(FREE)**
8
9> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab 12.6.
10> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
11
12WARNING:
13The Conan package registry for GitLab is under development and isn't ready for production use due to
14limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6816) details the remaining
15work and timelines to make it production ready.
16
17Publish Conan packages in your project's Package Registry. Then install the
18packages whenever you need to use them as a dependency.
19
20To publish Conan packages to the Package Registry, add the Package Registry as a
21remote and authenticate with it.
22
23Then you can run `conan` commands and publish your package to the
24Package Registry.
25
26For documentation of the specific API endpoints that the Conan package manager
27client uses, see the [Conan API documentation](../../../api/packages/conan.md).
28
29## Build a Conan package
30
31This section explains how to install Conan and build a package for your C/C++
32project.
33
34If you already use Conan and know how to build your own packages, go to the
35[next section](#add-the-package-registry-as-a-conan-remote).
36
37### Install Conan
38
39Download the Conan package manager to your local development environment by
40following the instructions at [conan.io](https://conan.io/downloads.html).
41
42When installation is complete, verify you can use Conan in your terminal by
43running:
44
45```shell
46conan --version
47```
48
49The Conan version is printed in the output:
50
51```plaintext
52Conan version 1.20.5
53```
54
55### Install CMake
56
57When you develop with C++ and Conan, you can select from many available
58compilers. This example uses the CMake build system generator.
59
60To install CMake:
61
62- For Mac, use [Homebrew](https://brew.sh/) and run `brew install cmake`.
63- For other operating systems, follow the instructions at [cmake.org](https://cmake.org/install/).
64
65When installation is complete, verify you can use CMake in your terminal by
66running:
67
68```shell
69cmake --version
70```
71
72The CMake version is printed in the output.
73
74### Create a project
75
76To test the Package Registry, you need a C++ project. If you don't already have
77one, you can clone the Conan [hello world starter project](https://github.com/conan-io/hello).
78
79### Build a package
80
81To build a package:
82
831. Open a terminal and navigate to your project's root folder.
841. Generate a new recipe by running `conan new` with a package name and version:
85
86 ```shell
87 conan new Hello/0.1 -t
88 ```
89
901. Create a package for the recipe by running `conan create` with the Conan user
91 and channel:
92
93 ```shell
94 conan create . mycompany/beta
95 ```
96
97 NOTE:
98 If you use an [instance remote](#add-a-remote-for-your-instance), you must
99 follow a specific [naming convention](#package-recipe-naming-convention-for-instance-remotes).
100
101A package with the recipe `Hello/0.1@mycompany/beta` is created.
102
103For more details about creating and managing Conan packages, see the
104[Conan documentation](https://docs.conan.io/en/latest/creating_packages.html).
105
106#### Package without a username and a channel
107
108> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345055) in GitLab 14.6.
109
110Even though they are [recommended](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#user-channel)
111to distinguish your package from a similarly named existing package,
112the username and channel are not mandatory fields for a Conan package.
113
114You can create a package without a username and channel by removing them from
115the `create` command:
116
117```shell
118conan create .
119```
120
121The username _and_ the channel must be blank. If only one of these fields is
122blank, the request is rejected.
123
124NOTE:
125Empty usernames and channels can only be used if you use a [project remote](#add-a-remote-for-your-project).
126If you use an [instance remote](#add-a-remote-for-your-instance), the username
127and the channel must be set.
128
129## Add the Package Registry as a Conan remote
130
131To run `conan` commands, you must add the Package Registry as a Conan remote for
132your project or instance. Then you can publish packages to
133and install packages from the Package Registry.
134
135### Add a remote for your project
136
137> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) in GitLab 13.4.
138
139Set a remote so you can work with packages in a project without
140having to specify the remote name in every command.
141
142When you set a remote for a project, there are no restrictions to your package names.
143However, your commands must include the full recipe, including the user and channel,
144for example, `package_name/version@user/channel`.
145
146To add the remote:
147
1481. In your terminal, run this command:
149
150 ```shell
151 conan remote add gitlab https://gitlab.example.com/api/v4/projects/<project_id>/packages/conan
152 ```
153
1541. Use the remote by adding `--remote=gitlab` to the end of your Conan command.
155
156 For example:
157
158 ```shell
159 conan search Hello* --remote=gitlab
160 ```
161
162### Add a remote for your instance
163
164Use a single remote to access packages across your entire GitLab instance.
165
166However, when using this remote, you must follow these
167[package naming restrictions](#package-recipe-naming-convention-for-instance-remotes).
168
169To add the remote:
170
1711. In your terminal, run this command:
172
173 ```shell
174 conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan
175 ```
176
1771. Use the remote by adding `--remote=gitlab` to the end of your Conan command.
178
179 For example:
180
181 ```shell
182 conan search 'Hello*' --remote=gitlab
183 ```
184
185#### Package recipe naming convention for instance remotes
186
187The standard Conan recipe convention is `package_name/version@user/channel`, but
188if you're using an [instance remote](#add-a-remote-for-your-instance), the
189recipe `user` must be the plus sign (`+`) separated project path.
190
191Example recipe names:
192
193| Project | Package | Supported |
194| ---------------------------------- | ----------------------------------------------- | --------- |
195| `foo/bar` | `my-package/1.0.0@foo+bar/stable` | Yes |
196| `foo/bar-baz/buz` | `my-package/1.0.0@foo+bar-baz+buz/stable` | Yes |
197| `gitlab-org/gitlab-ce` | `my-package/1.0.0@gitlab-org+gitlab-ce/stable` | Yes |
198| `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No |
199
200[Project remotes](#add-a-remote-for-your-project) have a more flexible naming
201convention.
202
203## Authenticate to the Package Registry
204
205GitLab requires authentication to upload packages, and to install packages
206from private and internal projects. (You can, however, install packages
207from public projects without authentication.)
208
209To authenticate to the Package Registry, you need one of the following:
210
211- A [personal access token](../../../user/profile/personal_access_tokens.md)
212 with the scope set to `api`.
213- A [deploy token](../../project/deploy_tokens/index.md) with the
214 scope set to `read_package_registry`, `write_package_registry`, or both.
215- A [CI job token](#publish-a-conan-package-by-using-cicd).
216
217NOTE:
218Packages from private and internal projects are hidden if you are not
219authenticated. 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.
220
221### Add your credentials to the GitLab remote
222
223Associate your token with the GitLab remote, so that you don't have to
224explicitly add a token to every Conan command.
225
226Prerequisites:
227
228- You must have an authentication token.
229- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote).
230
231In a terminal, run this command. In this example, the remote name is `gitlab`.
232Use the name of your remote.
233
234```shell
235conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token>
236```
237
238Now when you run commands with `--remote=gitlab`, your username and password are
239included in the requests.
240
241NOTE:
242Because your authentication with GitLab expires on a regular basis, you may
243occasionally need to re-enter your personal access token.
244
245### Set a default remote for your project (optional)
246
247If you want to interact with the GitLab Package Registry without having to
248specify a remote, you can tell Conan to always use the Package Registry for your
249packages.
250
251In a terminal, run this command:
252
253```shell
254conan remote add_ref Hello/0.1@mycompany/beta gitlab
255```
256
257NOTE:
258The package recipe includes the version, so the default remote for
259`Hello/0.1@user/channel` doesn't work for `Hello/0.2@user/channel`.
260
261If you don't set a default user or remote, you can still include the user and
262remote in your commands:
263
264```shell
265`CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> <conan command> --remote=gitlab
266```
267
268## Publish a Conan package
269
270Publish a Conan package to the Package Registry, so that anyone who can access
271the project can use the package as a dependency.
272
273Prerequisites:
274
275- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote).
276- [Authentication](#authenticate-to-the-package-registry) with the
277 Package Registry must be configured.
278- A local [Conan package](https://docs.conan.io/en/latest/creating_packages/getting_started.html)
279 must exist.
280 - For an instance remote, the package must meet the [naming convention](#package-recipe-naming-convention-for-instance-remotes).
281- You must have the project ID, which is on the project's homepage.
282
283To publish the package, use the `conan upload` command:
284
285```shell
286conan upload Hello/0.1@mycompany/beta --all
287```
288
289## Publish a Conan package by using CI/CD
290
291> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in GitLab 12.7.
292> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
293
294To work with Conan commands in [GitLab CI/CD](../../../ci/index.md), you can
295use `CI_JOB_TOKEN` in place of the personal access token in your commands.
296
297You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each Conan
298command in your `.gitlab-ci.yml` file. For example:
299
300```yaml
301image: conanio/gcc7
302
303create_package:
304 stage: deploy
305 script:
306 - conan remote add gitlab ${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/conan
307 - conan new <package-name>/0.1 -t
308 - conan create . <group-name>+<project-name>/stable
309 - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab
310```
311
312Additional Conan images to use as the basis of your CI file are available in the
313[Conan docs](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images).
314
315### Re-publishing a package with the same recipe
316
317When you publish a package that has the same recipe (`package-name/version@user/channel`)
318as an existing package, the duplicate files are uploaded successfully and
319are accessible through the UI. However, when the package is installed,
320only the most recently-published package is returned.
321
322## Install a Conan package
323
324Install a Conan package from the Package Registry so you can use it as a
325dependency. You can install a package from the scope of your instance or your project.
326If multiple packages have the same recipe, when you install
327a package, the most recently-published package is retrieved.
328
329Conan packages are often installed as dependencies by using the `conanfile.txt`
330file.
331
332Prerequisites:
333
334- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote).
335- For private and internal projects, you must configure
336 [Authentication](#authenticate-to-the-package-registry)
337 with the Package Registry.
338
3391. In the project where you want to install the package as a dependency, open
340 `conanfile.txt`. Or, in the root of your project, create a file called
341 `conanfile.txt`.
342
3431. Add the Conan recipe to the `[requires]` section of the file:
344
345 ```plaintext
346 [requires]
347 Hello/0.1@mycompany/beta
348
349 [generators]
350 cmake
351 ```
352
3531. At the root of your project, create a `build` directory and change to that
354 directory:
355
356 ```shell
357 mkdir build && cd build
358 ```
359
3601. Install the dependencies listed in `conanfile.txt`:
361
362 ```shell
363 conan install .. <options>
364 ```
365
366NOTE:
367If you try to install the package you just created in this tutorial, the package
368already exists on your local computer, so this command has no effect.
369
370## Remove a Conan package
371
372There are two ways to remove a Conan package from the GitLab Package Registry.
373
374- From the command line, using the Conan client:
375
376 ```shell
377 conan remove Hello/0.2@user/channel --remote=gitlab
378 ```
379
380 You must explicitly include the remote in this command, otherwise the package
381 is removed only from your local system cache.
382
383 NOTE:
384 This command removes all recipe and binary package files from the
385 Package Registry.
386
387- From the GitLab user interface:
388
389 Go to your project's **Packages & Registries > Package Registry**. Remove the
390 package by selecting **Remove repository** (**{remove}**).
391
392## Search for Conan packages in the Package Registry
393
394To search by full or partial package name, or by exact recipe, run the
395`conan search` command.
396
397- To search for all packages with a specific package name:
398
399 ```shell
400 conan search Hello --remote=gitlab
401 ```
402
403- To search for a partial name, like all packages starting with `He`:
404
405 ```shell
406 conan search He* --remote=gitlab
407 ```
408
409The scope of your search includes all projects you have permission to access.
410This includes your private projects as well as all public projects.
411
412## Fetch Conan package information from the Package Registry
413
414The `conan info` command returns information about a package:
415
416```shell
417conan info Hello/0.1@mycompany/beta
418```
419
420## Supported CLI commands
421
422The GitLab Conan repository supports the following Conan CLI commands:
423
424- `conan upload`: Upload your recipe and package files to the Package Registry.
425- `conan install`: Install a Conan package from the Package Registry, which
426 includes using the `conanfile.txt` file.
427- `conan search`: Search the Package Registry for public packages, and private
428 packages you have permission to view.
429- `conan info`: View the information on a given package from the Package Registry.
430- `conan remove`: Delete the package from the Package Registry.