conan runner docs added

examples.rst

@@ -15,3 +15,4 @@ Examples
    examples/graph
    examples/dev_flow
    examples/commands
+   examples/runners

examples/runners.rst

@@ -0,0 +1,10 @@
+.. _examples_runners:
+
+Conan runners examples
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   runners/docker/basic
+   runners/docker/configfile_build_args

examples/runners/docker/configfile_build_args.rst

@@ -0,0 +1,190 @@
+.. _examples_runners_docker_configfile_build_args:
+
+Using a docker runner configfile to parameterize a Dockerfile
+=============================================================
+
+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.
+
+.. code-block:: bash
+
+    $ cd </my/runner/folder>
+    $ tree
+    .
+    ├── Dockerfile
+    ├── configfile
+    ├── docker_example_build
+    └── docker_example_host
+
+``docker_example_host`` profile
+
+..  code-block:: text
+
+    [settings]
+    arch=x86_64
+    build_type=Release
+    compiler=gcc
+    compiler.cppstd=gnu17
+    compiler.libcxx=libstdc++11
+    compiler.version=11
+    os=Linux
+    [runner]
+    type=docker
+    configfile=</my/runner/folder>/configfile
+    cache=copy
+    remove=false
+
+``docker_example_build`` profile
+
+..  code-block:: text
+
+    [settings]
+    arch=x86_64
+    build_type=Release
+    compiler=gcc
+    compiler.cppstd=gnu17
+    compiler.libcxx=libstdc++11
+    compiler.version=11
+    os=Linux
+
+``configfile``
+
+..  code-block:: yaml
+
+    image: my-conan-runner-image
+    build:
+        dockerfile: </my/runner/folder>
+        build_context: </my/runner/folder>
+        build_args:
+            BASE_IMAGE: ubuntu:22.04
+    run:
+        name: my-conan-runner-container
+
+
+..  code-block:: docker
+    :caption: Dockerfile
+
+    ARG BASE_IMAGE
+    FROM $BASE_IMAGE
+    RUN apt-get update \
+        && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+            build-essential \
+            cmake \
+            python3 \
+            python3-pip \
+            python3-venv \
+        && rm -rf /var/lib/apt/lists/*
+    RUN pip install conan
+
+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.
+
+.. code-block:: bash
+
+    $ conan list "*:*"
+    Found 0 pkg/version recipes matching * in local cache
+
+    $ docker ps --all
+    CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
+
+    $ docker images  
+    REPOSITORY   TAG       IMAGE ID   CREATED   SIZE
+
+
+Now, we are going to clone and build zlib from conan-center-index and create it using our new runner definition.
+
+.. code-block:: bash
+
+    $ git clone https://github.com/conan-io/conan-center-index.git --depth 1
+    $ 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
+
+    ...
+
+    ┌──────────────────────────────────────────────────┐
+    | Building the Docker image: my-conan-runner-image |
+    └──────────────────────────────────────────────────┘
+
+    Dockerfile path: '</my/runner/folder>/Dockerfile'
+    Docker build context: '</my/runner/folder>'
+
+    Step 1/5 : ARG BASE_IMAGE
+
+    Step 2/5 : FROM $BASE_IMAGE
+
+    ...
+
+    Successfully built 286df085400f
+    Successfully tagged my-conan-runner-image:latest
+
+    ...
+
+    ┌───────────────────────────────┐
+    | Creating the docker container |
+    └───────────────────────────────┘
+
+
+    ┌─────────────────────────────────────────┐
+    | Container my-conan-runner-image running |
+    └─────────────────────────────────────────┘
+
+
+    ┌─────────────────────────────────────────┐
+    | Running in container: "conan --version" |
+    └─────────────────────────────────────────┘
+
+    ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+    | Restore host cache from: </my/runner/folder>/conan-center-index/recipes/zlib/all/.conanrunner/docker_cache_save.tgz |
+    └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+
+    Restore: zlib/1.3.1 in p/zlib95420566fc0dd
+    Restore: zlib/1.3.1:b647c43bfefae3f830561ca202b6cfd935b56205 in p/zlibd59462fc4358e/p
+    Restore: zlib/1.3.1:b647c43bfefae3f830561ca202b6cfd935b56205 metadata in p/zlibd59462fc4358e/d/metadata
+
+    ┌────────────────────┐
+    | Stopping container |
+    └────────────────────┘
+
+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.
+
+.. code-block:: bash
+
+    $ conan list "*:*"
+    Found 1 pkg/version recipes matching * in local cache
+    Local Cache
+    zlib
+        zlib/1.3.1
+        revisions
+            e20364c96c45455608a72543f3a53133 (2024-04-29 17:18:07 UTC)
+            packages
+                b647c43bfefae3f830561ca202b6cfd935b56205
+                info
+                    settings
+                    arch: x86_64
+                    build_type: Release
+                    compiler: gcc
+                    compiler.version: 11
+                    os: Linux
+                    options
+                    fPIC: True
+                    shared: False
+
+    $ docker ps --all
+    CONTAINER ID   IMAGE                   COMMAND                  CREATED          STATUS                       PORTS     NAMES
+    1379072ae424   my-conan-runner-image   "/bin/bash -c 'while…"   17 seconds ago   Exited (137) 2 seconds ago             my-conan-runner-image
+
+    $ docker images  
+    REPOSITORY        TAG       IMAGE ID       CREATED          SIZE
+    my-conan-runner   latest    383b905f352e   22 minutes ago   531MB
+    ubuntu            22.04     437ec753bef3   12 days ago      77.9MB
+
+If we run the ``conan create`` command again we will see how Conan reuses the previous container because we have set ``remove=False``.
+
+.. code-block:: bash
+
+    $ 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
+
+    ...
+
+    ┌───────────────────────────────┐
+    | Starting the docker container |
+    └───────────────────────────────┘
+
+    ...

reference.rst

@@ -17,3 +17,4 @@ Reference
    reference/environment
    reference/binary_model
    reference/conan_server
+   reference/runners

reference/runners.rst

@@ -0,0 +1,17 @@
+.. _reference_runners:
+
+Runners
+=======
+
+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.
+
+- Installing a version of Conan with runner dependencies ``pip install conan[runners]``. 
+- Install the tools to run each of the runners (``docker``).
+- Add the ``[runner]`` section defined in the documentation of each runner to the host profile.
+
+Runners:
+
+.. toctree::
+    :maxdepth: 1
+
+    runners/docker

reference/runners/docker.rst

@@ -0,0 +1,64 @@
+.. _reference_runners_docker:
+
+Docker runner
+=============
+
+How to use a docker runner
+--------------------------
+
+To run Conan inside a docker container you need to define a ``[runner]`` section in your host profile using the following fields:
+
+- ``type`` **(mandatory)**: define the runner we want to use, in this case ``docker``.
+- ``dockerfile`` **(optional, default None)**: absolute path to a Dockerfile in case you want to build a docker image.
+- ``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.
+- ``cache`` **(optional, default clean)**: how docker container uses (or not) the host's Conan cache.
+
+    - ``clean``: use an empty cache.
+    - ``copy``: copy the host cache inside the container using the :ref:`conan cache save/restore<reference_commands_cache>` command.
+    - ``shared``: mount the host's Conan cache as a shared volume.
+
+- ``remove`` **(optional, default false)**: ``true`` or ``false``. Remove the container after running the Conan command.
+- ``configfile``  **(optional, default None)**: Absolute path to a configuration file with extra parameters (see **extra configuration** section for more info).
+
+..  note::
+
+    The runner profile section doesn't affect the package id.
+
+Extra configuration
+-------------------
+
+If you need more control over the build and execution of the container, you can define more parameters inside a ``configfile`` yaml.
+
+..  code-block:: yaml
+
+    image: image_name # The image to build or run.
+    build:
+        dockerfile: /dockerfile/path # Dockerfile path.
+        build_context: /build/context/path # Path within the build context to the Dockerfile.
+        build_args: # A dictionary of build arguments
+            foo: bar
+        cacheFrom: # A list of images used for build cache resolution
+            - image_1
+    run:
+        name: container_name # The name for this container.
+        containerEnv: # Environment variables to set inside the container.
+            env_var_1: env_value
+        containerUser: user_name # Username or UID to run commands as inside the container.
+        privileged: False # Run as privileged
+        capAdd: # Add kernel capabilities.
+            - SYS_ADMIN
+            - MKNOD
+        securityOpt: # A list of string values to customize labels for MLS systems, such as SELinux.
+            - opt_1
+        mount: # A dictionary to configure volumes mounted inside the container.
+            /home/user1/: # The host path or a volume name
+                bind: /mnt/vol2 # The path to mount the volume inside the container
+                mode: rw # rw to mount the volume read/write, or ro to mount it read-only.
+
+How to run a `conan create` in a runner
+---------------------------------------
+
+In the following links you can find some examples about how to use a conan docker runner:
+
+- :ref:`Creating a Conan package using a Docker runner<examples_runners_docker_basic>`
+- :ref:`Using a docker runner configfile to parameterize the Dockerfile base image<examples_runners_docker_configfile_build_args>`