BuffyBox is a suite of graphical applications for the terminal.
buffyboard – Touch-enabled on-screen keyboard for virtual terminals
unl0kr – Disk unlocking UI for the initramfs
f0rmz – A form/setup wizard for the initramfs
squeek2lvgl – Converter for transforming Squeekboard layouts into LVGL-compatible C code
iskey - A utility for checking for key presses in bash scripts.
shared – Internal code that is shared by some or all applications in the suite but not meant to be used externally
You can join our development chat at #buffybox:matrix.org.
Some dependencies are included as git submodules in this repository. You can clone the repository and initialise the submodules with
$ git clone https://gitlab.postmarketos.org/postmarketOS/buffybox.git
$ cd buffybox
$ git submodule init
$ git submodule update
When pulling changes from the remote later, either use git pull --recurse-submodules or manually run git submodule update as needed after pulling.
Once you have the sources, you can build the app and run it in a VT. Unless your user account has special privileges, sudo will be needed to access input device files.
$ meson setup _build
$ meson compile -C _build
$ sudo chvt 2
$ sudo ./_build/unl0kr/unl0kr # For Unl0kr
$ sudo ./_build/buffyboard/buffyboard # For Buffyboard
On distributions based on systemd, unl0kr can be used as a password agent, to give systemd the ability to ask passwords on touchscreen-only devices:
# systemctl stop systemd-ask-password-console.path
# systemctl stop systemd-ask-password-wall.path
# systemctl start unl0kr-agent.path
# systemd-ask-password --no-tty # Unl0kr is started
Note: SDL can be used as a display backend for development purposes by setting the Meson option lvgl_backends=sdl and using backend=sdl in the configuration file.
Other uses besides development are not supported by Buffybox.
Create a full package:
meson setup builddir/
meson compile -C builddir/
meson install -C builddir/ --destdir "$pkgdir"
Create separate packages for Buffyboard and Unl0kr:
meson setup builddir/
meson compile -C builddir/
meson install -C builddir/ --tags=unl0kr --destdir "$pkgdir_unl0kr"
meson install -C builddir/ --tags=buffyboard --destdir "$pkgdir_buffyboard"
Create a package for Unl0kr only:
meson setup builddir/
meson compile -C builddir/ unl0kr/unl0kr
meson compile -C builddir/ unl0kr/unl0kr-agent # on systemd-based distributions
meson install -C builddir/ --tags=unl0kr --destdir "$pkgdir"
Create a package for Buffyboard only:
meson setup builddir/
meson compile -C builddir/ buffyboard/buffyboard
meson install -C builddir/ --tags=buffyboard --destdir "$pkgdir"
To make it easier for distributions to package BuffyBox, we include source tarballs including the LVGL submodule in GitLab releases. See unl0kr#42 for more background on this.
Producing and uploading a source tarball requires git-archive-all to be installed as well as an access token for the GitLab API. To tag a release and upload a source tarball, run
./release.sh $VERSION $TOKEN
Once the upload completes, create a new release on GitLab and attach the URL of the uploaded source tarball.
This project is licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
For the license of bundled images and fonts, see shared/cursor and shared/fonts.