A couple further vagrant clarifications

README.md

@@ -93,10 +93,6 @@ directory of your host machine, which is mounted at `/vagrant` within the VM.
 You can use this shared folder to move your Proton build out of the VM, or as
 one way to copy files into the VM.
 
-If you do not wish to use Vagrant, you can reference Vagrantfile and
-`vagrant-user-setup.sh` for the list of dependencies and instructions on how to
-set up your own machine or another VM of your choosing.
-
 When you are done with the VM, you can shut it down from the host machine:
 
         vagrant halt
@@ -104,6 +100,11 @@ When you are done with the VM, you can shut it down from the host machine:
 Please read the Vagrant documentation for more information about how to use
 Vagrant VMs.
 
+If you do not wish to use Vagrant, you can read through both Vagrantfile and
+`vagrant-user-setup.sh` for the list of dependencies and instructions on how to
+set up your own machine or another VM of your choosing. It is aimed at Debian
+9, but you should be able to adapt them for other distributions.
+
 ---
 Alternative: Building without the Steam Runtime
 ---
@@ -142,13 +143,12 @@ dependencies for Wine.
 ---
 Build Proton
 ---
-A couple of Makefile targets are provided. `make dist` will create a Proton
+A couple of Makefile targets are provided.
-installation that you can install locally with `make install`. `make deploy`
-will package Proton up for distribution via Steamworks.
 
-The `dist/` folder now contains a build of Proton which you can install
+`make dist` will create a Proton installation in `dist/` that you can install
-manually or with `make install` to install into your user's Steam installation.
+manually (see below), or automatically with `make install`.
-See the next section for more details.
+
+`make deploy` will package Proton up for distribution via Steamworks.
 
 ---
 Install Proton locally

Vagrantfile

@@ -16,7 +16,9 @@ Vagrant.configure(2) do |config|
   config.vm.synced_folder "./vagrant_share/", "/vagrant/", id: "share", create: true
   config.vm.synced_folder ".", "/home/vagrant/proton", id: "proton", type: "rsync", rsync__exclude: ["/output/", "vagrant_share"], rsync__args: ["--verbose", "--archive", "-z", "--links", "--update"]
 
+  #this is where the VM is initialized on first setup
   config.vm.provision "shell", privileged: "true", inline: <<-SHELL
+    #install docker and steam-runtime dependencies
     dpkg --add-architecture i386
     apt-get update
     apt-get install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common
@@ -25,18 +27,21 @@ Vagrant.configure(2) do |config|
     curl -fsSL https://dl.winehq.org/wine-builds/Release.key | apt-key add -
     echo 'deb http://dl.winehq.org/wine-builds/debian stretch main' > /etc/apt/sources.list.d/winehq.list
 
-    #add backports
-    echo 'deb http://ftp.debian.org/debian stretch-backports main' > /etc/apt/sources.list.d/backports.list
-
     #add docker repo
     curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add -
     add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian stretch stable"
 
+    #add backports
+    echo 'deb http://ftp.debian.org/debian stretch-backports main' > /etc/apt/sources.list.d/backports.list
+
     #install host build-time dependencies
     apt-get update
-    apt-get install -y gpgv2 gnupg2 g++ g++-6-multilib mingw-w64 git docker-ce winehq-devel fontforge-nox
+    apt-get install -y gpgv2 gnupg2 g++ g++-6-multilib mingw-w64 git docker-ce fontforge-nox
     apt-get -y -t stretch-backports install meson
 
+    #winehq-devel is installed to pull in dependencies to run Wine
+    apt-get install -y --install-recommends winehq-devel
+
     #remove system Wine installation to ensure no accidental leakage
     apt-get remove -y winehq-devel
 
@@ -52,6 +57,8 @@ Vagrant.configure(2) do |config|
 
   config.vm.provision "shell", privileged: "true", inline: <<-SHELL
     # unprivileged shell still runs as root for some reason
+
+    # the script below will set up the steam-runtime docker containers
     sudo -u vagrant /home/vagrant/proton/vagrant-user-setup.sh
   SHELL
 end

vagrant-user-setup.sh

@@ -1,4 +1,5 @@
 #!/bin/sh
+
 #set up steam runtimes. remove these lines if building without the runtime
 git clone https://github.com/ValveSoftware/steam-runtime.git -b wip-docker
 ./steam-runtime/setup_docker.sh --beta amd64 --extra-bootstrap=/home/vagrant/proton/steamrt-bootstrap.sh steam-proton-dev
@@ -8,5 +9,5 @@ git clone https://github.com/ValveSoftware/steam-runtime.git -b wip-docker
 mkdir build
 cd build
 ../proton/configure.sh --steam-runtime64=docker:steam-proton-dev --steam-runtime32=docker:steam-proton-dev32
-#if building without the runtime:
+#if building without the runtime, use:
 #../proton/configure.sh --no-steam-runtime