fscrypt: Adding additional documentation

This commit moves most of the documentation about contributing to
fscrypt into CONTRIBUTING.md and updates the legal disclaimer.

It also updates the README.md to include all of fscrypt's planned
functionality and dependencies. Finally, the makefile is updated to
include more documentation, versioning support, and a different location
for the output file.

Change-Id: Ib7be98d41bc06dd12b02e42addf06e12a940235a

4 files changed, 122 insertions, 48 deletions

diff --git a/.gitignore b/.gitignore
index 9b55488..d60aa9a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,2 @@
-build/
+/fscrypt
 fscrypt.sublime-*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..1f69c12
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,54 @@
+# How to Contribute to fscrypt
+
+We'd love to accept your patches and contributions to this project. There are
+just a few small guidelines we ask you to follow.
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution,
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+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
+```
diff --git a/Makefile b/Makefile
index ac41537..22da24a 100644
--- a/Makefile
+++ b/Makefile
@@ -16,18 +16,36 @@
 # the License.
 
 NAME = fscrypt
-BUILD_DIR = build
-CFLAGS += -O2 -Wall
+# VERSION is formatted as <major>.<minor>.<bugfix>
+# Bugfix releases resolve issues in existing features.
+# Minor releases introduce new features.
+# Major releases may introduce breaking changes to the API.
+VERSION = 0.1.0
+# Holds a formatted string of the build time
+BUILD_TIME = $(shell date)
 
+CFLAGS += -O2 -Wall
 CMD_DIR = $(NAME)/cmd/$(NAME)
 
-# So we don't have to put our flags in each go file. This also lets the caller
-# of the makefile change the build flags in the normal manner:
+# The code below lets the caller of the makefile change the build flags for
+# fscrypt in a familiar manner. For example, to force the program to statically
+# link its C components, run "make fscrypt" with:
 #	make fscrypt "LDFLAGS += -static"
+#
+# Similarly, to modify the flags passed to the C components, just modify CFLAGS
+# or LDFLAGS as you would with a C program. To modify the Go flags, either
+# modify GO_FLAGS or GO_LINK_FLAGS (as appropriate).
+
+# Set the C flags so we don't need to set C flags in each CGO file.
 export CGO_CFLAGS = $(CFLAGS)
-ifdef LDFLAGS
-	GOFLAGS += --ldflags '-extldflags "$(LDFLAGS)"'
-endif
+
+# Pass the version to the command line program
+VERSION_FLAG = -X "main.version=$(VERSION)"
+# Pass the current date and time to the command line program
+DATE_FLAG = -X "main.buildTime=$(BUILD_TIME)"
+# Pass the C linking flags into Go
+GO_LINK_FLAGS += -s -w $(VERSION_FLAG) $(DATE_FLAG) -extldflags "$(LDFLAGS)"
+GOFLAGS += --ldflags '$(GO_LINK_FLAGS)'
 
 .PHONY: default all $(NAME) go update lint format install clean
 
@@ -35,12 +53,11 @@ default: $(NAME)
 all: update go format lint $(NAME)
 
 $(NAME):
-	@mkdir -p $(BUILD_DIR)
-	go build $(GOFLAGS) -o $(BUILD_DIR)/$(NAME) $(CMD_DIR)
+	go build $(GOFLAGS) -o $(NAME) $(CMD_DIR)
 
 # Makes sure go files build and tests pass
 go:
-	govendor generate $(GOFLAGS) +local
+	govendor generate +local
 	govendor build $(GOFLAGS) +local
 	govendor test $(GOFLAGS) +local
 
@@ -55,9 +72,10 @@ lint:
 
 format:
 	@govendor fmt +local
+	@find . -name "*.h" -o -name "*.c" -not -path "./vendor/*" | xargs clang-format -i -style=Google
 
 install:
 	govendor install $(GOFLAGS) +local
 
 clean:
-	rm -rf $(BUILD_DIR)
+	rm -rf $(NAME)
diff --git a/README.md b/README.md
index 79cbca8..be0e3e3 100644
--- a/README.md
+++ b/README.md
@@ -54,9 +54,23 @@ more managed environment and handling more functionality in the
 background. `fscrypt` has a [design document](https://goo.gl/55cCrI) that
 discusses many of the higher level design choices that were made.
 
-<!-- TODO add in features when command-line interface is complete -->
 Specifically, `fscrypt` contains the following functionality:
-*   Telling the time (but this is a stub program)
+*   `fscrypt info` - Prints detailed application info
+*   `fscrypt setup global` - Initializes the `fscrypt.conf` file
+*   `fscrypt setup filesystem` - Gets a filesystem ready for use with fscrypt
+*   `fscrypt setup directory` - Sets up encryption for a directory
+*   `fscrypt unlock` - Unlocks an encrypted directory for use
+*   `fscrypt encrypt` - Shortcut for `fscrypt setup directory`+`fscrypt unlock`
+*   `fscrypt change` - Changes how a directory is protected
+*   `fscrypt status` - Gets the status of some component of fscrypt
+*   `fscrypt backup` - Manages backups of the fscrypt metadata
+*   `fscrypt recovery` - Manages recovery keys for fscrypt protectors
+*   `fscrypt cleanup` - Scans filesystem for unused policies
+*   `fscrypt purge` - Removes keys for a filesystem before unmounting.
+*   `fscrypt [protector|policy]` - Manages metadata directly
+
+See the example usage section below or run `fscrypt <command> --help` for more
+information about each of the commands.
 
 ## Building
 
@@ -82,9 +96,12 @@ You will also want to add `$GOPATH/bin` to your `$PATH`.
     > make
     > sudo make install
     ```
+*   Headers for `libblkid` (specifically `blkid/blkid.h`). This can be installed
+    with your appropriate package manager (`libblkid-dev` for APT,
+    `libblkid-devel` for RPM, should already be part of `util-linux` for Arch).
 
 Once this is setup, you can run `make fscrypt` to build the executable in
-`build/fscrypt`. Pass `"LDFLAGS += -static"` to `make` to get a static
+the root directory. Pass `"LDFLAGS += -static"` to `make` to get a static
 executable. If a Go project contains C code, the go compiler produces a
 dynamically linked binary by default.
 
@@ -95,6 +112,9 @@ dynamically linked binary by default.
     configuration and specific filesystem)
 *   `libargon2` (see the above installation instructions for Argon2), unless you
     built a static executable.
+*   `libblkid` and `libuuid` (these are dependancies for `util-linux` and
+    `e2fsprogs` so your system almost certainly has it), unless you built a
+    static executable.
 
 Installing it just requires placing it in your path or running `make install`.
 Change `$GOBIN` to change the install location of `fscrypt`. By default,
@@ -102,48 +122,30 @@ Change `$GOBIN` to change the install location of `fscrypt`. By default,
 
 ## Example Usage
 
-TODO
+```bash
+# Setup your global configuration and filesystem
+> sudo fscrypt setup global
+Created global config file at "/etc/fscrypt.conf".
+> fscrypt setup filesystem /mnt/disk/to/encrypt
+Setup "/mnt/disk/to/encrypt (/dev/sda1) for use with ext4 filesystem encryption.
+```
 
 ## Contributing
 
-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.
-*   `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 any changes.
-
-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
-```
+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.
 
 ## Known Issues
 
 None so far!
 
-## License
+## Legal
 
-Copyright 2017 Google Inc.
+Copyright 2017 Google Inc. under the
+[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0); see the
+`LICENSE` file for more information.
 
 Author: Joe Richey <joerichey@google.com>
 
-Distributed under the
-[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0); see the
-`LICENSE` file for more information.
+This is not an official Google product.