PageRenderTime 77ms CodeModel.GetById 37ms RepoModel.GetById 0ms app.codeStats 0ms

/doc/user/packages/conan_repository/index.md

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