1Arcan 2===== 3 4Arcan is a powerful development framework for creating virtually anything from 5user interfaces for specialized embedded applications all the way to full-blown 6standalone desktop environments. 7 8At its heart lies a robust and portable multimedia engine, with a well-tested 9and well-documented Lua scripting interface. The development emphasizes 10security, debuggability and performance -- guided by a principle of least 11surprise in terms of API design. 12 13For more details about capabilities, design, goals, current development, 14roadmap, changelogs, notes on contributing and so on, please refer to the 15[arcan-wiki](https://github.com/letoram/arcan/wiki). 16 17There is also a [website](https://arcan-fe.com) that collects other links, 18announcements, releases, videos / presentations and so on. 19 20* For community contact, check out the IRC channel #arcan on irc.libera.chat 21 and/or the [discord (invite-link)](https://discord.com/invite/sdNzrgXMn7) 22 23* For developer information, see the HACKING.md 24 25Getting Started 26==== 27 28Some distributions, e.g. [voidlinux](https://voidlinux.org) have most of arcan 29as part of its packages, so you can save yourself some work going for one of 30those. 31 32Docker- container templates (mainly used for headless development and testing) 33can be found here, quality varies wildly from bad to poor (just like Docker): 34[dockerfiles](https://github.com/letoram/arcan-docker). 35 36## Compiling from Source 37 38There are many ways to tune the build steps in order to reduce dependencies. 39There are even more ways to configure and integrate the components depending 40on what you are going for; running as a native desktop or as an application 41runtime inside another desktop? 42 43Most options are exposed via the build output from running cmake on the src 44directory. 45 46For the sake of simplicity over size, there is a build preset, 'everything' 47which is the one we will use here. 48 49### Dependencies 50 51Specific package names depend on your distribution, but common ones are: 52 53 sqlite3, openal-soft, sdl2, opengl, luajit, gbm, kms, freetype, harfbuzz 54 libxkbcommon 55 56For encoding and decoding options you would also want: 57 58 libvlc-core (videolan), the ffmpeg suite, leptonica, tesseract 59 libvncserver libusb1 60 61First we need some in-source dependencies that are cloned manually for now: 62 63 git clone https://github.com/letoram/arcan.git 64 cd arcan/external/git 65 ./clone.sh 66 cd ../../ 67 68These are typically not needed, the main use is for ensuring certain build 69options that might vary between distributions (freetype/luajit) and to ensure 70that a recoverable desktop can be statically linked and executed in an 71otherwise broken userspace (so embedded bringup). The one exception is OpenAL 72which is patched to be used by a special (arcan-lwa) build. This is slated for 73refactoring to remove that dependency, but there are other priorities in the 74way. 75 76### Compiling 77 78Now we can configure and build the main engine: 79 80 mkdir build 81 cd build 82 cmake -DBUILD_PRESET="everything" ../src 83 84Like with other CMake based projects, you can add: 85 86 -DCMAKE_BUILD_TYPE=Debug 87 88To switch from a release build to a debug one. 89 90When it has finished probing dependencies, you will get a report of which 91dependencies that has been found and which features that were turned on/off, 92or alert you if some of the required dependencies could not be found. 93 94Make and install like normal (i.e. make, sudo make install). A number of 95binaries are produced, with the 'main' one being called simply arcan. To 96test 'in source' (without installing) you should be able to run: 97 98 ./arcan -T ../data/scripts -p ../data/resources ../data/appl/welcome 99 100The -T argument sets our built-in/shared set of scripts, the -p where shared 101resources like fonts and so on can be found, and the last argument being 102the actual 'script' to run. 103 104With installation, this should reduce to: 105 106 arcan welcome 107 108It will automatically try to figure out if it should be a native display 109server or run nested within another or even itself based on the presence 110of various environment variables (DISPLAY, WAYLAND\_DISPLAY, ARCAN\_CONNPATH). 111 112'welcome' is a name of a simple builtin welcome screen, *that will shut down 113automatically after a few seconds of use*. 114 115For something of more directly useful, you can try the builtin appl 'console': 116 117 arcan console 118 119Which should work just like your normal console command-line, but with the 120added twist of being able to run (arcan compatible) graphical applications 121as well. For other projects, see the 'Related Projects' further below. 122 123If input devices are misbehaving, the quick and dirty 'eventtest' in: 124 125 arcan /path/to/arcan/tests/interactive/eventtest 126 127Might be useful in figuring out who to blame. 128 129### SUID Notes 130 131The produced egl-dri platform 'arcan' binary installs suid by default. This is 132not strictly necessary unless some specific features are desired, e.g. laptop 133backlight controls on Linux as those require access to sysfs and friends. 134 135Do note that your current user then still requires access to relevant 136/dev/input/event and /dev/dri/cardN and /dev/dri/renderN files to work properly 137otherwise input and/or graphics devices might not be detected or useable. 138 139The binary does split off into a non-suid part that the main engine runs off 140of, see posix/psep\_open.c for auditing what is being run with higher 141privileges as well as the code for dropping privileges. The privileged process 142is responsible for negotiating device access, implementing virtual-terminal 143switching and as a watchdog for recovering the main process on live locks or 144some GPU failures. 145 146### Hook-Scripts 147 148Another way to extend engine behavior regardless of the appl being used are 149so called hook-scripts. These reside inside the 'system script path' covered 150by the -T command-line argument, or the default of shared/arcan/scripts. 151 152The idea is that these should be able to provide 'toggle on' features that 153would need cooperation from within the engine, in order to do quick custom 154modifications or help bridge other tools. 155 156A good example is 'external\_input': 157 158 arcan -H hooks/external_input.lua -H hooks/external_input.lua myappl 159 160This would open up two connection points, 'extio\_1', 'extio\_2' that will 161allow one client to connect and provide input that will appear to the 'myappl' 162appl as coming from the engine. 163 164These are covered in more detail in the manpage. 165 166### Networking 167 168Arcan-net is a binary that allows you to forward one or many arcan clients 169over a network. It is built by default, and can be triggered both as a 170separate network tool as well as being launched indirectly from shmif by 171setting ARCAN\_CONNPATH=a12://id@host:port, or when issuing a migration 172request by the window manager. 173 174See also: src/a12/net/README.md and src/a12/net/HACKING.md. 175 176### Wayland 177 178The 'arcan-wayland' or 'waybridge', as it is refered to in some places is 179binary adds support for wayland and X clients (via Xwayland). It can be run as 180either a global system service, e.g. 181 182 arcan-wayland -xwl 183 184Or on a case by case basis, like: 185 186 arcan-wayland -exec weston-terminal 187 188For a compliant wayland client, and: 189 190 arcan-wayland -exec-x11 xterm 191 192For an X client. The 'per case' basis is recommended as it is safer and more 193secure than letting multiple clients share the same bridge process, at a 194negilable cost. The downside is that some complex clients that rely on making 195multiple distinct wayland connections may fail to work properly. Firefox is a 196known offender. 197 198There is a number of tuning and troubleshooting options due to the complexity 199of using wayland, consult the manpage and the --help toggle. 200 201### Database 202 203All runtime configuration is consolidated into a database, either the default 204'arcan.sqlite' one or an explicitly set one (arcan -d mydb.sqlite). 205 206This is used for platform specific options, engine specific options and for 207trusted clients that the running scripts are allowed to start. It is also used 208as a configuration key-value store for any arcan applications that are running. 209 210As a quick example, this is how to inspect and modify keys that 'Durden' 211are currently using: 212 213 arcan_db show_appl durden 214 arcan_db add_appl_kv durden shadow_on true 215 216Advanced configuration for some video platforms can be set via the reserved 217arcan appl name. This would, for instance, set the primary graphics card 218device name for the 'egl-dri' platform version: 219 220 arcan_db add_appl_kv arcan video_device=/dev/dri/card2 221 222To add 'launch targets', you can use something like: 223 224 arcan_db add_target net BIN /usr/bin/arcan-net -l netfwd 225 arcan_db add_config arcan-net default 10.0.0.10 6666 226 arcan_db add_target xterm BIN /usr/bin/arcan-wayland -exec-x11 227 228This allow applications to start a program as a trusted child (that inherits 229its connection primitives rather than to try and find them using some OS 230dependent namespace). The example above would have spawned arcan-net in the 231local mode where clients connecting to the 'netfwd' connpath would be 232redirected to the server listening at 10.0.0.10:6666. 233 234There are many controls and options for this tool, so it is suggested that you 235look at its manpage for further detail and instructions. 236 237### Headless Mode 238 239The 'everything' build option should also produce a binary called 240'arcan\_headless', at least on BSDs and Linux. This binary can be used to run 241arcan without interfering with your other graphics and display system. Given 242access to a 'render node' (/dev/dri/renderD128 and so on) and it should also 243work fine inside containers and other strict sandboxing solutions. 244 245To make it useful, it can record/stream to a virtual screen. An example of 246such a setup following the example above would be: 247 248 ARCAN_VIDEO_ENCODE=protocol=vnc arcan_headless console 249 250Assuming the build-system found the libvncserver dependency, this should 251leave you with an exposed (insecure, unprotected, ...) vnc server at 252localhost+5900. See afsrv\_encode for a list of arguments that can be added 253to the encode environment in order to control what happens. 254 255Related Projects 256================ 257 258If you are not interested in developing something of your own, you will 259likely find little use with the parts of this project alone. Here are some 260projects that you might want to look into: 261 262* [Durden](https://github.com/letoram/durden) is the main desktop 263 environment that uses this project as its display server. 264 265* [Safespaces](https://github.com/letoram/safespaces) is an experimental 266 VR/3D desktop environment. 267 268* [Pipeworld](https://github.com/letoram/pipeworld) is a dataflow 269 (think excel) programming environment 270 271* [Arcan-Devices](https://github.com/letoram/arcan-devices) accumulates 272 extra drivers. 273 274To get support for more types of clients and so on, there is also: 275 276* Wayland support (see Wayland section above, and src/wayland/README.md). 277 278* [QEmu](https://github.com/letoram/qemu) a patched QEmu version that 279 adds a -ui arcan option. 280 281* [Xarcan](https://github.com/letoram/xarcan) is a patched Xorg that 282 allows you to run an X session 'as a window'. 283 284* [nvim-arcan](https://github.com/letoram/nvim-arcan) is a neovim frontend 285 that act as a native arcan client. 286 287Tools 288===== 289 290There is also a number of helper tools that can be used to add certain 291features, such as support for VR devices and tray-icons. These are built 292separately and can be found in the tools/ subdirectory. They have their 293own separate build systems and corresponding README.md files. 294 295They work on the assumption that arcan and its respective libraries have been 296built and installed. They are lockstepped and versioned to the engine, so if 297you upgrade it, make sure to rebuild the tools as well. 298 299The main tools of interest are: 300 301## Acfgfs 302 303Acfgfs is a tool that lets you mount certain arcan applications as a FUSE 304file-system. The application has to explicitly support it. For the Durden 305desktop environment, you can use global/settings/system/control=somename 306and then: 307 308 arcan_cfgfs --control=/path/to/durden/ipc/somename /mnt/desktop 309 310And desktop control / configuration should be exposed in the specified 311mountpoint. 312 313## Aclip 314 315Aclip is a clipboard manager similar to Xclip. It allows for bridging the 316clipboard between a desktop environment like Durden, and that of an X server. 317 318This requires that clipboard bridging has been allowed (disabled by default for 319security reasons). In Durden this is activated via 320global/settings/system/clipboard where you can control how much clipboard 321access the tool gets. 322 323## Aloadimage 324 325Aloadimage is a simple sandboxing image loader, similar to xloadimage. It is 326useful both for testing client behavior when developing applications using 327arcan, but also as an image viewer in its own right, with reasonably fast image 328loading, basic playlist controls and so on. 329 330## Vrbridge 331 332VR bridge is an optional input driver that provides the arcan\_vr binary which 333adds support for various head-mounted displays. More detailed instructions on 334its setup and use can be found as part of the Safespaces project mentioned in 335the 'Related Projects 'section. 336 337## Trayicon 338 339Arcan-trayicon is a tool that chain-loads another arcan client, along with two 340reference images (active and inactive). It tries to register itself in the 341icon-tray of a running arcan application, though it must explicitly enable the 342support. In Durden, this is done via the path: 343 344 global/settings/statusbar/buttons/right/add_external=tray 345 346Then you can use: 347 348 ARCAN_CONNPATH=tray arcan-trayicon active.svg inactive.svg afsrv_terminal 349 350Or some other arcan client that will then be loaded when the tray button is 351clicked, confined into a popup and then killed off as the popup is destroyed. 352This is a quick and convenient way to wrap various system services and external 353command scripts. 354
