docs: update BUILDING and README

jessvalarezo · jessvalarezo · commit b284da317599 · 2017-12-04T20:02:18.000-08:00
Signed-off-by: Jess Valarezo &lt;valarezo.jessica@gmail.com&gt;
diff --git a/BUILDING.md b/BUILDING.md
@@ -3,29 +3,49 @@
 This guide is useful if you intend to contribute on containerd. Thanks for your
 effort. Every contribution is very appreciated.
 
+This doc includes:
+* [Build requirements](#build-requirements)
+* [Build the development environment](#build-the-development-environment)
+* [Build containerd](#build-containerd)
+* [Via docker container](#via-docker-container)
+* [Testing](#testing-containerd)
+
+## Build requirements
+
+To build the `containerd` daemon, and the `ctr` simple test client, the following build system dependencies are required:
+
+* Go 1.9.x or above
+* Protoc 3.x compiler and headers (download at the [Google protobuf releases page](https://github.com/google/protobuf/releases))
+* 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.
+
 ## Build the development environment
 
-In first you need to setup your Go development environment. You can follow this
+First you need to setup your Go development environment. You can follow this
 guideline [How to write go code](https://golang.org/doc/code.html) and at the
 end you need to have `GOPATH` and `GOROOT` set in your environment.
 
-Current containerd requires Go 1.9.x or above.
-
 At this point you can use `go` to checkout `containerd` in your `GOPATH`:
 
 ```sh
 go get github.com/containerd/containerd
 ```
 
+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:
+
+```
+$ wget -c https://github.com/google/protobuf/releases/download/v3.5.0/protoc-3.5.0-linux-x86_64.zip
+$ sudo unzip protoc-3.5.0-linux-x86_64.zip -d /usr/local
+```
+
 `containerd` uses [Btrfs](https://en.wikipedia.org/wiki/Btrfs) it means that you
 need to satisfy this dependencies in your system:
 
 * CentOS/Fedora: `yum install btrfs-progs-devel`
 * Debian/Ubuntu: `apt-get install btrfs-tools`
 
-At this point you are ready to build `containerd` yourself.
+At this point you are ready to build `containerd` yourself!
 
-## In your local environment
+## Build containerd
 
 `containerd` uses `make` to create a repeatable build flow. It means that you
 can run:
@@ -34,35 +54,49 @@ can run:
 make
 ```
 
-This is going to build all the binaries provided by this project in the `./bin`
-directory.
+This is going to build all the project binaries in the `./bin/` directory.
 
-You can move them in your global path with:
+You can move them in your global path, `/usr/local/bin` with:
 
 ```sudo
 sudo make install
 ```
 
+When making any changes to the gRPC API, you can use the installed `protoc`
+compiler to regenerate the API generated code packages with:
+
+```sudo
+make generate
+```
+
+> *Note*: A build tag is currently available to disable building the btrfs snapshot driver.
+> Adding `BUILDTAGS=no_btrfs` to your environment before calling the **binaries**
+> Makefile target will disable the btrfs driver within the containerd Go build.
+
+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.
+
+Please refer to [RUNC.md](/RUNC.md) for the currently supported version of `runc` that is used by containerd.
+
 ### Static binaries
 
 You can build static binaries by providing a few variables to `make`:
 
 ```sudo
-make	EXTRA_FLAGS="-buildmode pie" \
+make EXTRA_FLAGS="-buildmode pie" \
 	EXTRA_LDFLAGS='-extldflags "-fno-PIC -static"' \
 	BUILDTAGS="static_build"
 ```
 
-Note that
- - static build is discouraged
- - static containerd binary does not support plugins loading
+> *Note*:
+> - static build is discouraged
+> - static containerd binary does not support loading plugins
 
-## Via Docker Container
+# Via Docker container
 
-### Build containerd
+## Build containerd
 
-You can build `containerd` via Docker container. You can build an image from
-this `Dockerfile`:
+You can build `containerd` via a Linux-based Docker container.
+You can build an image from this `Dockerfile`:
 
 ```
 FROM golang
@@ -71,34 +105,34 @@ RUN apt-get update && \
     apt-get install btrfs-tools
 ```
 
-Let's suppose that you built an image called `containerd/build` and you are into
-the containerd root directory you can run the following command:
+Let's suppose that you built an image called `containerd/build`. From the
+containerd source root directory you can run the following command:
 
 ```sh
-docker run -it --rm \
+docker run -it \
     -v ${PWD}:/go/src/github.com/containerd/containerd \
     -e GOPATH=/go \
-    -w /go/src/github.com/containerd/containerd containerd/build make
+    -w /go/src/github.com/containerd/containerd containerd/build sh
 ```
 
-At this point you can find your binaries in the `./bin` directory in your host.
-You can move the binaries in your `$PATH` with the command:
+This mounts `containerd` repository
+
+You are now ready to [build](#build-containerd):
 
 ```sh
-sudo make install
+ make && make install
 ```
 
-### Build runc and containerd
-
-To have complete core container runtime, you will need both `containerd` and `runc`. It is possible to build both of these via Docker container.
+## Build containerd and runc
+To have complete core container runtime, you will both `containerd` and `runc`. It is possible to build both of these via Docker container.
 
 You can use `go` to checkout `runc` in your `GOPATH`:
 
 ```sh
 go get github.com/opencontainers/runc
 ```
 
-We can build an image from this `Dockerfile`
+We can build an image from this `Dockerfile`:
 
 ```sh
 FROM golang
@@ -108,7 +142,7 @@ RUN apt-get update && \
 
 ```
 
-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 these dependencies: `libapparmor-dev` `libseccomp-dev`.
+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 these dependencies: `libapparmor-dev` `libseccomp-dev`. Please refer to [RUNC.md](/RUNC.md) for the currently supported version of `runc` that is used by containerd.
 
 Let's suppose you build an image called `containerd/build` from the above Dockerfile. You can run the following command:
 
@@ -117,13 +151,13 @@ docker run -it --privileged \
     -v /var/lib/containerd \
     -v ${GOPATH}/src/github.com/opencontainers/runc:/go/src/github.com/opencontainers/runc \
     -v ${GOPATH}/src/github.com/containerd/containerd:/go/src/github.com/containerd/containerd \
-    -e GOPATH=/go
+    -e GOPATH=/go \
     -w /go/src/github.com/containerd/containerd containerd/build sh
 ```
 
 This mounts both `runc` and `containerd` repositories in our Docker container.
 
-From within our Docker container let's build `containerd`
+From within our Docker container let's build `containerd`:
 
 ```sh
 cd /go/src/github.com/containerd/containerd
@@ -133,14 +167,14 @@ make && make install
 These binaries can be found in the `./bin` directory in your host.
 `make install` will move the binaries in your `$PATH`.
 
-Next, let's build `runc`
+Next, let's build `runc`:
 
 ```sh
 cd /go/src/github.com/opencontainers/runc
 make BUILDTAGS='seccomp apparmor' && make install
 ```
 
-When working with `ctr`, the containerd CLI we just built, don't forget to start `containerd`!
+When working with `ctr`, the simple test client we just built, don't forget to start the daemon!
 
 ```sh
 containerd --config config.toml
diff --git a/README.md b/README.md
@@ -27,7 +27,7 @@ If you are interested in trying out containerd see our example at [Getting Start
 
 Runtime requirements for containerd are very minimal. Most interactions with
 the Linux and Windows container feature sets are handled via [runc](https://github.com/opencontainers/runc) and/or
-OS-specific libraries (e.g. [hcsshim](https://github.com/Microsoft/hcsshim) for Microsoft). The current required version of runc is always listed in [RUNC.md](/RUNC.md).
+OS-specific libraries (e.g. [hcsshim](https://github.com/Microsoft/hcsshim) for Microsoft). The current required version of `runc` is always listed in [RUNC.md](/RUNC.md).
 
 There are specific features
 used by containerd core code and snapshotters that will require a minimum kernel
@@ -43,7 +43,7 @@ distribution.
 To use Linux checkpoint and restore features, you will need `criu` installed on
 your system. See more details in [Checkpoint and Restore](#checkpoint-and-restore).
 
-Build requirements for developers are listed in the [Developer Quick-Start](#developer-quick-start) section.
+Build requirements for developers are listed in [BUILDING](BUILDING.md).
 
 ## Features
 
@@ -183,31 +183,6 @@ defer task.Delete(context)
 err := task.Start(context)
 ```
 
-## Developer Quick Start
-
-To build the daemon and `ctr` simple test client, the following build system dependencies are required:
-
-* Go 1.9.x or above
-* Protoc 3.x compiler and headers (download at the [Google protobuf releases page](https://github.com/google/protobuf/releases))
-* Btrfs headers and libraries for your distribution. Note that building the btrfs driver can be disabled via build tag removing this dependency.
-
-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:
-
-```
-$ wget -c https://github.com/google/protobuf/releases/download/v3.5.0/protoc-3.5.0-linux-x86_64.zip
-$ sudo unzip protoc-3.5.0-linux-x86_64.zip -d /usr/local
-```
-
-With the required dependencies installed, the `Makefile` target named **binaries** will compile the `ctr` and `containerd` binaries and place them in the `bin/` directory. Using `sudo make install` will place the binaries in `/usr/local/bin`. When making any changes to the gRPC API, `make generate` will use the installed `protoc` compiler to regenerate the API generated code packages.
-
-> *Note*: A build tag is currently available to disable building the btrfs snapshot driver.
-> Adding `BUILDTAGS=no_btrfs` to your environment before calling the **binaries**
-> Makefile target will disable the btrfs driver within the containerd Go build.
-
-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.
-
-Please refer to [RUNC.md](/RUNC.md) for the currently supported version of `runc` that is used by containerd.
-
 ### Releases and API Stability
 
 Please see [RELEASES.md](RELEASES.md) for details on versioning and stability
