VirtualMachine_v6

For documentation on the buildsystems prior to v6, 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, drop a note on the mailing list or per private mail, so that the issue is fixed (and your problem solved).

• Minimal instructions
• Optional steps
• Trouble shooting / Problems
• Details of the system
• 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 6 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 minimal instructions. The login data is

User: wavepacket
Password: wavepacket1

1. We need to set the Debian mirror to download packages from. The default is the German mirror which will work, but may be slow outside of Germany. If you do not care, you might skip this step.
   * 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")
2. Start the preparation of everything by typing "bash prepareAll.sh".
3. When asked for a password, enter the user password. When asked for any decision, whatever you pick should be fine.

The script "prepareAll.sh" now installs all required programs for compilations. It then downloads and compiles the tensor library, on which Wavepacket relies, and finally downloads the WavePacket git repository. Altogether, you should expect around 400 MB of downloaded data and a few minutes of waiting.

1. Enter the Wavepacket directory "cd wavepacket"
2. Check which version (or branch) you want to compile
   • "git tag" lists all available tags (one for each release)
   • "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>"
3. Follow the normal instructions in the readme for compilation
   • "less README" lets you browse the readme; q exits the viewer
   • If you also want to install the python bindings, type "sudo apt install python-pip" (or python-pip3 if you want to do everything with python3). You then still need to download the requirements as documented in README.Python

Optional steps

1. Sharing a folder between guest and host system. That allows you to exchange data between the two.
   • Create a directory on your host 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".
     • Reboot the system if you have not done so yet (we installed a new OS version, and the VirtualBox utils were compiled against that version)
       "sudo reboot" and login again afterwards
     • You should now be able to mount the shared folder
       • "sudo mount -t vboxsf my_share /mnt/shared" should work without error
       • "ls /mnt/shared" should show you changes if you add/remove files from within the host system
       • unmount for now again with "sudo umount /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
   • Close the VM window and select the option "Send shutdown signal".
   • You could also type "sudo halt", then turn the VM off (the "Power off" option when you close the VM).

Trouble shooting / Problems

• If you manage to screw up the boot process (e.g., mistype something when setting up the shared folder below), there is no simple way to recover. Reason: I locked the root (/admin) account, but if there are problems with the boot process, the system wants to boot into the root account. Such a problem can be fixed, but that requires some deeper Linux/Unix skills.
• I observed occasional black screens when rebooting. Probably something broken with the VM console display (?). If the screen is black when there should be a login screen, just type username and password blindly. After a successful login eveything is refreshed, and you see the console again.

Details of the system

The system installed on the guest is a 64 bit Debian stretch. By default, the virtual machine is set up with 1GB of RAM, one CPU and a 20 GB hard disk (written to a file)

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 change the VirtualMachine resources.

  • Select "Machine / Settings" in the VirtualBox menu
  • Switch to the "System" display
  • Now you can assign more memory and CPUs to the virtual machine if you need them. There are also lots of other settings, but they are probably less relevant.

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

  • 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 show <packagename>" to get more detailed information</packagename>
    • Use "sudo apt install <packagename>" to install new packages
      (sudo gives you administrator permissions for the subsequent command)</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
    • Install the "xinit" package to setup the graphical system
    • Type "startx" to start up the window manager
    • If this does not work, try to reboot "sudo reboot" and login again.
      (This should not be required in principle. Probably a packaging bug, but I did not follow up on this issue)