Update vagrant config to ubuntu 16.04LTS
[iotivity.git] / tools / vagrant / README.md
index cb28569..b8b392f 100644 (file)
@@ -1,19 +1,34 @@
 IoTivity Build VM from Vagrant
 ==============================
 
-Vagrant can use the files in this directory to provision an Ubuntu 12.04
-development environment for IoTivity.  To create a new VM type
+Vagrant can use the files in this directory to provision an Ubuntu
+16.04LTS development environment for IoTivity.  To create a new VM:
 
     % vagrant up
 
-in the current directory.  You can then connect to the VM with
+in the current directory.  The default provider on your given host
+may not be supported by the box to be used, which will give an error.
+If so specify a provider to use. e.g. to use virtualbox:
+
+   % vagrant up --provider virtualbox
+
+You can then connect to the VM with:
 
     % vagrant ssh
 
-On the newly provisioned VM, the IoTivity repo will be checked out in
-the `iotivity` directory in the vagrant user's home directory and
-configured to use the Arduino SDKs which are automatically downloaded
-and installed in the home directory and patched when the VM is provisioned.
+On the newly provisioned VM, the IoTivity git repo will be checked out
+in the `iotivity` directory in the vagrant user's home directory.
+
+Optional (currently disabled) features are provisioning for Android
+and Arduino building. Android will now correctly provision on first
+scons run where those build options are selected. Arduino building is
+no longer really supported on iotivity (use iotivity-constrained instead).
+
+Also optional, it should be able to configure for Ubuntu 17.04
+and 17.10, by changing which of the the stanzas in Vagrantfile is
+uncommented. Non-LTS Vagrant boxes vanish from the upstream as soon as
+they go out of support (nine months for Ubuntu), so these sections will
+go out of date quickly.
 
 Using Vagrant to build a VM might be useful for:
 
@@ -22,36 +37,42 @@ Using Vagrant to build a VM might be useful for:
 
 * Configuring a Linux build environment for Windows or Mac users
 
-* Configuring build VMs for build automation
+* Configuring VMs for build automation
 
-The bootstrap.sh and iotivity-setup.sh files can be used independent of
-Vagrant to configure a existing Ubuntu environment.  How to do so is left
-as an exercise for the reader.  (Hint: try `sudo bootstrap.sh &&
-iotivity-setup.sh`.)
+The Vagrantfile has only virtualbox provider-specific options. To use
+other provides such as vmware, libvirt, just copy this stanza and
+update (feel free to submit a patch!).  Note the default 2gb RAM
+leaves a working system, but not much spare in doing builds. Don't
+do parallel builds on this without bumping the memory up. Look for:
 
-For more information about Vagrant, please see https://docs.vagrantup.com/v2/
+  config.vm.provider "virtualbox" do |vb|
 
-Assumptions
-===========
-
-* The ${HOME}/.ssh/ directory contains config, id_rsa, id_rsa.pub, and
-  known_hosts, that when copied to the VM will allow connection to the
-  git repo.  (And that you don't mind those files being copied to the VM.)
+The Vagrantfile defaults to setting up bridged networking, so that the
+new image will be visible on the network for running iotivity tests
+against other iotivity machines. It will lead to a pausing question in
+the provisioning. If this is not wanted, comment this line out:
 
-* If a USER environment variable, it has the user name to use for git
-  otherwise, USERNAME has the user ID for git.  USER should work for
-  Linux and USERNAME works inside Git bash on Windows.
+  config.vm.network "public_network"
 
-To Do
-=====
+This directory will be available inside the box as /vagrant, so if
+you need to add something visible inside the box, just dropping it
+here should be sufficient (e.g. the proxy_config file mentioned in 
+comments in iotivity-setup.sh).
 
-* Everything is dumped into the top-level directory.  A cleaner layout
-  would be better (e.g., move the Arduino libraries to iotivity/extlibs).
+For more information about Vagrant, please see https://docs.vagrantup.com/v2/
 
-* Verify on more configurations (tested on Git bash under Windows)
+Assumptions
+===========
 
-* Try with Ubuntu 14.04
+* The ${HOME}/.ssh/ directory contains files config, id_rsa, id_rsa.pub,
+  and known_hosts which when copied to the VM will allow connection to
+  iotivity gerrit, which is where the master git repo lives. That implies
+  access to gerrit has been set up already on this machine.  Sub-assumption:
+  you don't mind these personal files being copied to the VM.
 
-* Have a more flexible way to determine the git user name
+* Your git username is obtainable by doing "ssh -G gerrit.iotivity.org".
+  It will fall back to the USER and then to USERNAME environment variables,
+  which may or may not be usable.  This information is part of the setup
+  (try "git remote -v" in the iotivity directory in the running box to see),
+  but can easily be changed if the guess is wrong.
 
-* Install Android NDK