jabber.el

• Explanation
  • Differences from upstream
  • Requirements
  • Encrypted connections
  • Usage
  • Configuration
  • File transfer
  • XMPP URIs
  • Literate program
    • literate/organizational tasks [37%]
  • Debugging tips
  • fsm.el - the Finite State Machine library
  • The jabber-connection FSM
    • States
  • Stanza processing
• Tutorials
  • Installation
    • from MELPA
    • from source
• How-to guides
  • How to contribute to jabber.el
• maintenance [0%]
• Credits
  • Developers
  • Contributors
  • Maintainers

Explanation

This is jabber.el 0.8.92, an XMPP client for Emacs. XMPP (also known as 'Jabber') is an instant messaging system; see http://xmpp.org for more information.

New resources

• project page
• chat: xmpp:emacs@salas.suchat.org?join (general Emacs and jabber.el talk)
• chat: xmpp:jabber-el@conference.hmm.st?join (jabber.el developement)

Old resources

• project page
• home page
• wiki page

• mailing list:

  • http://lists.sourceforge.net/lists/listinfo/emacs-jabber-general
  • http://dir.gmane.org/gmane.emacs.jabber.general
• chat: jabber.el@conference.jabber.se and emacs@conference.jabber.ru (Russian, English)

Differences from upstream

1. (WIP) Support for XEP-0363: HTTP File Upload
2. Support for XEP-0280: Message Carbons
3. Use of the deprecated cl library is almost completely replaced with cl-lib
4. Build system changed from Autotools to a Makefile
5. Lots of cleanup by addressing checkdoc and byte-compiler warnings - addition/improvement of docstrings, function/variable declarations, etc
6. Converted to an Org literate program

Requirements

jabber.el runs on GNU Emacs 27.1 or later.

