rust-wlc

Rust bindings for wlc, the Wayland compositor library.

Requires wlc v0.0.2.

Rust Example

// For more functional example see example/src/main.rs

extern crate rustwlc;
use rustwlc::types::*;
use rustwlc::callback;
use rustwlc::WlcView;

// Callbacks must be labeled extern as they will be called from C
extern "C" fn view_created(view: WlcView) -> bool {
    view.bring_to_front();
    view.focus();
    return true;
}

extern "C" fn view_focus(view: WlcView, focused: bool) {
    view.set_state(VIEW_ACTIVATED, focused);
}

fn main() {
    callback::view_created(view_created);
    callback::view_focus(view_focus);

    // The default log handler will print wlc logs to stdout
    rustwlc::log_set_default_handler();
    let run_fn = rustwlc::init().expect("Unable to initialize!");
    run_fn();
}

Usage

We're on crates.io, so to use the library simply add:

[depdenencies]
rustwlc = "^0.3.1"

to your Cargo.toml.

You also need to setup the wlc library so that rust-wlc can see it. If you simply install the library, that will be sufficient.

If you are looking to use a custom version of wlc (to ensure compatiblity by building against a specific version or to build the library with debug symbols for example), then you simply need to set the LD_LIBRARY_PATH environment variable to the full path of the share library object file (.so). To verify that the correct shared library is seen by rust-wlc, use the ldd utility to view the full paths of shared libraries, the entry that starts with "libwlc.so" should point to your custom path.

So if you wlc install is at /opt/wlc, then the full path will probably be /opt/wlc/target/src. Notice that we only include the directory that containts the .so, not the .so itself. For more information on using DLLs in Linux, see this link.

Documentation

At the moment, we have Cargo documentation hosted at our github.io site. You can also generate it with cargo doc:

$ git clone "https://github.com/ImmingtonIndustries/rust-wlc.git"
$ cd rust-wlc
$ cargo doc

If the documentation isn't clear enough or in the wrong places, please let us know.

Safety

rust-wlc is written to be a clean Rust wrapper around wlc. While we've taken the liberty to make the code more Rust-friendly (such as creating instance methods for WlcView and WlcOutput), but we did not try to extend wlc itself.

The callbacks registered in callbacks must be labeled extern (or extern "C") because they are called from C code. In addition, as per the Rust spec, panicking from C is undefined behavior (although it's worked for us).

Compositors using rust-wlc can do so without any unsafe code. The only exception to this is registering a callback for wlc's logging function exposed through rustwlc::log_set_handler (the callback must take in a *const libc::c_char). We have provided a println!-powered default enabled with rustwlc::log_set_default_handler(). In addition, the methods get_user_data and set_user_data in WlcView and WlcOutput are unsafe because they use C raw types (void*) underneath, and proper usage requires a deeper understanding of wlc itself.

Contributing