2017-02-25 16:25:33 +01:00
|
|
|
# Coconut
|
2016-10-09 01:01:25 +02:00
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
Coconut is a framework and toolset for creating reusable stacks of services.
|
2016-10-09 01:24:26 +02:00
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
If you are learning about Coconut for the first time, please see [the overview document](docs/overview.md).
|
2017-01-02 00:19:22 +01:00
|
|
|
|
2017-02-25 19:46:26 +01:00
|
|
|
## Installing
|
|
|
|
|
|
|
|
To install Coconut from source, simply run:
|
|
|
|
|
|
|
|
$ go get -u github.com/pulumi/coconut
|
|
|
|
|
|
|
|
A `GOPATH` must be set. A good default value is `~/go`. In fact, [this is the default in Go 1.8](
|
|
|
|
https://github.com/golang/go/issues/17262).
|
|
|
|
|
|
|
|
It is common to alias the shorter command `coco` to the full binary `coconut`:
|
|
|
|
|
|
|
|
alias coco=coconut
|
|
|
|
|
|
|
|
At this moment, libraries must be manually installed. See below. Eventually we will have an installer.
|
|
|
|
|
|
|
|
## Development
|
|
|
|
|
|
|
|
This section is for Coconut developers.
|
|
|
|
|
|
|
|
### Prerequisites
|
2017-02-02 20:09:33 +01:00
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
Coconut is written in Go and uses Glide for dependency management. They must be installed:
|
2017-02-02 20:09:33 +01:00
|
|
|
|
|
|
|
* [Go](https://golang.org/doc/install)
|
|
|
|
* [Glide](https://github.com/Masterminds/glide)
|
2016-11-23 21:41:30 +01:00
|
|
|
|
2017-02-02 20:09:33 +01:00
|
|
|
If you wish to use the optional `lint` make target, you'll also need to install Golint:
|
|
|
|
|
2017-02-25 19:46:26 +01:00
|
|
|
$ go get -u github.com/golang/lint/golint
|
2017-02-02 20:09:33 +01:00
|
|
|
|
2017-02-25 19:46:26 +01:00
|
|
|
### Building and Testing
|
2017-02-02 04:33:45 +01:00
|
|
|
|
2017-02-25 19:46:26 +01:00
|
|
|
To build Coconut, ensure `GOPATH` is set, and clone into a standard Go workspace:
|
2016-11-23 21:41:30 +01:00
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
$ git clone git@github.com:pulumi/coconut $GOPATH/src/github.com/pulumi/coconut
|
2016-11-23 21:41:30 +01:00
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
Coconut needs to know where to look for its runtime, library, etc. By default, it will look in `/usr/local/coconut`,
|
|
|
|
however you can override this with the `COCOPATH` variable. Normally it's easiest just to create a symlink:
|
2016-11-23 23:22:42 +01:00
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
$ ln -s $GOPATH/src/github.com/pulumi/coconut /usr/local/coconut
|
2016-11-23 23:22:42 +01:00
|
|
|
|
2016-11-23 21:41:30 +01:00
|
|
|
There is one additional build-time dependency, `golint`, which can be installed using:
|
|
|
|
|
|
|
|
$ go get -u github.com/golang/lint/golint
|
|
|
|
|
|
|
|
And placed on your path by:
|
|
|
|
|
|
|
|
$ export PATH=$PATH:$GOPATH/bin
|
|
|
|
|
|
|
|
At this point you should be able to build and run tests from the root directory:
|
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
$ cd $GOPATH/src/github.com/pulumi/coconut
|
2017-02-02 04:33:45 +01:00
|
|
|
$ glide update
|
2016-11-23 21:41:30 +01:00
|
|
|
$ make
|
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
This installs the `coco` binary into `$GOPATH/bin`, which may now be run provided `make` exited successfully.
|
2016-11-23 21:41:30 +01:00
|
|
|
|
2017-02-02 20:12:09 +01:00
|
|
|
## Compilers
|
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
The Coconut compilers are built and tested independently from `coco` and its runtime written in Go. Please see
|
|
|
|
the respective pages for details on this process for each compiler:
|
2017-02-02 20:12:09 +01:00
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
* [CoconutJS](tools/cocojs/README.md)
|
2017-02-02 20:14:10 +01:00
|
|
|
|
2017-01-26 22:50:27 +01:00
|
|
|
## Debugging
|
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
The Coconut tools have extensive logging built in. In fact, we encourage liberal logging in new code, and addding new
|
2017-01-26 22:50:27 +01:00
|
|
|
logging when debugging problems. This helps to ensure future debugging endeavors benefit from your sleuthing.
|
|
|
|
|
|
|
|
All logging is done using Google's [Glog library](https://github.com/golang/glog). It is relatively barebones, and adds
|
|
|
|
basic leveled logging, stack dumping, and other capabilities beyond what Go's built-in logging routines offer.
|
|
|
|
|
2017-02-25 16:25:33 +01:00
|
|
|
The Coconut command line has two flags that control this logging and that can come in handy when debugging problems. The
|
2017-01-26 22:50:27 +01:00
|
|
|
`--logtostderr` flag spews directly to stderr, rather than the default of logging to files in your temp directory. And
|
|
|
|
the `--verbose=n` flag (`-v=n` for short) sets the logging level to `n`. Anything greater than 3 is reserved for
|
|
|
|
debug-level logging, greater than 5 is going to be quite verbose, and anything beyond 7 is extremely noisy.
|
|
|
|
|
|
|
|
For example, the command
|
|
|
|
|
2017-02-25 19:46:26 +01:00
|
|
|
$ coco eval --logtostderr -v=5
|
2017-01-26 22:50:27 +01:00
|
|
|
|
|
|
|
is a pretty standard starting point during debugging that will show a fairly comprehensive trace log of a compilation.
|
|
|
|
|