Add Buffyboard Man pages and Unify Build

.gitlab-ci.yml

@@ -1,15 +1,4 @@
-build-and-test-buffyboard:
-  image: alpine:3.19
-  tags:
-    - saas-linux-small-amd64
-  script:
-    - apk -q add git bash build-base meson linux-headers inih-dev libinput-dev eudev-dev
-    - git submodule init
-    - git submodule update
-    - cd buffyboard
-    - ./test/test-all.sh
-
-build-and-test-unl0kr-with-drm:
+build-and-test-with-drm:
   image: alpine:3.19
   tags:
     - saas-linux-small-amd64
@@ -17,10 +6,9 @@ build-and-test-unl0kr-with-drm:
     - apk -q add git bash build-base meson linux-headers inih-dev libinput-dev libxkbcommon-dev libdrm-dev scdoc
     - git submodule init
     - git submodule update
-    - cd unl0kr
     - ./test/test-with-drm.sh
 
-build-and-test-unl0kr-without-drm:
+build-and-test-without-drm:
   image: alpine:3.19
   tags:
     - saas-linux-small-amd64
@@ -28,7 +16,6 @@ build-and-test-unl0kr-without-drm:
     - apk -q add git bash build-base meson linux-headers inih-dev libinput-dev libxkbcommon-dev scdoc
     - git submodule init
     - git submodule update
-    - cd unl0kr
     - ./test/test-without-drm.sh
 
 build-iskey:

README.md

