github.com/demonoid81/containerd@v1.3.4/BUILDING.md (about)

     1  # Build containerd from source
     2  
     3  This guide is useful if you intend to contribute on containerd. Thanks for your
     4  effort. Every contribution is very appreciated.
     5  
     6  This doc includes:
     7  * [Build requirements](#build-requirements)
     8  * [Build the development environment](#build-the-development-environment)
     9  * [Build containerd](#build-containerd)
    10  * [Via docker container](#via-docker-container)
    11  * [Testing](#testing-containerd)
    12  
    13  ## Build requirements
    14  
    15  To build the `containerd` daemon, and the `ctr` simple test client, the following build system dependencies are required:
    16  
    17  * Go 1.10.x or above
    18  * Protoc 3.x compiler and headers (download at the [Google protobuf releases page](https://github.com/google/protobuf/releases))
    19  * Btrfs headers and libraries for your distribution. Note that building the btrfs driver can be disabled via the build tag `no_btrfs`, removing this dependency.
    20  * `libseccomp` is required if you're building with seccomp support
    21  
    22  ## Build the development environment
    23  
    24  First you need to setup your Go development environment. You can follow this
    25  guideline [How to write go code](https://golang.org/doc/code.html) and at the
    26  end you need to have `GOPATH` and `GOROOT` set in your environment.
    27  
    28  At this point you can use `go` to checkout `containerd` in your `GOPATH`:
    29  
    30  ```sh
    31  go get github.com/containerd/containerd
    32  ```
    33  
    34  For proper results, install the `protoc` release into `/usr/local` on your build system. For example, the following commands will download and install the 3.5.0 release for a 64-bit Linux host:
    35  
    36  ```
    37  $ wget -c https://github.com/google/protobuf/releases/download/v3.5.0/protoc-3.5.0-linux-x86_64.zip
    38  $ sudo unzip protoc-3.5.0-linux-x86_64.zip -d /usr/local
    39  ```
    40  
    41  `containerd` uses [Btrfs](https://en.wikipedia.org/wiki/Btrfs) it means that you
    42  need to satisfy this dependencies in your system:
    43  
    44  * CentOS/Fedora: `yum install btrfs-progs-devel`
    45  * Debian/Ubuntu: `apt-get install btrfs-tools`
    46  
    47  If you're building with seccomp, you'll need to install it with the following:
    48  
    49  * CentOS/Fedora: `yum install libseccomp-devel`
    50  * Debian/Ubuntu: `apt install libseccomp-dev`
    51  
    52  At this point you are ready to build `containerd` yourself!
    53  
    54  ## Build runc
    55  
    56  `runc` is the default container runtime used by `containerd` and is required to
    57  run containerd. While it is okay to download a runc binary and install that on
    58  the system, sometimes it is necessary to build runc directly when working with
    59  container runtime development. You can skip this step if you already have the
    60  correct version of `runc` installed.
    61  
    62  For the quick and dirty installation, you can use the following:
    63  
    64      go get github.com/opencontainers/runc
    65  
    66  This is not recommended, as the generated binary will not have version
    67  information. Instead, cd into the source directory and use make to build and
    68  install the binary:
    69  
    70  	cd $GOPATH/src/github.com/opencontainers/runc
    71  	make
    72  	make install
    73  
    74  Make sure to follow the guidelines for versioning in [RUNC.md](RUNC.md) for the
    75  best results. Some pointers on proper build tag setupVersion mismatches can
    76  result in undefined behavior.
    77  
    78  ## Build containerd
    79  
    80  `containerd` uses `make` to create a repeatable build flow. It means that you
    81  can run:
    82  
    83  ```
    84  cd $GOPATH/src/github.com/containerd/containerd
    85  make
    86  ```
    87  
    88  This is going to build all the project binaries in the `./bin/` directory.
    89  
    90  You can move them in your global path, `/usr/local/bin` with:
    91  
    92  ```sudo
    93  sudo make install
    94  ```
    95  
    96  When making any changes to the gRPC API, you can use the installed `protoc`
    97  compiler to regenerate the API generated code packages with:
    98  
    99  ```sudo
   100  make generate
   101  ```
   102  
   103  > *Note*: Several build tags are currently available:
   104  > * `no_btrfs`: A build tag disables building the btrfs snapshot driver.
   105  > * `no_cri`: A build tag disables building Kubernetes [CRI](http://blog.kubernetes.io/2016/12/container-runtime-interface-cri-in-kubernetes.html) support into containerd.
   106  > See [here](https://github.com/containerd/cri-containerd#build-tags) for build tags of CRI plugin.
   107  > * `no_devmapper`: A build tag disables building the device mapper snapshot driver.
   108  >
   109  > For example, adding `BUILDTAGS=no_btrfs` to your environment before calling the **binaries**
   110  > Makefile target will disable the btrfs driver within the containerd Go build.
   111  
   112  Vendoring of external imports uses the [`vndr` tool](https://github.com/LK4D4/vndr) which uses a simple config file, `vendor.conf`, to provide the URL and version or hash details for each vendored import. After modifying `vendor.conf` run the `vndr` tool to update the `vendor/` directory contents. Combining the `vendor.conf` update with the changeset in `vendor/` after running `vndr` should become a single commit for a PR which relies on vendored updates.
   113  
   114  Please refer to [RUNC.md](/RUNC.md) for the currently supported version of `runc` that is used by containerd.
   115  
   116  ### Static binaries
   117  
   118  You can build static binaries by providing a few variables to `make`:
   119  
   120  ```sudo
   121  make EXTRA_FLAGS="-buildmode pie" \
   122  	EXTRA_LDFLAGS='-extldflags "-fno-PIC -static"' \
   123  	BUILDTAGS="netgo osusergo static_build"
   124  ```
   125  
   126  > *Note*:
   127  > - static build is discouraged
   128  > - static containerd binary does not support loading plugins
   129  
   130  # Via Docker container
   131  
   132  ## Build containerd
   133  
   134  You can build `containerd` via a Linux-based Docker container.
   135  You can build an image from this `Dockerfile`:
   136  
   137  ```
   138  FROM golang
   139  
   140  RUN apt-get update && \
   141      apt-get install -y btrfs-tools libseccomp-dev
   142  ```
   143  
   144  Let's suppose that you built an image called `containerd/build`. From the
   145  containerd source root directory you can run the following command:
   146  
   147  ```sh
   148  docker run -it \
   149      -v ${PWD}:/go/src/github.com/containerd/containerd \
   150      -e GOPATH=/go \
   151      -w /go/src/github.com/containerd/containerd containerd/build sh
   152  ```
   153  
   154  This mounts `containerd` repository
   155  
   156  You are now ready to [build](#build-containerd):
   157  
   158  ```sh
   159   make && make install
   160  ```
   161  
   162  ## Build containerd and runc
   163  To have complete core container runtime, you will both `containerd` and `runc`. It is possible to build both of these via Docker container.
   164  
   165  You can use `go` to checkout `runc` in your `GOPATH`:
   166  
   167  ```sh
   168  go get github.com/opencontainers/runc
   169  ```
   170  
   171  We can build an image from this `Dockerfile`:
   172  
   173  ```sh
   174  FROM golang
   175  
   176  RUN apt-get update && \
   177      apt-get install -y btrfs-tools libseccomp-dev
   178  
   179  ```
   180  
   181  In our Docker container we will use a specific `runc` build which includes [seccomp](https://en.wikipedia.org/wiki/seccomp) and [apparmor](https://en.wikipedia.org/wiki/AppArmor) support. Hence why our Dockerfile includes `libseccomp-dev` as a dependency (apparmor support doesn't require external libraries). Please refer to [RUNC.md](/RUNC.md) for the currently supported version of `runc` that is used by containerd.
   182  
   183  Let's suppose you build an image called `containerd/build` from the above Dockerfile. You can run the following command:
   184  
   185  ```sh
   186  docker run -it --privileged \
   187      -v /var/lib/containerd \
   188      -v ${GOPATH}/src/github.com/opencontainers/runc:/go/src/github.com/opencontainers/runc \
   189      -v ${GOPATH}/src/github.com/containerd/containerd:/go/src/github.com/containerd/containerd \
   190      -e GOPATH=/go \
   191      -w /go/src/github.com/containerd/containerd containerd/build sh
   192  ```
   193  
   194  This mounts both `runc` and `containerd` repositories in our Docker container.
   195  
   196  From within our Docker container let's build `containerd`:
   197  
   198  ```sh
   199  cd /go/src/github.com/containerd/containerd
   200  make && make install
   201  ```
   202  
   203  These binaries can be found in the `./bin` directory in your host.
   204  `make install` will move the binaries in your `$PATH`.
   205  
   206  Next, let's build `runc`:
   207  
   208  ```sh
   209  cd /go/src/github.com/opencontainers/runc
   210  make BUILDTAGS='seccomp apparmor' && make install
   211  ```
   212  
   213  When working with `ctr`, the simple test client we just built, don't forget to start the daemon!
   214  
   215  ```sh
   216  containerd --config config.toml
   217  ```
   218  
   219  # Testing containerd
   220  
   221  During the automated CI the unit tests and integration tests are run as part of the PR validation. As a developer you can run these tests locally by using any of the following `Makefile` targets:
   222   - `make test`: run all non-integration tests that do not require `root` privileges
   223   - `make root-test`: run all non-integration tests which require `root`
   224   - `make integration`: run all tests, including integration tests and those which require `root`. `TESTFLAGS_PARALLEL` can be used to control parallelism. For example, `TESTFLAGS_PARALLEL=1 make integration` will lead a non-parallel execution. The default value of `TESTFLAGS_PARALLEL` is **8**.
   225  
   226  To execute a specific test or set of tests you can use the `go test` capabilities
   227  without using the `Makefile` targets. The following examples show how to specify a test
   228  name and also how to use the flag directly against `go test` to run root-requiring tests.
   229  
   230  ```sh
   231  # run the test <TEST_NAME>:
   232  go test	-v -run "<TEST_NAME>" .
   233  # enable the root-requiring tests:
   234  go test -v -run . -test.root
   235  ```
   236  
   237  Example output from directly running `go test` to execute the `TestContainerList` test:
   238  ```sh
   239  sudo go test -v -run "TestContainerList" . -test.root
   240  INFO[0000] running tests against containerd revision=f2ae8a020a985a8d9862c9eb5ab66902c2888361 version=v1.0.0-beta.2-49-gf2ae8a0
   241  === RUN   TestContainerList
   242  --- PASS: TestContainerList (0.00s)
   243  PASS
   244  ok  	github.com/containerd/containerd	4.778s
   245  ```
   246  
   247  ## Additional tools
   248  
   249  ### containerd-stress
   250  In addition to `go test`-based testing executed via the `Makefile` targets, the `containerd-stress` tool is available and built with the `all` or `binaries` targets and installed during `make install`.
   251  
   252  With this tool you can stress a running containerd daemon for a specified period of time, selecting a concurrency level to generate stress against the daemon. The following command is an example of having five workers running for two hours against a default containerd gRPC socket address:
   253  
   254  ```sh
   255  containerd-stress -c 5 -t 120
   256  ```
   257  
   258  For more information on this tool's options please run `containerd-stress --help`.
   259  
   260  ### bucketbench
   261  [Bucketbench](https://github.com/estesp/bucketbench) is an external tool which can be used to drive load against a container runtime, specifying a particular set of lifecycle operations to run with a specified amount of concurrency. Bucketbench is more focused on generating performance details than simply inducing load against containerd.
   262  
   263  Bucketbench differs from the `containerd-stress` tool in a few ways:
   264   - Bucketbench has support for testing the Docker engine, the `runc` binary, and containerd 0.2.x (via `ctr`) and 1.0 (via the client library) branches.
   265   - Bucketbench is driven via configuration file that allows specifying a list of lifecycle operations to execute. This can be used to generate detailed statistics per-command (e.g. start, stop, pause, delete).
   266   - Bucketbench generates detailed reports and timing data at the end of the configured test run.
   267  
   268  More details on how to install and run `bucketbench` are available at the [GitHub project page](https://github.com/estesp/bucketbench).