Merge pull request #992 from cfromknecht/makefile-docs

Makefile docs

docs/INSTALL.md

@@ -42,8 +42,11 @@
     you can avoid typing this every time you open a new terminal window.
 
   * **dep:** This project uses `dep` to manage dependencies as well
-    as to provide *reproducible builds*. To install `dep`, execute the
-    following command (assumes you already have Go properly installed):
+    as to provide *reproducible builds*.
+    
+    **Note**: `dep` is automatically installed via the `make`. To fetch `dep`
+    manually, use the following command (assumes you already have Go properly
+    installed):
     ```
     go get -u github.com/golang/dep/cmd/dep
     ```
@@ -53,10 +56,9 @@
 With the preliminary steps completed, to install `lnd`, `lncli`, and all
 related dependencies run the following commands:
 ```
-git clone https://github.com/lightningnetwork/lnd $GOPATH/src/github.com/lightningnetwork/lnd
+go get -d github.com/lightningnetwork/lnd
 cd $GOPATH/src/github.com/lightningnetwork/lnd
-dep ensure
-go install . ./cmd/...
+make && make install
 ```
 
 **Updating**
@@ -64,16 +66,15 @@ go install . ./cmd/...
 To update your version of `lnd` to the latest version run the following
 commands:
 ```
-cd $GOPATH/src/github.com/lightningnetwork/lnd
-git pull && dep ensure
-go install . ./cmd/...
+git pull
+make && make install
 ```
 
 **Tests**
 
 To check that `lnd` was installed properly run the following command:
 ```
-go install; go test -v -p 1 $(go list ./... | grep -v  '/vendor/')
+make check
 ```
 
 ### Installing btcd
@@ -84,11 +85,7 @@ branch. To install, run the following commands:
 
 Install **btcd**: (must be from roasbeef fork, not from btcsuite)
 ```
-go get -u github.com/Masterminds/glide
-git clone https://github.com/roasbeef/btcd $GOPATH/src/github.com/roasbeef/btcd
-cd $GOPATH/src/github.com/roasbeef/btcd
-glide install
-go install . ./cmd/...
+make btcd 
 ```
 
 ### Starting btcd

docs/MAKEFILE.md

