@@ -22,46 +22,134 @@ by default. To enable it for existing projects, or if you want to disable it:
You should then be able to see the **Packages** section on the left sidebar.
Before proceeding to authenticating with the GitLab Conan Repository, you should
get familiar with the package naming convention.
## Getting started
## Authenticating to the GitLab Conan Repository
This section will cover installing Conan and building a package for your C/C++ project. This is a quickstart if you are new
to Conan. If you already are using Conan and understand how to build your own packages, move on to the [next section](#adding-the-gitlab-package-registry-as-a-conan-remote).
You will need to generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication.
### Installing Conan
Follow the instructions at [conan.io](https://conan.io/downloads.html) to download the Conan package manager to your local development environment.
Once installation is complete, verify you can use Conan in your terminal by running
```sh
conan --version
```
You should see the Conan version printed in the output:
When developing with C++ and Conan, you have a wide range of options for compilers. This tutorial walks through using the cmake
compiler. In your terminal, run the command
Alternatively, you can set the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` in your local conan config to be used when connecting to the `gitlab` remote. The examples here show the username and password inline.
```sh
cmake --version
```
You should see the cmake version printed in the output. If you see something else, you may have to install cmake.
On a Mac, you can use [homebrew](https://brew.sh/) to install cmake by running `brew install cmake`. Otherwise, follow
instructions at [cmake.org](https://cmake.org/install/) for your operating system.
### Creating a project
Understanding what is needed to create a valid and compilable C++ project is out of the scope of this guide, but if you are new to C++ and want to try out the GitLab
package registry, Conan.io has a great [hello world starter project](https://github.com/conan-io/hello) that you can clone to get started.
Next, you'll need to set your Conan remote to point to the GitLab Package Registry.
Clone the repo and it can be used for the rest of the tutorial if you don't have your own C++ project.
## Setting the Conan remote to the GitLab Package Registry
### Building a package
After you authenticate to the [GitLab Conan Repository](#authenticating-to-the-gitlab-conan-repository),
you can set the Conan remote:
In your terminal, navigate to the root folder of your project. Generate a new recipe by running `conan new` and providing it with a
package name and version:
```sh
conan new Hello/0.1 -t
```
Next, you will create a package for that recipe by running `conan create` providing the Conan user and channel:
```sh
conan create . my-org+my-group+my-project/beta
```
NOTE: **Note**
Current [naming restrictions](#package-recipe-naming-convention) require you to name the `user` value as the `+` separated path of your project on GitLab.
The example above would create a package belonging to this project: `https://gitlab.com/my-org/my-group/my-project` with a channel of `beta`.
These two example commands will generate a final package with the recipe `Hello/0.1@my-org+my-group+my-project/beta`.
For more advanced details on creating and managing your packages, refer to the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html).
You are now ready to upload your package to the GitLab registry. To get started, first you will need to set GitLab as a remote, then you will need to add a Conan user for that remote to authenticate your requests.
## Adding the GitLab Package Registry as a Conan remote
Once the remote is set, you can use the remote when running Conan commands:
Once the remote is set, you can use the remote when running Conan commands by adding `--remote=gitlab` to the end of your commands.
For example:
```sh
conan search Hello*--all--remote=gitlab
```
## Supported CLI commands
## Authenticating to the GitLab Conan Repository
The GitLab Conan repository supports the following Conan CLI commands:
You will need to generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication.
-`conan upload`: Upload your recipe and package files to the GitLab Package Registry.
-`conan install`: Install a conan package from the GitLab Package Registry, this includes using the `conan.txt` file.
-`conan search`: Search the GitLab Package Registry for public packages, and private packages you have permission to view.
-`conan info`: View the info on a given package from the GitLab Package Registry.
-`conan remove`: Delete the package from the GitLab Package Registry.
### Adding a Conan user to the GitLab remote
Once you have a personal access token and have [set your Conan remote](#adding-the-gitlab-package-registry-as-a-conan-remote), you can associate the token with the remote so you do not have to explicitly add them to each Conan command you run:
```sh
conan user <gitlab-username> -r gitlab -p <personal_access_token>
```
Note: **Note**
If you named your remote something other than `gitlab`, your remote name should be used in this command instead of `gitlab`.
From now on, when you run commands using `--remote=gitlab`, your username and password will automatically be included in the requests.
Note: **Note**
The personal access token is not stored locally at any moment. Conan uses JWT, so when you run this command, Conan will request an expirable token from GitLab using your token. The JWT does expire on a regular basis, so you will need to re-enter your personal access token when that happens.
Alternatively, you could explicitly include your credentials in any given command.
### Setting a default remote to your project (optional)
If you'd like Conan to always use GitLab as the registry for your package, you can tell Conan to always reference the GitLab remote for a given package recipe:
The package recipe does include the version, so setting the default remote for `Hello/0.1@user/channel` will not work for `Hello/0.2@user/channel`.
This functionality is best suited for when you want to consume or install packages from the GitLab registry without having to specify a remote.
The rest of the example commands in this documentation assume that you have added a Conan user with your credentials to the `gitlab` remote and will not include the explicit credentials or remote option, but be aware that any of the commands could be run without having added a user or default remote:
Standard Conan recipe convention looks like `package_name/version@username/channel`.
Standard Conan recipe convention looks like `package_name/version@user/channel`.
**Recipe usernames must be the `+` separated project path**. The package
**The recipe user must be the `+` separated project path**. The package
name may be anything, but it is preferred that the project name be used unless
it is not possible due to a naming collision. For example:
...
...
@@ -95,7 +183,36 @@ A future iteration will extend support to [project and group level](https://gitl
## Installing a package
Add the conan package to the `[requires]` section of your `conan.txt` file and they will be installed when you run `conan install` within your project.
Conan packages are commonly installed as dependencies using the `conanfile.txt` file.
In your project where you would like to install the Conan package as a dependency, open `conanfile.txt` or create
an empty file named `conanfile.txt` in the root of your project.
Add the Conan recipe to the `[requires]` section of the file:
```ini
[requires]
Hello/0.1@my-group+my-project/beta
[generators]
cmake
```
Next, from the root of your project, create a build directory and navigate to it:
```sh
mkdir build &&cd build
```
Now you can install the dependencies listed in `conanfile.txt`:
```sh
conan install ..
```
NOTE: **Note:**
If you are trying to install the package you just created in this tutorial, not much will happen since that package
already exists on your local machine.
## Removing a package
...
...
@@ -104,8 +221,11 @@ There are two ways to remove a Conan package from the GitLab Package Registry.
| [Container Registry](container_registry/index.md) | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | 8.8+ |
| [Dependency Proxy](dependency_proxy/index.md)**(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | 11.11+ |
| [Conan Repository](conan_repository/index.md)**(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.4+ |
| [Conan Repository](conan_repository/index.md)**(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.6+ |
| [Maven Repository](maven_repository/index.md)**(PREMIUM)** | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ |
| [NPM Registry](npm_registry/index.md)**(PREMIUM)** | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ |
| [NuGet Repository](https://gitlab.com/gitlab-org/gitlab/issues/20050)**(PREMIUM)** | *COMING SOON* The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.7 (planned) |
