buffybox/README.md

119 lines
3.8 KiB
Markdown
Raw Normal View History

2024-01-02 20:32:29 +01:00
# BuffyBox
2021-09-02 21:17:56 +02:00
2024-01-02 20:32:29 +01:00
BuffyBox is a suite of graphical applications for the terminal.
2021-09-02 21:17:56 +02:00
2024-01-10 20:08:33 +01:00
## Components
2024-03-28 13:27:01 +01:00
### Standalone apps
**[buffyboard]** Touch-enabled on-screen keyboard for virtual terminals
**[unl0kr]** Disk unlocking UI for the initramfs
### Utilities
**[squeek2lvgl]** Converter for transforming [Squeekboard] layouts into [LVGL]-compatible C code
**[iskey]** - A utility for checking for key presses in bash scripts.
2024-03-28 13:27:01 +01:00
**[shared]** Internal code that is shared by some or all applications in the suite but not meant to be used externally
2024-01-10 20:08:33 +01:00
2024-01-02 21:00:11 +01:00
## Contributing
2024-01-10 20:08:33 +01:00
You can join our development chat at [#buffybox:matrix.org].
2024-01-02 21:00:11 +01:00
## Building & running
2024-07-26 18:42:24 +02:00
Some dependencies are included as git submodules in this repository. You can clone the repository and initialise the submodules with
```
2025-04-16 13:19:01 +03:00
$ 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
```
2024-09-23 16:49:41 +03:00
On distributions based on systemd, `unl0kr` can be used as a [password agent](https://systemd.io/PASSWORD_AGENTS/), 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
```
## Packaging
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"
```
## 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.
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.
2024-01-02 20:32:29 +01:00
## License
2021-09-02 21:17:56 +02:00
2024-01-02 20:32:29 +01:00
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.
2024-01-10 20:08:33 +01:00
2024-03-30 19:35:29 +00:00
For the license of bundled images and fonts, see [shared/cursor] and [shared/fonts].
2024-01-10 20:08:33 +01:00
[#buffybox:matrix.org]: https://matrix.to/#/#buffybox:matrix.org
[buffyboard]: ./buffyboard
[git-archive-all]: https://github.com/Kentzo/git-archive-all
2024-01-10 20:10:01 +01:00
[LVGL]: https://github.com/lvgl/lvgl
2024-03-28 13:27:01 +01:00
[shared]: ./shared
2024-01-10 20:08:33 +01:00
[squeek2lvgl]: ./squeek2lvgl
[iskey]: ./iskey
2024-01-10 20:08:33 +01:00
[Squeekboard]: https://gitlab.gnome.org/World/Phosh/squeekboard
2024-03-30 19:35:29 +00:00
[shared/cursor]: ./shared/cursor
[shared/fonts]: ./shared/fonts
2024-01-10 20:08:33 +01:00
[unl0kr]: ./unl0kr
[unl0kr#42]: https://gitlab.com/cherrypicker/unl0kr/-/issues/42