From 0adde310ed59fe3779cba8946b9e2e213926dd52 Mon Sep 17 00:00:00 2001
From: Sean Fitzgerald <sean@fitzgeralds.me>
Date: Mon, 23 May 2016 22:47:00 -0700
Subject: [PATCH] Updating scripts and docs for dev environment setup.

---
 README.md    | 47 +++++++++++++++++++++++------------------------
 dev_setup.sh | 30 ++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index c6be3f01d2..becd61e238 100644
--- a/README.md
+++ b/README.md
@@ -6,23 +6,7 @@ Full docs at: https://docs.mycroft.ai
 Pair Mycroft instance with Cerberus Account Management Service: https://cerberus.mycroft.ai
 
 # Getting Started in Ubuntu - Development Environment
-- Install ` virtualenv` >= 13.1.2 and `virtualenvwrapper` (Restart session)
-- Install the following native packages
-  - `libtool`
-  - `autoconf`
-  - `bison`
-  - `swig`
-  - `libglib2.0-dev`
-  - `portaudio19-dev`
-  - `python-dev`
-  - `curl`
-  - `mpg123`
-  - `espeak`
-
-- In addition, if you are running Ubuntu 16.04 or another O/S, install:
-  - `libffi-dev`
-  - `libssl-dev` 
-
+- run `build_host_setup.sh` (installs debian packages with apt-get, please read it) 
 - run `dev_setup.sh` (feel free to read it, as well)
 - Restart session (reboot computer, or logging out and back in might work).
 
@@ -66,18 +50,33 @@ Mycroft configuration consists of 3 possible config files.
 
 When the configuration loader starts, it looks in those locations in that order, and loads ALL configuration. Keys that exist in multiple config files will be overridden by the last file to contain that config value. This results in a minimal amount of config being written for a specific device/user, without modifying the distribution files.
 
-## Starting the Virtualenv
-To ensure that you are in the Mycroft virtualenv before trying to start the services, as everything is installed there, Run:
+# Running Mycroft
+## With `start.sh`
+Mycroft provides `start.sh` to run a large number of common tasks. This script uses the virtualenv created by `dev_setup.sh`. The usage statement lists all run targets, but to run a Mycroft stack out of a git checkout, the following processes should be started:
+
+- run `./start.sh service`
+- run `./start.sh skills`
+- run `./start.sh voice`
+
+*Note: The above scripts are blocking, so each will need to be run in a separate terminal session.*
+
+## Without `start.sh`
+
+Activate your virtualenv.
+
+With virtualenv-wrapper:
 ```
 workon mycroft
 ```
 
-### Running the initial stack
+Without virtualenv-wrapper:
+```
+source ~/.virtualenvs/mycroft/bin/activate
+```
+
+
 - run `PYTHONPATH=. python client/speech/main.py` # the main speech detection loop, which prints events to stdout and broadcasts them to a message bus
 - run `PYTHONPATH=. python client/messagebus/service/main.py` # the main message bus, implemented via web sockets
 - run `PYTHONPATH=. python client/skills/main.py` # main skills executable, loads all skills under skills dir
 
-### Running stack via the script
-- run `./start.sh service`
-- run `./start.sh skills`
-- run `./start.sh voice`
+*Note: The above scripts are blocking, so each will need to be run in a separate terminal session. Each terminal session will require that the virtualenv be activated. There are very few reasons to use this method.*
diff --git a/dev_setup.sh b/dev_setup.sh
index 07ad5f7999..b6e6e0ffef 100755
--- a/dev_setup.sh
+++ b/dev_setup.sh
@@ -1,7 +1,37 @@
 #!/usr/bin/env bash
+######################################################
+# dev_setup.sh
+# @author sean.fitzgerald (aka clusterfudge)
+#
+# The purpose of this script is to create a self-
+# contained development environment using
+# virtualenv for python dependency sandboxing.
+# This script will create a virtualenv (using the
+# conventions set by virtualenv-wrapper for
+# location and naming) and install the requirements
+# laid out in requirements.txt, pocketsphinx, and
+# pygtk into the virtualenv. Mimic will be
+# installed and built from source inside the local
+# checkout.
+#
+# The goal of this script is to create a development
+# environment in user space that is fully functional.
+# It is expected (and even encouraged) for a developer
+# to work on multiple projects concurrently, and a
+# good OSS citizen respects that and does not pollute
+# a developers workspace with it's own dependencies
+# (as much as possible).
+# </endRant>
+######################################################
+
 # exit on any error
 set -Ee
 
+if [ $(id -u) -eq 0 ]; then
+  echo "This script should not be run as root or with sudo."
+  exit 1
+fi
+
 TOP=$(cd $(dirname $0) && pwd -L)
 VIRTUALENV_ROOT=${VIRTUALENV_ROOT:-"${HOME}/.virtualenvs/mycroft"}