@@ -0,0 +1,191 @@
+Makefile
+========
+
+To build, verify, and install `lnd` from source, use the following
+commands:
+```
+make
+make check
+make install
+```
+
+Developers
+==========
+
+This document specifies all commands available from `lnd`'s `Makefile`.
+The commands included handle:
+- Installation of all go-related dependencies.
+- Compilation and installation of `lnd` and `lncli`.
+- Compilation and installation of `btcd` and `btcctl`.
+- Running unit and integration suites.
+- Testing, debugging, and flake hunting.
+- Formatting and linting.
+
+Commands
+========
+
+- [`all`](#scratch)
+- [`btcd`](#btcd)
+- [`build`](#build)
+- [`check`](#check)
+- [`clean`](#clean)
+- [`default`](#default)
+- [`dep`](#dep)
+- [`flake-unit`](#flake-unit)
+- [`flakehunter`](#flakehunter)
+- [`fmt`](#fmt)
+- [`install`](#install)
+- [`itest`](#itest)
+- [`lint`](#lint)
+- [`list`](#list)
+- [`rpc`](#rpc)
+- [`scratch`](#scratch)
+- [`travis`](#travis)
+- [`unit`](#unit)
+- [`unit-cover`](#unit-cover)
+- [`unit-race`](#unit-race)
+
+`all`
+-----
+Compiles, tests, and installs `lnd` and `lncli`. Equivalent to 
+[`scratch`](#scratch) [`check`](#check) [`install`](#install).
+
+`btcd`
+------
+Ensures that [`github.com/Masterminds/glide`][glide] is installed, and
+that the [`github.com/roasbeef/btcd`][btcd] repository is checked out
+locally. Lastly, installs the version of 
+[`github.com/roasbeef/btcd`][btcd] specified in `Gopkg.toml`
+
+`build`
+-------
+Compiles the current source and vendor trees, creating `./lnd` and
+`./lncli`.
+
+`check`
+-------
+Installs the version of [`github.com/roasbeef/btcd`][btcd] specified
+in `Gopkg.toml`, then runs the unit tests followed by the integration
+tests.
+
+Related: [`unit`](#unit) [`itest`](#itest)
+
+`clean`
+-------
+Removes compiled versions of both `./lnd` and `./lncli`, and removes the
+`vendor` tree.
+
+`default`
+---------
+Alias for [`scratch`](#scratch).
+
+`dep`
+------
+Ensures that [`github.com/golang/dep/cmd/dep`][dep] is installed, then
+updates then dependencies in the `vendor` tree using `dep ensure`.
+
+`flake-unit`
+------------
+Runs the unit test endlessly until a failure is detected.
+
+Arguments:
+- `pkg=<package>` 
+- `case=<testcase>`
+- `timeout=<timeout>`
+
+Related: [`unit`](#unit)
+
+`flakehunter`
+-------------
+Runs the itegration test suite endlessly until a failure is detected.
+
+Arguments:
+- `icase=<itestcase>`
+- `timeout=<timeout>`
+
+Related: [`itest`](#itest)
+
+`fmt`
+-----
+Runs `go fmt` on the entire project. 
+
+`install`
+---------
+Copies the compiled `lnd` and `lncli` binaries into `$GOPATH/bin`.
+
+`itest`
+-------
+Installs the version of [`github.com/roasbeef/btcd`][btcd] specified in
+`Gopkg.toml`, builds the `./lnd` and `./lncli` binaries, then runs the
+integration test suite.
+
+Arguments:
+- `icase=<itestcase>`
+- `timeout=<timeout>`
+
+`lint`
+------
+Ensures that [`gopkg.in/alecthomas/gometalinter.v1`][gometalinter] is
+installed, then lints the project.
+
+`list`
+------
+Lists all known make targets.
+
+`rpc`
+-----
+Compiles the `lnrpc` proto files.
+
+`scratch`
+---------
+Compiles all dependencies and builds the `./lnd` and `./lncli` binaries.
+Equivalent to [`lint`](#lint) [`dep`](#dep) [`btcd`](#btcd)
+[`unit-race`](#unit-race).
+
+`travis`
+--------
+**Note**: This must be run with either `RACE=true` or `RACE=false`.
+- `RACE=true` runs [`lint`](#lint) [`scratch`](#scratch) [`btcd`](#btcd)
+  [`unit-race`](#unit-race).
+- `RACE=false` runs [`lint`](#lint) [`scratch`](#scratch) [`itest`](#itest) 
+  [`unit-cover`](#unit-cover). Afterwards,
+  [`github.com/mattn/goveralls`][goveralls] is installed, and the coverage stats
+  are uploaded to [coveralls.io](https://coveralls.io).
+
+`unit`
+------
+Runs the unit test suite. By default, this will run all known unit tests.
+
+Arguments:
+- `pkg=<package>` 
+- `case=<testcase>`
+- `timeout=<timeout>`
+
+`unit-cover`
+------------
+Runs the unit test suite with test coverage, compiling the statisitics in
+`profile.cov`.
+
+Arguments:
+- `pkg=<package>` 
+- `case=<testcase>`
+- `timeout=<timeout>`
+
+Related: [`unit`](#unit)
+
+`unit-race`
+-----------
+Runs the unit test suite with go's race detector.
+
+Arguments:
+- `pkg=<package>` 
+- `case=<testcase>`
+- `timeout=<timeout>`
+
+Related: [`unit`](#unit)
+
+[btcd]: https://github.com/roasbeef/btcd (github.com/roasbeef/btcd")
+[glide]: https://github.com/Masterminds/glide (github.com/Masterminds/glide)
+[gometalinter]: https://gopkg.in/alecthomas/gometalinter.v1 (gopkg.in/alecthomas/gometalinter.v1)
+[dep]: https://github.com/golang/dep/cmd/dep (github.com/golang/dep/cmd/dep)
+[goveralls]: https://github.com/mattn/goveralls (github.com/mattn/goveralls)