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