#+TITLE: jabber.el - The XMPP client for Emacs

* About
[[https://elpa.nongnu.org/nongnu/jabber.svg]]

=jabber.el= is an [[http://xmpp.org][XMPP]] client for Emacs.

See the [[https://xmpp.org/software/jabber-el/][xmpp.org page]] for the full list of supported XEPs.

+ [[https://thanosapollo.org/projects/jabber/][Homepage]]

+ Source:
  + [[https://git.thanosapollo.org/emacs-jabber/][Upstream]]
  + [[https://codeberg.org/emacs-jabber/emacs-jabber/][Codeberg]] /Mirror/

* Requirements

+ Emacs 29.1 or later, compiled with dynamic module support

** OMEMO encryption (optional)

OMEMO end-to-end encryption requires building a native C module.  You
need a C compiler, =pkg-config=, and =libmbedtls= (development
headers).

If you installed from source (=:vc= or =git clone=), Emacs will offer
to fetch the [[https://github.com/mierenhoop/picomemo][picomemo]] dependency and build the module on first load.

If you installed from ELPA, clone the repository and build manually:

#+begin_src sh
  git clone https://git.thanosapollo.org/emacs-jabber/
  cd emacs-jabber
  make module
#+end_src

Then copy the resulting =jabber-omemo-core.so= (or =.dylib= on
macOS) into your ELPA package directory, which is already on
=load-path=:

#+begin_src sh
  cp lisp/jabber-omemo-core.so ~/.emacs.d/elpa/jabber-VERSION/
#+end_src

* Installation
=jabber.el= is available via [[https://elpa.nongnu.org/nongnu/jabber.html][NonGNU ELPA]].

You can install it via =M-x package-install RET jabber=

** package-vc (Emacs 30+)

#+begin_src emacs-lisp
  (use-package jabber
    :ensure nil
    :vc (:url "https://git.thanosapollo.org/emacs-jabber/"
              :branch "master"
              :rev :newest
              :lisp-dir "lisp")
    :custom
    (jabber-account-list '(("user@example.org")))
    :config
    (jabber-modeline-mode 1)
    :bind-keymap (("C-x C-j" . jabber-global-keymap))
    :hook (kill-emacs . jabber-disconnect))
#+end_src

** GNU Guix

The repository ships a =guix.scm= that builds straight from the
current working tree, so you never need to update hashes or pin a
commit.  Whatever is checked out is what gets installed.  Picomemo is
fetched as a pinned input by =guix.scm=, so the optional OMEMO
submodule does not need to be initialised.

#+begin_src sh
  git clone https://git.thanosapollo.org/emacs-jabber/
  cd emacs-jabber
#+end_src

One-shot install into your user profile:

#+begin_src sh
  guix package -f guix.scm
#+end_src

A development shell with all build dependencies:

#+begin_src sh
  guix shell -D -f guix.scm
#+end_src

To use =emacs-jabber= from a Guix Home configuration, load the
package definition and reference it from your services:

#+begin_src scheme
  (use-modules (gnu home)
               (gnu home services)
               (gnu home services guix)
               (gnu services)
               (guix channels)
               (guix gexp))

  (define emacs-jabber-git
    (load "/path/to/emacs-jabber/guix.scm"))

  (home-environment
   (packages (list emacs-jabber-git)))
#+end_src

Re-run =guix home reconfigure= after pulling new commits and the
package will be rebuilt from the updated checkout.

* Configuration

Accounts are configured via =jabber-account-list=.  The simplest form
uses auth-source =~/.authinfo.gpg= for passwords:

#+begin_src emacs-lisp
  (setq jabber-account-list '(("user@example.org")
                               ("second@account.org")))
#+end_src

With =pass= (password-store):

#+begin_src emacs-lisp
  (setq jabber-account-list
        `(("user@example.org"
           (:password . ,(auth-source-pass-get 'secret "xmpp/example.org/user")))))
#+end_src

* Basic commands

| Key                  | Command                          |
|----------------------+----------------------------------|
| =M-x jabber-connect= | Connect (prompts for account)    |
| =C-x C-j C-c=        | Connect all accounts             |
| =C-x C-j C-d=        | Disconnect                       |
| =C-x C-j C-r=        | Open roster buffer               |
| =C-x C-j C-j=        | Start or switch to a chat        |
| =C-x C-j C-m=        | Join/switch to a MUC (groupchat) |
| =C-x C-j C-b=        | Switch to a chat buffer          |
