{"id":13673712,"url":"https://github.com/jcrd/wm-launch","last_synced_at":"2025-04-28T11:30:40.065Z","repository":{"id":97084568,"uuid":"177899255","full_name":"jcrd/wm-launch","owner":"jcrd","description":"Tool to launch X11 clients with unique IDs","archived":false,"fork":false,"pushed_at":"2022-08-22T16:33:10.000Z","size":186,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-11T13:35:39.783Z","etag":null,"topics":["c","ld-preload","ld-preload-hack","x11","xorg"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcrd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-03-27T01:54:40.000Z","updated_at":"2024-10-29T18:37:27.000Z","dependencies_parsed_at":"2023-03-12T18:00:50.811Z","dependency_job_id":null,"html_url":"https://github.com/jcrd/wm-launch","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcrd%2Fwm-launch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcrd%2Fwm-launch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcrd%2Fwm-launch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcrd%2Fwm-launch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcrd","download_url":"https://codeload.github.com/jcrd/wm-launch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251304665,"owners_count":21567918,"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":["c","ld-preload","ld-preload-hack","x11","xorg"],"created_at":"2024-08-02T11:00:19.842Z","updated_at":"2025-04-28T11:30:39.401Z","avatar_url":"https://github.com/jcrd.png","language":"C","funding_links":[],"categories":["Dependencies"],"sub_categories":[],"readme":"# wm-launch\n\n![test](https://github.com/jcrd/wm-launch/actions/workflows/test.yml/badge.svg)\n[![Copr build status](https://copr.fedorainfracloud.org/coprs/jcrd/wm-launch/package/wm-launch/status_image/last_build.png)](https://copr.fedorainfracloud.org/coprs/jcrd/wm-launch/package/wm-launch/)\n\n**wm-launch** provides a shared library for use with `LD_PRELOAD` and a\ncommand-line tool to set IDs on newly created X11 windows. It is intended to be\nused by a window manager to uniquely identify clients it launches.\n\n## Packages\n\n* Fedora ([copr][copr])\n\n  ```sh\n  dnf copr enable jcrd/wm-launch\n  dnf install wm-launch\n  ```\n\n* Arch Linux ([AUR][aur])\n\n  ```sh\n  git clone https://aur.archlinux.org/wm-launch.git\n  cd wm-launch\n  makepkg -si\n  ```\n\n[copr]: https://copr.fedorainfracloud.org/coprs/jcrd/wm-launch/\n[aur]: https://aur.archlinux.org/packages/wm-launch\n\n## Usage\n\n`LD_PRELOAD` can be specified along with `WM_LAUNCH_ID` in the\nenvironment of a command:\n\n```sh\nLD_PRELOAD=/usr/lib/wm-launch/wm-launch-preload.so WM_LAUNCH_ID=id1 xterm\n```\n\nThe window created by `xterm` will have the property `WM_LAUNCH_ID`:\n\n```sh\n$ xprop WM_LAUNCH_ID\n\u003e WM_LAUNCH_ID(UTF8_STRING) = \"id1\"\n```\n\nA command-line tool is provided for convenience and for interacting with window\nfactories:\n\n```txt\nusage: wm-launch [options] WM_LAUNCH_ID COMMAND...\n\noptions:\n  -h          Show help message\n  -s          Launch with systemd-run\n  -j          Launch with firejail\n  -f FACTORY  Launch via a window factory\n  -w DIR      Launch workspace from DIR\n  -v          Show version\n```\n\n### Example use cases\n\nwm-launch can be used to:\n\n* reliably assign clients to window manager desktops/workspaces so that even\n  slow-to-spawn windows appear where intended\n* identify separate instances of the same application to be managed differently,\n  focused via keybindings, etc.\n* launch or focus a single instance of an application\n\n## Window factories\n\nA window factory is an X11 client responsible for creating the windows of new\nclients. It can be either implicit or explicit, the key difference being that\nimplicit factories create their own window.\n\n### Implicit factory\n\nAn implicit factory is an X11 client that reuses a single instance to create\nadditional windows each time it's launched, e.g. `qutebrowser`, `kitty -1`.\n\nTo correctly set the `WM_LAUNCH_ID` of an implicit factory, always run it via\n`wm-launch` with the same argument to the `-f` flag:\n\n```sh\nwm-launch -f qute id2 qutebrowser\n```\n\n### Explicit factory\n\nAn explicit window factory is a daemon that creates windows based on a client's\nrequest, e.g. `emacsd` and `emacsclient`, `urxvtd` and `urxvtc`.\n\nTo correctly set the `WM_LAUNCH_ID` of an explicit factory, run the daemon with\n`LD_PRELOAD` and `WM_LAUNCH_FACTORY`:\n\n```sh\nLD_PRELOAD=/usr/lib/wm-launch/wm-launch-preload.so WM_LAUNCH_FACTORY=emacs emacsd\n```\n\nThen launch with `wm-launch -f emacs id3 emacsclient`.\n\n## wm-launchd\n\nwm-launchd must be running to handle window factories. Enable the systemd\nservice to run when the `graphical-session.target` is reached:\n\n```sh\nsystemctl --user enable wm-launchd\n```\n\n## Workspaces\n\nWith the `-w` flag, `wm-launch` can initiate the startup of multiple clients\nbased on a `.workspace` file. The programs therein are expected to be\nlaunched by the running window manager, which must implement the\n`com.github.jcrd.wm_launch.WindowManager` DBus interface.\n\n### .workspace files\n\nA `.workspace` file contains one program per line to run.\nIf preceded by a `@`, the program will be interpreted as one defined by the\nwindow manager, otherwise the window manager should execute it directly.\n\nFor example, given:\n\n```txt\n@terminal\nxterm\n```\n\n`@terminal` should be defined by the window manager. This is useful when\nadditional context is necessary, such as running with a factory,\n`systemd-run`, etc.\n\n`xterm` should be executed directly by the window manager.\n\n### DBus interface\n\nA window manager must implement the `com.github.jcrd.wm_launch.WindowManager`\ninterface under the path `/com/github/jcrd/wm_launch/WindowManager` at the\nwell-known name `com.github.jcrd.wm_launch`.\n\nThis interface must define the `NewWorkspace` method, which takes three arguments:\n\n1. The workspace name as a string\n2. The workspace working directory as a string\n3. An array of strings representing clients to launch\n\nIt returns nothing.\n\n## systemd-run\n\nA client can be launched with `systemd-run` by running it via `wm-launch` using\nthe `-s` flag. This will run the command in a user scope with\n`systemd-run --user --scope`.\n\n## Firejail\n\nA client can be launched with [firejail](https://github.com/netblue30/firejail)\nby running it via `wm-launch` using the `-j` flag. This sets the required\nenvironment variables in the sandbox created by firejail.\n\n## Limitations\n\n* Be aware of environment variable inheritance. This becomes a problem when\n  launching a client from a terminal created by a factory, i.e.\n  `WM_LAUNCH_FACTORY` is present in its environment. The new client will inherit\n  this variable and expect the given factory to exist. This scenario can be\n  avoided by launching the client with `wm-launch -f \"\"`.\n\n## Window manager integration\n\n* Integration with Awesome WM is provided by\n  [awesome-launch](https://github.com/jcrd/awesome-launch).\n\n## Building\n\n### Dependencies\n\n* libxcb\n* libx11\n* perl\n* go\n\nBuild with `make`.\n\n### Installing\n\nInstall with `make install`.\n\n### Testing\n\nTests have additional dependencies:\n\n* xvfb\n\nRun tests locally with `make test` or use `make test-podman` to run them in a\n[supplantr/wm-launch](https://hub.docker.com/r/supplantr/wm-launch) container\nwhich includes all dependencies.\n\n*Note:* firejail [cannot](https://github.com/netblue30/firejail/issues/2579)\nrun in containers. It must be tested locally.\n\n## License\n\nwm-launch is licensed under the GNU General Public License v3.0 or later\n(see [LICENSE](LICENSE)).\n\n## Acknowledgements\n\nwm-launch-preload.c is based on\n[ld-preload-xcreatewindow-net-wm-pid](https://github.com/deepfire/ld-preload-xcreatewindow-net-wm-pid).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcrd%2Fwm-launch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcrd%2Fwm-launch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcrd%2Fwm-launch/lists"}