Weechat is an extensible chat client.
Matrix is an open network for secure, decentralized communication.
weechat-matrix-rs is a Rust plugin for Weechat that lets Weechat communicate over the Matrix protocol. This is a Rust rewrite of the weechat-matrix Python script.
This project is a work in progress and doesn't do much yet. It can connect to a Matrix server and send messages.
It is not an IRC relay or bridge: IRC clients connected through WeeChat's relay plugin cannot use Matrix rooms as IRC channels. Remote WeeChat interfaces using WeeChat relay protocols can access plugin buffers, but Matrix features that rewrite already-printed lines, such as message edits and redactions, depend on the remote client supporting WeeChat relay line-update events.
If you are interested in helping out take a look at the issue tracker.
Install Rust and the native build dependencies first. On Debian or Ubuntu a typical build environment needs:
sudo apt install build-essential clang libclang-dev libsqlite3-dev pkg-config
Other distributions use different package names, but the important native
pieces are a C/C++ compiler, clang/libclang, and SQLite development headers.
The weechat-sys dependency has a bundled WeeChat plugin header
(weechat-plugin.h) fallback. If you want to build against the exact WeeChat
API installed on your system, install the matching development package
(weechat-dev on Debian/Ubuntu) or point WEECHAT_PLUGIN_FILE at the full
path to that header:
export WEECHAT_PLUGIN_FILE=/usr/include/weechat/weechat-plugin.h
If bindgen reports that stddef.h, libclang, or libLLVM is missing, check
that the clang command-line tools, C/C++ compiler headers, and matching
libclang package are installed. On minimal distributions the library package
alone may not provide the compiler include paths that bindgen needs.
After the dependencies are installed the plugin can be compiled with:
cargo build --release
If you are developing on weechat-matrix-rs, use debug builds which are faster at the expense of plugin performance:
cargo build
On Linux this creates a libmatrix.so file in the target/release/
(target/debug for dev builds) folder. Rename it to matrix.so and copy it to
your WeeChat plugin directory.
make install installs the plugin systemwide:
sudo make install
On Debian-like multiarch systems this installs the release build to:
/usr/lib/${DEB_HOST_MULTIARCH}/weechat/plugins/matrix.so
On other systems it defaults to:
/usr/lib/weechat/plugins/matrix.so
Set WEECHAT_PLUGIN_DIR if your distribution uses another system plugin
directory:
sudo make install WEECHAT_PLUGIN_DIR=/path/to/weechat/plugins
To install only for the current user, use:
make install-user
This installs the release build to:
${XDG_DATA_HOME:-$HOME/.local/share}/weechat/plugins/matrix.so
Use PROFILE=debug for a debug build:
make install-user PROFILE=debug
The matching uninstall targets are:
sudo make uninstall
make uninstall-user
On older WeeChat setups the plugin directory may instead live under
$WEECHAT_HOME/plugins, commonly ~/.weechat/plugins/. Create the directory if
needed and copy the renamed plugin there.
On macOS the built library extension is usually .dylib. WeeChat may need this
extension enabled before it loads the plugin:
/set weechat.plugin.extension ".so,.dll,.dylib"
Rename target/release/libmatrix.dylib to matrix.dylib before copying it to
your WeeChat plugin directory.
A .deb package can be built using cargo-deb. This requires
Rust installed (via rustup, the recommended method).
First ensure cargo-deb is available:
cargo install cargo-deb
Then build the package with:
make deb
The resulting .deb package is placed in target/debian/. Install it with:
sudo dpkg -i target/debian/weechat-matrix-rs_*.deb
Restart WeeChat after installing the plugin, or load it manually:
/plugin load matrix
Check that it is loaded with:
/plugin list
If WeeChat cannot find the plugin, check that the file is named matrix.so
(matrix.dylib on macOS), that it is in a directory from WeeChat's plugin
search path, and that .so/.dylib is enabled in
weechat.plugin.extension.
Configuration is completed primarily through the Weechat interface. First start WeeChat, make sure the plugin is loaded, and then issue the following commands (replace the placeholders in brackets [] with your own details):
-
Add a server (make sure the url includes the scheme e.g. 'https://matrix.org'):
/matrix server add [server-name] [server-url] -
Set your username and password:
/set matrix-rust.server.[server-name].username [username] /set matrix-rust.server.[server-name].password [password] -
Now try to connect. The first connection can take a few minutes while the client syncs the account:
/matrix connect [server-name] -
Automatically connect to the server:
/set matrix-rust.server.[server-name].autoconnect on -
If everything works, save the configuration:
/save
To hide join/leave noise from users who have not been active recently, add a WeeChat filter for Matrix smart-filter tags:
/filter add matrix_smart * matrix_smart_filter *
The inactivity delay defaults to five minutes and can be changed with:
/set matrix-rust.look.smart_filter_delay 300000
Room buffers expose Matrix parent Spaces as WeeChat local variables. Switch to a room buffer that belongs to a Space and run:
/buffer listvar
Look for space, space_id, spaces, and space_ids. The singular variables
hold the first parent Space name and room id; the plural variables contain all
known parent Spaces as comma-separated lists.
The buflist plugin will not reorganize Matrix rooms under Spaces by itself. These variables are available to scripts and custom buflist formats. For example, to prefix Matrix room names with their first parent Space:
/set buflist.format.name "${if:${space}?${space}/${name}:${name}}"
/buflist refresh
Remove that prefix again with:
/unset buflist.format.name
The plugin keeps Matrix state and encryption data in
$WEECHAT_HOME/matrix-rust/<server>/. It keeps the Matrix SDK event cache in
$WEECHAT_HOME/matrix-rust/<server>-cache/.
If the cache grows or causes too much disk I/O, disconnect WeeChat and remove
only the -cache directory. Do not remove the main server directory unless you
want to reset stored Matrix state.
/help matrix will print information about the /matrix command.
/matrix help [command] will print information for subcommands, such as /matrix help server.
Room buffers accept normal message input after /matrix connect [server-name]
has completed.
/matrix media download <mxc-uri> [file] downloads Matrix media through the logged-in client, including homeservers that require authenticated media. It refuses to overwrite an existing file. When [file] is omitted, the media id is saved with the configured prefix, which defaults to matrix-media-:
/set matrix-rust.media.download_prefix matrix-media-
The prefix may include a directory and supports ~, $XDG_STATE_HOME, and ${XDG_STATE_HOME}. Parent directories are created automatically:
/set matrix-rust.media.download_prefix "$XDG_STATE_HOME/weechat-matrix/media/matrix-media-"