Menu ▾ ▴

VirtualMachine_v1

Anonymous Ulf Lorenz

While developing WavePacket, it turned out that many people had problems compiling the library and the dependencies. As a simple solution, this document describes how to use a virtual machine (VM) to help with this task. A virtual machine is essentially a program that behaves like a computer with very kind hardware, and in which you can install another operating system (a guest), for example to ease compiling.

The solution is the bare minimum to install / compile /run the programs in the VM on the command line, and share the input/output with your host system. There are some drawbacks ranging from possibly reduced speed to rather generous resource consumption (especially memory, which the VM may claim permanently while running). These issues are only rudimentarily addressed towards the end of this document.

Note that no matter what strange system you have or what changes we did to the code, the installation described in this page should always work out of the box. If it does not, drop us an email, so that we can fix it or possibly update the documentation.

Finally, note that this document is slightly biased towards WavePacket developers. For example, pulling the git repository is overkill for normal users, although the download is small enough that this should not hurt.

1. Basic installation

As the first step, we set up the virtual machine and install all required software.

You should now have a set up virtual machine "WavePacket" with a rudimentary Linux (for insiders: the distribution is Debian wheezy/jessie, because Debian ships with the Atlas library). Now it is time to start your VM the first time. Select it and push "Start", wait for it to boot, and then login.

  • User: wavepacket
  • Password: wavepacket1

You can change the password at your convenience using the program "passwd". You only see a terminal right now, which is not a bug; we will only use the command line for the rest of the installation.

The installed keyboard layout is the standard US keyboard. If you do not like this, say, because you are used to German keyboards:

  • Reconfigure it: "sudo dpkg-reconfigure keyboard-configuration"
  • Enter your password, select the keyboard model you like
  • Restart the service: "sudo service keyboard-setup restart"

Finally, we install the required software:

  • Run the installation script by entering "bash installAll.sh"
  • You might be asked (possibly repeatedly) to enter your password, just type it in then.
  • You might be asked to select some options. They should not usually matter, so just select the default (push Return or Space+Return if you have to select something)
  • Reboot the system. We just installed a new operating system kernel, this needs to be loaded or the steps below may fail.

The minimal installation that we are going to do here should only require packages that are already downloaded and locally available in the VM, so you should not even need a network connection for this step.

2. Installing the Guest Add-ons

The most important reason for installing these add-ons are shared folders, i.e., directories on your host machine that are also visible inside the VM.

Installing the add-ons is reasonably simple:

  • In the terminal menu, click on "Devices / Install Guest Additions". This downloads a CD image if required and inserts it in the virtural CD drive.
  • make it available via "mount /media/cdrom"
  • install the guest additions with "sudo bash /media/cdrom/VBoxLinuxAdditions.run". This should work out of the box.
  • Add yourselves to the new group to have access to shared folders: "sudo adduser wavepacket vboxsf".
  • Power down your system "sudo halt"

Now we can create a shared folder.

  • in the main manager screen, click on "Settings / Shared Folders"
  • right-click, add another shared folder at a location of your choice.
  • tick the option "automount"
  • confirm everything and start the VM again

If everything went well, you will now have access to the shared folder under /media/sf_<shared_folder_name>. You can checkout the sharing by, e.g., editing a file in your host system and seeing the changes in the VM.

If the automatic mounting fails, you have to specify this manually. For this:

  • Explicitly create the directory where you want the shared folder to appear, e.g., with "sudo mkdir /media/my_shared_folder"
  • Tell the operating system to mount the shared folder (named, say, "data"). For this, type "sudo nano /etc/fstab" and add the line "data /media/my_shared_folder vboxsf uid=wavepacket 0 0"
  • on the next reboot, the shared folder will be mounted automatically.

3. Compiling / Installing the various libraries

Thanks to the prepared scripts, this should now be the simplest part.

  • Create a source directory in your home folder where all sources are downloaded to: "mkdir ~/src" ("~" expands to your user's home directory).
  • Change to this directory: "cd ~/src"
  • Run the automatic downloading and compilation script: "bash ~/compileAll.sh"
  • Go get some coffee. It will take quite some time. You will be asked for your password here and there again.

Now all WavePacket dependencies should have been compiled, and you can continue with compiling WavePacket itself.

  • Go into the wavepacket source directory. By default, this would require "cd ~/src/wavepacket"
  • Get the version that you want to have. By default, you are on the "master" branch, which is the current somewhat stable development state.
    • Run "git tag" and "git branch -r". The former lists the tagged states (releases), the latter available branches
    • Select the release or branch <name> that you want to have and run "git checkout <name>". For branches, ignore the "origin/" part.
  • Set up everything according to the instructions in the README. You should not have to modify anything (versions>= 0.1.2) or only the LIB_SRCDIR parameter (versions <0.1.2)

4. Where to go from here

You now have a fully working WavePacket installation. You can create programs in your native system, and compile/run them in the virtual machine, then look at the output again in your native system. This is all very rudimentary, but it will do the job.

Things that you could dive into from here:

  • If you have no idea at all about Unix/Linux, now would be a good time to get a book about the basics of Linux / Linux shell

  • You can improve the performance of the VM considerably if you enable hardware virtualization:

    • go to the main manager window, select the virtual machine, and click on "Settings".
    • under System/Motherboard, you can change the amount of RAM given to the machine. Note that this RAM may be claimed by VirtualBox and not be available for other programs.
    • under System/Acceleration, you can check "Enable VT-x..." to enable hardware support. If you get strange errors when starting the VM, you have to disable that again.
    • under System/Processor, you can enable more than one processor/core (requires hardware support, though)

  • you can continue with installing a graphical system in your VM

    • "sudo apt-get install xorg icewm" installs a minimalistic Window environment (replace "icewem" by "kde-full" for a more windows-like desktop)
    • Rebuild the Guest Add-ons (the graphical integration add-on failed to build before because the graphical environment was not installed)
    • You can enter the graphical mode by typing "startx" on the command line

  • Note that if you want to install additional software, it may be a good idea to use local package mirrors instead of the main debain server (usually much faster):

    • Enter "sudo nano /etc/apt/sources.list", and enter your password (sudo gives you administrator (root) privileges for the command, nano is an editor).
    • In the URLs with the form "ftp.de.*", replace "de" by the country code where you are in (e.g., "ftp.dk.debian.org" for Danish). This should speed up the download.
    • Save the changes ("Ctrl-x", "y", "Return")

  • You can have a look at the scripts installAll.sh and compileAll.sh to get a feeling what all the magic was about. If you feel confident enough, you might want to redo the installation in a VM with a 64 bit system (use, e.g., a Debian netinstall image) or even install Linux on your actual machine, optimize it etc.

Problems and Solutions

  • Image version 1 does not compile out of the box
    This is an unfortunate problem of a dependency (googletest and googlemock) no longer being available. Google has removed hosting of the downloads, which led to some restructuring of these two projects. The net effect is that the download that I originally used for the virtual machine image no longer exists, and the default paths of versions < 0.1.1b is not compatible with current versions of these libraries.

Related

Wiki: VirtualMachine_v5