[core] Update documentation

Author: teo

hacking/BUILDING.md

@@ -1,18 +1,26 @@
 # Building O² Control
 
+## Overview
+
+O² Control consists of four main components:
+* core - Go, runs locally for testing purposes and connects to a Mesos master
+* executor - Go, runs throughout the cluster
+* coconut - Go, runs locally or wherever you like and connects to core
+* process control plugin + library - C++, runs throughout the cluster linked by user processes
+
 ## Go environment
 
 ```bash
 $ sudo yum update
-$ sudo yum install golang
+$ sudo yum install golang # or alisw-golang+1.11.1-1 and load the module
 ```
 
-We need to get the `protoc` binary for Protobuf 3.5 or later. 
-It is available as an aliDist recipe, or as `alisw-protobuf+v3.5.2-2` (or newer) in the alisw YUM repository. 
+We also need to get the `protoc` binary for Protobuf 3.5 or later. 
+It is available as an aliDist recipe, or as `alisw-protobuf+v3.5.2-4` (or newer) in the alisw YUM repository. 
 Pick your favorite way to install it, and make sure to load the Protobuf module before continuing.
 
 Installing the `protobuf3-compiler` package from regular CentOS repositories and then creating a `protoc` 
-symlink to the `protoc3` binary might also work, but is unsupported. 
+symlink to the `protoc3` binary might also work, but is unsupported.
 
 Setting `GOPATH` and `PATH`:
 ```bash
@@ -26,10 +34,10 @@ $ go version
 $ go env
 ```
 
-## Clone and build
+## Clone and build the Go bits
 
-Fetching the sources. You'll get a "no buildable Go source files" error,
-that's because O² Control has its own Makefile instead of using plain `go build`.
+Fetching the sources. You'll get a "no buildable Go source files" error and that's ok,
+it happens because O² Control has its own Makefile instead of using plain `go build`.
 ```bash
 $ go get -d github.com/AliceO2Group/Control
 ```
@@ -42,4 +50,7 @@ $ make all
 
 You should find `o2control-core`, `o2control-executor` and `coconut` in `bin`.
 
-Continue with [setting up the development cluster](DCOS.md).
+If you wish to also build the process control library and/or plugin, see [the OCC readme](../occ/README.md).
+
+Otherwise, continue with [setting up the development cluster](DCOS.md) which includes instructions on
+installing these components from RPM.

hacking/DCOS.md

@@ -1,8 +1,10 @@
-# Setting up the DCOS Vagrant development environment
+# Setting up the DC/OS Vagrant development environment
 
-Unfortunately there is no suitable setup with just Mesos, so we're going to have to roll out the official DCOS development environment which is based on Vagrant and VirtualBox. Do not try this with less than 32GB of RAM.
+Unfortunately there is no suitable setup with just Mesos, so we're going to have to roll out the
+official DC/OS development environment which is based on Vagrant and VirtualBox. Do not try this
+with less than 32GB of RAM.
 
-## DCOS Vagrant quick start
+## DC/OS Vagrant quick start
 
 1. Install Vagrant and VirtualBox.
 2. Install vagrant-hostmanager plugin.
@@ -13,23 +15,31 @@ $ vagrant plugin install vagrant-hostmanager
 ```bash
 $ git clone https://github.com/dcos/dcos-vagrant
 $ cd dcos-vagrant
-$ cd <path/to/o²control/hacking>/VagrantConfig.yaml .
+$ cp <path/to/o²control/hacking>/VagrantConfig.yaml .
 $ vagrant up
 ```
