Add Vagrant workflow and documentation

The project previously did not include suggested development workflows
or environments. The one workflow script included
(`bin/rebuild-and-deploy`) was tightly coupled to my own local
environment.

This PR:

  - adds a Vagrantfile for a Ubuntu virtual machine running Xen
  - turns my existing (undocumented) workflows into helper scripts
  - adds a tutorial for building and running a program with AtmanOS
  - starts a document for developing AtmanOS itself

.gitignore

@@ -1 +1,2 @@
 /build
+/.vagrant

Makefile

@@ -2,8 +2,12 @@ GOROOT_BOOTSTRAP := $(abspath build/go_bootstrap)
 GOROOT           := $(abspath build/go)
 
 .PHONY: build
-build: $(GOROOT)/bin/go update-stdlib
-	GOOS=atman $(GOROOT)/bin/go build -a runtime
+build: $(GOROOT)/bin/atman $(GOROOT)/bin/go update-stdlib
+	$(GOROOT)/bin/atman build -a runtime
+
+$(GOROOT)/bin/atman: bin/atman
+	sed 's|GOROOT=.*|GOROOT=$(GOROOT)|' $< > $@
+	chmod +x $@
 
 GODEPS = $(shell find $(GOROOT)/src/cmd $(GOROOT)/src/go -name "*.go")
 $(GOROOT)/bin/go: $(GODEPS)

README.md

