aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 933c988efb882d34c340945d37f610cf58d74a7a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
xdg_pipe_menu
=====

Openbox pipemenu generator from XDG .desktop files

Build
-----

    $ rebar3 compile

Live-reload (rebuilding the menu when `.desktop` files change) uses
the `fs` library, which on Linux shells out to `inotifywait`. Install
the `inotify-tools` package for this to work; without it the daemon
still serves the menu it built at startup, it just won't notice
later changes until restarted.

Running locally
----------------

The app is a long-running daemon: it scans your XDG application
directories once at startup, caches the rendered menu in memory, and
serves it over a Unix domain socket at
`$XDG_RUNTIME_DIR/xdg_pipe_menu.sock` (falling back to
`/tmp/xdg_pipe_menu-$USER.sock` if `XDG_RUNTIME_DIR` isn't set),
rebuilding the cache whenever a watched `.desktop` file changes.

For a quick manual run (e.g. while developing):

    $ rebar3 shell --eval "application:ensure_all_started(xdg_pipe_menu)."

To run it as a service, build a production release (a self-contained
directory with its own copy of the Erlang runtime):

    $ rebar3 as prod release

This produces `_build/prod/rel/xdg_pipe_menu`. Re-run the command
after pulling changes, then restart the service. To start it with
your session, add a systemd user unit, e.g.
`~/.config/systemd/user/xdg-pipe-menu.service`:

    [Unit]
    Description=XDG pipe menu daemon

    [Service]
    ExecStart=/path/to/xdg-pipe-menu/_build/prod/rel/xdg_pipe_menu/bin/xdg_pipe_menu foreground
    Restart=on-failure

    [Install]
    WantedBy=default.target

then enable it with `systemctl --user enable --now xdg-pipe-menu`.

The running node is named `xdg_pipe_menu@localhost` and only accepts
Erlang distribution connections from localhost, using the cookie in
`~/.erlang.cookie` (see `config/vm.args`). That lets you manage it with
the release script:

    $ _build/prod/rel/xdg_pipe_menu/bin/xdg_pipe_menu ping
    $ _build/prod/rel/xdg_pipe_menu/bin/xdg_pipe_menu remote_console

Openbox itself doesn't talk to the socket directly -- it invokes
`bin/xdg_pipe_menu_menu` as the pipe menu command, which connects
to the daemon's socket and prints whatever comes back (or, if the
daemon isn't running, falls back to scanning/rendering inline so the
menu still works). Point a pipe menu at it in `~/.config/openbox/menu.xml`:

    <menu id="apps" label="Applications" execute="/path/to/xdg-pipe-menu/bin/xdg_pipe_menu_menu" />

The script resolves its own location to find the compiled code, so
it works from an absolute path as long as the repo's `_build`
directory (from `rebar3 compile`) is alongside it.