-
Notifications
You must be signed in to change notification settings - Fork 90
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 | pull-req |
Be warned that Arcan is difficult to package and integrate into a distribution although not 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, Xorg and session managers (blergh), and there's a lot of ways to configure things in order to account for many interests. 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 biggest complication come from the video/audio/input platform and from the special "lwa" build. System graphics on this level are quite hard to work with and to debug. Therefore, the choice has been to statically link/tie these layers together and tag the build accordingly. The choice in platform affect a lot of low level tuning and is internally incompatible. The SHMIF (IPC library) depends on the video platform of the display server to work around a coupling that has traditionally been hidden inside the GL drivers. When Issue #114 is closed, this will likely be easier to deal with.
The primary development platform is egl-dri, while the sdl one is mostly provided for testing/trying things out without being forced to run on a dedicated low-level graphics setup.
The audio platform is a bit special in its dependence on openal for the main build, and a patched version of openal for the LWA build. This is a sub-optimal solution that will be changed, but it will take some time. That is why the build system looks for external/git/openal, external/git/freetype, external/git/luajit and the external/git/clone.sh script populates external gits for this purpose.
-
Possibly have two different package options that are mutually exclusive based on platform, like arcan-sdl or arcan-dri. Alternatively provide both binaries and have a 'startx' like script that probes and choses the one to use. There is a problem with the libarcan_shmif_extvlibrary in that case, since it depends on the corresponding video platform of the arcan build.
-
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 | (see video- platform suggestion) |
| 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) |
| arcan_lwa | nested run | no (rec.) | see arcan_lwa section |
| 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_tui | text-dev-lib | no | text- UIs, combined with ltui |
| libahijack_sdl12 | preload-lib | no (adv.) | req: sdl1.2-dev, arcan build with -DDISABLE_HIJACK=OFF |
| 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 |
| ltui | tool | no | lua runner for libarcan_tui, build: src/tools/ltui |
| xarcan | tool | no | separate git (github.com/letoram/xarcan.git) |
| vrbridge | tool | ign (adv.) | separate build: src/tools/vrbridge |
adv = advanced, rec = recommended, req = requires, ign = ignore
The SDL2 and Qemu backends have also been ignored here. 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