Void Package Contribution

Documentation

Prerequisite

I’m submitting a patch I made for buku (cli bookmark manager), so the most important docs are Committing your changes and Handling patches.

The former has plenty of examples about the naming scheme, for me, it should be buku: fix deprecation warning for python3>=3.11. The latter tells me the necessary knowledge for handling patches, as the name suggests.

I also checked Building from source info on Reddit as I’ve never contributed to Void-packages so far.

The Patch

Just taken from my PR for buku and made a few adjustments:

adapted from https://github.com/jarun/buku/pull/605
--- a/buku
+++ b/buku
@@ -19,10 +19,10 @@
 
 import argparse
 import calendar
-import cgi
 import codecs
 import collections
 import contextlib
+import email.message
 import json
 import locale
 import logging
@@ -3811,15 +3811,17 @@
         if soup.meta and soup.meta.get('charset') is not None:
             charset = soup.meta.get('charset')
         elif 'content-type' in resp.headers:
-            _, params = cgi.parse_header(resp.headers['content-type'])
-            if params.get('charset') is not None:
-                charset = params.get('charset')
+            m = email.message.Message()
+            m['content-type'] = resp.headers['content-type']
+            if m.get_param('charset') is not None:
+                charset = m.get_param('charset')
 
         if not charset and soup:
             meta_tag = soup.find('meta', attrs={'http-equiv': 'Content-Type'})
             if meta_tag:
-                _, params = cgi.parse_header(meta_tag.attrs['content'])
-                charset = params.get('charset', charset)
+                m = email.message.Message()
+                m['content'] = meta_tag.attrs['content']
+                charset = m.get_param('charset', charset)
 
         if charset:
             LOGDBG('charset: %s', charset)

Patching for buku

# Install xtools
sudo xbps-install xtools

# Bootstrap
git clone --depth=1 https://github.com/Vinfall/void-packages
cd void-packages
./xbps-src binary-bootstrap

# Make necessary patching
cd srcpkgs/buku
#patching files...
# Check the template works
xlint template
cd -

# Build test
./xbps-src pkg buku
xi -f buku-4.7_2
# Try cross-build as well
./xbps-src -a armv6l pkg buku

Ok, so everything looks good, and buku no longer shows the annoying warning any more.

💬 Quote

Just make a PR and spread the patch!

Ops, actually I need to change revision from 1 to 2, before it can get merged.

Update: Dumb as I was, I kept missing the suggestion and got notified only after 2 weeks… It would finally ship in the next build of srcpkgs.

Workflow

Above is the first time I made a PR to void-packages, and I did not know about many useful utils provided by xtools. This is my current update workflow.

A companion script (focusing on finding updates) is available on my gist instance.

💡 Note on cross-build

According to Building packages natively for the musl C library, you can build packages natively for musl libc using -A param.

Do NOT confuse this with -a param, which cross compile packages instead.

Init

# Install xtools
sudo xbps-install xtools

# Clone repo
git clone --depth=100 git@github.com:Vinfall/void-packages.git
cd void-packages

💡 Tip

For long term packaging (contrary to one-off PR), you’d probably better customize the config before bootstrap, as it will only take effect once you zap & recreate it. In such case, check #Cache before bootstrap!

# Bootstrap
./xbps-src binary-bootstrap
# N.B.: -A (native), not -a (cross)
./xbps-src -A x86_64-musl binary-bootstrap

# Init
git remote add upstream https://github.com/void-linux/void-packages.git
git config --local user.name "Vinfall"
git config --local user.email "a real email as Void does not allow anonymous contribution and xlint would err anyway"
git config --local user.signingkey ""

Update

cd $XBPS_DISTDIR

# Update masterdir & clean obsolete cache
./xbps-src bootstrap-update
./xbps-src clean-repocache

# Update void-packages
git pull --rebase upstream master

# Init
PKG_CHK=firefox-esr

# Check update
./xbps-src update-check ${PKG_CHK}
# Generate new sum
cd srcpkgs/${PKG_CHK}
# Change version
vim template
xgensum -f -i ${PKG_CHK}
# Try again if failed
xgensum -i ${PKG_CHK}
# Check the template works
xlint template
cd ../..

# Build and test
./xbps-src pkg ${PKG_CHK}
./xbps-src check ${PKG_CHK}
# sudo xbps-install --repository=hostdir/binpkgs/${PKG_CHK}-update -f ${PKG_CHK}
xi ${PKG_CHK}

# Try cross-build (-a)  or native (-A) as well
PKG_ARCH=x86_64-musl
# PKG_ARCH=aarch64-musl
# PKG_ARCH=armv7l
./xbps-src -A ${PKG_ARCH} bootstrap-update
./xbps-src -A ${PKG_ARCH} clean-repocache
./xbps-src -A ${PKG_ARCH} pkg ${PKG_CHK}
./xbps-src -A ${PKG_ARCH} check ${PKG_CHK}

# Privacy tweak
echo "Uncheck 'Block command line pushes that expose my email' in GitHub settings!"
# Push changes
xbump ${PKG_CHK}
# Create new branch
git branch ${PKG_CHK}-update
git checkout ${PKG_CHK}-update
git push

# In case I need update later
git checkout
PKG_CHK=$(git branch --show-current | sed 's/-[^-]*$//')
./xbps-src pkg ${PKG_CHK}

