VirtualMachine_v5

For documentation on the buildsystems prior to v5, see here

In simplistic terms, a virtual machine is a program that emulates a computer. On this virtual machine, you can then install another operating system (the guest). This document describes how to use a virtual machine to simplify the setup of a Wavepacket system. Everything needed to compile Wavepacket (or compile and run your programs that use the library) is done in the Linux guest system, then you can share data for easier manipulation with your "real" system (the host).

Note that compilation with a reasonably current build image should always work, no matter what. If you experience problems while following the instructions here, you are highly welcome to drop a note on the mailing list or per private mail, so that the issue can be fixed.

• Minimal instructions
• Optional steps
• Details of the system, limitations
• Where to go from here

Minimal instructions

1. Download and install the VirtualBox emulation software from http://www.virtualbox.org
2. Download the image for the already prepared operating system from https://sourceforge.net/projects/cpp.wavepacket.p/files/Compilation%20images/. You need at least version 5 of the build system for the instructions on this page.
3. Start VirtualBox, select File / Import Appliance, and select the downloaded .ova image.
4. Start the created virtual machine

After booting the guest, you should see a command-line asking you to enter a username. We will stick with the command line for the rest of the instructions. The login data is

User: wavepacket
Password: wavepacket1

1. Start the preparation of everything by typing "bash prepareAll.sh".
2. When asked for a password, enter the user password

This now installs all required programs, downloads and installs all dependencies of Wavepacket, and also downloads WavePacket. The Wavepacket code is downloaded to a directory "wavepacket" as git repository.

1. Enter the Wavepacket directory "cd ~/wavepacket"
2. Check which version (or branch) you want to compile
   • "git tag" lists all available tags (here: stable versions
   • "git branch -r" lists all available development branches
   • Pick a tag or branch and make it the current one "git checkout <tag_or_branch_name>"</tag_or_branch_name>
3. Follow the normal instructions in the readme for compilation
   • "less README" lets you browse the readme; q exits the viewer

Optional steps

1. Sharing a folder between guest and host system. That allows you to exchange data between the two.
   • Create a directory that will hold the shared content
   • Tell VirtualBox about this shared folder
     • In the VirtualBox GUI, right-click on the virtual machine, select "Settings"
     • Select "Shared Folders", add the created directory as shared folder with some name, say "my_share"
   • Tell the guest system about the shared folder
     • Create a new directory that later hosts the shared folder, say "sudo mkdir /mnt/shared".
     • Tell the operating system to mount the shared folder.
       • Type "sudo nano /etc/fstab"
       • Add the line "my_share /mnt/shared vboxsf uid=wavepacket 0 0" (using the example names)
       • Save the file with "Ctrl-X" and confirm with "Y" and "Return"
   • Mount the shared folder (automatically done on later reboots) "mount -a"
   • Now you can exchange files via the directory "/mnt/shared" in the guest system and your created directory in the host system.
2. Changing the keyboard layout
   • Run "sudo dpkg-reconfigure keyboard-configuration"
   • Pick the keyboard model and configuration that you want
   • Restart the service: "sudo service keyboard-setup restart"
3. Changing the password
   • Type "passwd" and follow the instructions
4. Power off the system
   • Use "sudo halt" to stop the system, then turn the VM off or just save the state (one of the options when you close the VM).

Details of the system, limitations

The system installed on the guest is a Debian stretch. I fetched all the packages to install to ensure a well-defined, stable system. The total system after a compilation of Wavepacket is about 2 GB. The hard disk can grow up to 20 GB, which should be enough for almost all purposes.

The guest system is a 32-bit Linux for compatibility reasons. This has some minor efficiency problems, most notably only one CPU can be assigned to the guest system. Also, the maximum memory is limited to single Gigabytes, and some settings for the virtual machine cannot be activated. In practice, this should rarely be a problem. The build system may be upgraded to 64 bit in the future (this would not run on a 32-bit host system, but these become really rare nowadays).

Where to go from here

• If Linux and Command lines are completely new, study a basic tutorial. Chances are you will come across them again anyway in science contexts

  • For example https://ryanstutorials.net/linuxtutorial/
  • Or one of the various books on the subject Linux / Unix / Bash / Command line interface

• You can upgrade the guest system programs (packages) or install some new ones.

  • First you should set your local Debian mirror, this speeds up downloads
    • Enter "sudo nano /etc/apt/sources.list"
    • 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).
    • Save the changes ("Ctrl-x", "y", "Return")
  • Update the list of packages "apt update"
  • You can upgrade the installed packages with "apt upgrade"
  • Or you can install new packages
    • Use "apt search <keyword>" to search for packages by keyword</keyword>
    • Use "apt install <packagename>" to install new packages</packagename>
  • To get a window manager in the host
    • Install the "icewm" package (minimal window manager) or "kde-full" for a more Windows-like desktop
    • Whenever you see a command-line interface, type "startx" to start up the window manager

• If you feel confident enough, you can have a look at the script "prepareAll.sh" to see what the magic was about. You could also install for example a 64-bit system or even try the installation on your real machine.