Ontology
The ontology attempts to briefly and accessibly describe how the different parts of the project interact. Starting with the following figure:
Components are color coded based on how important they are, those marked green and bold are mostly necessary to be able to grasp and discuss anything regarding the project. Those in blue are more refined and corresponds to more advanced use and knowledge but particularly relevant for developers.
For the rest of this page, we will go through these groups one by one in a sequence- like flow.
Arcan refers both to the project as a whole, and the program that you actually run. Depending on your computing background and context, it may make sense to think of it as a framework, multimedia- or app- engine, frontend or display server. On its own, it does very little -- you need to provide it with an Appl to run (pronounced similar to the appalling 'app' but with either a deep depressive sigh added as a subtle sign of dissent at the end, or by 'blowing raspberries' as a more obvious one).
Appl "more than an 'app', less than an 'application'". In general, it is just the set of scripts and resources that control how Arcan behaves. For display server uses, the running appl can be compared to a "Window Manager" - a set of dynamic rules that decide how inputs and outputs are routed and reconfigured based on the users preferences and interaction behavior.
Frameserver refer to a separate process that communicates with an Arcan instance using the shared memory interface to exchange audio,video and input related data. These can be 'authoritative' where Arcan can enforce stronger rules on behavior, or 'non-authoritative' (also referred to as a client) which corresponds more to a normal program connected to a display server. The authoritative frameservers are built and managed in lock step with other components, each with a specific role.
Target is something that the active appl may launch. It can be frameservers, external listening points that allow other programs to connect and render or controlled launch of programs that need a customized environment setup. Each target can have multiple configurations defined; an always present default one and a user defined number of additional ones, think of them as sets of program arguments.
The Database is not shown in the figure as it has a more overreaching role, but every Arcan instance can be started with a database that is primarily populated using an external tool, arcan db. It acts as a key/value store both for caching appl specific configuration and state, for targets and for target configurations. It can be backed by a system shared file, a temporary memory backend or a user local file. This can be considered an intermediate representation for your configuration, it it probably more useful to have scripts or a text config file with an offline parser that invokes the arcan_db tool to synchronize the configuration with the database.
The Platform is the compile- time selection of OS specific glue for everything from file system and IPC primitive access to low level graphics (video platform) for managing displays, mid-level graphics (AGP platform, e.g. OpenGL) to input devices. It is statically defined and the resulting binary is tagged to match this configuration.
The SHMIF refers to the internal protocol and IPC used for passing data between one Arcan instance and a Target or a frameserver. Its inner workings is described in more detail here, but briefly put covers one or multiple segments where a segment is comprised of a shared memory page that is partitioned into control metadata, input / output ring buffers for event queues, a reserved subprotocol region and a number of dynamic audio and video buffers. Every segment also has a set of semaphores (Audio, Video, Event) and a socket (for I/O multiplexation and descriptor passes). Every connection gets one segment (primary) that can be used to request additional ones, though the running appl has to explicitly accept each such request based on available resources.
LWA is a specialized platform configuration where some functions are replaced with calls that use the SHMIF library. This allows one Arcan instance to connect and interact with- and output using- another.
Every file or resource that an appl directly or indirectly use is constrained to a Namespace, with rather complex rules on what goes where and why. These can be used and manipulated to split and control access to data sources of varying sensitivity, e.g. debug data, dynamically created content, font files etc.
Every authoritative frameserver implements a single Archetype. An archetype covers a fixed policy and behavior profile (which system resources it is allowed to use and how they should be used, how it should respond to state transfers and incoming events) etc. The decode frameserver is capable of receiving file- or streaming- coded input and converting it to a presentable aural/visual representation. The encode frameserver receives streaming data and encodes it for distribution. The terminal frameserver provides a command-line system interface. The networking frameserver mediates service discovery, network connection negotiation, message passing and data transfers. The game frameserver wraps the more complicated setup and restrictions that games and virtual machines. The avfeed frameserver is a dumb 'quick hookup and test' mainly for wrapping special devices.
For each running Arcan instance, a frameserver chainloader and a set of archetype implementations are chosen, either dynamically or defined as arguments to the program. It is up to the chain-loader to configure sandboxing and other environmental parameters for the archetype that is to be activated.