diff --git a/lubuntu-packaging-guide.rst b/lubuntu-packaging-guide.rst index 438962b..25affa8 100644 --- a/lubuntu-packaging-guide.rst +++ b/lubuntu-packaging-guide.rst @@ -374,3 +374,338 @@ The steps are, roughly: * Create a shared folder for working on packages on both the VM and host. * Install and configure packaging utilities. * Test the system by building sample source and binary packages. + +KVM preparation and VM installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The most common way to use KVM is through virt-manager, a GUI app that is +somewhat similar to VirtualBox. Under the hood, it uses libvirt, QEMU, and KVM +to run VMs. + +.. NOTE:: + KVM virtualization, much like the rest of Linux, has a lot of different + pieces that work together. QEMU emulates hardware and CPU instructions that + can't be run at full speed, KVM runs CPU instructions that can be run at + full speed, and libvirt makes it easier for applications to work with + QEMU/KVM virtual machines. virt-manager then provides a graphical user + interface for libvirt. + +Installation is fairly simple; open QTerminal and run:: + + sudo apt install virt-manager libvirt-clients libvirt-daemon virtiofsd + sudo systemctl enable libvirtd.service + sudo systemctl start libvirtd.service + +You should now be able to create virtual machines using virt-manager. + +.. NOTE:: + When talking about virtual and physical systems, the physical machine that + runs the VMs is typically called the "host", while the VMs themselves are + typically called "guests". + +The next thing to do is to download the latest pre-release image of Lubuntu. +Like mentioned above, it is important to use the latest possible version of +Ubuntu to prevent issues with package builds later. The latest ISO can be +found +``__. +It is generally a good idea to verify your ISO download using GnuPG and +sha256sum. To do this: + +1. Create a directory to store the ISO at. ``$HOME/ISO/Lubuntu`` is a good + location. +2. Download the ``CODENAME-desktop-amd64.iso``, ``SHA256SUMS``, and + ``SHA256SUMS.gpg`` files for Lubuntu, and move them to the newly created + directory. +3. Open QTerminal in the new directory, and import the PGP key used to sign + Ubuntu ISO images: + ``gpg --keyserver keyserver.ubuntu.com --recv-keys 843938DF228D22F7B3742BC0D94AA3F0EFE21092`` +4. Verify the SHA256SUMS file is unmodified using GnuPG: + ``gpg --keyid-format=long --verify SHA256SUMS.gpg SHA256SUMS``. This + command should show output that looks similar to this:: + + gpg: Signature made Tue 26 Aug 2025 12:14:14 PM CDT + gpg: using RSA key 843938DF228D22F7B3742BC0D94AA3F0EFE21092 + gpg: Good signature from "Ubuntu CD Image Automatic Signing Key (2012) " [unknown] + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: 8439 38DF 228D 22F7 B374 2BC0 D94A A3F0 EFE2 1092 + +5. Ensure you see the words "Good signature" in the output of GnuPG. If you + see "No public key" or "BAD signature", your download is corrupt. If you + see "Good signature", the SHA256SUMS file is authentic and intact. +6. Verify the ISO file is unmodified using sha256sum: + ``sha256sum -c SHA256SUMS``. This command should show output that looks + like ``resolute-desktop-amd64.iso: OK``. If you see this, your ISO download + is authentic and intact. + +Once you have a verified Lubuntu download, it's finally time we can create the +VM! To do this: + +1. Open the application menu, and launch "Virtual Machine Manager". +2. Wait until the "Connecting" notice near the top of the window disappears. +3. Click the "Create a new virtual machine" button (it's in the very top-left + corner of the window). +4. In the "Create a new virtual machine" window, under "Choose how you would + like to install the operating system", click "Local install media (ISO + image or CDROM), then click "Forward". +5. At the top-right corner of the window, under "Choose ISO or CDROM install + media", click "Browse...". +6. In the "Locate ISO media volume" window, click "Browse Local". +7. In the file selector, navigate to the directory containing the Lubuntu ISO, + then click the ISO file and click "Open". +8. Uncheck the "Automatically detect from the installation media / source" + checkbox. +9. In the "Choose the operating system you are installing" text box, type + "Ubuntu". +10. In the popup that papears, click "ubuntu 25.10 (ubuntu25.10)", then click + "Forward". +11. Set a reasonable amount of RAM and number of CPUs for your hardware. + Package builds usually don't require that much memory or CPU power, but + sometimes they can benefit from lots of memory and CPU power, so it's a + good idea to allocate at least 8192 MB RAM and 4 CPUs if possible. +12. Set a reasonable amount of disk space for the VM. Package builds can take + a lot of disk space, so allocating at least 64 GB is highly recommended + here. +13. Set the VM name to something descriptive (i.e. ``lubuntu-dev``), then + click "Finish". We'll refer to this VM as ``lubuntu-dev`` in the rest of + this document. + +The Lubuntu ISO should boot, and you can install it like you normally would. +For best performance, the ``ext4`` filesystem should be used. We won't cover +the Lubuntu installation process here, it's fairly straightforward. Once the +installed system boots up, you should check for updates and install them using +Lubuntu Update (or by running ``sudo apt update && sudo apt full-upgrade`` in +a terminal). + +Once all updates are installed, click the application menu inside +``lubuntu-dev``, then hover over "Leave" and click "Shutdown". When LXQt asks +if you want to switch off your computer, click "Yes". (It is important that +you shut down the VM using LXQt's GUI buttons, do NOT run ``shutdown now`` in +a terminal! Doing the first shutdown in this manner prevents an LXQt bug that +breaks several features of Lubuntu.) + +Shared folder setup +^^^^^^^^^^^^^^^^^^^ + +When doing Debian packaging, you will frequently have to modify packages on +both the host and guest systems. Rather than moving files between the guest +and the host all the time, it's easier to use a shared folder. This allows +both the guest and host to see and work on a set of files in the shared +directory. + +.. NOTE:: + KVM shared folders understand UNIX file permissions, so if a file is owned + by a particular UID on the host, it will appear as being owned by that same + UID in the guest. The default UID for the first user in Lubuntu is 1000. If + your user on the host system has UID 1000, things should work normally, but + if your UID on the host is something other than 1000, you will almost + certainly run into file ownership issues when trying to modify files in the + shared folder within the guest. If this happens, you should create a new + user in the guest with the same UID as your user account on the host, then + do your packaging work using that user account. + +.. WARNING:: + Do not share your entire home directory with the guest. This can expose + your PGP key to the guest, which is a security hazard. + +To add a shared folder to the VM: + +1. In the host OS, create a new directory to share between the host and the + guest. We'll assume the shared folder is at ``$HOME/vmshare``. +2. Create a file named ``test-marker.txt`` in ``$HOME/vmshare``. Well use this + to ensure that the shared folder actually works later. +3. Ensure the ``lubuntu-dev`` window is open but the VM itself is powered off. + (You should see the words "Guest is not running." in the middle of the + window.) +4. Click the "Show virtual hardware details" button (it's in the top toolbar, + and is the second button from the left). +5. In the left-hand sidebar, click "Memory", then check the "Enable shared + memory" checkbox and click "Apply"." +6. Underneath the left-hand sidebar, click "Add Hardware". +7. In the "Add New Virtual Hardware" window, in the left-hand sidebar, click + "Filesystem". +8. Ensure that the "Driver" is set to "virtiofs", then set the "Source path" + to ``/home/USERNAME/vmshare`` and the "Target path" to ``vmshare``. + (Replace ``USERNAME`` with your username on the host system.) +9. Click "Finish" to add the shared folder to the VM. + +Next, to set up the VM to automatically mount this shared folder on startup: + +1. Ensure the ``lubuntu-dev`` window is open, then click the "Power on the + virtual machine" button (it's in the top toolbar, looks like a play button, + and is the third button from the left). +2. Log in if necessary. +3. In the guest, open QTerminal, and run the following commands, replacing + ``USERNAME`` with the guest's account's username. This will create a + systemd unit for mounting the shared folder, enable it so it starts on + bootup, and then start it so that the shared folder immediately starts + working:: + + mkdir $HOME/vmshare + cat <<'EOF' | sudo tee /etc/systemd/system/mount-vmshare.service + [Unit] + Description=Mount shared folder on startup + + [Service] + Type=oneshot + RemainAfterExit=true + ExecStart=mount -t virtiofs vmshare /home/USERNAME/vmshare + + [Install] + WantedBy=multi-user.target + EOF + sudo systemctl enable mount-vmshare.service + sudo systemctl start mount-vmshare.service + +4. The shared folder should be immediately mounted. In the guest, run + ``ls $HOME/vmshare``, and verify that you can see the file + ``test-marker.txt`` in the directory. +5. In the guest, run ``touch $HOME/vmshare/test-marker-guest.txt``. +6. On the host, run ``ls $HOME/vmshare``, and verify that you can see the + ``test-marker-guest.txt`` file. + +If both test files can be seen on both the guest and the host, the shared +folder is working. With that out of the way, we can get to the fun part; +installing tools for Debian packaging! + +Installing and configuring packaging utilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Like mentioned earlier, we're going to be using ``sbuild`` as our primary +packaging tool. We'll go into a bit of detail about what all ``sbuild`` does +and how later. For now, we're just going to get it and the rest of the Debian +packaging tools installed and ready to work. + +1. Ensure the ``lubuntu-dev`` window is open and the VM is running. +2. In the guest, open QTerminal, and run the following commands to install + ``sbuild`` and several other packaging utilities:: + + sudo apt install ubuntu-dev-tools debhelper devscripts mmdebstrap git sbuild + +3. In the guest, configure ``sbuild``. The following configuration is + relatively basic, works for almost everything, and integrates automatic + package caching. Replace ``Your Name`` and ``name@example.com`` as + appropriate. Do NOT remove the ``1;`` at the end of this config, or it will + break ``sbuild``. To create the config file:: + + mkdir -p $HOME/.config/sbuild + cat <<'EOF' > $HOME/.config/sbuild/config.pl + $maintainer_name = 'Your Name '; + $distribution = "resolute"; + $build_arch_all = 1; + $purge_build_directory = "successful"; + $purge_session = "successful"; + $purge_build_deps = "successful"; + $log_dir = $ENV{HOME}."/ubuntu/logs"; + $chroot_mode = "unshare"; + $unshare_mmdebstrap_keep_tarball = 1; + $unshare_mmdebstrap_extra_args = [ + "*" => [ "--include=debhelper,auto-apt-proxy,ca-certificates" ], + "resolute" => [ "--include=debhelper,auto-apt-proxy,ca-certificates", "--components=main,universe,restricted,multiverse" ], + "questing" => [ "--include=debhelper,auto-apt-proxy,ca-certificates", "--components=main,universe,restricted,multiverse" ], + "plucky" => [ "--include=debhelper,auto-apt-proxy,ca-certificates", "--components=main,universe,restricted,multiverse" ], + "noble" => [ "--include=debhelper,auto-apt-proxy,ca-certificates", "--components=main,universe,restricted,multiverse" ], + ]; + $lintian_opts = [ '-E', '-v', '-I', '-L', '+pedantic' ]; + $clean_source = 0; + 1; + EOF + +4. In the guest, configure ``quilt``. We'll explain more about what this tool + is and what it does later:: + + cat <<'EOF' > $HOME/.quiltrc + for where in ./ ../ ../../ ../../../ ../../../../ ../../../../../; do + if [ -e ${where}debian/rules -a -d ${where}debian/patches ]; then + export QUILT_PATCHES=debian/patches + break + fi + done + QUILT_PUSH_ARGS="--color=auto" + QUILT_DIFF_ARGS="--no-timestamps --no-index -p ab --color=auto" + QUILT_REFRESH_ARGS="--no-timestamps --no-index -p ab" + QUILT_DIFF_OPTS='-p' + EOF + +5. In the guest, configure ``git``. You may already know what this tool does, + but we'll explain more about it later. Replace ``Your Name`` and + ``name@example.com`` as appropriate:: + + git config --global user.name 'Your Name' + git config --global user.email 'name@example.com' + +6. In the guest, configure ``dch``. We'll explain more about what this tool is + and what it does later. Replace ``Your Name`` and ``name@example.com`` as + appropriate:: + + cat <<'EOF' >> $HOME/.bashrc + export EMAIL='name@example.com' + export DEBEMAIL='name@example.com' + export DEBFULLNAME='Your Name' + EOF + +7. In the guest, run ``source $HOME/.bashrc`` so the new settings you've + created for ``dch`` take effect in the currently running shell. +8. On the host, run the following commands to install some necessary packaging + tools there as well:: + + sudo apt install debhelper devscripts + +There's a lot going on here, most of which won't make sense right now. We'll +go into detail about what all these options do later on in this guide. + +At this point, your packaging environment is configured and ready to use. It's +time for the last step of setup; building a test package! + +Testing the packaging environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To make sure everything's working smoothly, we're going to use ``sbuild`` to +build binary packages for ``lxqt-about``, the same package we showed an +overview of at the beginning of this document. ``lxqt-about``'s packaging is +stored in the Lubuntu Git instance, so we're going to download the packaging +from there and build it. + +1. Ensure the ``lubuntu-dev`` window is open and the VM is running. +2. In the guest, open QTerminal, and create a directory at + ``$HOME/vmshare/pkg`` to do packaging in. Then change to the directory:: + + mkdir $HOME/vmshare/pkg + cd $HOME/vmshare/pkg + +3. In the guest, download the Debian packaging for the ``lxqt-about`` package + from Lubuntu Git:: + + git clone https://git.lubuntu.me/Lubuntu/lxqt-about-packaging.git + +4. In the guest, change to the new ``lxqt-about-packaging`` directory with + ``cd lxqt-about-packaging``. +5. In the guest, run ``ls``, and ensure you see a single directory named + ``debian``. + +.. NOTE:: + If you remember the overview of ``lxqt-about`` from the start of this + document, you might be confused here, since you only see a ``debian`` + directory, not a full package. This is normal; Lubuntu does not duplicate + upstream source code in our packaging, since it's a waste of space and + isn't needed for package builds to still work. + +6. In the guest, download the source code for ``lxqt-about`` by running + ``uscan --download-current-version``. ``uscan`` is a packaging tool used + to download source code for packaged applications. + +.. NOTE:: + Due to a + `bug `__, + this might not work for all packages yet. + +7. In the guest, build the package with the following command:: + + sbuild -d resolute + +8. In the guest, run ``ls ..``. If all went well, you should see an + ``lxqt-about`` deb file, alongside several other files. + +That's it! If the above worked, you now have a working packaging environment! +We're now ready to move past system setup, and start learning how packaging +works.