{"id":13439724,"url":"https://github.com/letoram/arcan","last_synced_at":"2025-05-14T10:13:04.209Z","repository":{"id":11714908,"uuid":"14234034","full_name":"letoram/arcan","owner":"letoram","description":"Arcan - [Display Server, Multimedia Framework, Game Engine] -\u003e \"Desktop Engine\"","archived":false,"fork":false,"pushed_at":"2025-05-03T14:14:57.000Z","size":70331,"stargazers_count":1664,"open_issues_count":23,"forks_count":91,"subscribers_count":73,"default_branch":"master","last_synced_at":"2025-05-03T15:25:33.462Z","etag":null,"topics":["audio-processing","c","desktop-environment","display-server","freebsd","game-engine","linux","lua","multimedia-graphic-library","openbsd","video-processing","virtual-reality","visualization","wayland"],"latest_commit_sha":null,"homepage":"http://arcan-fe.com","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/letoram.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-11-08T13:47:43.000Z","updated_at":"2025-05-03T14:15:04.000Z","dependencies_parsed_at":"2023-01-16T19:46:32.139Z","dependency_job_id":"a79d28d2-ceed-49e9-8eaa-e9aeb77790b4","html_url":"https://github.com/letoram/arcan","commit_stats":{"total_commits":4365,"total_committers":30,"mean_commits":145.5,"dds":0.5734249713631157,"last_synced_commit":"433241c22489bf862742053a5c869439a65bc5ef"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Farcan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Farcan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Farcan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letoram%2Farcan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/letoram","download_url":"https://codeload.github.com/letoram/arcan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254120179,"owners_count":22017953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-processing","c","desktop-environment","display-server","freebsd","game-engine","linux","lua","multimedia-graphic-library","openbsd","video-processing","virtual-reality","visualization","wayland"],"created_at":"2024-07-31T03:01:16.571Z","updated_at":"2025-05-14T10:13:04.151Z","avatar_url":"https://github.com/letoram.png","language":"C","readme":"Arcan\n=====\n\nArcan is a powerful development framework for creating virtually anything from\nuser interfaces for specialized embedded applications all the way to full-blown\nstandalone desktop environments.\n\nAt its heart lies a robust and portable multimedia engine, with a well-tested\nand well-documented Lua scripting interface. The development emphasizes\nsecurity, debuggability and performance -- guided by a principle of least\nsurprise in terms of API design.\n\nFor more details about capabilities, design, goals, current development,\nroadmap, changelogs, notes on contributing and so on, please refer to the\n[arcan-wiki](https://github.com/letoram/arcan/wiki).\n\nThere is also a [website](https://arcan-fe.com) that collects other links,\nannouncements, releases, videos / presentations and so on.\n\n* For community contact, check out the IRC channel #arcan on irc.libera.chat\n  and/or the [discord (invite-link)](https://discord.com/invite/sdNzrgXMn7)\n\n* For developer information, see the HACKING.md\n\nThe github repository is going defunct thanks to Microsofts incresingly abusive\npractices, and we are thus moving to self-hosted Fossil. The repository will be\nsynched to github for the time being, but no active development activities\nthere. See [fossil.arcan-fe.com](https://fossil.arcan-fe.com).\n\nGetting Started\n====\n\nSome distributions, e.g. [voidlinux](https://voidlinux.org) have most of arcan\nas part of its packages, so you can save yourself some work going for one of\nthose. Other ones with an active community would be through Nix (for example:\nnix-shell -p arcan.all-wrapped).\n\nDocker- container templates (mainly used for headless development and testing)\ncan be found here, quality varies wildly from bad to poor (just like Docker):\n[dockerfiles](https://github.com/letoram/arcan-docker).\n\n## Compiling from Source\n\nThere are many ways to tune the build steps in order to reduce dependencies.\nThere are even more ways to configure and integrate the components depending\non what you are going for; running as a native desktop or as an application\nruntime inside another desktop?\n\nMost options are exposed via the build output from running cmake on the src\ndirectory.\n\nFor the sake of simplicity over size, there is a build preset, 'everything'\nwhich is the one we will use here.\n\n### Dependencies\n\nSpecific package names depend on your distribution, but common ones are:\n\n    sqlite3, openal-soft, sdl2, opengl, luajit, gbm, kms, freetype, harfbuzz\n    libxkbcommon\n\nFor more encoding and decoding options you might also want:\n\n    libvlc-core (videolan), the ffmpeg suite, leptonica + tesseract (ocr)\n    libvncserver libusb1, v4l2-loopback, mupdf\n\nFirst we need some in-source dependencies that are cloned manually for now:\n\n    git clone https://github.com/letoram/arcan.git\n    cd arcan/external/git\n    ./clone.sh\n    cd ../../\n\nThese are typically not needed, the main use is for ensuring certain build\noptions that might vary between distributions (luajit) and to ensure that a\nrecoverable desktop can be statically linked and executed in an otherwise\nbroken userspace (so embedded bringup). The one exception is OpenAL which is\npatched to be used by a special (arcan-lwa) build. This is slated for\nrefactoring to remove that dependency, but there are other priorities in the\nway.\n\n### Compiling\n\nNow we can configure and build the main engine:\n\n    mkdir build\n    cd build\n    cmake -DBUILD_PRESET=\"everything\" ../src\n\nLike with other CMake based projects, you can add:\n\n    -DCMAKE_BUILD_TYPE=Debug\n\nTo switch from a release build to a debug one.\n\nWhen it has finished probing dependencies, you will get a report of which\ndependencies that has been found and which features that were turned on/off,\nor alert you if some of the required dependencies could not be found.\n\nMake and install like normal (i.e. make, sudo make install). A number of\nbinaries are produced, with the 'main' one being called simply arcan. To\ntest 'in source' (without installing) you should be able to run:\n\n     ./arcan -T ../data/scripts -p ../data/resources ../data/appl/welcome\n\nThe -T argument sets our built-in/shared set of scripts, the -p where shared\nresources like fonts and so on can be found, and the last argument being\nthe actual 'script' to run.\n\nWith installation, this should reduce to:\n\n     arcan welcome\n\nIt will automatically try to figure out if it should be a native display\nserver or run nested within another or even itself based on the presence\nof various environment variables (DISPLAY, WAYLAND\\_DISPLAY, ARCAN\\_CONNPATH).\n\n'welcome' is a name of a simple builtin welcome screen, *that will shut down\nautomatically after a few seconds*.\n\nFor something of more directly useful, you can try the builtin appl 'console':\n\n    arcan console\n\nWhich should work just like your normal console command-line, but with the\nadded twist of being able to run (arcan compatible) graphical applications\nas well. For other projects, see the 'Related Projects' further below.\n\nIf input devices are misbehaving, the quick and dirty 'eventtest' in:\n\n    arcan /path/to/arcan/tests/interactive/eventtest\n\nMight be useful in figuring out who to blame.\n\n### SUID Notes\n\nThe produced egl-dri platform 'arcan' binary installs suid by default. This is\nnot strictly necessary unless some specific features are desired, e.g. laptop\nbacklight controls on Linux as those require access to sysfs and friends.\n\nIf that is not relevant, you can strip the suid property on the binary, but do\nnote that your current user still requires access to relevant /dev/input/event\nand /dev/dri/cardN and /dev/dri/renderN files to work properly -- otherwise\ninput and/or graphics devices might not be detected or useable.\n\nThe binary does split off into a non-suid part that the main engine runs off\nof, see posix/psep\\_open.c for auditing what is being run with higher\nprivileges as well as the code for dropping privileges. The privileged process\nis responsible for negotiating device access, implementing virtual-terminal\nswitching and as a watchdog for recovering the main process on live locks or\nsome GPU failures.\n\n### Hook-Scripts\n\nAnother way to extend engine behavior regardless of the appl being used are\nso called hook-scripts. These reside inside the 'system script path' covered\nby the -T command-line argument, or the default of shared/arcan/scripts.\n\nThe idea is that these should be able to provide 'toggle on' features that\nwould need cooperation from within the engine, in order to do quick custom\nmodifications or help bridge other tools.\n\nA good example is 'external\\_input':\n\n    arcan -H hooks/external_input.lua -H hooks/external_input.lua myappl\n\nThis would open up two connection points, 'extio\\_1', 'extio\\_2' that will\nallow one client to connect and provide input that will appear to the 'myappl'\nappl as coming from the engine.\n\nThese are covered in more detail in the manpage.\n\n### Networking\n\nArcan-net is a binary that allows you to forward one or many arcan clients over\na network. It is built by default, and can be triggered both as a separate\nnetwork tool as well as being launched indirectly from shmif by setting\nARCAN\\_CONNPATH=a12://id@host:port, or when issuing a migration request by the\nwindow manager.\n\nSee also: src/a12/net/README.md and src/a12/net/HACKING.md.\n\n### Wayland\n\nThe 'arcan-wayland' or 'waybridge', as it is refered to in some places is\nbinary adds support for wayland and X clients (via Xwayland). It can be run as\neither a global system service, e.g.\n\n    arcan-wayland -xwl\n\nOr on a case by case basis, like:\n\n    arcan-wayland -exec weston-terminal\n\nFor a compliant wayland client, and:\n\n    arcan-wayland -exec-x11 xterm\n\nFor an X client. The 'per case' basis is recommended as it is safer and more\nsecure than letting multiple clients share the same bridge process, at a\nnegilable cost. The downside is that some complex clients that rely on making\nmultiple distinct wayland connections may fail to work properly. Firefox is a\nknown offender.\n\nThere is a number of tuning and troubleshooting options due to the complexity\nof using wayland, consult the manpage and the --help toggle.\n\n### Database\n\nAll runtime configuration is consolidated into a database, either the default\n'arcan.sqlite' one or an explicitly set one (arcan -d mydb.sqlite).\n\nThis is used for platform specific options, engine specific options and for\ntrusted clients that the running scripts are allowed to start. It is also used\nas a configuration key-value store for any arcan applications that are running.\n\nAs a quick example, this is how to inspect and modify keys that 'Durden'\nare currently using:\n\n    arcan_db show_appl durden\n    arcan_db add_appl_kv durden shadow_on true\n\nAdvanced configuration for some video platforms can be set via the reserved\narcan appl name. This would, for instance, set the primary graphics card\ndevice name for the 'egl-dri' platform version:\n\n    arcan_db add_appl_kv arcan video_device=/dev/dri/card2\n\nTo add 'launch targets', you can use something like:\n\n    arcan_db add_target net BIN /usr/bin/arcan-net -l netfwd\n    arcan_db add_config arcan-net default 10.0.0.10 6666\n    arcan_db add_target xterm BIN /usr/bin/arcan-wayland -exec-x11\n\nThis allow applications to start a program as a trusted child (that inherits\nits connection primitives rather than to try and find them using some OS\ndependent namespace). The example above would have spawned arcan-net in the\nlocal mode where clients connecting to the 'netfwd' connpath would be\nredirected to the server listening at 10.0.0.10:6666.\n\nThere are many controls and options for this tool, so it is suggested that you\nlook at its manpage for further detail and instructions.\n\n### Headless Mode\n\nThe 'everything' build option should also produce a binary called\n'arcan\\_headless', at least on BSDs and Linux. This binary can be used to run\narcan without interfering with your other graphics and display system. Given\naccess to a 'render node' (/dev/dri/renderD128 and so on) and it should also\nwork fine inside containers and other strict sandboxing solutions.\n\nTo make it useful, it can record/stream to a virtual screen. An example of\nsuch a setup following the example above would be:\n\n    ARCAN_VIDEO_ENCODE=protocol=vnc arcan_headless console\n\nAssuming the build-system found the libvncserver dependency, this should\nleave you with an exposed (insecure, unprotected, ...) vnc server at\nlocalhost+5900. See afsrv\\_encode for a list of arguments that can be added\nto the encode environment in order to control what happens.\n\nFunding\n=======\n\nThis project is funded through [NGI0 Entrust](https://nlnet.nl/entrust), a fund\nestablished by [NLnet](https://nlnet.nl) with financial support from the\nEuropean Commission's [Next Generation Internet](https://ngi.eu) program. Learn\nmore at the [NLnet project page](https://nlnet.nl/Arcan-A12).\n\n[\u003cimg src=\"https://nlnet.nl/logo/banner.png\" alt=\"NLnet foundation logo\" width=\"20%\" /\u003e](https://nlnet.nl)\n[\u003cimg src=\"https://nlnet.nl/image/logos/NGI0_tag.svg\" alt=\"NGI Zero Logo\" width=\"20%\" /\u003e](https://nlnet.nl/entrust)\n\nRelated Projects\n================\n\nIf you are not interested in developing something of your own, you will\nlikely find little use with the parts of this project alone. Here are some\nprojects that you might want to look into:\n\n* [Durden](https://github.com/letoram/durden) is the main desktop\n  environment that uses this project as its display server.\n\n* [Safespaces](https://github.com/letoram/safespaces) is an experimental\n  VR/3D desktop environment.\n\n* [Pipeworld](https://github.com/letoram/pipeworld) is a dataflow\n  (think excel) programming environment\n\n* [Arcan-Devices](https://github.com/letoram/arcan-devices) accumulates\n  extra drivers.\n\nTo get support for more types of clients and so on, there is also:\n\n* Wayland support (see Wayland section above, and src/wayland/README.md).\n\n* [QEmu](https://github.com/letoram/qemu) a patched QEmu version that\n  adds a -ui arcan option.\n\n* [Xarcan](https://github.com/letoram/xarcan) is a patched Xorg that\n  allows you to run an X session 'as a window'.\n\n* [nvim-arcan](https://github.com/letoram/nvim-arcan) is a neovim frontend\n  that act as a native arcan client.\n\nTools\n=====\n\nThere is also a number of helper tools that can be used to add certain\nfeatures, such as support for VR devices and tray-icons. These are built\nseparately and can be found in the tools/ subdirectory. They have their\nown separate build systems and corresponding README.md files.\n\nThey work on the assumption that arcan and its respective libraries have been\nbuilt and installed. They are lockstepped and versioned to the engine, so if\nyou upgrade it, make sure to rebuild the tools as well.\n\nThe main tools of interest are:\n\n## Acfgfs\n\nAcfgfs is a tool that lets you mount certain arcan applications as a FUSE\nfile-system. The application has to explicitly support it. For the Durden\ndesktop environment, you can use global/settings/system/control=somename\nand then:\n\n    arcan_cfgfs --control=/path/to/durden/ipc/somename /mnt/desktop\n\nAnd desktop control / configuration should be exposed in the specified\nmountpoint.\n\n## Aclip\n\nAclip is a clipboard manager similar to Xclip. It allows for bridging the\nclipboard between a desktop environment like Durden, and that of an X server.\n\nThis requires that clipboard bridging has been allowed (disabled by default for\nsecurity reasons). In Durden this is activated via\nglobal/settings/system/clipboard where you can control how much clipboard\naccess the tool gets.\n\n## Aloadimage\n\nAloadimage is a simple sandboxing image loader, similar to xloadimage. It is\nuseful both for testing client behavior when developing applications using\narcan, but also as an image viewer in its own right, with reasonably fast image\nloading, basic playlist controls and so on.\n\n## Vrbridge\n\nVR bridge is an optional input driver that provides the arcan\\_vr binary which\nadds support for various head-mounted displays. More detailed instructions on\nits setup and use can be found as part of the Safespaces project mentioned in\nthe 'Related Projects 'section.\n\n## Trayicon\n\nArcan-trayicon is a tool that chain-loads another arcan client, along with two\nreference images (active and inactive). It tries to register itself in the\nicon-tray of a running arcan application, though it must explicitly enable the\nsupport. In Durden, this is done via the path:\n\n    global/settings/statusbar/buttons/right/add_external=tray\n\nThen you can use:\n\n    ARCAN_CONNPATH=tray arcan-trayicon active.svg inactive.svg afsrv_terminal\n\nOr some other arcan client that will then be loaded when the tray button is\nclicked, confined into a popup and then killed off as the popup is destroyed.\nThis is a quick and convenient way to wrap various system services and external\ncommand scripts.\n","funding_links":[],"categories":["C","Projects"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fletoram%2Farcan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fletoram%2Farcan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fletoram%2Farcan/lists"}