@@ -22,6 +22,31 @@ BuffyBox is a suite of graphical applications for the terminal.
 
 You can join our development chat at [#buffybox:matrix.org].
 
+## Building & running
+
+Some of unl0kr's dependencies are included as git submodules in this repository. You can clone the repository and initialise the submodules with
+
+```
+$ git clone https://gitlab.com/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
+```
+
+With meson <0\.55 use `ninja` instead of `meson compile`\.
+
 ## Making a release
 
 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.

buffyboard/README.md

@@ -77,30 +77,6 @@ For an example configuration file, see [buffyboard.conf].
 - evdev kernel module
 - uinput kernel module
 
-## Building & running
-
-Some of buffyboard's dependencies are included as git submodules in this repository. You can clone the repository and initialise the submodules with
-
-```
-$ git clone https://gitlab.com/cherrypicker/buffyboard.git
-$ cd buffyboard
-$ 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 _build
-$ meson compile -C _build
-$ sudo chvt 2
-$ sudo ./_build/buffyboard
-```
-
-With meson <0.55 use `ninja` instead of `meson compile`.
-
 ## Keyboard layouts
 
 Buffyboard uses [squeekboard layouts] converted to C via [squeek2lvgl]. To regenerate the layouts, ensure that you have pipenv installed (e.g. via `pip install --user pipenv`) and then run
@@ -114,10 +90,10 @@ $ ./regenerate-layouts.sh
 To generate screenshots in a variety of common sizes, install [fbcat], build buffyboard and then run
 
 ```
-$ sudo ./regenerate-screenshots _build/buffyboard
+$ sudo ./regenerate-screenshots ../_build/unl0kr/buffyboard
 ```
 
-where `_build/buffyboard` is the location of the buffyboard binary.
+where `../_build/unl0kr/buffyboard` is the location of the buffyboard binary.
 
 # Acknowledgements
 

buffyboard/doc/buffyboard.1.scd

@@ -0,0 +1,63 @@
+buffyboard(1) "buffyboard"
+
+# NAME
+
+BUFFYBOARD - Touch-enabled framebuffer keyboard (not only) for vampire slayers.
+
+# SYNOPSIS
+
+buffyboard [OPTION]
+
+# DESCRIPTION
+
+Buffyboard is a touch-enabled on-screen keyboard running on the Linux
+framebuffer. It's primarily intended for vampire hunting but you can
+also use it as a general purpose keyboard.
+
+Buffyboard uses LVGL for input processing and rendering. Key events are
+forwarded directly to the kernel via a uinput device. Since the latter
+emulates a hardware keyboard, the terminal keymap must match with
+buffyboard's layout or else on-screen keys might not produce the correct
+result.
+
+# OPTIONS
+
+## Optional
+
+*-C, --config-override*
+	Path to a config override file. Can be supplied multiple times. Config
+	files are merged in the following order:
+		- /etc/buffyboard.conf
+		- /etc/buffyboard.conf.d/\* (alphabetically)
+		- Override files (in supplied order)
+*-g, --geometry=NxM[@X,Y]*
+	Force a display size of N horizontal times M vertical pixels, offset
+	horizontally by X pixels and vertically by Y pixels.
+*-d  --dpi=N*
+	Override the display's DPI value.
+*-r, --rotate=[0-3]*
+	Rotate the UI to the given orientation. The
+	values match the ones provided by the kernel in
+	/sys/class/graphics/fbcon/rotate.
+	* 0 - normal orientation (0 degree)
+	* 1 - clockwise orientation (90 degrees)
+	* 2 - upside down orientation (180 degrees)
+	* 3 - counterclockwise orientation (270 degrees)
+*-h, --help*
+	Print this message and exit.
+*-v, --verbose*
+	Enable more detailed logging output on STDERR.
+*-V, --version*
+	Print the unl0kr version and exit.
+
+# EXAMPLES
+
+*Execute Buffyboard using the default config*
+	buffyboard
+
+# SEE ALSO
+	*buffyboard.conf*(5)
+
+# AUTHORS
+
+*Undef* <debian@undef.tools>

buffyboard/doc/buffyboard.conf.5.scd

@@ -0,0 +1,53 @@
+buffyboard(5) "buffyboard"
+
+# NAME
+
+BUFFYBOARD - configuration file
+
+# DESCRIPTION
+
+BUFFYBOARD expects a configuration file with options in the following format, with
+one option/value pair per line:
+
+```
+[section]
+<option>=<value>
+```
+
+The default configuration file is at /etc/buffyboard.conf, BUFFYBOARD will use this
+configuration file if present along with overrides placed in
+/etc/buffyboard.conf.d/ and those specified with the -C option. All config files
+will be merged in the following order:
+	- /etc/buffyboard.conf
+	- /etc/buffyboard.conf.d/ (alphabetically)
+	- Override files (in supplied order)
+
+# OPTIONS
+
+## Theme
+*default* = <adwaita-light|adwaita-dark|breezy-light|breezy-dark|nord-light|nord-dark|pmos-light|pmos-dark>
+	Selects the default theme on boot. Can be changed at runtime to the
+	alternative theme. Default: breezy-dark.
+
+## Input
+*pointer* = <true|false>
+	Enable or disable the use of a hardware mouse or other pointing device.
+	Default: true.
+
+*touchscreen* = <true|false>
+	Enable or disable the use of the touchscreen.
+	Default: true.
+
+## Quirks
+*fbdev_force_refresh* = <true|false>
+	If true and using the framebuffer backend, this triggers a display refresh
+	after every draw operation. This has a negative performance impact.
+	Default: false.
+
+# SEE ALSO
+	*buffyboard*(1)
+
+# AUTHORS
+
+*Undef* <debian@undef.tools>
+*Johannes Marbach* <n0-0ne@mailbox.org>

buffyboard/meson.build

@@ -2,16 +2,6 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 
-project(
-  'buffyboard',
-  'c',
-  version: '3.2.0',
-  default_options: 'warning_level=1',
-  meson_version: '>=0.53.0'
-)
-
-add_project_arguments('-DBB_VERSION="@0@"'.format(meson.project_version()), language: ['c'])
-
 buffyboard_sources = [
   'command_line.c',
   'config.c',
@@ -35,6 +25,11 @@ squeek2lvgl_sources = [
   '../squeek2lvgl/sq2lv.c',
 ]
 
+man_files = [
+	'doc/buffyboard.1',
+	'doc/buffyboard.conf.5',
+]
+
 lvgl_sources = run_command('../find-lvgl-sources.sh', '../lvgl', check: true).stdout().strip().split('\n')
 
 executable(
@@ -49,3 +44,23 @@ executable(
   ],
   install: true
 )
+
+scdoc = dependency('scdoc')
+scdoc_prog = find_program(scdoc.get_pkgconfig_variable('scdoc'), native : true)
+sh = find_program('sh', native : true)
+foreach file : man_files
+	filename = file + '.scd'
+	section = file.split('.')[-1]
+	topic = file.split('.' + section)[-2].split('/')[-1]
+	output = '@0@.@1@'.format(topic, section)
+
+	custom_target(
+		output,
+		input : filename,
+		output : output,
+		capture : true,
+		command : [sh, '-c', scdoc_prog.path() + ' < @INPUT@'],
+		install : true,
+		install_dir : get_option('mandir') / 'man' + section
+	)
+endforeach

buffyboard/test/build.sh

@@ -1,5 +0,0 @@
-#!/bin/bash
-
-rm -rf _build
-meson _build
-meson compile -C _build

buffyboard/test/helpers.sh

@@ -1,25 +0,0 @@
-#!/bin/bash
-
-source "$(dirname "${BASH_SOURCE[0]}")/../../test/helpers.sh"
-
-function run_buffyboard_async() {
-    local log=$1
-    local conf=$2
-
-    ./_build/buffyboard -v -C "$conf" > "$log" 2>&1 &
-    pid=$!
-    sleep 3
-
-    kill -9 $pid
-    wait $pid > /dev/null 2>&1
-}
-
-function run_buffyboard_sync() {
-    local log=$1
-    shift
-    local conf=$2
-    shift
-    local args=$@
-
-    ./_build/buffyboard -v -C "$conf" $@ > "$log" 2>&1
-}

buffyboard/test/test-all.sh

@@ -1,8 +0,0 @@
-#!/bin/bash
-
-root=$(dirname "${BASH_SOURCE[0]}")
-
-source "$root/helpers.sh"
-
-run_script "$root/build.sh"
-run_script "$root/test-version-matches-meson-and-changelog.sh"

meson.build

@@ -0,0 +1,13 @@
+project(
+  'buffybox',
+  'c',
+  version: '3.2.0',
+  default_options: 'warning_level=3',
+  meson_version: '>=0.53.0'
+)
+
+add_project_arguments('-DBB_VERSION="@0@"'.format(meson.project_version()), language: ['c'])
+add_project_arguments('-DUL_VERSION="@0@"'.format(meson.project_version()), language: ['c'])
+
+subdir('unl0kr')
+subdir('buffyboard')

squeek2lvgl/sq2lv.h

@@ -7,7 +7,7 @@
 #ifndef SQ2LV_H
 #define SQ2LV_H
 
-#include "../sq2lv_layouts.h"
+#include "sq2lv_layouts.h"
 
 /* Key attributes */
 #define SQ2LV_CTRL_NON_CHAR     (LV_BUTTONMATRIX_CTRL_CLICK_TRIG | LV_BUTTONMATRIX_CTRL_CHECKED)

test/helpers.sh

@@ -1,5 +1,49 @@
 #!/bin/bash
 
+function run_unl0kr_async() {
+    local log=$1
+    local conf=$2
+
+    ./_build/unl0kr/unl0kr -v -C "$conf" > "$log" 2>&1 &
+    pid=$!
+    sleep 3
+
+    kill -9 $pid
+    wait $pid > /dev/null 2>&1
+}
+
+function run_unl0kr_sync() {
+    local log=$1
+    shift
+    local conf=$2
+    shift
+    local args=$@
+
+    ./_build/unl0kr/unl0kr -v -C "$conf" $@ > "$log" 2>&1
+}
+
+function run_buffyboard_async() {
+    local log=$1
+    local conf=$2
+
+    ./_build/buffyboard/buffyboard -v -C "$conf" > "$log" 2>&1 &
+    pid=$!
+    sleep 3
+
+    kill -9 $pid
+    wait $pid > /dev/null 2>&1
+}
+
+function run_buffyboard_sync() {
+    local log=$1
+    shift
+    local conf=$2
+    shift
+    local args=$@
+
+    ./_build/buffyboard/buffyboard -v -C "$conf" $@ > "$log" 2>&1
+}
+
 function info() {
     echo -e "[Info] $1"
 }
@@ -23,5 +67,5 @@ function read_version_from_meson() {
 }
 
 function read_version_from_changelog() {
-    grep "^## [[:digit:]]" "$root/../../CHANGELOG.md" | head -n1 | grep -o "[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]]\+"
+    grep "^## [[:digit:]]" "$root/../CHANGELOG.md" | head -n1 | grep -o "[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]]\+"
 }

test/test-version-matches-meson-and-changelog.sh

@@ -24,6 +24,16 @@ if [[ "$meson_version" != "$changelog_version" ]]; then
     exit 1
 fi
 
+info "Running unl0kr"
+run_unl0kr_sync "$log" "$conf" -V
+
+info "Verifying output"
+if ! grep "unl0kr $meson_version" "$log"; then
+    error "Expected version $meson_version"
+    cat "$log"
+    exit 1
+fi
+
 info "Running buffyboard"
 run_buffyboard_sync "$log" "$conf" -V
 

unl0kr/README.md

@@ -80,30 +80,6 @@ For an example configuration file, see [unl0kr.conf].
 - evdev kernel module
 - [scdoc] (for generating the man page)
 
-## Building & running
-
-Some of unl0kr's dependencies are included as git submodules in this repository. You can clone the repository and initialise the submodules with
-
-```
-$ git clone https://gitlab.com/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 _build
-$ meson compile -C _build
-$ sudo chvt 2
-$ sudo ./_build/unl0kr
-```
-
-With meson <0\.55 use `ninja` instead of `meson compile`\.
-
 ## Valgrind
 
 > Using C without Valgrind is like skydiving without a parachute.
@@ -111,7 +87,7 @@ With meson <0\.55 use `ninja` instead of `meson compile`\.
 To be able to use Valgrind, add `default_options: ['optimization=g']` in the `project` section of `meson.build` and rebuild. Afterwards you can run the application with Valgrind's leaks check enabled via
 
 ```
-sudo valgrind --leak-check=yes ./_build/unl0kr
+sudo valgrind --leak-check=yes ../_build/unl0kr/unl0kr
 ```
 
 ## Backends
@@ -142,10 +118,10 @@ $ ./regenerate-layouts.sh
 To generate screenshots in a variety of common sizes, install [fbcat], build unl0kr and then run
 
 ```
-$ sudo ./regenerate-screenshots _build/unl0kr
+$ sudo ./regenerate-screenshots ../_build/unl0kr/unl0kr
 ```
 
-where `_build/unl0kr` is the location of the unl0kr binary.
+where `../_build/unl0kr/unl0kr` is the location of the unl0kr binary.
 
 ## Screen recording
 

unl0kr/doc/unl0kr.conf.5.scd

@@ -58,7 +58,7 @@ will be merged in the following order:
 	The character that will be used to obscure the password. Default: bullet.
 
 ## Theme
-*default* = <breezy-light|breezy-dark|pmos-light|pmos-dark>
+*default* = <adwaita-light|adwaita-dark|breezy-light|breezy-dark|nord-light|nord-dark|pmos-light|pmos-dark>
 	Selects the default theme on boot. Can be changed at runtime to the 
 	alternative theme. Default: breezy-dark.
 

unl0kr/meson.build

@@ -2,16 +2,6 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 
-project(
-  'unl0kr',
-  'c',
-  version: '3.2.0',
-  default_options: 'warning_level=3',
-  meson_version: '>=0.53.0'
-)
-
-add_project_arguments('-DUL_VERSION="@0@"'.format(meson.project_version()), language: ['c'])
-
 unl0kr_sources = [
   'backends.c',
   'command_line.c',

unl0kr/test/helpers.sh

@@ -1,25 +0,0 @@
-#!/bin/bash
-
-source "$(dirname "${BASH_SOURCE[0]}")/../../test/helpers.sh"
-
-function run_unl0kr_async() {
-    local log=$1
-    local conf=$2
-
-    ./_build/unl0kr -v -C "$conf" > "$log" 2>&1 &
-    pid=$!
-    sleep 3
-
-    kill -9 $pid
-    wait $pid > /dev/null 2>&1
-}
-
-function run_unl0kr_sync() {
-    local log=$1
-    shift
-    local conf=$2
-    shift
-    local args=$@
-
-    ./_build/unl0kr -v -C "$conf" $@ > "$log" 2>&1
-}

unl0kr/test/test-version-matches-meson-and-changelog.sh

@@ -1,37 +0,0 @@
-#!/bin/bash
-
-log=tmp.log
-
-root=$(dirname "${BASH_SOURCE[0]}")
-
-source "$root/helpers.sh"
-
-function clean_up() {
-    rm -f "$log"
-}
-
-trap clean_up EXIT
-
-info "Querying version from build.meson"
-meson_version=$(read_version_from_meson)
-
-info "Querying version from CHANGELOG.md"
-changelog_version=$(read_version_from_changelog)
-
-info "Verifying versions"
-if [[ "$meson_version" != "$changelog_version" ]]; then
-    error "Version $meson_version from meson.build doesn't match version $changelog_version from CHANGELOG.md"
-    exit 1
-fi
-
-info "Running unl0kr"
-run_unl0kr_sync "$log" "$conf" -V
-
-info "Verifying output"
-if ! grep "unl0kr $meson_version" "$log"; then
-    error "Expected version $meson_version"
-    cat "$log"
-    exit 1
-fi
-
-ok