mkosi

LilyDev -- mkosi

Full virtual machine

Runs on: any OS with a Virtual Machine software.

Download the latest release. The image built for being emulated on VM software has a -vm suffix.

You must first decompress the zip archive. Then you can verify the integrity of the data running this command in the directory where you've extracted the files:

sha256sum -c SHA256SUMS

The image is a raw disk image format, which can be converted to the specific format used by the software you want to use.

VirtualBox

If you are running Windows or Mac in the host, you'll want to use VirtualBox, which requires VDI images. You can generate it with this command:

VBoxManage convertfromraw LilyDev-VERSION-debian-vm.img LilyDev-VERSION-debian-vm.vdi

Please follow all the steps described in the LilyPond Contributor guide to install and configure the VirtualBox machine. In particular, remember that you need to enable EFI or the image won't boot. With the current legacy version of VirtualBox guest additions from stretch-backports, only the VBoxVGA graphics driver will allow to dynamically resize the host window.

QEMU/libvirt

If your host is running Linux, you can use QEMU. It works well with either the raw image or its own format (qcow2), which you can generate it with:

qemu-img convert -f raw -O qcow2 \
LilyDev-VERSION-debian-vm.img LilyDev-VERSION-debian-vm.qcow2

Raw images give optimal performance, but only basic features are available (for example, no snapshots). qcow2 is the QEMU image format and has a number of features including snapshots. In the rest of this section we'll assume you converted it to qcow2.

Move the image to the usual location for libvirt images:

mv LilyDev-VERSION-debian-vm.qcow2 ~/.local/share/libvirt/images/

Now you can register the virtual machine in libvirt or, in libvirt terms, define a domain:

virt-install --name LilyDev-VERSION-debian-vm \
--memory 1024 --os-type=linux --os-variant=debian9 \
--boot loader=/usr/share/edk2/ovmf/OVMF_CODE.fd --network=default \
--disk ~/.local/share/libvirt/images/LilyDev-VERSION-debian-vm.qcow2 \
--noautoconsole --import

(available OS variants are listed by the command osinfo-query os)

512M of RAM should be enough, as the image contains also a swap partition of 2G. If you can assign 1024M, even better. In case you see some weird error while compiling lilypond, your guest might be running out of memory (check the RAM available with the command free -m) and you should try assigning more RAM to the virtual machine.

Now the virtual machine will be available on all libvirt clients, such as virt-manager or GNOME Boxes. If you still want to launch it from command-line, use these commands:

virsh start LilyDev-VERSION-debian-vm
virt-viewer --connect qemu:///session LilyDev-VERSION-debian-vm

You'll log in as dev user (the password is lilypond).

Desktop preferences suggestions:

• Change keybord layout from default US (american) to your national layout in Applications»Settings»Keyboard»Layout: add your layout and then move it up to the list so it will be the default.

Container

Runs on: Linux only. Requirements: systemd-nspawn, available in systemd-container package.

It's the best choice if you want to run LilyDev in a Linux host: lightweight, full access to host system resource (including RAM), easy access from host to guest file system through the file manager (so no need to set up shared folders).

Download the latest release. You can choose your favorite Linux distribution: current options are Debian and Fedora, but others may be added.

You need root privileges to extract the content, so you'd better do it on the command line:

sudo tar xf LilyDev-VERSION-DISTRO.tar.xz

Start the container:

sudo systemd-nspawn -bD LilyDev-VERSION-DISTRO

and log in as dev user (the password is lilypond). Launch the setup.sh script:

./setup.sh

You are now ready to start contributing to LilyPond.

When you've done, you can shutdown the machine:

sudo shutdown -h now

There's a good chance that your user in the Linux host and the dev user in the container have the same uid (probably 1000, use the command id to find it out). If that's the case, you can easily access and edit the files in the container from your host as you wish, using a file manager or your favorite GUI text editor. In case the id is different, read this tutorial on changing UID and GID.

Running graphical applications from the container

You might need to run one or more graphical applications from the container, for example gitk or lily-git. This should work out of the box, if two requirements are met:

1. The id of the guest user must the same as the id of the host user. Usually it is the same; if it's not, see above link.
2. Another requirement is that the DISPLAY variable must be set to the same value of the DISPLAY value in the host. We assumed that the value is :0. If it's not, run echo $DISPLAY in the host and change accordingly the DISPLAY variable in ~/.bashrc in the guest.

The containers does not include a browser, which is needed to log in to Rietveld while uploading the patch via git-cl. Unfortunately I could not find any text browser which worked with git-cl. As installing a graphical browser would add several dependencies and I want to keep the containers as small as possible, the best solution is launching git-cl from the host. Otherwise you may install a browser in the container, e.g.:

sudo dnf install firefox           # Fedora
sudo aptitude install firefox-esr  # Debian