osmith
/
wireshark
forked from osmocom/wireshark
1
0
Fork 0
Code Pull Requests Releases Wiki Activity

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>
This commit is contained in:
Jim Young 2016-10-06 18:03:40 -05:00 committed by Anders Broman
parent 18883a7154
commit 8b6de4c81e
1 changed files with 61 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
doc/README.vagrant
View File

@ -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`.