|Ian Eure 0b6fc2af34||5 months ago|
|README.md||2 years ago|
|README_src.org||2 years ago|
|debase--test.el||2 years ago|
|debase-gen--test.el||2 years ago|
|debase-gen.el||10 months ago|
|debase-objectmanager.el||5 months ago|
|debase.el||5 months ago|
|sorry.jpg||4 years ago|
Debase, the D-Bus convenience layer for Emacs
D-Bus is an IPC system which is ubiquitous on Linux, and (in this author’s opinion) not very good. Emacs has bindings for interfacing with it (see the former point), which are annoying to use (see the latter point).
These days, numerous common system management tasks are implemented as D-Bus services rather than tradidional executables, and many of the command-line tools themselves are now front-ends which communicate via D-Bus. Mounting and unmounting disks, monitoring battery status, controlling display brightness, connecting to wireless networks and more are now handled with D-Bus services.
It makes no sense to shell out to the tools when one could interact with them directly via D-Bus, if only it was less annoying to do so.
Debase frees you from writing repetitive, annoying boilerplate code to drive D-Bus services by throwing another pile of abstraction at the problem, in the form of unreadably dense, macro-heavy, profoundly cursed Lisp.
D-Bus Crash Course
Bus. A bus contains services; D-Bus can manage many different busses, but the two standard ones are:
- System bus. This generally has hardware-interfacing and system management services.
- Session bus. This is private to the current session, i.e. a logged-in user.
Services. A service exists on a bus, and is a set of information and operations offered by a program. Example:
org.bluezon the system bus is the service which manages Bluetooth.
Objects. An object exists within a service, and typically represents a resource it manages. Objects are identified by paths; paths are namespaced under the service. Example:
/org/bluez/hci0/dev_01_23_45_67_89_ABis the path to an object representing a specific Bluetooth device. Because this is part of the service, that path doesn’t represent anything in a different service, like
Interfaces. An interface is a view into the capabilities of an object. Objects can (and almost always do) support multiple interfaces. Example:
org.bluez.Device1is a general interface for managing pairing/unpairing/connecting/disconnecting from Bluetooth devices;
org.bluez.MediaControl1is an interface for media devices, such as speakers or speakerphones. Since
/org/bluez/hci0/dev_01_23_45_67_89_ABis a media device, it supports both interfaces.
Properties. A property is a value attached to an interface, which exposes information about an object. For example, the
Nameproperty in the
/org/bluez/hci0/dev_01_23_45_67_89_ABis "Bluetooth Speaker" — the name of the device. Properties can be read/write, read-only, or write-only.
Methods. A method is a remote function call attached to an interface. For example, the
VolumeUp()method in the
org.bluez.MediaControl1interface of object
org.bluezservice of the system bus increases the volume of "Bluetooth Speaker." Methods can take arguments and return values.
Signals. D-Bus enabled applications can generate and respond to signals. A signal represents some kind of event, such as hardware being plugged in or unplugged.
Common interfaces. Most D-Bus objects support some common interfaces:
org.freedesktop.DBus.Introspectable. Allows retrieving the schema for the object as XML. It has all the interfaces it supports, as well as their properties and methods.
org.freedesktop.DBus.Peer. Provides a
org.freedesktop.DBus.Properties. An interface which exposes object properties, and provides signals so other D-Bus applications receive notifications of changes to them.
org.freedesktop.DBus.ObjectManager. Used by D-Bus applications which manage other D-Bus objects. For example, the
ObjectManager, which can be used to enumerate connected Bluetooth devices. It also provides signals when managed objects are added or removed.
Debase defines a
DEBASE-OBJECT EIEIO base class, which acts as a proxy between Emacs Lisp and the D-Bus service. A
DEBASE-OBJECT maps 1:1 with a D-Bus object, and stores the bus, service, path, and (optionally) interface of that object.
(setf upower (debase-object :bus :system :service "org.freedesktop.UPower" :path "/org/freedesktop/UPower" :interface "org.freedesktop.UPower"))
Since many D-Bus objects use identical (or readily computable) values for service, path, and interface, you may omit the path and/or interface, and Debase will fill them in with what seem like reasonable values. The
DEBASE-TARGET function will return a plist of these values, whether computed or provided explicitly.
(debase-object-target (debase-object :bus :system :service "org.freedesktop.UPower"))
(:bus :system :service "org.freedesktop.UPower" :path "/org/freedesktop/UPower" :interface "org.freedesktop.UPower")
(debase-object-target (debase-object :bus :system :service "org.freedesktop.UDisks2" :interface "org.freedesktop.UDisks2.Manager"))
Debase also provides generic functions which mirror the ones in
dbus.el, but take a single
DEBASE-OBJECT instance instead of the bus/service/path/interface. So instead of slogging through a dozen lengthy variations:
(list (dbus-get-property :system "org.freedesktop.UDisks2" "/org/freedesktop/UDisks2/Manager" "org.freedesktop.UDisks2.Manager" "Version") (dbus-get-property :system "org.freedesktop.UDisks2" "/org/freedesktop/UDisks2/Manager" "org.freedesktop.UDisks2.Manager" "SupportedFilesystems"))
You can set a single object and use it over and over:
(let ((udisks2-manager (debase-object :bus :system :service "org.freedesktop.UDisks2" :interface "org.freedesktop.UDisks2.Manager"))) (list (debase-get-property udisks2-manager "Version") (debase-get-property udisks2-manager "SupportedFilesystems")))
DBUS- prefix of most
dbus.el function names with
DEBASE- should work, for example
DEBASE-GET-PROPERTY instead of
Many times, you’ll need to change the interface or path of a
DEBASE-OBJECT, either to access a different facet of the object, or to access another object within the same service. EIEIO’s
CLONE function makes it easy to swap out any part of the targeted object:
(let* ((block (debase-object :bus :system :service "org.freedesktop.UDisks2" :path "/org/freedesktop/UDisks2/block_devices/sda1" :interface "org.freedesktop.UDisks2.Block")) (block-dev (substring (apply #'string (debase-object-get block "Device")) 0 -1)) (partition (clone block :interface "org.freedesktop.UDisks2.Partition"))) (list block-dev (debase-object-get partition "UUID")))
Even though Debase makes this easier, many D-Bus methods require additional type wrangling or conversion to be used comfortably. For these cases, you should subclass
DEBASE-OBJECT and write more specialized methods.
(defclass udisks2-block (debase-object) ()) (cl-defmethod initialize-instance :after ((this udisks2-block) &rest ignore) (with-slots (bus service interface) this (setf bus :system service "org.freedesktop.UDisks2" interface "org.freedesktop.UDisks2.Block"))) (cl-defmethod udisks2-block-preferred-device ((this udisks2-block)) "Returns the preferred device for `UDISKS2-BLOCK' object THIS." (substring (apply #'string (debase-object-get this "Device")) 0 -1)) (let ((block (udisks2-block :path "/org/freedesktop/UDisks2/block_devices/sda1"))) (udisks2-block-preferred-device block))
Debase provides a
DEBASE-OBJECTMANAGER class which interacts with the
org.freedesktop.DBus.ObjectManager interface. It maintains a local cache of managed objects, which is populated on instantiation and automatically updated when one is added or removed.
If a class inherits from it, accessing the
MANAGED-OBJECTS slot will return the currently managed objects.
It can also dispatch notifications when the list of managed objects changes.
- Support for providing D-Bus services from Emacs (which non-Emacs programs could invoke) is not supported.
Code Generation (Experimental)
Debase also offers a code generation facility, which turns the XML D-Bus interface descriptions into EIEIO classes. The intent is to eliminate the drudgery of building the code that interacts with D-Bus, so you can focus on making it do interesting things instead.
This is an experimental feature, and while I think it might be a good idea, I’ve struggled with usability for actual projects. Feedback and/or code welcomed.
Codegen is implemented as a hierarchy of EIEIO classes which extend the
DEBASE-GEN base class, and provide a
DEBASE-GEN-CODE generic functions which produce the desired output. The
DEBASE-GEN-CLASS class is the main entrypoint.
(thread-first (debase-gen-class :bus :system :service "org.freedesktop.UDisks2" :interface "org.freedesktop.UDisks2.Manager" :class-name 'udisks2-manager) debase-gen-code)
To make generated code more pleasant,
DEBASE-GEN mangles D-Bus names into ones that are Lispier. The default mangling is handled by
DEBASE-GEN-MANGLE, but you can supply your own functions for properties, methods, and argument names.
For example, to leave method and argument names untouched, and prefix properties with "Prop":
(thread-first (debase-gen-class :bus :system :service "org.freedesktop.UDisks2" :interface "org.freedesktop.UDisks2.Manager" :class-name 'udisks2-manager :property-mangle (debase-gen-mangle-prefix "Prop") :method-mangle #'identity) debase-gen-code)
Fully representing a D-Bus object with EIEIO classes means generating one class for each interface it has, then creating a new class which inherits from all of them.
I haven’t found a nice way of making this easy yet, so you’re on your own.