The file hexrgb.el (http://www.emacswiki.org/emacs/hexrgb.el) is needed for MUC nick coloring feature. A copy is located in the compat directory, and used if the configure script doesn't find another copy already installed.

Encrypted connections

Many Jabber servers require encrypted connections, and even if yours doesn't it may be good idea. To get an encrypted connection, the most convenient option is to use GNU Emacs 24 with GnuTLS support compiled in. You can check whether you have that by typing:

M-: (gnutls-available-p)

If that commands shows t in the echo area, then you have working GnuTLS support. If it shows nil or signals an error, then you don't.

Failing that, jabber.el will use the starttls.el library, which requires that the GnuTLS command line tool "gnutls-cli" is installed.

In Debian-based distributions, "gnutls-cli" is in the "gnutls-bin" package.

The above applies to STARTTLS connections, the most common way to encrypt a Jabber connection and the only one specified in the standards. STARTTLS connections start out unencrypted, but switch to encrypted after negotiation. jabber.el also supports connections that are encrypted from start. For this it uses the tls.el library, which requires either "gnutls-cli" or the OpenSSL command line tool "openssl" to be installed.

To use the latter form of encryption, customize jabber-account-list.

Note that only the connection from you to the server is encrypted; there is no guarantee of connections from your server to your contacts' server being encrypted.

Usage

To connect to a Jabber server, type C-x C-j C-c (or equivalently M-x jabber-connect-all) and enter your JID. With prefix argument, register a new account. You can set your JID permanently with M-x jabber-customize.

Your roster is displayed in a buffer called -jabber-. To disconnect, type C-x C-j C-d or M-x jabber-disconnect.

You may want to use the menu bar to execute Jabber commands. To enable the Jabber menu, type M-x jabber-menu.

For a less terse description, read the enclosed manual.

For bug reports, help requests and other feedback, use the trackers and forums at the project page mentioned above.

Configuration

All available configuration options are described in the manual. This section only serves to point out the most important ones.

To change how you are notified about incoming events, type M-x customize-group RET jabber-alerts.

To activate logging of all chats, set jabber-history-enabled to t. By default, history will be saved in ~/.jabber_global_message_log; make sure that this file has appropriate permissions. Type M-x customize-group RET jabber-history for more options.

By default, jabber.el will send a confirmation when messages sent to you are delivered and displayed, and also send "contact is typing" notifications. To change this, type M-x customize-group RET jabber-events, and set the three jabber-events-confirm-* variables to nil.

File transfer

This release of jabber.el contains support for file transfer. You may need to configure some variables to make it work; see the manual for details.

XMPP URIs

It is possible to make various web browsers pass links starting with "xmpp:" to jabber.el. In the ideal case, this works right after running "make install". Otherwise, see the manual, section "XMPP URIs".

Literate program

jabber.el is a literate program made using Org. Thanks to package.el limitations, we check in the tangled sources to Git. The tangled sources are what Emacs knows how to load.

Alternatively, it is possible to use literate-elisp-load-file from literate-elisp to directly load this Org literate program. This way, links to the source (e.g. xref, describe-* buffers, byte-compilation messages) take the user directly to the Org file rather than to the tangled source.

If a source block does not have syntax highlighting, press M-o M-o (font-lock-fontify-block) in it.

TODO literate/organizational tasks [37%]

1. (maybe) make dependencies optional and tangle them to separate files, reducing load time for users.
2. contemplate distribution strategies
3. make headings for remaining definitions - some FSM-related definitions remain.
4. move tests to this file (probably migrate them to ert or buttercup first), in sub-headings of their concerned components.
5. move dependencies to the Dependencies heading; also make library headers for them

6. move per-file author information and copyright notice here, and delete the empty .el files

   • But it will cease to remain applicable as soon as we move anything around…
7. "Code" has a lot of direct sub-headings, making it somewhat cumbersome to navigate; someone with a better understanding of the program could organize these better
8. The tangled file currently does not list all the other authors (currently listed in :COPYRIGHT: drawers). We could add them all at once in the library headers section…or something else. 🤔

Debugging tips

Useful tips for debugging:

• There is a buffer called *fsm-debug* that displays all transitions and errors during the event handling.
• There is a jabber-debug customization group.
• You can set the jabber-debug-log-xml custom variable to t to enable the XML debug console.
• The XML console is a buffer called *-jabber-console-ACCOUNT-* by default. Enable jabber-debug-log-xml and switch to that buffer to see the incoming and outgoing XML stanzas. See xml-console-mode.

fsm.el - the Finite State Machine library

fsm.el implements functions to define multiple finite state machines (FSM), their states, and all the events associated to each of them.

The following is a list of the most important functions or macros defined in this library:

• (define-state-machine name &key start sleep)
• (define-state fsm-name state-name arglist &body body)
• (define-enter-state fsm-name state-name arglist &body body)
• (define-fsm name &key strat sleep states ...)
• (fsm-send fsm event &optional callback)
• (fsm-call fsm event)

It is required a name and the starting state to define a new FSM. The define-state-machine creates a new function called start-NAME. Its start argument is a function argument and body definition used by the created function. The result of the new function must be a list (STATE STATE-DATA [TIMEOUT]) which is the starting state of the machine.

See jabber-connection section for an example. Its :start parameter explicitly mentioned, and its value is a list with the arguments ( (username server resource ...) ), a docstring ( "Start a jabber connection." ) and the body of the start-jabber-connection function.

The machine requires states. They are defined with the define-state function.

The jabber-connection FSM

jabber.el use a finite state machine (FSM) to track the current Jabber connection step. It defines a FSM called jabber-connection (or jc when it is used as parameter in functions) and several states along with their sentinels. The Org-mode tag :fsm: is used at jabber.org headlines to describe FSM definitions.

States

The following graph shows the states and their transitions, as of commit dddcccb926 (2021-03-20). The nodes represent the states and the arrows are events.

All states have filter and sentinel events that do not change the FSM state. Also, they have a :do-disconnect event that change the FSM to the nil state except for the connecting state.

Some state changes depend on the event and the data received, in this case, the event name has a number added. For instance, :stream-start1, :stream-start2 and :stream-start3 is the same event (:stream-start) but triggers different states changes depending on the data received.

Implemented states in the Jabber FSM.

Stanza processing

The following is a brief summary about the stanza processing.

1. The :session-established state is reached.
2. The FSM receives the event :stanza at the :session-established state.
3. If no error has been found, call jabber-process-input. See jabber-process-input section.
4. Select one of the following variables depending on the type of message received: jabber-iq-chain, jabber-presence-chain and jabber-message-chain. All of them contains a list of functions that process its type of message.
5. Call all of their functions with the jabber connection and XML data as parameters .
6. Continue in the same state.

Tutorials

Installation

from MELPA

1. Add the MELPA repositories to your Emacs - https://melpa.org/#/getting-started
2. Type M-x package-install RET jabber RET

If all goes well, jabber.el commands like jabber-connect should now be available in the M-x menu.

from source

1. Clone the repository by typing the following into a terminal -

   mkdir ~/emacs-jabber/
   cd ~/emacs-jabber/
   git clone https://codeberg.org/emacs-jabber/emacs-jabber
   make

2. Add the following lines to your init.el -

   (add-to-list 'load-path "~/emacs-jabber/")
   (load "~/emacs-jabber/jabber-autoloads")

   …and, while still in your init.el, type M-x eval-buffer RET.

If all goes well, jabber.el commands like jabber-connect should now be available in the M-x menu.

To install the Info documentation, copy jabber.info to /usr/local/info and run "install-info /usr/local/info/jabber.info".

How-to guides

How to contribute to jabber.el

1. Fork and clone the repository.

     mkdir ~/git/ && cd ~/git/
     git clone https://codeberg.org/YOUR-ACCOUNT/emacs-jabber

   • You can also send patches to wgreenhouse@tilde.club, using git-send-email. In that case, no forking is necessary.

2. Install development dependencies.

   1. Ensure you have Org mode v9.3.8 or higher. If necessary, install from source -

        git clone https://code.orgmode.org/bzg/org-mode.git
        cd ~/git/org-mode/
        make

   2. Optionally, evaluate the following to install additional development tools (requires MELPA to be set up as package source) -

        (mapcar #'package-install
                '(indent-lint package-lint relint nameless literate-elisp))

3. Make your edits to jabber.org (not jabber.el), and save. Then, tangle the file -

   M-x compile RET make -Bk RET

   • If you installed Org from source, be sure to mention the ORG_PATH -

     M-x compile RET ORG_PATH=/path/to/org/source/lisp/ make -Bk RET

   • If you don't like working with literate programs, just edit jabber.el and we'll incorporate your PR into jabber.org.

   This tangles the literate program and byte compiles the tangled sources. Try to address any byte compilation errors.

   You can also run make dev to tangle, compile, and run linters in one go, and address their output.

   Stage the changes you made to jabber.org, as well as any changes the tangling process made to jabber.el.

   Try to follow the seven rules of a great Git commit message in your commits.

4. Update the documentation.

   1. Add your name to the list of contributors.
   2. Document user-facing changes in CHANGELOG.org.
   3. Update or add other documentation in this README.org if necessary. Try to follow the Diataxis Framework.
5. Push and create your PR.

TODO maintenance [0%]

1. Satisfy M-x checkdoc

2. Use rx where regular expressions get hairy

   • jabber-jid-username
   • jabber-jid-server
   • jabber-jid-resource
3. hexrgb.el is not available on MELPA
4. Migrate tests to ERT/Buttercup/etc
5. Add Windows support to developer tutorial
6. Create testing for tutorial

Credits

Developers

• Tom Berger
• Magnus Henoch
• Kirill A. Korinskiy

• Detlev Zundel

  • wmii support
• Evgenii Terechkov

Contributors

• Georg Lehner

  • network transport functions
• Anthony Chaumas-Pellet
• Jérémy Compostella

• Mathias Dahl

  • history logging
  • watch functionality

• Mario Domenech Goulart

  • sawfish support
  • xmessage support
• Nolan Eakins

• Ami Fischman

  • Chat State Notifications
• François Fleuret
• David Hansen

• Adam Sjøgren

  • notifications.el support

• Rodrigo Lazo

  • notifications.el support
  • libnotify.el support
• Justin Kirby

• Carl Henrik Lunde

  • network transport functions
  • activity tracking
• Olivier Ramonat
• Andrey Slusar

• Valery V. Vorotyntsev

  • GMail notifications
• Milan Zamazal
• Xavier Maillard
• Vitaly Mayatskikh
• Alexander Solovyov

• Demyan Rogozhin

  • XML console mode

• Michael Cardell Widerkrantz

  • tmux support

• Case Duckworth (acdw)

  • PR #2

Maintainers

• wgreenhouse

  • 2021 resurrection

• cngimenez

  • HTTP Upload support
  • documentation for FSM and its use in this project

• contrapunctus

  • literate Org migration
  • Makefile (shoutout to tomasino of #team@irc.tilde.chat for the Makefile-debugging help)