Lubuntu/lubuntu-packaging-guide
4
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finish packaging environment setup sections

Browse Source
This commit is contained in:
Aaron Rainbolt 2025-11-17 18:01:40 -06:00
parent 04b8744750
commit 3465376d9a
Signed by: arraybolt3
GPG Key ID: A709160D73C79109
1 changed files with 335 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

335
lubuntu-packaging-guide.rst
View File

@ -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
`<on cdimage.ubuntu.com https://cdimage.ubuntu.com/lubuntu/daily-live/pending/>`__.
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) <cdimage@ubuntu.com>" [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 <name@example.com>';
$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 <https://bugs.launchpad.net/ubuntu/+source/devscripts/+bug/2122486>`__,
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.