From 0076f448344bc14068597d09b057148e50ec8970 Mon Sep 17 00:00:00 2001
From: "Joe Richey joerichey@google.com" <joerichey@google.com>
Date: Tue, 18 Jul 2017 21:09:55 -0700
Subject: Update documentation about new build system

---
 CONTRIBUTING.md | 107 +++++++++++++++++++++++++++++++++++++++++---------------
 README.md       |  79 ++++++++++++++++++++---------------------
 2 files changed, 116 insertions(+), 70 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1f69c12..45c5487 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,33 +22,82 @@ use GitHub pull requests for this purpose. Consult
 [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
 information on using pull requests.
 
-## Before you submit a pull request
-
-If you are making changes to the `fscrypt` component, you will need to have
-[govendor](https://github.com/kardianos/govendor) installed, and you will want
-to use the following additional commands:
-*   `make update` - Updates the dependencies in the `vendor/` directory and
-    updates the `VENDOR_LICENSES` file.
-*   `make go` - Generates, builds, and tests all the Go code. Requires
-    [protoc (v3.0 or later)](https://github.com/google/protobuf/releases) and
-    [protoc-gen-go](https://github.com/golang/protobuf).
-*   `make format` - Formats all of the go code.
-*   `make lint` - Checks the code for style errors. Requires
-    [`golint`](https://github.com/golang/lint).
-*   `make all` - Runs the above commands and builds `fscrypt`.
-
-These commands should be run before submitting a pull request.
-
-Make sure that `$GOPATH/bin` is in you `$PATH`. All the above dependencies can
-be installed with:
-``` bash
-# Grab the latest version of protoc from github.com/google/protobuf/releases
-> curl -L <download_link_for_your_architecture> > protoc.zip
-> unzip protoc.zip -d protoc
-> sudo mv protoc/bin/protoc /usr/local/bin/
-> rm -rf protoc.zip protoc/
-# Grab the go packages in the standard manner
-> go get -u github.com/golang/protobuf/protoc-gen-go
-> go get -u github.com/kardianos/govendor
-> go get -u github.com/golang/lint/golint
+## Working on fscrypt
+
+On every pull request, [Travis CI](https://travis-ci.org/google/fscrypt) runs
+unit tests, integration tests, code formatters, and linters. You can also run
+these commands when writing your code.
+
+### Building and Testing
+
+As mentioned in `README.md`, running `make` will build the fscrypt executable.
+Running `make go` will build each package and run the tests, but just running
+`make go` with nothing else will skip the integration tests.
+
+To run the integration tests, you will need a filesystem that supports
+encryption. If you already have some empty filesystem at `/foo/bar`, just run:
+```bash
+make go MOUNT=/foo/bar
 ```
+
+Otherwise, you can use the `make test-setup` and `make test-teardown` commands
+to create a fake filesystem for testing. Note that the commands require `sudo`,
+and the `make test-setup` command requires `e2fsprogs` version 1.43 or later.
+For example:
+```bash
+make test-setup
+make go
+make test-teardown
+```
+
+### Formatting and Linting
+
+The `make format` command formats all the code in fscrypt with either `gofmt`
+(for Go code) or [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html)
+(for C code). `gofmt` comes with any Go distribution, and `clang-format` can be
+installed with your package manager.
+
+The `make lint` command runs a series of static analysis checks on your code.
+This requires the
+[megacheck](https://github.com/dominikh/go-tools/tree/master/cmd/megacheck) and
+[golint](https://github.com/golang/lint) tools.
+
+### Changing proto files
+
+If you make any changes to files ending in `.proto`, the corresponding `.pb.go`
+files have to be regenerated with `make gen`. This requires version 3.0.0 or
+later of `protoc` the
+[protobuf compiler](https://github.com/google/protobuf) and
+[protoc-gen-go](https://github.com/golang/protobuf).
+
+### Changing dependencies
+
+fscrypt vendors all of it's Go dependencies. If you add or remove a dependency
+on an external Go package, be sure to run `make update` to resync the `vendor/`
+directory. This requires [govendor](https://github.com/kardianos/govendor).
+
+Also, if adding in an external Go package, be sure that he license of the
+package is compatible with the
+[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). See the
+[FSF's article](https://www.gnu.org/licenses/license-list.html) for more
+information. This (unfortunately) means we cannot use external packages under
+the [GPL](https://choosealicense.com/licenses/gpl-3.0) or
+[LGPL](https://choosealicense.com/licenses/lgpl-3.0/). We also cannot use
+packages with missing or joke licenses (see [Unlicense](http://unlicense.org/), 
+[WTFPL](http://www.wtfpl.net/), or
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/)).
+
+### Putting it all together
+
+Run `make go-tools` to install all the Go tools mentioned above (make sure that
+`$GOPATH/bin` is in you `$PATH`). Install `protoc` and `clang-format` with your
+system's package manager. In the case of `protoc`, your system's version might
+be older than v3.0.0. In that case, just get the build
+[directly from GitHub](https://github.com/google/protobuf/releases/latest).
+
+After installing everything, running `make all` will run all the commands
+mentioned above. As with `make test`, you can run the integration tests by
+either using `make all MOUNT=/path/to/my/filesystem` or using the
+`make test-setup` and `make test-teardown` commands.
+
+`make all` should always be run before submitting a pull request.
diff --git a/README.md b/README.md
index d69cc07..59df8e4 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,7 @@
 
 [![GitHub version](https://badge.fury.io/gh/google%2Ffscrypt.svg)](https://github.com/google/fscrypt/releases)
 [![GoDoc](https://godoc.org/github.com/google/fscrypt?status.svg)](https://godoc.org/github.com/google/fscrypt)
+[![Build Status](https://travis-ci.org/google/fscrypt.svg?branch=master)](https://travis-ci.org/google/fscrypt)
 [![Go Report Card](https://goreportcard.com/badge/github.com/google/fscrypt)](https://goreportcard.com/report/github.com/google/fscrypt)
 
 fscrypt is a high-level tool for the management of
@@ -102,62 +103,59 @@ The following functionality is planned:
 See the example usage section below or run `fscrypt COMMAND --help` for more
 information about each of the commands.
 
-## Building
-
-fscrypt is written in Go, so to build the program you will need to
-[setup Go](https://golang.org/doc/install),
-[setup your `GOPATH`](https://golang.org/doc/code.html#GOPATH), and clone the
-repository into the correct location by running:
-```shell
-go get -d github.com/google/fscrypt
-```
-Alternatively, just copy or checkout the source into
-`$GOPATH/src/github.com/google/fscrypt`. If you only want to install the fscrypt
-binary to `$GOPATH/bin`, it is enough to run:
-```shell
-go get github.com/google/fscrypt/cmd/fscrypt
-```
+## Building and Installing
 
 fscrypt has the following build dependencies:
-*   `make`
+*   [Go](https://golang.org/doc/install)
 *   A C compiler (`gcc` or `clang`)
-*   Go
-*   [Argon2 Passphrase Hash](https://github.com/P-H-C/phc-winner-argon2), a C
-    library which can be installed (both the header `argon2.h` and library
-    `libargon2`) by running:
+*   `make` 
+*   The [Argon2 Passphrase Hash](https://github.com/P-H-C/phc-winner-argon2)
+    library, which can be
+    [directly installed on Artful Ubuntu](https://packages.ubuntu.com/artful/libargon2-0-dev),
+    or installed from source by running:
     ```bash
     >>>>> git clone https://github.com/P-H-C/phc-winner-argon2 argon2
     >>>>> cd argon2
     >>>>> make
     >>>>> sudo make install
     ```
-*   Headers for `libblkid` (specifically `blkid/blkid.h`) and `libpam`
-    (specifically `security/pam_appl.h`). These can be installed with your
+*   Headers for `libblkid` and `libpam`. These can be installed with the
     appropriate package manager.
     - `sudo apt-get install libblkid-dev libpam0g-dev`
     - `sudo yum install libblkid-devel pam-devel`
     - `pam` and `util-liux` packages for Arch
 
-Once this is setup, you can run `make fscrypt` to build the executable in the
-current directory. See the `Makefile` for instructions on building a static
-executable. The C libraries used by fscrypt will be dynamically linked by
-default.
+Once all the dependencies are installed, you can get the repository by running:
+```shell
+go get -d github.com/google/fscrypt
+```
+and then you can run `make` in `$GOPATH/github.com/google/fscrypt` to build the
+executable in that directory. Running `sudo make install` installs the binary to
+`/usr/local/bin`.
+
+See the `Makefile` for instructions on how to customize the build. This includes
+building a static binary (C libraries used by fscrypt will be dynamically linked
+by default).
+
+Alternatively, if you only want to install the fscrypt binary to `$GOPATH/bin`,
+it is enough to just run:
+```shell
+go get github.com/google/fscrypt/cmd/fscrypt
+```
 
-## Running and Installing
+### Runtime Dependencies
 
 fscrypt has the following runtime dependencies:
 *   Kernel support for filesystem encryption (this will depend on your kernel
     configuration and specific filesystem)
-*   `libargon2` (see the above installation instructions for Argon2), unless you
-    built a static executable.
-*   `libblkid` and `libpam` (which are almost certainly already on your system),
-    unless you built a static executable.
+*   `libargon2.so` (see the above installation instructions for Argon2)
+*   `libblkid.so` and `libpam.so`. These libraries are almost certainly already
+    on your system.
 
-Installing it just requires placing it in your path or running `make install`.
-Change `$GOBIN` to change the install location of fscrypt. By default,
-fscrypt is installed to `$GOPATH/bin`.
+The dynamic libraries are not needed if you built a static executable.
 
 ## Note about stability
+
 fscrypt follows [semantic versioning](http://semver.org). As such, all versions
 below `1.0.0` should be considered development versions. This means no
 guarantees are make about the stability of APIs or formats of config files. As
@@ -497,9 +495,8 @@ Protector 2c75f519b9c9959d no longer protecting policy 16382f282d7b29ee.
 
 ## Contributing
 
-We would love to accept your contributions to fscrypt. See the
-`CONTRIBUTING.md` file for more information about singing the CLA and submitting
-a pull request.
+We would love to accept your contributions to fscrypt. See the `CONTRIBUTING.md`
+file for more information about singing the CLA and submitting a pull request.
 
 ## Troubleshooting
 
@@ -534,10 +531,10 @@ To turn on the encryption feature flag for your filesystem, run
 ```
 tune2fs -O encrypt /dev/device
 ```
-This command may require root privileges. Once the flag is enabled, older
-kernels may not be able to mount the filesystem. Note that there was a bug in an
-older kernel version that allowed encryption policies to be set on ext4
-filesystems without enabling this encryption feature flag.
+This command requires root privileges and `e2fsprogs` v1.43 or later. Once the
+filesystem flag is enabled, older kernels may not be able to mount this
+filesystem. Note that there was a bug in older kernel versions that allowed
+encryption policies to be set on ext4 filesystems without this flag.
 
 ## Legal
 
-- 
cgit v1.2.3