# Sign package in every branch for custom repo
xbps-rindex --sign-pkg --privkey privkey.pem $PWD/hostdir/binpkgs/*/*.xbps

# Clean up cache, and binpkgs (aka .xbps) would be kept for good
./xbps-src clean

Submit PR

Well, it’s easy to submit PR via github-cli so I don’t even need GUI.

# Only needed once
cd $XBPS_DISTDIR
gh repo set-default https://github.com/void-linux/void-packages

# PR workflow
git checkout ${PKG_CHK}-update
gh pr create
# edit body in editor value set in $XDG_CONFIG_HOME/gh/config.yaml
e
#### Testing the changes
- I tested the changes in this PR: **YES**

#### Local build testing
- I built this PR locally for my native architecture, x86_64-glibc

Test PR

Test PRs that I’m in need of but have not been merged, extracted from CONTRIBUTING:

# Add remote
git remote add upstream https://github.com/void-linux/void-packages.git

# Checkout PR
# format:
# git fetch upstream pull/<number>/head:<branch-name>
# git checkout <branch-name>
git fetch upstream pull/51146/head:dolphin-emu
git checkout dolphin-emu

# Rebase and update to latest
git pull --rebase upstream master
./xbps-src bootstrap-update
./xbps-src clean-repocache
# Same as update from now on
PKG_CHK=dolphin-emu
./xbps-src pkg ${PKG_CHK}
xi -f ${PKG_CHK}

If the PR is too far from HEAD, it would fetch too many unnecessary commits, in such case, simply fetch & apply the patch (replacing Checkout PR section above):

PR_NUM=46691

wget https://patch-diff.githubusercontent.com/raw/void-linux/void-packages/pull/${PR_NUM}.patch

# apply the patch
git apply ${PR_NUM}.patch
# alternatively, git am if you are sure there is no conflict
git am ${PR_NUM}.patch

That’s it. But this is only this simple if things do not conflict, that’s why fetching remote is recommeded over this: you can deal with the rebase later.

Cache

cd $XBPS_DISTDIR

# NOT /etc, this is a sub-directory of void-packages
cp etc/defaults.conf etc/conf
vim etc/conf

Customize with your preference, I highly recommend enable ccache to speed up compilation. (unmerged) PR#41617 is also useful for sccache support for Cargo builds (aka. Rust codes).

# etc/conf
XBPS_MAKEJOBS=4
XBPS_CCACHE=yes
XBPS_CHECK_PKGS=yes

# only enable with PR#41617 applied
XBPS_SCCACHE=yes

My ccache config to raise hit rate (at the cost of possible mismatches):

# ~/.config/ccache/ccache.conf
# Manual: https://ccache.dev/manual/latest.html#_configuration_options
max_size = 3.0G
# locale & time_macros from Arch Wiki
# https://wiki.archlinux.org/title/Ccache#Sloppiness
# include_file_ctime for R CMD INSTALL *.tar.gz
#   as tarballs are expanded freshly -> fresh ctime
sloppiness = include_file_ctime,locale,time_macros
# (temp) directory name will differ, cause unwanted miss
hash_dir = false

Bootstrap again if you have it previously, or after compiler update (which invalidates most caches):

# bootstrap again to make sure etc/conf is used
./xbps-src zap
./xbps-src binary-bootstrap

# after compiler update (gcc/clang), clean & zap invalid cache
ccache -C -d hostdir/ccache
ccache -z -d hostdir/ccache

Get cache statistics:

# ccache, much cleaner
$ ccache -s -d hostdir/ccache
Cacheable calls:    14457 / 16344 (88.45%)
  Hits:              5875 / 14457 (40.64%)
    Direct:          5866 /  5875 (99.85%)
    Preprocessed:       9 /  5875 ( 0.15%)
  Misses:            8582 / 14457 (59.36%)
Uncacheable calls:   1883 / 16344 (11.52%)
Errors:                 4 / 16344 ( 0.02%)
Local storage:
  Cache size (GiB):   1.3 /   5.0 (26.70%)
  Hits:              5875 / 14457 (40.64%)
  Misses:            8582 / 14457 (59.36%)

# sccache, dirty
$ sccache -s
Compile requests                   1534
Compile requests executed          1266
Cache hits                          627
Cache hits (C/C++)                  194
Cache hits (Rust)                   433
Cache misses                        627
Cache misses (C/C++)                194
Cache misses (Rust)                 433
Cache timeouts                        0
Cache read errors                     0
Forced recaches                       0
Cache write errors                    0
Compilation failures                 12
Cache errors                          0
Non-cacheable compilations            0
Non-cacheable calls                 252
Non-compilation calls                16
Unsupported compiler calls            0
Average cache write               0.000 s
Average compiler                  0.590 s
Average cache read hit            0.000 s
Failed distributed compilations       0

Non-cacheable reasons:
crate-type                          140
unknown source language              52
-                                    32
missing output_dir                   12
missing input                        10
multiple input files                  4
incremental                           2

Cache location                  Local disk: "/host/sccache"
Use direct/preprocessor mode?   yes
Version (client)                0.8.1
Cache size                          290 MiB
Max cache size                       10 GiB

Custom Repo

Quick Install

Host OS:

cd $XBPS_DISTDIR
# before proceeding, merge everything into offline-builds
rsync -avz --delete "hostdir/binpkgs/offline-builds/" void:~/downloads/

Quest OS:

cd ~/downloads
xbps-rindex -a *.xbps
xi --repository=$(pwd) pkgname

Vinfall's Geekademy

Sine īrā et studiō