packaging
The following distributions carry arcan and some related projects as packages today and may be used as templates for others:
| distribution | package-names | source link |
|---|---|---|
| voidlinux | arcan, xarcan, arcan-wayland, aclip, aloadimage, durden | pkg |
Be warned that Arcan is difficult to package and integrate into a distribution. It might not be as painful as Xorg, but we are talking about working with many decades of system integration legacy that is in partial conflict with everything from virtual terminals to session managers and Xorg itself, and there's a lot of ways to configure things in order to account for the wide variety of use cases.
Depending on which scripts you run it with, you can use it as graphical boot UI, virtual-terminal replacement, installation UI, full desktop, display-manager, embedded system HMI and so on.
A goal is to to be configurable to the point that distributions should be able to pick a fitting combination for their user-space management model, but steer away from setting direct policies towards as to how that is to be done.
Therefore, very few assumptions are made in regards to available file-systems and hotplug- management and will remain adamant towards suggestions of "integrating" parasitic dependencies such as DBus, Udev, Systemd or other projects that would tie the codebase to depend on service/event management, /dev, /proc or /sys layout as it is a goal to be able to get accelerated low-mid level graphics working statically, even in a read-only environment with a minimal init.
Patched builds that ignore this should at least have the decency to clearly mark that in the DISTR_TAG cmake compile time option so that bug reports can be treated accordingly as the tag will be appended to version outputs and to lua scripting error report snapshots.
The normal recommendation is to use the build preset "everything" (-DBUILD_PRESET) and, if your distribution prefer split packages, and give the arcan_sdl binary its own package that depends on the main one.
Note how the lwa platform is built and the in-source treatment of OpenAL via the external/git/clone.sh. This is a temporary measure (solved around ~0.7) to deal with the many peculiars of nested "arcan as display server running other arcan scripts as normal applications".
- Provide some kind of launcher script to set up mapping to local rules and policies by setting environment variables, selecting main binary and frameserver prefix, log and similar sensitive storage. For desktop use, a fallback appl and a relaunch-on-crash loop (most clients can reconnect in the event of a crash) is also advisable.
Depending on how fine-grained your package management scheme is (everything from separated -dev headers and onwards), you likely want to split things up into different packages. The following table tracks all related project binaries and tools:
| binary | role | required | notes |
|---|---|---|---|
| arcan | main | yes | |
| arcan_lwa | nested run | yes | |
| [ arcan_sdl | (Xorg, Wl) | no | |
| arcan_db | cfg- tool | yes | |
| arcan_frameserver | chainloader | yes | cleans environment, sets up sandboxing etc. |
| afsrv_terminal | CLI-shell | no (rec.) | provides a command-line shell and terminal emulator |
| afsrv_decode | media-decode | no (rec.) | provides video/media/data decoding |
| afsrv_encode | media-encode | no (rec.) | provides media encoding, optionally OCR, vnc server |
| afsrv_net | networking | no (ign.) | networking code test-bed, ignore for now |
| afsrv_remoting | remote-cl | no (rec.) | provides VNC client support |
| afsrv_avfeed | media-integ. | no (ign.) | only for special projects, ignore |
| afsrv_game | game | no (rec.) | provides support for running libretro- cores (gaming) |
| libarcan_shmif | main-dev-lib | no (rec.) | required for building/running support tools right now |
| libarcan_shmif_ext | 3d-dev-lib | no (rec.) | accel-graphics support, tied to arcan video platform |
| libarcan_shmif_srv | main-dev-lib | no (rec.) | free-standing server library, used for net-proxy |
| libarcan_tui | text-dev-lib | no (rec.) | text- UIs, combined with ltui |
| aclip | tool | no | req: arcan_shmif, separate build: src/tools/aclip |
| aloadimage | tool | no | req: arcan_shmif, separate build: src/tools/aloadimage |
| arcan-wayland | tool | no | separate build: src/tools/waybridge |
| arcan-net | tool | no | separate build: src/tools/netproxy |
| xarcan | tool | no | separate git (github.com/letoram/xarcan.git) |
| ltui | tool | ign (adv.) | lua runner for libarcan_tui, build: src/tools/ltui |
| libahijack_sdl12 | preload-lib | ign (adv.) | req: sdl1.2-dev, arcan build with -DDISABLE_HIJACK=OFF |
| vrbridge | tool | ign (adv.) | separate build: src/tools/vrbridge |
adv = advanced, rec = recommended, req = requires, ign = ignore
Then there is the choice of providing the manpages for the scripting API or not. They are by default not installed as they pollute the manpage namespace rather heavily. They can either be provided in their normal .lua form (doc/*.lua) or as generated manpages via:
cd doc; ruby docgen.rb mangen
if they have been generated, the make install build target will copy them into the corresponding share output folder.
An easy setup / layout is to have a folder structure like:
/home/user/
.arcan/
arcan_db.sqlite (will be automatically created)
resources (symlink /home/user or some subdir like /home/user/Documents)
appl (copy of the /usr/share/arcan/appl folder so that it is modifiable by the user)
And then install other appls like durden or prio into /home/user/.arcan/appl. With access to the relevant audio/video/input, most things should be auto-detected. This can be further fine-grained or tuned later with all the different ARCAN_XXXXPATH environment variables.
-DDISTR_TAG=string ; use this tag to help identify your build, the engine will tag video/agp/audio/input platform along with git revision and use this tag in crash dumps.
These are just some test- steps that have been reported to lead to successful local from-source builds in various distributions:
Arcan will use one sqlite3 database file for tracking all kinds of appl- specific state, for engine/platform configuration tuning and for tracking external programs that a script is allowed to execute. This allows for an efficient way to manage/backup/switch between different user configurations and tuning - while preventing the kind of "eval('rm -rf /')" like problems that can otherwise easily be hidden inside a script.
The arcan_db command line tool is provided for working with this database directly, and can of course be integrated with scripts to act as a 'commit' step for going from file based configuration to something the engine can see.
In the future, a CLI tool (via TUI) will likely be provided to help with populating the database with the contents from system- wide scraping (like using those atrocious .desktop files to extract programs, arguments and icons) and for automatically adding games and contents suitable for the libretro runner (afsrv_game).
Platform specific tuning options are set either via the arcan_db tool, or overridden using environment variables. Running arcan without any arguments should produce a list of key/value pairs the system is looking for.
- ARCAN_RESOURCEPATH - data that can be shared r/o for all users
- ARCAN_FONTPATH - system fonts (data can be an attack vector) can be shared r/o for all users
- ARCAN_BINPATH - defaults to arcan_frameserver (that maps to afsrv_) but act as a prefix for frameservers (eg. ARCAN_BINPATH=test will make the engine use test_encode test_decode etc. in order to allow for multiple interchangeable sets of frameservers.
- ARCAN_APPLBASEPATH - can usually be ignored, useful when there are multiple appls that one could switch between dynamically, see the system_collapse Lua function.
- ARCAN_STATEPATH - set to a user- writeable destination
- ARCAN_APPLSTOREPATH - set to a user- writeable destination
- ARCAN_LIBPATH - hijack libraries and system_load() libraries for extending script interface
- ARCAN_LOGPATH - crash-dumps and output files
There are also a number of platform specific environment variables, mostly related to debugging. For linux the key ones are ARCAN_VIDEO_DEVICE, ARCAN_INPUT_SCANDIR (folder to monitor for allowed device nodes), ARCAN_INPUT_TTYOVERRIDE, ARCAN_INPUT_DISABLE_TTYPSWAP (alt-f* for swapping virtual terminals).
- -b - specify a fallback appl from APPLBASE should the running one crash
- -d - specify database path for user settings