![Guy Harris](/assets/img/avatar_default.png)
Avoid anachronisms, however; there was no "macOS 10.0" or even "OS X 10.0", for example. It was "Mac OS X" until 10.8 (although 10.7 was sometimes called "OS X" and sometimes called "Mac OS X"), and it was "OS X" from 10.8 to 10.11. Change-Id: Ie4a848997dcc6c45c2245c1fb84ec526032375c3 Reviewed-on: https://code.wireshark.org/review/20933 Reviewed-by: Guy Harris <guy@alum.mit.edu>
77 lines
3.4 KiB
Text
77 lines
3.4 KiB
Text
1. Introduction
|
|
|
|
Vagrant is a virtual machine management program that makes it trivial to build
|
|
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 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
|
|
|
|
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
|
|
|
|
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 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 ({Mac} 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`.
|