From 8b6de4c81eeb92c347273847318c117b6bd961b7 Mon Sep 17 00:00:00 2001 From: Jim Young Date: Thu, 6 Oct 2016 18:03:40 -0500 Subject: [PATCH] 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 --- doc/README.vagrant | 77 ++++++++++++++++++++++++++++++++++++---------- 1 file 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`.