                ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                 JABBER.EL - THE XMPP CLIENT FOR EMACS
                ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


1 About
═══════

  <https://elpa.nongnu.org/nongnu/jabber.svg>

  `jabber.el' is an [XMPP] client for Emacs.

  See the [xmpp.org page] for the full list of supported XEPs.

  ⁃ [Homepage]

  ⁃ Source:
    ⁃ [git.thanosapollo.org]


[XMPP] <http://xmpp.org>

[xmpp.org page] <https://xmpp.org/software/jabber-el/>

[Homepage] <https://thanosapollo.org/projects/jabber/>

[git.thanosapollo.org]
<https://git.thanosapollo.org/emacs-jabber/about/>


2 Requirements
══════════════

  ⁃ Emacs 29.1 or later, compiled with dynamic module support
  ⁃ [fsm] 0.2.0 or later
  ⁃ [keymap-popup] 0.2 or later


[fsm] <https://elpa.gnu.org/packages/fsm.html>

[keymap-popup] <https://elpa.gnu.org/packages/keymap-popup.html>

2.1 OMEMO encryption (optional)
───────────────────────────────

  OMEMO end-to-end encryption uses a native C module built from the
  vendored [picomemo] source.  Build dependencies: a C compiler,
  `pkg-config', and Mbed TLS 3.0 or later (`mbedcrypto').

  Build the module manually from the jabber source or ELPA/package
  directory:

  ┌────
  │ cd /path/to/jabber-source-or-elpa-dir
  │ make module
  └────

  The resulting `jabber-omemo-core.so' (or `.dylib' on macOS) lands
  beside the Elisp files and is loaded automatically.  If the module is
  missing, OMEMO use signals `OMEMO module not compiled'.


[picomemo] <https://github.com/mierenhoop/picomemo>


3 Installation
══════════════

  `jabber.el' is available via [NonGNU ELPA].

  You can install it via `M-x package-install RET jabber'


[NonGNU ELPA] <https://elpa.nongnu.org/nongnu/jabber.html>

3.1 package-vc (Emacs 30+)
──────────────────────────

  Emacs honors package-vc build commands such as `:make' only when
  `package-vc-allow-build-commands' allows the package.

  ┌────
  │ (setq package-vc-allow-build-commands '(jabber))
  │ 
  │ (use-package jabber
  │   :ensure nil
  │   :vc (:url "https://git.thanosapollo.org/emacs-jabber"
  │             :branch "master"
  │             :rev :newest
  │             :lisp-dir "lisp"
  │             :doc "README.org"
  │             :make "module")
  │   :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))
  └────


3.2 straight.el
───────────────

  ┌────
  │ (use-package jabber
  │   :straight `(jabber
  │               :type git
  │               :host nil
  │               :repo "https://git.thanosapollo.org/emacs-jabber"
  │               :branch "master"
  │               :files ("lisp/*.el"
  │                       "lisp/jabber-omemo-core.so"
  │                       "lisp/jabber-omemo-core.dylib")
  │               :pre-build ,(pcase system-type
  │                             ('berkeley-unix '(("gmake" "module" "CC=clang")))
  │                             ('darwin '(("make" "module" "CC=clang")))
  │                             (_ '(("make" "module")))))
  │   :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))
  └────


3.3 Nix
───────

  The repository ships a `flake.nix' with Emacs, test, lint, and
  native-module build dependencies.

  ┌────
  │ make test
  │ make module
  └────

  To enter the same environment manually:

  ┌────
  │ nix develop
  └────

  To run the isolated Nix checks:

  ┌────
  │ nix flake check
  └────


4 Configuration
═══════════════

4.1 Authentication
──────────────────

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

  ┌────
  │ (setq jabber-account-list '(("user@example.org")
  │                              ("second@account.org")))
  └────

  With `pass' (password-store):

  ┌────
  │ (setq jabber-account-list
  │       `(("user@example.org"
  │          (:password . ,(auth-source-pass-get 'secret "xmpp/example.org/user")))))
  └────


4.2 SOCKS5 proxy
────────────────

  An account can connect through an unauthenticated SOCKS5 proxy:

  ┌────
  │ (setq jabber-account-list
  │       '(("user@example.org"
  │          (:proxy . (:type socks5 :host "127.0.0.1" :port 9050)))))
  └────

  The destination hostname is sent to the proxy rather than resolved
  locally.  Proxy connections bypass SRV lookup and use the JID domain
  on port 5222, or `:network-server' and `:port' when those are
  configured.  STARTTLS is supported.  Direct TLS discovery, proxy
  authentication, and other proxy protocols are not supported for
  proxied accounts.


4.3 Bug references
──────────────────

  ┌────
  │ (add-hook 'jabber-chat-mode-hook #'bug-reference-mode)
  │ 
  │ ;; Customize references
  │ (setq jabber-bug-reference-alist
  │       '(("jabber-el@conference\\.hmm\\.st"
  │          "\\(#\\([0-9]+\\)\\)"
  │          "https://todos.thanosapollo.org/r/emacs-jabber/%s")))
  └────


5 Basic commands
════════════════

  ⁃ Use `M-x jabber-roster' or `C-x C-j C-r' to get started.
