Phoenix/vagrant

Phoenix builds on various Linux distros with Vagrant
====================================================

Vagrant (https://www.vagrantup.com/) is a tool that enables creating and using
automated, relatively lightweight virtual environments.  Vagrant and the
Vagrant community provide several base images that are essentially simplistic
bare-bones installs of various operating systems, that can be thought of as a
bare canvas ready for provisioning with the needs of whatever applications
they will be used for.

For Phoenix, this means that we can automate the creation and provisioning of
virtual Linux machines with all the packages installed that are needed for
building Phoenix.  The subfodlers located in this folder contain the Vagrant
configurations and a bootstrap script for all of the Linux distros that we
currently support.


Setup
-----

The following steps should be followed to set up a computer to be a Vagrant
host:

  1. Install VirtualBox: https://www.virtualbox.org/wiki/Downloads

  2. Install vagrant: https://www.vagrantup.com/downloads.html

  3. Install the vagrant-vbguest plugin to keep the VirtualBox Guest Additions
     package installed and up to date. See: https://github.com/dotless-de/vagrant-vbguest
     and run::

         vagrant plugin install vagrant-vbguest


Building
--------

The Vagrant VMs are provisioned to contain everything they need to build
Phoenix packages, except for two things: the source code and a build script to
do all the work. To make this a little simpler, the VMs are also configured to
share the ``{PhoenixRoot}/dist`` folder, and the
``{PhoenixRoot}/vagrant/scrtpts`` folder so they can access those two things
as well.

To perform a build there must be a Phoenix source tarball located in the
``{PhoenixRoot}/dist`` folder, which can either be generated with the
``build.py dox etg sip sdist`` command, or one of the source tarballs from a
release or the snapshots server can be used. With that file in place then a
build for a specific distro can be done with just a few vagrant commands, for
example::

    cd vagrant/ubuntu-16.04-x64
    vagrant up
    vagrant ssh -c "scripts/build.sh ubuntu-16.04"
    vagrant halt

Please note that currently this will do up to 6 complete builds, one for each
supported version of Python on that distro, for both gtk2 and gtk3. Additional
paramters can be passed to the ``build.sh`` script to narrow the build down to
a specific Python version or port.  See ``build.sh`` for details.

The wheel file(s) generated by the build will be placed in subfolders of
``{PhoenixRoot}/dist``.