@@ -15,51 +15,16 @@ manner:
 GOOS=atman go build
 ```
 
-## Building AtmanOS
+## Build AtmanOS
 
 Build AtmanOS by running `bin/setup`,
 which will download the required dependencies to the build directory
 and then build AtmanOS itself.
 
-## Example
+## Build a program and deploy it
 
-Here's the output when running the [concurrent prime sieve][sieve] on a local
-Xen host:
-
-  [sieve]: https://golang.org/doc/play/sieve.go
-
-```
-(d87) Atman OS
-(d87)      ptr_size:  8
-(d87)    start_info:  0x502000
-(d87)         magic:  xen-3.0-x86_64
-(d87)      nr_pages:  8192
-(d87)   shared_info:  393093120
-(d87)    siff_flags:  0
-(d87)     store_mfn:  68117
-(d87)     store_evc:  1
-(d87)   console_mfn:  68116
-(d87)   console_evc:  2
-(d87)       pt_base:  5263360
-(d87)  nr_pt_frames:  7
-(d87)      mfn_list:  5185536
-(d87)     mod_start:  0
-(d87)       mod_len:  0
-(d87)      cmd_line:  [1024/1024]0x502080
-(d87)     first_pfn:  0
-(d87) nr_p2m_frames:  0
-(d87)
-(d87) 2
-(d87) 3
-(d87) 5
-(d87) 7
-(d87) 11
-(d87) 13
-(d87) 17
-(d87) 19
-(d87) 23
-(d87) 29
-```
+Read the [Running locally with Vagrant](doc/running-locally-with-vagrant.md)
+tutorial for the fastest way to build your first program with AtmanOS.
 
 Contributing
 ------------

Vagrantfile

@@ -0,0 +1,21 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+Vagrant.configure(2) do |config|
+  config.vm.box = "ubuntu/trusty64"
+
+  # Disable the default shared folder, because we can't use VirtualBox shared
+  # folders when running under Xen.
+  config.vm.synced_folder ".", "/vagrant", disabled: true
+
+  # Run vagrant rsync to update the shared images.
+  config.vm.synced_folder "vagrant/", "/home/vagrant/atman", type: "rsync"
+
+  # Install xen hypervisor
+  config.vm.provision "shell", inline: <<-SHELL
+    sudo apt-get update
+    sudo apt-get install -y xen-hypervisor-4.4-amd64 gdb
+    sed -i '1s|^|export PATH=$HOME/atman/bin:$PATH\\n|' .bashrc
+    sudo reboot
+  SHELL
+end

bin/atman

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+GOROOT=build/go
+
+GOOS=atman exec "$GOROOT"/bin/go "$@"

bin/rebuild-and-deploy

@@ -3,18 +3,11 @@
 set -e
 
 PACKAGE=$1
-
-XEN_DEBUG_HOST=xen-debug
 VMNAME=$(basename $PACKAGE)
-KERNEL=${GOBIN:-$HOME/bin}/atman_amd64/$VMNAME
 
 make build
 
-GOOS=atman build/go/bin/go install -a "$PACKAGE"
-
-scp "$KERNEL" "$XEN_DEBUG_HOST":~/$VMNAME
+bin/atman build -o vagrant/images/$VMNAME -a "$PACKAGE"
 
-ssh "$XEN_DEBUG_HOST" \
-  "sudo xl destroy $VMNAME 2>/dev/null ; \
-   sudo xl dmesg -c &>/dev/null ; \
-   sudo xl create atman.xl \"name = '$VMNAME'\" \"kernel = '$VMNAME'\""
+vagrant rsync
+vagrant ssh -- startvm $VMNAME

doc/developing-atmanos.md

@@ -0,0 +1,36 @@
+# Developing AtmanOS
+
+## Build AtmanOS
+
+If you've just downloaded the AtmanOS project, run `bin/setup` to download the
+required dependencies and build AtmanOS.
+
+Once you've run `bin/setup`, rebuilding AtmanOS can be done with `make build`.
+
+## Testing changes
+
+You can test changes using basic workflow outlined in [Running locally with
+Vagrant](./running-locally-with-vagrant.md).
+
+There's also a helper script which automates the process of rebuilding AtmanOS
+and deploying a test program:
+
+```
+$ bin/rebuild-and-deploy github.com/atmanos/example/hello
+```
+
+It may be useful to automatically build and deploy whenever changes are made,
+which can be done with [entr](http://entrproject.org/):
+
+```
+$ find src -type f |
+  entr bin/rebuild-and-deploy github.com/atmanos/example/hello
+```
+
+## Debug an AtmanOS kernel
+
+You can get a GDB session for a running (or crashed) kernel with:
+
+```
+$ vagrant ssh -- debugvm hello
+```

doc/running-locally-with-vagrant.md

@@ -0,0 +1,98 @@
+# Running locally with Vagrant
+
+The AtmanOS includes a Vagrantfile whch describes a development Xen
+environment. To use this development environment, you'll need:
+
+  * Vagrant: https://www.vagrantup.com/
+  * VirtualBox: https://www.virtualbox.org/
+
+If you're on OS X and use Homebrew, you can get these with:
+
+```
+$ brew cask install vagrant virtualbox
+```
+
+## Build AtmanOS
+
+If you've just downloaded the AtmanOS project, run `bin/setup` to download the
+required dependencies and build AtmanOS.
+
+Once you've run `bin/setup`, rebuilding AtmanOS can be done with `make build`.
+
+## Provision the virtual machine
+
+From the root directory of the AtmanOS project, run:
+
+```
+$ vagrant up
+```
+
+The first time you run this, it will take a while, as it needs to install Xen
+and reboot the virtual machine.
+
+Once the command completes, you should be able to connect to the machine by
+running `vagrant ssh`.
+
+At any time you can use `vagrant halt` to shut down the virtual machine, or
+`vagrant pause` to pause it for faster boot later.
+
+## Run an AtmanOS kernel
+
+For this section, we'll be using the hello program from the [repository of
+AtmanOS example programs][example].
+
+  [example]: github.com/atmanos/example
+
+Download the program with:
+
+```
+$ go get github.com/atmanos/example/hello
+```
+
+You can run `hello` locally to see that it first prints "Hello, world", and
+then prints the current time every few seconds.
+
+But we want to run the `hello` program on Xen!
+
+To do that, we'll first need to build a kernel image with `atman`:
+
+```
+$ bin/atman build -o vagrant/images/hello \
+  github.com/atmanos/example/hello
+```
+
+We told `atman` to put the built image in `vagrant/images`. That allows up to
+transfer the image to the Vagrant environment with:
+
+```
+$ vagrant rsync
+```
+
+Finally, we can run our `hello` kernel with:
+
+```
+$ vagrant ssh -- startvm hello
+```
+
+The [`startvm` command](../vagrant/bin/startvm) is a wrapper for a few Xen
+commands, stopping any existing machine with the same name, and then starting a
+new machine with the [default template](../vagrant/template.xl).
+
+To see the output of `hello`, attach to the console with [another Xen
+wrapper](../vagrant/bin/console):
+
+```
+$ vagrant ssh -- console hello
+Hello, world
+The current time is 2016-04-23 23:53:05.651799283 +0000 UTC
+The current time is 2016-04-23 23:53:10.651806585 +0000 UTC
+The current time is 2016-04-23 23:53:15.651807123 +0000 UTC
+```
+
+Success!
+
+Now we can stop the `hello` machine with:
+
+```
+$ vagrant ssh -- sudo xl destroy hello
+```

vagrant/.gitignore

@@ -0,0 +1 @@
+/images

vagrant/bin/console

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+VMNAME=$1
+
+sudo xl console $VMNAME

vagrant/bin/debugvm

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+set -e
+
+VMNAME=$1
+domid=$(sudo xl domid $VMNAME)
+
+sudo /usr/lib/xen-4.4/bin/gdbsx -a $domid 64 9999 &
+sleep 1
+gdb -ex "target remote localhost:9999" $HOME/atman/images/$VMNAME

vagrant/bin/startvm

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+VMNAME=$1
+
+sudo xl destroy $VMNAME 2>/dev/null
+sudo xl dmesg -c &>/dev/null
+sudo xl create -e $HOME/atman/template.xl \
+  "name = '$VMNAME'" \
+  "kernel = '$HOME/atman/images/$VMNAME'"

vagrant/template.xl

@@ -0,0 +1,4 @@
+vcpus = 1
+memory = 16
+
+on_crash = 'preserve'