-See [the DCOS Vagrant README](https://github.com/dcos/dcos-vagrant/blob/master/README.md) for more information.
+See [the DC/OS Vagrant README](https://github.com/dcos/dcos-vagrant/blob/master/README.md) for more information.
 
 ## Setting up O² software
 
-For this we need [`fpctl`](https://github.com/AliceO2Group/Control/tree/master/fpctl). Install it as [instructed](https://github.com/AliceO2Group/Control/blob/master/fpctl/README.md) with `fpctl setup`, then copy into the `fpctl` configuration directory the inventory file for DCOS Vagrant.
+This bit really depends on what we want to run. As a minimum, the executor and occ plugin must be installed
+on the DC/OS cluster, and the easiest way to do this is from aliBuild-generated RPMs `alisw-Control` including
+`alisw-Control-OCCPlugin`.
+
+[`fpctl`](https://github.com/AliceO2Group/Control/tree/master/fpctl) can help with this. Install it
+as [instructed](https://github.com/AliceO2Group/Control/blob/master/fpctl/README.md) with
+`fpctl setup`, then copy into the `fpctl` configuration directory the inventory file for DC/OS Vagrant.
 ```bash
 $ cp <path/to/o²control/hacking>/inventory ~/.config/fpctl/
 ```
 
-Then we run `fpctl` to install O² software and configuration. This will also set some Mesos agent attributes which are necessary for matching an O² role to the correct machine. Ansible will spit out some errors, which are generally safe to ignore in this case.
+Then we run `fpctl` to install O² software and configuration. This will also set some Mesos agent
+attributes which can be useful for matching an O² role to the correct machine. Ansible will spit
+out some errors, which are generally safe to ignore in this case.
 ```bash
 $ fpctl deploy -e "ignore_errors=yes"
 ```
 
-If `fpctl` prompts for it, the password for the `vagrant` user on the DCOS VMs is `vagrant`.
+If `fpctl` prompts for it, the password for the `vagrant` user on the DC/OS VMs is `vagrant`.
 
 Continue with [running O² Control](RUNNING.md).

hacking/RUNNING.md

@@ -1,34 +1,40 @@
 # Running the O² control system
 
-This part assumes you have already set up the Go environment, fetched the sources and built `o2control-core` and `o2control-executor` in `bin`, deployed the DCOS Vagrant development environment and set up O² on this cluster with `fpctl`.
+This part assumes you have already set up the Go environment, fetched the sources and built
+`o2control-core` and `o2control-executor` in `bin`, deployed the DC/OS Vagrant development
+environment and set up the software you wish to run on this cluster (for example with `fpctl`).
 
 ## grpcc
 
-In order to talk to `o2control-core` we can use `coconut`, or we can make calls directly with a gRPC client, such as [`grpcc`](https://github.com/njpatel/grpcc).
+In order to talk to `o2control-core` we can use `coconut`, or we can make calls directly with a gRPC client,
+such as [`grpcc`](https://github.com/njpatel/grpcc).
 
-Assuming you have installed Node.js and `npm` (on CC7 `$ sudo yum install http-parser nodejs npm`), the installation with `npm` is straightforward.
+Assuming you have installed Node.js and `npm` (on CC7 `$ sudo yum install http-parser nodejs npm`), the
+installation with `npm` is straightforward.
 ```bash
-$ npm install -g grpcc
+$ sudo npm install -g grpcc
 ```
 
 ## Putting it all together
 
-Assuming the DCOS Vagrant environment is up, a Mesos master will be running at `m1.dcos` with:
-* DCOS interface at [`http://m1.dcos/`](http://m1.dcos/),
+Assuming the DC/OS Vagrant environment is up, a Mesos master will be running at `m1.dcos` with:
+* DC/OS interface at [`http://m1.dcos/`](http://m1.dcos/),
 * Mesos interface at [`http://m1.dcos/mesos/`](http://m1.dcos/mesos/),
 * Marathon interface at [`http://m1.dcos/marathon/`](http://m1.dcos/marathon/).
 
-The `hacking` directory contains some wrapper scripts that rely on a Mesos master at `m1.dcos` and make running `o2control-core` easy.
+The `hacking` directory contains some wrapper scripts that rely on a Mesos master at `m1.dcos` and
+make running `o2control-core` easy.
 
-It also contains a dummy configuration file (`example-config.yaml`) which simulates what should normally be a Consul instance.
+It also contains a dummy configuration file (`config.yaml`) which simulates what should normally be
+a Consul instance.
 
 Run `o2control-core`:
 ```bash
 $ hacking/run.sh
 ```
 or:
 ```bash
-$ bin/o2control-core -mesos.url http://m1.dcos:5050/api/v1/scheduler -executor.binary ./bin/o2control-executor -verbose -config "file://hacking/example-config.yaml"
+$ bin/o2control-core -mesos.url http://m1.dcos:5050/api/v1/scheduler -executor.binary </in-cluster/path/to/o2control-executor> -verbose -config "file://hacking/example-config.yaml"
 ```
 
 Use `grpcc` to talk to it:
@@ -39,3 +45,5 @@ or:
 ```bash
 $ grpcc -i --proto core/protos/o2control.proto --address 127.0.0.1:47102
 ```
+
+See [Using `coconut`](../coconut/README.md) for instructions on the O² Control core command line interface.