Skip to content

Commit 313343b

Browse files
davidsanfalAbrilRBSczoido
authoredMay 6, 2024··
conan runner docs added (#3699)
* conan runner docs added * Update reference/runners.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update reference/runners/docker.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update reference/runners/docker.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update reference/runners/docker.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update reference/runners/docker.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update reference/runners/docker.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update reference/runners/docker.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update reference/runners/docker.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * docker runners examples added * basic docker runner example updated * Update reference/runners.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/runners/docker.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * note about package id added * Update examples/runners/docker/basic.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * conan docker runner basic example updated --------- Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>
1 parent 6278ee9 commit 313343b

File tree

7 files changed

+760
-0
lines changed

7 files changed

+760
-0
lines changed
 

‎examples.rst

+1
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,4 @@ Examples
1515
examples/graph
1616
examples/dev_flow
1717
examples/commands
18+
examples/runners

‎examples/runners.rst

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. _examples_runners:
2+
3+
Conan runners examples
4+
======================
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
9+
runners/docker/basic
10+
runners/docker/configfile_build_args

‎examples/runners/docker/basic.rst

+477
Large diffs are not rendered by default.

‎examples/runners/docker/configfile_build_args.rst

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
.. _examples_runners_docker_configfile_build_args:
2+
3+
Using a docker runner configfile to parameterize a Dockerfile
4+
=============================================================
5+
6+
In this example we are going to see how to use a docker runner configfile to define our Dockerfile base image. Let’s create two profiles and a Dockerfile inside our project folder.
7+
8+
.. code-block:: bash
9+
10+
$ cd </my/runner/folder>
11+
$ tree
12+
.
13+
├── Dockerfile
14+
├── configfile
15+
├── docker_example_build
16+
└── docker_example_host
17+
18+
``docker_example_host`` profile
19+
20+
.. code-block:: text
21+
22+
[settings]
23+
arch=x86_64
24+
build_type=Release
25+
compiler=gcc
26+
compiler.cppstd=gnu17
27+
compiler.libcxx=libstdc++11
28+
compiler.version=11
29+
os=Linux
30+
[runner]
31+
type=docker
32+
configfile=</my/runner/folder>/configfile
33+
cache=copy
34+
remove=false
35+
36+
``docker_example_build`` profile
37+
38+
.. code-block:: text
39+
40+
[settings]
41+
arch=x86_64
42+
build_type=Release
43+
compiler=gcc
44+
compiler.cppstd=gnu17
45+
compiler.libcxx=libstdc++11
46+
compiler.version=11
47+
os=Linux
48+
49+
``configfile``
50+
51+
.. code-block:: yaml
52+
53+
image: my-conan-runner-image
54+
build:
55+
dockerfile: </my/runner/folder>
56+
build_context: </my/runner/folder>
57+
build_args:
58+
BASE_IMAGE: ubuntu:22.04
59+
run:
60+
name: my-conan-runner-container
61+
62+
63+
.. code-block:: docker
64+
:caption: Dockerfile
65+
66+
ARG BASE_IMAGE
67+
FROM $BASE_IMAGE
68+
RUN apt-get update \
69+
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
70+
build-essential \
71+
cmake \
72+
python3 \
73+
python3-pip \
74+
python3-venv \
75+
&& rm -rf /var/lib/apt/lists/*
76+
RUN pip install conan
77+
78+
In this example we are going to start from a totally clean docker, without containers or images. In addition, we are going to have the conan cache also completely empty.
79+
80+
.. code-block:: bash
81+
82+
$ conan list "*:*"
83+
Found 0 pkg/version recipes matching * in local cache
84+
85+
$ docker ps --all
86+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
87+
88+
$ docker images
89+
REPOSITORY TAG IMAGE ID CREATED SIZE
90+
91+
92+
Now, we are going to clone and build zlib from conan-center-index and create it using our new runner definition.
93+
94+
.. code-block:: bash
95+
96+
$ git clone https://github.com/conan-io/conan-center-index.git --depth 1
97+
$ conan create ./conan-center-index/recipes/zlib/all --version 1.3.1 -pr:h </my/runner/folder>/docker_example_host -pr:b </my/runner/folder>/docker_example_build
98+
99+
...
100+
101+
┌──────────────────────────────────────────────────┐
102+
| Building the Docker image: my-conan-runner-image |
103+
└──────────────────────────────────────────────────┘
104+
105+
Dockerfile path: '</my/runner/folder>/Dockerfile'
106+
Docker build context: '</my/runner/folder>'
107+
108+
Step 1/5 : ARG BASE_IMAGE
109+
110+
Step 2/5 : FROM $BASE_IMAGE
111+
112+
...
113+
114+
Successfully built 286df085400f
115+
Successfully tagged my-conan-runner-image:latest
116+
117+
...
118+
119+
┌───────────────────────────────┐
120+
| Creating the docker container |
121+
└───────────────────────────────┘
122+
123+
124+
┌─────────────────────────────────────────┐
125+
| Container my-conan-runner-image running |
126+
└─────────────────────────────────────────┘
127+
128+
129+
┌─────────────────────────────────────────┐
130+
| Running in container: "conan --version" |
131+
└─────────────────────────────────────────┘
132+
133+
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
134+
| Restore host cache from: </my/runner/folder>/conan-center-index/recipes/zlib/all/.conanrunner/docker_cache_save.tgz |
135+
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
136+
137+
Restore: zlib/1.3.1 in p/zlib95420566fc0dd
138+
Restore: zlib/1.3.1:b647c43bfefae3f830561ca202b6cfd935b56205 in p/zlibd59462fc4358e/p
139+
Restore: zlib/1.3.1:b647c43bfefae3f830561ca202b6cfd935b56205 metadata in p/zlibd59462fc4358e/d/metadata
140+
141+
┌────────────────────┐
142+
| Stopping container |
143+
└────────────────────┘
144+
145+
If we now check the status of our Conan and docker cache, we will see the zlib package compiled for Linux and the new docker image and container.
146+
147+
.. code-block:: bash
148+
149+
$ conan list "*:*"
150+
Found 1 pkg/version recipes matching * in local cache
151+
Local Cache
152+
zlib
153+
zlib/1.3.1
154+
revisions
155+
e20364c96c45455608a72543f3a53133 (2024-04-29 17:18:07 UTC)
156+
packages
157+
b647c43bfefae3f830561ca202b6cfd935b56205
158+
info
159+
settings
160+
arch: x86_64
161+
build_type: Release
162+
compiler: gcc
163+
compiler.version: 11
164+
os: Linux
165+
options
166+
fPIC: True
167+
shared: False
168+
169+
$ docker ps --all
170+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
171+
1379072ae424 my-conan-runner-image "/bin/bash -c 'while…" 17 seconds ago Exited (137) 2 seconds ago my-conan-runner-image
172+
173+
$ docker images
174+
REPOSITORY TAG IMAGE ID CREATED SIZE
175+
my-conan-runner latest 383b905f352e 22 minutes ago 531MB
176+
ubuntu 22.04 437ec753bef3 12 days ago 77.9MB
177+
178+
If we run the ``conan create`` command again we will see how Conan reuses the previous container because we have set ``remove=False``.
179+
180+
.. code-block:: bash
181+
182+
$ conan create ./conan-center-index/recipes/zlib/all --version 1.3.1 -pr:h </my/runner/folder>/docker_example_host -pr:b </my/runner/folder>/docker_example_build
183+
184+
...
185+
186+
┌───────────────────────────────┐
187+
| Starting the docker container |
188+
└───────────────────────────────┘
189+
190+
...

‎reference.rst

+1
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ Reference
1717
reference/environment
1818
reference/binary_model
1919
reference/conan_server
20+
reference/runners

‎reference/runners.rst

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. _reference_runners:
2+
3+
Runners
4+
=======
5+
6+
Runners provide a seamless method to execute Conan on remote build environments like Docker ones, directly from your local setup by simply configuring your host profile.
7+
8+
- Installing a version of Conan with runner dependencies ``pip install conan[runners]``.
9+
- Install the tools to run each of the runners (``docker``).
10+
- Add the ``[runner]`` section defined in the documentation of each runner to the host profile.
11+
12+
Runners:
13+
14+
.. toctree::
15+
:maxdepth: 1
16+
17+
runners/docker

‎reference/runners/docker.rst

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
.. _reference_runners_docker:
2+
3+
Docker runner
4+
=============
5+
6+
How to use a docker runner
7+
--------------------------
8+
9+
To run Conan inside a docker container you need to define a ``[runner]`` section in your host profile using the following fields:
10+
11+
- ``type`` **(mandatory)**: define the runner we want to use, in this case ``docker``.
12+
- ``dockerfile`` **(optional, default None)**: absolute path to a Dockerfile in case you want to build a docker image.
13+
- ``image`` **(optional, default conan-runner-default)**: docker image name you want to download from a docker registry or the name of the built image in case you define a dockerfile path.
14+
- ``cache`` **(optional, default clean)**: how docker container uses (or not) the host's Conan cache.
15+
16+
- ``clean``: use an empty cache.
17+
- ``copy``: copy the host cache inside the container using the :ref:`conan cache save/restore<reference_commands_cache>` command.
18+
- ``shared``: mount the host's Conan cache as a shared volume.
19+
20+
- ``remove`` **(optional, default false)**: ``true`` or ``false``. Remove the container after running the Conan command.
21+
- ``configfile`` **(optional, default None)**: Absolute path to a configuration file with extra parameters (see **extra configuration** section for more info).
22+
23+
.. note::
24+
25+
The runner profile section doesn't affect the package id.
26+
27+
Extra configuration
28+
-------------------
29+
30+
If you need more control over the build and execution of the container, you can define more parameters inside a ``configfile`` yaml.
31+
32+
.. code-block:: yaml
33+
34+
image: image_name # The image to build or run.
35+
build:
36+
dockerfile: /dockerfile/path # Dockerfile path.
37+
build_context: /build/context/path # Path within the build context to the Dockerfile.
38+
build_args: # A dictionary of build arguments
39+
foo: bar
40+
cacheFrom: # A list of images used for build cache resolution
41+
- image_1
42+
run:
43+
name: container_name # The name for this container.
44+
containerEnv: # Environment variables to set inside the container.
45+
env_var_1: env_value
46+
containerUser: user_name # Username or UID to run commands as inside the container.
47+
privileged: False # Run as privileged
48+
capAdd: # Add kernel capabilities.
49+
- SYS_ADMIN
50+
- MKNOD
51+
securityOpt: # A list of string values to customize labels for MLS systems, such as SELinux.
52+
- opt_1
53+
mount: # A dictionary to configure volumes mounted inside the container.
54+
/home/user1/: # The host path or a volume name
55+
bind: /mnt/vol2 # The path to mount the volume inside the container
56+
mode: rw # rw to mount the volume read/write, or ro to mount it read-only.
57+
58+
How to run a `conan create` in a runner
59+
---------------------------------------
60+
61+
In the following links you can find some examples about how to use a conan docker runner:
62+
63+
- :ref:`Creating a Conan package using a Docker runner<examples_runners_docker_basic>`
64+
- :ref:`Using a docker runner configfile to parameterize the Dockerfile base image<examples_runners_docker_configfile_build_args>`

0 commit comments

Comments
 (0)
Please sign in to comment.