Merge pull request #19 from tonistiigi/add-readme

add readme

readme.md

@@ -0,0 +1,77 @@
+### Important: This repository is in an early development phase and not suitable for practical workloads. It does not compare with `docker build` features yet.
+
+[![asciicinema example](https://asciinema.org/a/gPEIEo1NzmDTUu2bEPsUboqmU.png)](https://asciinema.org/a/gPEIEo1NzmDTUu2bEPsUboqmU)
+
+
+## BuildKit
+
+BuildKit is a toolkit for converting source code to build artifacts in an efficient, expressive and repeatable manner.
+
+Key features:
+- Automatic garbage collection
+- Extendable frontend formats
+- Concurrent dependency resolution
+- Efficient instruction caching
+- Build cache import/export
+- Nested build job invocations
+- Distributable workers
+- Multiple output formats
+- Pluggable architecture
+
+
+Read the proposal from https://github.com/moby/moby/issues/32925
+
+#### Quick start
+
+BuildKit daemon can be built in two different versions: one that uses [containerd](https://github.com/containerd/containerd) for execution and distribution, and a standalone version that doesn't have other dependencies apart from [runc](https://github.com/opencontainers/runc). We are open for adding more backends. `buildd` is a CLI utility for running the gRPC API. 
+
+```bash
+# buildd daemon (choose one)
+go build -o buildd-containerd -tags containerd ./cmd/buildd
+go build -o buildd-standalone -tags standalone ./cmd/buildd
+
+# buildctl utility
+go build -o buildctl ./cmd/buildctl
+```
+
+You can also use `make binaries` that prepares all binaries into the `bin/` directory.
+
+The first thing to test could be to try building BuildKit with BuildKit. BuildKit provides a low-level solver format that could be used by multiple build definitions. Preparation work for making the Dockerfile parser reusable as a frontend is tracked in https://github.com/moby/moby/pull/33492. As no frontends have been integrated yet we currently have to use a script to generate this low-level definition.
+
+`examples/buildkit/buildkit.go` is a script that defines how to build different configurations of BuildKit and its dependencies using the `client` package. Running this script generates a protobuf definition of a build graph. Note that the script itself does not execute any steps of the build.
+
+You can use `buildctl debug dump` to see what data is this definition.
+
+```bash
+go run examples/buildkit/buildkit.go | buildctl debug dump | jq .
+```
+
+To start building use `buildctl build` command. The script accepts `--target` flag to choose between `containerd` and `standalone` configurations. In standalone mode BuildKit binaries are built together with `runc`. In containerd mode, the `containerd` binary is built as well from the upstream repo.
+
+```bash
+go run examples/buildkit/buildkit.go | buildctl build
+```
+
+`buildctl build` will show interactive progress bar by default while the build job is running. It will also show you the path to the trace file that contains all information about the timing of the individual steps and logs.
+
+
+#### Contributing
+
+Running tests:
+
+```bash
+make test
+```
+
+Updating vendored dependencies:
+
+```bash
+# update vendor.conf
+make vendor
+```
+
+Validating your updates before submission:
+
+```bash
+make validate-all
+```