This is a collection of tutorials describing the xbps-src package build system
of Void Linux. It is made using mdBook.
This book requires mdBook,
mdbook-toc and
mdbook-admonish.
You can use
sudo xbps-install mdBook mdbook-toc
to install the dependencies on Void Linux. Note that mdbook-admonish isn't
currently packaged on Void Linux. You can download its executable in
https://github.com/tommilligan/mdbook-admonish/releases/latest. You'll have to
extract the appropriate archive and put the executable into a directory in
$PATH.
This book also makes use of
mdbook-catppuccin, but it is managed
internally, it doesn't need to be installed. Support for catppuccin themes can
be turned off with ./book.sh -e false.
Alternatively, nix can be used to automatically
(and reproducibly) download dependencies. This can be done with nix-book.sh,
which is a wrapper around book.sh (described below); it behaves the same,
and it accepts the same arguments.
nix-book.sh is used in the GitHub workflow which builds the website.
You mustn't build this book with raw mdbook. This repo provides a book.sh
script which handles book building. See book.sh -h for more info about the
script.
You can build this book with
./book.sh build
Releases of this tutorial are available for offline reading. They include a prebuilt book.
If you want the zipfile of the latest website deployment, go to
https://github.com/xbps-src-tutorials/xbps-src-tutorials.github.io/actions,
select the top workflow run, click on the build job and click on the Upload artifact action. It should contain a link to a zipfile at the bottom of it.
This is the original URL the website was hosted on. It has been replaced by xbps-src-tutorials.github.io. The old URL is still functional, but it redirects to the correct website now. If you want to know more, you can look at the old repo: https://github.com/meator/xbps-src-tutorials
No. https://xbps-src-tutorials.github.io/ should be the final URL for xbps-src tutorials.
There is none! I will make a release whenever I feel like it or whenever I'll be asked to do so.
Why did you choose a program with half broken build system which doesn't even build without patches as your first example usage of xbps-src?
I believe it is useful to showcase xbps-src's capabilities on a real-world
example. It lets me showcase a variety of features of xbps-src that aren't
commonly used in "normal" templates (but are still needed from time to time).
I, meator, also happen to be a co-maintainer of j4-dmenu-desktop. I am familiar with its build system, which enables me to create a comprehensive tutorial on the subject.
j4-dmenu-desktop is also in my opinion a really cool program, so I wanted to spread the word a bit. But I chose it mainly for practical reasons.
The "naïve" approach of simply copying the build instructions one would normally use when building the program to the template is pretty relatable. This is how packaging systems with less abstraction like the AUR do it (but don't quote me on that, I don't have much experience with the AUR).
By showing how to package programs wrong, I can showcase why are the "correct" approaches better and what advantages do they have.
mdBook is already used in void-docs, so Void Linux users are likely to be familiar with it. It has all the features one would expect: it has nice theming support (not just white/black theme), themes can be changed explicitly (it doesn't depend solely on prefers-color-scheme), it has a simple interface for both readers and developers of the book and it renders well on phones.
It also has print support, but that isn't a priority.
mdBook isn't really designed for long winded articles. It has lack of support
for table of contents inside a single page. This is partly fixed by
mdbook-toc, but the reader has to go to the beginning of the page to access
the TOC. A collapsible sidebar with TOC for example would be nicer.
mdBook doesn't support copying blocks which use tabs for indentation. Tabs are converted to spaces even when it's indented by tabs in markdown.
mdBook simplicity can be a double-edged sword. It lacks nice to have features like trimming the last newline when copying a code block using the button or differentiating external links.
These things could probably be implemented by modifying the mdBook theme and writing some custom Javascript. I don't have much experience with that, but contributions are welcome!
The tutorial is written pretty much in pure Markdown. The exceptions are the
usage of admonish (which shouldn't be difficult to replace) and the mdBook's
{{#include}} mechanism.
If some other system would provide better features, porting this tutorial to it shouldn't be that difficult.
None of the sitemap generators I know about meet this book's needs.
Because of this, I edit it by hand. The appropriate <changefreq> should be
changed when a page is updated. Appropriate <url> tags should be added or
removed when pages are added or removed.
I retrieve <changefreq> by running
git log -n 1 --pretty=format:%cI <file>
This isn't 100% accurate, but it should be close enough.
The following error
[2024-03-04T22:54:06Z ERROR mdbook_admonish] Fatal error: ERROR:
Incompatible assets installed: required mdbook-admonish assets version '^3.0.0', but did not find a version.
Please run `mdbook-admonish install` to update installed assets.
For more information, see: https://github.com/tommilligan/mdbook-admonish#semantic-versioning
[2024-03-04T22:54:06Z ERROR mdbook_admonish] - ERROR:
Incompatible assets installed: required mdbook-admonish assets version '^3.0.0', but did not find a version.
Please run `mdbook-admonish install` to update installed assets.
For more information, see: https://github.com/tommilligan/mdbook-admonish#semantic-versioning
2024-03-04 23:54:06 [ERROR] (mdbook::utils): Error: The "admonish" preprocessor exited unsuccessfully with exit status: 1 status
is caused by not using book.sh.