diff options
author | Jim Young <jyoung@gsu.edu> | 2016-10-06 18:03:40 -0500 |
---|---|---|
committer | Anders Broman <a.broman58@gmail.com> | 2016-10-07 07:37:24 +0000 |
commit | 8b6de4c81eeb92c347273847318c117b6bd961b7 (patch) | |
tree | 329742299ad7915373a8249470e180a398bbc8c3 /doc | |
parent | 18883a7154f36efee5bc40ad3d23013fd742514b (diff) |
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>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/README.vagrant | 77 |
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`. |