Build a Desktop VM#

In the following, we explain how to build your own custom Quantum Mobile VirtualBox image from scratch.

Calculate at around two hours for building the full VM:

Approximate Timings
marvel-nccr.bigdft : Compile bigdft executables ----------------------- 906.73s
marvel-nccr.quantum_espresso : Make QE executables -------------------- 867.71s
marvel-nccr.abinit : Make abinit executable (2 cpu) ------------------- 807.30s
marvel-nccr.wannier90 : run Wannier90 default tests ------------------- 720.07s
marvel-nccr.libxc : Compile libxc executable (2 cpu) ------------------ 678.97s
marvel-nccr.ubuntu_desktop : Install ubuntu-desktop (apt) ------------- 532.78s
marvel-nccr.yambo : Make Yambo executables ---------------------------- 406.67s
marvel-nccr.fleur : run fleur tests ----------------------------------- 395.95s
marvel-nccr.fleur : Make fleur executables ---------------------------- 345.77s
marvel-nccr.abinit : run the tests (2 cpu) ---------------------------- 315.32s
marvel-nccr.libxc : Run make check for libxc -------------------------- 313.18s
marvel-nccr.siesta : Make siesta executable --------------------------- 308.16s
marvel-nccr.aiida : Install aiida-core + plugins into venv ------------ 262.80s
marvel-nccr.slurm : Install apt packages ------------------------------ 211.29s
marvel-nccr.simulationbase : Install plotting tools, etc. ------------- 187.73s
marvel-nccr.siesta : Make xmlf90 -------------------------------------- 179.07s
marvel-nccr.bigdft : run test suite ----------------------------------- 143.86s
marvel-nccr.aiidalab : install server-side (aiida) dependencies ------- 120.63s
marvel-nccr.cp2k : download cp2k binary ------------------------------- 108.26s
marvel-nccr.ansible_prerequisites : Install aptitude ------------------ 104.13s

See also

See the continuous deployment (CD) workflow for up-to-date timings

Prerequisites & Installation#

  • Operating system: Building Quantum Mobile has been tested on MacOS, Ubuntu and Windows.

  • Vagrant >= 2.0.1

  • VirtualBox >= 6.1.6

  • Python >= 3.6

Building on Windows

  • Install Windows Subsystem for Linux

  • Install VirtualBox under Windows

  • Add the following lines to your .bashrc in WSL:

    # Enable WSL feature in vagrant
export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"  
# Add virtualbox under Windows to $PATH
export PATH="${PATH}:/mnt/c/Program Files/Oracle/VirtualBox"

Clone the repository:

git clone https://github.com/marvel-nccr/quantum-mobile.git
cd quantum-mobile

Install tox and the vagrant-vbguest plugin:

pip install tox
# improves interface
vagrant plugin install vagrant-vbguest

Tip

For those using Conda, it is recommended to also install tox-conda:

pip install tox-conda

Create the Virtual Machine#

See also

If you would like to customise any aspects of the VM, now would be a good time to do so.

Use tox to set up the Python environment and run the build steps.

tox -a -v        # shows available automations
tox -e vagrant

This will call vagrant up, to initialise the VM, which then calls ansible-playbook playbook-build.yml, to configure the VM and build the required software on it.

Tip

If you get an error during the installation of the VirtualBox Guest Additions, you may need to perform additional steps (see issue #60).

Tip

Building the Desktop Edition is tested on GitHub Actions on every commit to the repository. For the tested steps see the .github/workflows/build.yml file.

Continuing a failed build#

If the build fails or is interrupted at any step (for example a failed download, due to a bad connection), you can continue the build with:

# output the vagrant box connection details
vagrant ssh-config > vagrant-ssh
tox -e ansible

The ansible automation steps are generally idempotent, meaning that if they have been previously run successfully, then they will be skipped in any subsequent runs.

Running only selected steps#

All steps of the ansible build process are “tagged”, which allows you to select to run only certain steps, or skip others.

To list all the tags:

tox -e ansible -- --list-tags

or look at playbook-build.yml.

To run only certain tags, use either:

ANSIBLE_ARGS="--tags tag1,tag2 --skip-tags tag3" tox -e vagrant

or

tox -e ansible -- --tags tag1,tag2 --skip-tags tag3

Creating the image#

First, clean unnecessary build files:

tox -e ansible -- --tags cleanup

Then run playbook-package.yml via:

tox -e package -- --skip-tags validate

This will compact the hard disk of the virtual machine and export the image and release notes to the dist/ folder.

Note

The validate tag checks that the repositories git tag is the same as the vm_version specified in inventory.yml, and is only needed for new releases by Quantum Mobile maintainers.

Other Useful commands#

  • vagrant reload: restart machine

  • vagrant halt: stop machine

Vagrant keeps information on how to connect in a folder called .vagrant. If you would like to create a new machine, vagrant destroy will remove the .vagrant folder and allow you to create a new VM (note: you may want to keep a copy in case you want to reconnect later).