Add a little more info about vagrant and our Vagrantfile.

Change-Id: I2f24f869e6b7b819e50e3ea5ade5dbae5272ced2
Reviewed-on: https://code.wireshark.org/review/18102
Reviewed-by: Anders Broman <a.broman58@gmail.com>

1 files changed, 61 insertions, 16 deletions

diff --git a/doc/README.vagrant b/doc/README.vagrant
index 57feabced3..790d969ebc 100644
--- a/doc/README.vagrant
+++ b/doc/README.vagrant
@@ -1,31 +1,76 @@
 1. Introduction
 
 Vagrant is a virtual machine management program that makes it trivial to build
-and configure reproducible virtual machines. Wireshark comes with a Vagrantfile
-which will set up a complete Ubuntu development environment in a virtual
-machine, including all necessary compilers, dependent libraries, and tools like
-valgrind.
+and configure reproducible virtual machines. Wireshark's source code includes
+a Vagrantfile which can be used to set up a complete Ubuntu development
+environment in a virtual machine, including all necessary compilers, dependent
+libraries, and tools like valgrind.
 
-Using vagrant can greatly simplify setup for new developers, at the cost of
-running your builds in a virtual machine, thus with reduced performance.
+Using vagrant can greatly simplify the creation of a Linux build environment
+for new developers, at the cost of running your builds in a virtual machine,
+thus with reduced performance.
 
 2. Installation
 
-Vagrant requires VirtualBox to be installed, as that is the backing virtual
-machine technology it uses. Install it first from https://www.virtualbox.org/.
+The Vagrantfile included in Wireshark's source directory is configured to use
+VirtualBox as the backing virtual machine technology provider. You must first
+install VirtualBox from https://www.virtualbox.org/.
 
 Now install vagrant itself from https://www.vagrantup.com/.
 
+Please note that vagrant is a CLI command and should typically be installed in
+your host system's $PATH. To better understand what vagrant is doing you may
+want to review vagrant's `Getting Started` web pages.
+
 3. Setup
 
-With virtualbox and vagrant installed, setting up your VM is as simple as
-running `vagrant provision` in the wireshark source directory. This will
-download, install and configure a complete Ubuntu development environment. It
-will also mount the Wireshark source directory into the VM, and run an
-out-of-tree cmake build into the ~/build directory of the VM.
+By default vagrant looks for the file name Vagrantfile in the current
+directory. Wireshark's Vagrantfile is located in the root of the Wireshark
+source folder.
+
+Once both VirtualBox and vagrant are installed, setting up an Ubuntu Wireshark
+development VM is as simple as running `vagrant up` followed by
+`vagrant provision`.
+
+The first time that the `vagrant up` command is executed vagrant will initiate
+the download of a specific Ubuntu VM image (what they call a box) from
+HashiCorp's Atlas box catalog. Once the box is downloaded an Unbuntu VM will
+be instantiated and powered-on.
+
+Use the command `vagrant status` to determine the state of the VM.
+
+The command `vagrant provision` will run any provisioning tasks defined in the
+Vagrantfile. Wireshark's Vagrantfile is configured to run two bash based
+provisioning scripts, vagrant_provision.sh and vagrant_build.sh. These
+provisoning scripts are executed on the Ubuntu VM system and not on the host
+system.
+
+The vagrant_provision.sh script initiates several apt-get tasks to get the
+Ubuntu VM reasonably up to date. The vagrant_build.sh script sets up a cmake
+build environment which includes creating a ~/build folder initialized for an
+out-of-tree cmake build and then triggering a build.
 
 4. Usage
 
-Running `vagrant ssh` from the wireshark source directory will put your shell
-into the VM. Running `make` inside the `~/build` directory of the VM will
-build wireshark based on whatever is in your source tree.
+Running `vagrant ssh` from the wireshark source directory will log you into
+Ubuntu VM as the userid vagrant.
+
+The Ubuntu VM's build folder is located in ~/build. The Ubuntu VM's source
+folder is actually the source folder from the host system mounted as /vagrant.
+Any changes made in the VM's /vagrant folder are reflected in the host system's
+Wireshark source folder and visa-versa.
+
+Once logged into the VM issue the command `cd ~/build` followed by `make` to
+trigger a new wireshark build based on whatever is in your host system's source
+tree (the Ubuntu VM's /vagrant folder).
+
+The various Wireshark applications can be run from the ~/build folder of the
+Ubuntu VM with commands such as `./run/wireshark`, `./run/tshark`, etc.
+
+To run the Wireshark GUI you will typically need an X server. If you are using
+macOS (OS X) as the host system then you would likely use XQuartz as your X
+server. XQuartz can be downloaded from https://www.xquartz.org/.
+
+The Ubuntu VM can be shutdown or suspended from the host system with the
+commands `vagrant halt` and `vagrant suspend` repectively. In either case the
+Ubuntu VM can be brought back up with the command `vagrant up`.