docs/Docker.rst

   1 =========================================
   2 A guide to Dockerfiles for building LLVM
   3 =========================================
   4
   5 Introduction
   6 ============
   7 You can find a number of sources to build docker images with LLVM components in
   8 ``llvm/utils/docker``. They can be used by anyone who wants to build the docker
   9 images for their own use, or as a starting point for someone who wants to write
  10 their own Dockerfiles.
  11
  12 We currently provide Dockerfiles with ``debian8`` and ``nvidia-cuda`` base images.
  13 We also provide an ``example`` image, which contains placeholders that one would need
  14 to fill out in order to produce Dockerfiles for a new docker image.
  15
  16 Why?
  17 ----
  18 Docker images provide a way to produce binary distributions of
  19 software inside a controlled environment. Having Dockerfiles to builds docker images
  20 inside LLVM repo makes them much more discoverable than putting them into any other
  21 place.
  22
  23 Docker basics
  24 -------------
  25 If you've never heard about Docker before, you might find this section helpful
  26 to get a very basic explanation of it.
  27 `Docker <https://www.docker.com/>`_ is a popular solution for running programs in
  28 an isolated and reproducible environment, especially to maintain releases for
  29 software deployed to large distributed fleets.
  30 It uses linux kernel namespaces and cgroups to provide a lightweight isolation
  31 inside currently running linux kernel.
  32 A single active instance of dockerized environment is called a *docker
  33 container*.
  34 A snapshot of a docker container filesystem is called a *docker image*.
  35 One can start a container from a prebuilt docker image.
  36
  37 Docker images are built from a so-called *Dockerfile*, a source file written in
  38 a specialized language that defines instructions to be used when build
  39 the docker image (see `official
  40 documentation <https://docs.docker.com/engine/reference/builder/>`_ for more
  41 details). A minimal Dockerfile typically contains a base image and a number
  42 of RUN commands that have to be executed to build the image. When building a new
  43 image, docker will first download your base image, mount its filesystem as
  44 read-only and then add a writable overlay on top of it to keep track of all
  45 filesystem modifications, performed while building your image. When the build
  46 process is finished, a diff between your image's final filesystem state and the
  47 base image's filesystem is stored in the resulting image.
  48
  49 Overview
  50 ========
  51 The ``llvm/utils/docker`` folder contains Dockerfiles and simple bash scripts to
  52 serve as a basis for anyone who wants to create their own Docker image with
  53 LLVM components, compiled from sources. The sources are checked out from the
  54 upstream svn repository when building the image.
  55
  56 Inside each subfolder we host Dockerfiles for two images:
  57
  58 - ``build/`` image is used to compile LLVM, it installs a system compiler and all
  59   build dependencies of LLVM. After the build process is finished, the build
  60   image will have an archive with compiled components at ``/tmp/clang.tar.gz``.
  61 - ``release/`` image usually only contains LLVM components, compiled by the
  62   ``build/`` image, and also libstdc++ and binutils to make image minimally
  63   useful for C++ development. The assumption is that you usually want clang to
  64   be one of the provided components.
  65
  66 To build both of those images, use ``build_docker_image.sh`` script.
  67 It will checkout LLVM sources and build clang in the ``build`` container, copy results
  68 of the build to the local filesystem and then build the ``release`` container using
  69 those. The ``build_docker_image.sh`` accepts a list of LLVM repositories to
  70 checkout, and arguments for CMake invocation.
  71
  72 If you want to write your own docker image, start with an ``example/`` subfolder.
  73 It provides incomplete Dockerfiles with (very few) FIXMEs explaining the steps
  74 you need to take in order to make your Dockerfiles functional.
  75
  76 Usage
  77 =====
  78 The ``llvm/utils/build_docker_image.sh`` script provides a rather high degree of
  79 control on how to run the build. It allows you to specify the projects to
  80 checkout from svn and provide a list of CMake arguments to use during when
  81 building LLVM inside docker container.
  82
  83 Here's a very simple example of getting a docker image with clang binary,
  84 compiled by the system compiler in the debian8 image:
  85
  86 .. code-block:: bash
  87
  88     ./llvm/utils/docker/build_docker_image.sh \
  89         --source debian8 \
  90         --docker-repository clang-debian8 --docker-tag "staging" \
  91         -p clang -i install-clang -i install-clang-headers \
  92         -- \
  93         -DCMAKE_BUILD_TYPE=Release
  94
  95 Note that a build like that doesn't use a 2-stage build process that
  96 you probably want for clang. Running a 2-stage build is a little more intricate,
  97 this command will do that:
  98
  99 .. code-block:: bash
 100
 101     # Run a 2-stage build.
 102     #   LLVM_TARGETS_TO_BUILD=Native is to reduce stage1 compile time.
 103     #   Options, starting with BOOTSTRAP_* are passed to stage2 cmake invocation.
 104     ./build_docker_image.sh \
 105         --source debian8 \
 106         --docker-repository clang-debian8 --docker-tag "staging" \
 107         -p clang -i stage2-install-clang -i stage2-install-clang-headers \
 108         -- \
 109         -DLLVM_TARGETS_TO_BUILD=Native -DCMAKE_BUILD_TYPE=Release \
 110         -DBOOTSTRAP_CMAKE_BUILD_TYPE=Release \
 111         -DCLANG_ENABLE_BOOTSTRAP=ON -DCLANG_BOOTSTRAP_TARGETS="install-clang;install-clang-headers"
 112
 113 This will produce two images, a release image ``clang-debian8:staging`` and a
 114 build image ``clang-debian8-build:staging`` from the latest upstream revision.
 115 After the image is built you can run bash inside a container based on your
 116 image like this:
 117
 118 .. code-block:: bash
 119
 120     docker run -ti clang-debian8:staging bash
 121
 122 Now you can run bash commands as you normally would:
 123
 124 .. code-block:: bash
 125
 126     root@80f351b51825:/# clang -v
 127     clang version 5.0.0 (trunk 305064)
 128     Target: x86_64-unknown-linux-gnu
 129     Thread model: posix
 130     InstalledDir: /bin
 131     Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.8
 132     Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.8.4
 133     Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9
 134     Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9.2
 135     Selected GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9
 136     Candidate multilib: .;@m64
 137     Selected multilib: .;@m64
 138
 139
 140 Which image should I choose?
 141 ============================
 142 We currently provide two images: debian8-based and nvidia-cuda-based. They
 143 differ in the base image that they use, i.e. they have a different set of
 144 preinstalled binaries. Debian8 is very minimal, nvidia-cuda is larger, but has
 145 preinstalled CUDA libraries and allows to access a GPU, installed on your
 146 machine.
 147
 148 If you need a minimal linux distribution with only clang and libstdc++ included,
 149 you should try debian8-based image.
 150
 151 If you want to use CUDA libraries and have access to a GPU on your machine,
 152 you should choose nvidia-cuda-based image and use `nvidia-docker
 153 <https://github.com/NVIDIA/nvidia-docker>`_ to run your docker containers. Note
 154 that you don't need nvidia-docker to build the images, but you need it in order
 155 to have an access to GPU from a docker container that is running the built
 156 image.
 157
 158 If you have a different use-case, you could create your own image based on
 159 ``example/`` folder.
 160
 161 Any docker image can be built and run using only the docker binary, i.e. you can
 162 run debian8 build on Fedora or any other Linux distribution. You don't need to
 163 install CMake, compilers or any other clang dependencies. It is all handled
 164 during the build process inside Docker's isolated environment.
 165
 166 Stable build
 167 ============
 168 If you want a somewhat recent and somewhat stable build, use the
 169 ``branches/google/stable`` branch, i.e. the following command will produce a
 170 debian8-based image using the latest ``google/stable`` sources for you:
 171
 172 .. code-block:: bash
 173
 174     ./llvm/utils/docker/build_docker_image.sh \
 175         -s debian8 --d clang-debian8 -t "staging" \
 176         --branch branches/google/stable \
 177         -p clang -i install-clang -i install-clang-headers \
 178         -- \
 179         -DCMAKE_BUILD_TYPE=Release
 180
 181
 182 Minimizing docker image size
 183 ============================
 184 Due to Docker restrictions we use two images (i.e., build and release folders)
 185 for the release image to be as small as possible. It's much easier to achieve
 186 that using two images, because Docker would store a filesystem layer for each
 187 command in the  Dockerfile, i.e. if you install some packages in one command,
 188 then remove  those in a separate command, the size of the resulting image will
 189 still be proportinal to the size of an image with installed packages.
 190 Therefore, we strive to provide a very simple release image which only copies
 191 compiled clang and does not do anything else.
 192
 193 Docker 1.13 added a ``--squash`` flag that allows to flatten the layers of the
 194 image, i.e. remove the parts that were actually deleted. That is an easier way
 195 to produce the smallest images possible by using just a single image. We do not
 196 use it because as of today the flag is in experimental stage and not everyone
 197 may have the latest docker version available. When the flag is out of
 198 experimental stage, we should investigate replacing two images approach with
 199 just a single image, built using ``--squash`` flag.