Author: Sébastien Helleu

# WeeChat developer’s guide

Sébastien Helleu
flashcode@flashtux.org
version 4.9.4

This manual documents WeeChat chat client, it is part of WeeChat.

Latest version of this document can be found on this page ↗.

## 1. Introduction

WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and light, designed for many operating systems.

This manual documents WeeChat internals:

- repositories

- coding rules

- core internals

- plugin internals

- how to contribute to WeeChat.

## 2. Repositories

WeeChat repositories are on GitHub organization weechat ↗.

List of repositories:

weechat

  core repository with source code and documentation

scripts

  the official scripts submitted on weechat.org

weechat.org

  source of WeeChat website ↗

weercd

  IRC testing server

qweechat

  Qt remote GUI for WeeChat.

This manual documents only weechat repository.

### 2.1. Overview

The main WeeChat directories are:

Directory | Description
--- | ---
`src/` | Root of sources.
`core/` | Core functions: entry point, internal structures.
`hook/` | Hook functions.
`gui/` | Functions for buffers, windows, …​ (used by all interfaces).
`curses/` | Curses interface.
`headless/` | Headless mode (no interface).
`normal/` | Curses interface.
`plugins/` | Plugin and scripting API.
`alias/` | Alias plugin.
`buflist/` | Buflist plugin.
`charset/` | Charset plugin.
`exec/` | Exec plugin.
`fifo/` | Fifo plugin (FIFO pipe used to remotely send commands to WeeChat).
`fset/` | Fset (Fast Set) plugin.
`guile/` | Guile (scheme) scripting API.
`irc/` | IRC (Internet Relay Chat) plugin.
`javascript/` | JavaScript scripting API.
`logger/` | Logger plugin (write messages displayed to files).
`lua/` | Lua scripting API.
`perl/` | Perl scripting API.
`php/` | PHP scripting API.
`python/` | Python scripting API.
`relay/` | Relay plugin (irc proxy + relay for remote interfaces).
`ruby/` | Ruby scripting API.
`script/` | Script manager.
`spell/` | Spell plugin.
`tcl/` | Tcl scripting API.
`trigger/` | Trigger plugin.
`typing/` | Typing plugin.
`xfer/` | Xfer plugin (IRC DCC file/chat).
`tests/` | Tests.
`fuzz/` | Fuzz testing.
`core/` | Fuzz testing for core functions.
`unit/` | Unit tests.
`core/` | Unit tests for core functions.
`hook/` | Unit tests for hook functions.
`gui/` | Unit tests for interfaces functions.
`curses/` | Unit tests for Curses interface functions.
`scripts/` | Scripting API tests.
`python/` | Python scripts to generate and run the scripting API tests.
`plugins/` | Unit tests for plugins.
`alias/` | Unit tests for alias plugin.
`irc/` | Unit tests for IRC plugin.
`logger/` | Unit tests for logger plugin.
`relay/` | Unit tests for relay plugin.
`trigger/` | Unit tests for trigger plugin.
`typing/` | Unit tests for typing plugin.
`xfer/` | Unit tests for xfer plugin.
`doc/` | Documentation.
`po/` | Translations files (gettext).
`debian/` | Debian packaging.

### 2.2. Sources

#### Core

WeeChat "core" is located in following directories:

- src/core/: core functions (for data manipulation)

- src/gui/: functions about interface (buffers, windows, …​)

Path/file | Description
--- | ---
`core/` | Core functions: entry point, internal structures.
`core-args.c` | Command-line arguments.
`core-arraylist.c` | Array lists.
`core-backtrace.c` | Display a backtrace after a crash.
`core-calc.c` | Calculate result of expressions.
`core-command.c` | WeeChat core commands.
`core-completion.c` | Default completions.
`core-config-file.c` | Configuration file management.
`core-config.c` | Configuration options for WeeChat core (file weechat.conf).
`core-crypto.c` | Cryptographic functions.
`core-debug.c` | Some debug functions.
`core-doc.c` | Build of files for documentation.
`core-dir.c` | Directory/file functions.
`core-eval.c` | Evaluation of expressions with references to internal vars.
`core-hashtable.c` | Hashtables.
`core-hdata.c` | Hdata (direct access to data using hashtables).
`core-hook.c` | Hooks.
`core-infolist.c` | Infolists (lists with objects data).
`core-input.c` | Input of commands/text.
`core-list.c` | Sorted lists.
`core-log.c` | Write to WeeChat log file (weechat.log).
`core-network.c` | Network functions (connection to servers/proxies).
`core-proxy.c` | Proxy management.
`core-secure.c` | Secured data functions.
`core-secure-buffer.c` | Secured data buffer.
`core-secure-config.c` | Secured data options (file sec.conf).
`core-signal.c` | Signal functions.
`core-string.c` | Functions on strings.
`core-sys.c` | System functions.
`core-upgrade-file.c` | Internal upgrade system.
`core-upgrade.c` | Upgrade for WeeChat core (buffers, lines, history, …​).
`core-url.c` | URL transfer (using libcurl).
`core-utf8.c` | UTF-8 functions.
`core-util.c` | Some other functions.
`core-version.c` | Functions for WeeChat version.
`weechat.c` | Main functions: command line options, startup.
`hook/` | Hook functions.
`hook-command-run.c` | Hook "command_run".
`hook-command.c` | Hook "command".
`hook-completion.c` | Hook "completion".
`hook-config.c` | Hook "config".
`hook-connect.c` | Hook "connect".
`hook-fd.c` | Hook "fd".
`hook-focus.c` | Hook "focus".
`hook-hdata.c` | Hook "hdata".
`hook-hsignal.c` | Hook "hsignal".
`hook-info-hashtable.c` | Hook "info_hashtable".
`hook-info.c` | Hook "info".
`hook-infolist.c` | Hook "infolist".
`hook-line.c` | Hook "line".
`hook-modifier.c` | Hook "modifier".
`hook-print.c` | Hook "print".
`hook-process.c` | Hook "process".
`hook-signal.c` | Hook "signal".
`hook-timer.c` | Hook "timer".
`hook-url.c` | Hook "url".
`gui/` | Functions for buffers, windows, …​ (used by all interfaces).
`gui-bar-item.c` | Bar items.
`gui-bar-window.c` | Bar windows.
`gui-bar.c` | Bars.
`gui-buffer.c` | Buffers.
`gui-chat.c` | Chat functions (display message, …​).
`gui-color.c` | Color functions.
`gui-completion.c` | Completion on command line.
`gui-cursor.c` | Cursor mode (free movement of cursor).
`gui-filter.c` | Filters.
`gui-focus.c` | Functions about focus (for cursor mode and mouse).
`gui-history.c` | Commands/text saved in buffers.
`gui-hotlist.c` | Hotlist management (list of buffers with activity).
`gui-input.c` | Input functions (input bar).
`gui-key.c` | Keyboard functions.
`gui-layout.c` | Layout.
`gui-line.c` | Lines in buffers.
`gui-mouse.c` | Mouse.
`gui-nick.c` | Nick functions.
`gui-nicklist.c` | Nicklist in buffers.
`gui-window.c` | Windows.
`curses/` | Curses interface.
`gui-curses-bar-window.c` | Display in bar windows.
`gui-curses-chat.c` | Display in chat area (messages).
`gui-curses-color.c` | Color functions.
`gui-curses-key.c` | Keyboard functions (default keys, read of input).
`gui-curses-main.c` | WeeChat main loop (waiting for keyboard/network events).
`gui-curses-mouse.c` | Mouse.
`gui-curses-term.c` | Functions about terminal.
`gui-curses-window.c` | Windows.
`headless/` | Headless mode (no interface).
`main.c` | Entry point for headless mode.
`ncurses-fake.c` | Fake ncurses library.
`normal/` | Curses interface.
`main.c` | Entry point for Curses interface.

#### Plugins

Path/file | Description
--- | ---
`plugins/` | Root of plugins.
`plugin.c` | Plugins management (load/unload dynamic C libraries).
`plugin-api.c` | Extra functions for plugin API (wrapper around WeeChat core functions).
`plugin-api-info.c` | Extra info/infolist functions for plugin API.
`plugin-config.c` | Plugin configuration options (file plugins.conf).
`plugin-script.c` | Common functions used by script plugins.
`plugin-script-api.c` | Script API functions: wrappers around some plugin API functions.
`plugin-script-config.c` | Script plugin configuration options (files python.conf, perl.conf, …​).
`weechat-plugin.h` | Header designed to be distributed with WeeChat plugins, in order to compile them.
`alias/` | Alias plugin.
`alias.c` | Main alias functions.
`alias-command.c` | Alias commands.
`alias-completion.c` | Alias completions.
`alias-config.c` | Alias config options (file alias.conf).
`alias-info.c` | Alias info/infolists/hdata.
`spell/` | Spell checker plugin.
`spell.c` | Main spell checker functions.
`spell-bar-item.c` | Spell checker bar items.
`spell-command.c` | Spell checker commands.
`spell-completion.c` | Spell checker completions.
`spell-config.c` | Spell checker config options (file spell.conf).
`spell-info.c` | Spell checker info/infolists/hdata.
`spell-speller.c` | Spellers management.
`buflist/` | Buflist plugin.
`buflist.c` | Main buflist functions.
`buflist-bar-item.c` | Buflist bar items.
`buflist-command.c` | Buflist commands.
`buflist-completion.c` | Buflist completions.
`buflist-config.c` | Buflist config options (file buflist.conf).
`buflist-info.c` | Buflist info/infolists/hdata.
`buflist-mouse.c` | Buflist mouse actions.
`charset/` | Charset plugin.
`charset.c` | Charset functions.
`exec/` | Exec plugin.
`exec.c` | Main exec functions.
`exec-buffer.c` | Exec buffer.
`exec-command.c` | Exec commands.
`exec-completion.c` | Exec completions.
`exec-config.c` | Exec config options (file exec.conf).
`fifo/` | Fifo plugin.
`fifo.c` | Main fifo functions.
`fifo-command.c` | Fifo commands.
`fifo-config.c` | Fifo config options (file fifo.conf).
`fifo-info.c` | Fifo info/infolists/hdata.
`fset/` | Fset plugin.
`fset.c` | Main fset functions.
`fset-bar-item.c` | Fset bar items.
`fset-buffer.c` | Fset buffer.
`fset-command.c` | Fset commands.
`fset-completion.c` | Fset completions.
`fset-config.c` | Fset config options (file fset.conf).
`fset-info.c` | Fset info/infolists/hdata.
`fset-mouse.c` | Fset mouse actions.
`fset-option.c` | Fset options management.
`guile/` | Guile (scheme) plugin.
`weechat-guile.c` | Main guile functions (load/unload scripts, execute guile code).
`weechat-guile-api.c` | Guile scripting API functions.
`irc/` | IRC (Internet Relay Chat) plugin.
`irc.c` | Main IRC functions.
`irc-bar-item.c` | IRC bar items.
`irc-batch.c` | IRC batched events.
`irc-buffer.c` | IRC buffers.
`irc-channel.c` | IRC channels.
`irc-color.c` | IRC colors.
`irc-command.c` | IRC commands.
`irc-completion.c` | IRC completions.
`irc-config.c` | IRC config options (file irc.conf).
`irc-ctcp.c` | IRC CTCP.
`irc-debug.c` | IRC debug functions.
`irc-ignore.c` | IRC Ignore.
`irc-info.c` | IRC info/infolists/hdata.
`irc-input.c` | Input of commands/text.
`irc-join.c` | Functions for list of channels to join.
`irc-list.c` | Buffer for reply to /list command.
`irc-message.c` | Functions to manipulate IRC messages.
`irc-mode.c` | Functions about channel/nick modes.
`irc-modelist.c` | IRC channel mode lists (+b, +e, +I, …​).
`irc-msgbuffer.c` | Target buffer for IRC messages.
`irc-nick.c` | IRC nicks.
`irc-notify.c` | IRC notify lists.
`irc-protocol.c` | IRC protocol (RFCs 1459/2810/2811/2812/2813/7194).
`irc-raw.c` | IRC raw buffer.
`irc-redirect.c` | Redirection of IRC command output.
`irc-sasl.c` | SASL authentication with IRC server.
`irc-server.c` | I/O communication with IRC server.
`irc-tag.c` | Functions to manipulate IRC message tags.
`irc-typing.c` | Typing status.
`irc-upgrade.c` | Save/restore of IRC data when upgrading WeeChat.
`javascript/` | JavaScript plugin.
`weechat-js.cpp` | Main JavaScript functions (load/unload scripts, execute JavaScript code).
`weechat-js-api.cpp` | JavaScript scripting API functions.
`weechat-js-v8.cpp` | JavaScript v8 functions.
`logger/` | Logger plugin.
`logger.c` | Main logger functions.
`logger-backlog.c` | Logger backlog functions.
`logger-buffer.c` | Logger buffer list management.
`logger-command.c` | Logger commands.
`logger-config.c` | Logger config options (file logger.conf).
`logger-info.c` | Logger info/infolists/hdata.
`logger-tail.c` | Functions to get last lines of a file.
`lua/` | Lua plugin.
`weechat-lua.c` | Main lua functions (load/unload scripts, execute lua code).
`weechat-lua-api.c` | Lua scripting API functions.
`perl/` | Perl plugin.
`weechat-perl.c` | Main perl functions (load/unload scripts, execute perl code).
`weechat-perl-api.c` | Perl scripting API functions.
`php/` | PHP plugin.
`weechat-php.c` | Main PHP functions (load/unload scripts, execute PHP code).
`weechat-php-api.c` | PHP scripting API functions.
`python/` | Python plugin.
`weechat-python.c` | Main python functions (load/unload scripts, execute python code).
`weechat-python-api.c` | Python scripting API functions.
`relay/` | Relay plugin (IRC proxy and relay for remote interfaces).
`relay.c` | Main relay functions.
`relay-auth.c` | Clients authentication.
`relay-bar-item.c` | Relay bar items.
`relay-buffer.c` | Relay buffer.
`relay-client.c` | Clients of relay.
`relay-command.c` | Relay commands.
`relay-completion.c` | Relay completions.
`relay-config.c` | Relay config options (file relay.conf).
`relay-http.c` | HTTP functions.
`relay-info.c` | Relay info/infolists/hdata.
`relay-network.c` | Network functions for relay.
`relay-raw.c` | Relay raw buffer.
`relay-remote.c` | Relay remote.
`relay-server.c` | Relay server.
`relay-upgrade.c` | Save/restore of relay data when upgrading WeeChat.
`relay-websocket.c` | WebSocket server functions (RFC 6455).
`api/` | Relay for remote interfaces (using HTTP REST API).
`relay-api.c` | Main API functions for HTTP REST API.
`relay-api-msg.c` | Send JSON messages to clients.
`relay-api-protocol.c` | HTTP REST API protocol.
`remote/` | Relay remote functions, specific to API.
`relay-remote-event.c` | Process events received from relay remote.
`relay-remote-network.c` | Network functions for relay remote.
`irc/` | IRC proxy.
`relay-irc.c` | Main IRC proxy functions.
`weechat/` | Relay for remote interfaces (using "weechat" binary protocol).
`relay-weechat.c` | Relay for remote interfaces (main functions).
`relay-weechat-msg.c` | Send binary messages to clients.
`relay-weechat-nicklist.c` | Nicklist functions.
`relay-weechat-protocol.c` | Read commands from clients.
`ruby/` | Ruby plugin.
`weechat-ruby.c` | Main ruby functions (load/unload scripts, execute ruby code).
`weechat-ruby-api.c` | Ruby scripting API functions.
`script/` | Script manager.
`script.c` | Main functions for script manager.
`script-action.c` | Actions on scripts (load/unload, install/remove, …​).
`script-buffer.c` | Buffer for script manager.
`script-command.c` | Commands for script manager.
`script-completion.c` | Completions for script manager.
`script-config.c` | Config options for script manager (file script.conf).
`script-info.c` | Script manager info/infolists/hdata.
`script-mouse.c` | Script mouse actions.
`script-repo.c` | Download and read repository file.
`tcl/` | Tcl plugin.
`weechat-tcl.c` | Main tcl functions (load/unload scripts, execute tcl code).
`weechat-tcl-api.c` | Tcl scripting API functions.
`trigger/` | Trigger plugin.
`trigger.c` | Main trigger functions.
`trigger-buffer.c` | Trigger buffer.
`trigger-callback.c` | Trigger callbacks.
`trigger-command.c` | Trigger commands.
`trigger-completion.c` | Trigger completions.
`trigger-config.c` | Trigger config options (file trigger.conf).
`typing/` | Typing plugin.
`typing.c` | Main typing functions.
`typing-bar-item.c` | Typing bar items.
`typing-config.c` | Typing config options (file typing.conf).
`typing-status.c` | Messages typing status on buffers.
`xfer/` | Xfer plugin (IRC DCC file/chat).
`xfer.c` | Main xfer functions.
`xfer-buffer.c` | Xfer buffer.
`xfer-chat.c` | DCC chat.
`xfer-command.c` | Xfer commands.
`xfer-completion.c` | Xfer completions.
`xfer-config.c` | Xfer config options (file xfer.conf).
`xfer-dcc.c` | DCC file transfer.
`xfer-file.c` | File functions for xfer.
`xfer-info.c` | Xfer info/infolists/hdata.
`xfer-network.c` | Network functions for xfer.
`xfer-upgrade.c` | Save/restore of xfer data when upgrading WeeChat.

#### Tests

Path/file | Description
--- | ---
`tests/` | Root of tests.
`fuzz/` | Root of fuzz testing.
`ossfuzz.sh` | Build script for OSS-Fuzz ↗.
`core/` | Root of fuzz testing for core.
`calc-fuzzer.c` | Fuzz testing: calculation of expressions.
`crypto-fuzzer.c` | Fuzz testing: cryptographic functions.
`secure-fuzzer.c` | Fuzz testing: secured data.
`string-fuzzer.c` | Fuzz testing: strings.
`utf8-fuzzer.c` | Fuzz testing: UTF-8.
`util-fuzzer.c` | Fuzz testing: utility functions.
`unit/` | Root of unit tests.
`tests.cpp` | Program used to run all tests.
`tests-record.cpp` | Record and search in messages displayed.
`core/` | Root of unit tests for core.
`test-core-arraylist.cpp` | Tests: arraylists.
`test-core-calc.cpp` | Tests: calculation of expressions.
`test-core-command.cpp` | Tests: commands.
`test-core-config-file.cpp` | Tests: configuration files.
`test-core-crypto.cpp` | Tests: cryptographic functions.
`test-core-dir.cpp` | Tests: directory/file functions.
`test-core-eval.cpp` | Tests: evaluation of expressions.
`test-core-hashtable.cpp` | Tests: hashtables.
`test-core-hdata.cpp` | Tests: hdata.
`test-core-hook.cpp` | Tests: hooks.
`test-core-infolist.cpp` | Tests: infolists.
`test-core-input.cpp` | Tests: input functions.
`test-core-list.cpp` | Tests: lists.
`test-core-network.cpp` | Tests: network functions.
`test-core-secure.cpp` | Tests: secured data.
`test-core-signal.cpp` | Tests: signals.
`test-core-string.cpp` | Tests: strings.
`test-core-sys.cpp` | Tests: system functions.
`test-core-url.cpp` | Tests: URLs.
`test-core-utf8.cpp` | Tests: UTF-8.
`test-core-util.cpp` | Tests: utility functions.
`hook/` | Root of unit tests for hooks.
`test-hook-command-run.cpp` | Tests: hooks "command_run".
`test-hook-command.cpp` | Tests: hooks "command".
`test-hook-completion.cpp` | Tests: hooks "completion".
`test-hook-config.cpp` | Tests: hooks "config".
`test-hook-connect.cpp` | Tests: hooks "connect".
`test-hook-fd.cpp` | Tests: hooks "fd".
`test-hook-focus.cpp` | Tests: hooks "focus".
`test-hook-hdata.cpp` | Tests: hooks "hdata".
`test-hook-hsignal.cpp` | Tests: hooks "hsignal".
`test-hook-info-hashtable.cpp` | Tests: hooks "info_hashtable".
`test-hook-info.cpp` | Tests: hooks "info".
`test-hook-infolist.cpp` | Tests: hooks "infolist".
`test-hook-line.cpp` | Tests: hooks "line".
`test-hook-modifier.cpp` | Tests: hooks "modifier".
`test-hook-print.cpp` | Tests: hooks "print".
`test-hook-process.cpp` | Tests: hooks "process".
`test-hook-signal.cpp` | Tests: hooks "signal".
`test-hook-timer.cpp` | Tests: hooks "timer".
`test-hook-url.cpp` | Tests: hooks "url".
`gui/` | Root of unit tests for interfaces.
`test-gui-bar-item-custom.cpp` | Tests: custom bar item functions.
`test-gui-bar-item.cpp` | Tests: bar item functions.
`test-gui-bar-window.cpp` | Tests: bar window functions.
`test-gui-bar.cpp` | Tests: bar functions.
`test-gui-buffer.cpp` | Tests: buffer functions.
`test-gui-chat.cpp` | Tests: chat functions.
`test-gui-color.cpp` | Tests: colors.
`test-gui-filter.cpp` | Tests: filters.
`test-gui-hotlist.cpp` | Tests: hotlist functions.
`test-gui-input.cpp` | Tests: input functions.
`test-gui-key.cpp` | Tests: keys.
`test-gui-line.cpp` | Tests: lines.
`test-gui-nick.cpp` | Tests: nicks.
`test-gui-nicklist.cpp` | Tests: nicklist functions.
`curses/` | Root of unit tests for Curses interface.
`test-gui-curses-mouse.cpp` | Tests: mouse (Curses interface).
`scripts/` | Root of scripting API tests.
`test-scripts.cpp` | Program used to run the scripting API tests.
`python/` | Python scripts to generate and run the scripting API tests.
`testapigen.py` | Python script generating scripts in all languages to test the scripting API.
`testapi.py` | Python script with scripting API tests, used by script testapigen.py.
`unparse.py` | Convert Python code to other languages, used by script testapigen.py.
`plugins/` | Root of unit tests for plugins.
`test-plugin-api-info.cpp` | Tests: plugin API info functions.
`test-plugin-config.cpp` | Tests: plugin config functions.
`test-plugins.cpp` | Tests: plugins.
`alias/` | Root of unit tests for alias plugin.
`test-alias.cpp` | Tests: aliases.
`irc/` | Root of unit tests for IRC plugin.
`test-irc-batch.cpp` | Tests: IRC batched events.
`test-irc-buffer.cpp` | Tests: IRC buffers.
`test-irc-channel.cpp` | Tests: IRC channels.
`test-irc-color.cpp` | Tests: IRC colors.
`test-irc-command.cpp` | Tests: IRC commands.
`test-irc-config.cpp` | Tests: IRC configuration.
`test-irc-ctcp.cpp` | Tests: IRC CTCP.
`test-irc-ignore.cpp` | Tests: IRC ignores.
`test-irc-info.cpp` | Tests: IRC info.
`test-irc-join.cpp` | Tests: IRC join functions.
`test-irc-list.cpp` | Tests: IRC buffer for reply to /list command.
`test-irc-message.cpp` | Tests: IRC messages.
`test-irc-mode.cpp` | Tests: IRC modes.
`test-irc-nick.cpp` | Tests: IRC nicks.
`test-irc-protocol.cpp` | Tests: IRC protocol.
`test-irc-sasl.cpp` | Tests: SASL authentication with IRC protocol.
`test-irc-server.cpp` | Tests: IRC server.
`test-irc-tag.cpp` | Tests: IRC message tags.
`logger/` | Root of unit tests for logger plugin.
`test-logger.cpp` | Tests: logger.
`test-logger-backlog.cpp` | Tests: logger backlog.
`test-logger-tail.cpp` | Tests: logger tail functions.
`relay/` | Root of unit tests for Relay plugin.
`test-relay-auth.cpp` | Tests: clients authentication.
`test-relay-bar-item.cpp` | Tests: bar items for Relay plugin.
`test-relay-http.cpp` | Tests: HTTP functions for Relay plugin.
`test-relay-raw.cpp` | Tests: raw messages functions for Relay plugin.
`test-relay-remote.cpp` | Tests: remote functions for Relay plugin.
`test-relay-websocket.cpp` | Tests: websocket functions for Relay plugin.
`api/` | Root of unit tests for Relay "api" protocol.
`test-relay-api.cpp` | Tests: Relay "api" protocol: general functions.
`test-relay-api-msg.cpp` | Tests: Relay "api" protocol: messages.
`test-relay-api-protocol.cpp` | Tests: Relay "api" protocol: protocol.
`remote/` | Tests: Relay "api" protocol: remote functions.
`test-relay-remote-event.cpp` | Tests: Relay "api" protocol: remote events.
`test-relay-remote-network.cpp` | Tests: Relay "api" protocol: remote network.
`irc/` | Root of unit tests for Relay "irc" protocol.
`test-relay-irc.cpp` | Tests: Relay "irc" protocol.
`trigger/` | Root of unit tests for trigger plugin.
`test-trigger.cpp` | Tests: triggers.
`test-trigger-config.cpp` | Tests: trigger configuration.
`typing/` | Root of unit tests for typing plugin.
`test-typing.cpp` | Tests: typing.
`test-typing-status.cpp` | Tests: typing status.
`xfer/` | Root of unit tests for Xfer plugin.
`test-xfer-file.cpp` | Tests: file functions.
`test-xfer-network.cpp` | Tests: network functions.

### 2.3. Documentation / translations

Documentation files:

Path/file | Description
--- | ---
`doc/` | Documentation.
`docinfo.html` | Asciidoctor style.
`XX/` | Documentation for language XX (languages: en, fr, de, it, …​).
`weechat.1.XX.adoc` | Man page (`man weechat`).
`weechat_dev.XX.adoc` | Developer’s guide ↗ (this document).
`weechat_faq.XX.adoc` | FAQ ↗.
`weechat_plugin_api.XX.adoc` | Plugin API reference ↗.
`weechat_quickstart.XX.adoc` | Quickstart guide ↗.
`weechat_relay_api.XX.adoc` | Relay "api" protocol ↗ (for remote interfaces).
`weechat_relay_weechat.XX.adoc` | Relay "weechat" protocol ↗ (for remote interfaces).
`weechat_scripting.XX.adoc` | Scripting guide ↗.
`weechat_user.XX.adoc` | User’s guide ↗.
`includes/` | Files included in documentation.
`cmdline_options.XX.adoc` | Command-line options (file included in man pages and user’s guide).
`man.XX.adoc` | Part of man pages: plugin options, files and copyright.

Translations for WeeChat and plugins are done with gettext, files are in po/ directory:

Path/file | Description
--- | ---
`po/` | Translation files (gettext).
`XX.po` | Translations for language XX (fr, de, it, …​), base language is English.
`weechat.pot` | Template for translations (auto-built).

## 3. Coding rules

### 3.1. General rules

- In source code, your comments, variable names, .. must be written in English only (no other language is allowed).

- Use a copyright header in each new source file with:

  - date

  - name

  - e-mail

  - license

  - short description of file (one line).

The copyright and license must be set using SPDX (System Package Data Exchange), following best practices in REUSE Software (see the REUSE specification ↗).

All files in the repository must have a valid copyright and license information.
When the information can not be put in the file itself, you can use the REUSE.toml file at the root of the project tree.

Example in C:

    /*
     * SPDX-FileCopyrightText: 2026 Your Name <your@email.com>
     *
     * SPDX-License-Identifier: GPL-3.0-or-later
     *
     * This file is part of WeeChat, the extensible chat client.
     *
     * WeeChat is free software; you can redistribute it and/or modify
     * it under the terms of the GNU General Public License as published by
     * the Free Software Foundation; either version 3 of the License, or
     * (at your option) any later version.
     *
     * WeeChat is distributed in the hope that it will be useful,
     * but WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     * GNU General Public License for more details.
     *
     * You should have received a copy of the GNU General Public License
     * along with WeeChat.  If not, see <https://www.gnu.org/licenses/>.
     */

    /* Core functions for WeeChat */

### 3.2. C style

Some basic rules you must follow when you write C code:

- Use 4 spaces for indentation (no tabs).

- Try to not exceed 80 chars by line, except if this is needed to increase readability.

- Use comments `/* comment */` (not C99-style comments like `// comment`).

- Add a comment before any function, to explain what it does (always use a multi-line comment, even if description is very short).

Example:

    /*
     * Check if a string with boolean value is valid.
     *
     * Return:
     *   1: boolean value is valid
     *   0: boolean value is NOT valid
     */

    int
    foo ()
    {
        int i;

        /* one line comment */
        i = 1;

        /*
         * multi-line comment: this is a very long description about next block
         * of code
         */
        i = 2;
        printf ("%d\n", i);
    }

- Use explicit variable names, for example "nicks_count" instead of "n" or "nc". Exception: in `for` loops, where variables like "i" or "n" are OK.

- Initialize local variables after declaration, in body of function, example:

    void
    foo ()
    {
        int nick_count, buffer_count;

        nick_count = 0;
        buffer_count = 1;
        /* ... */
    }

- Use parentheses to explicitly show how expression is evaluated, even if they are not required, for example: write `x + (y * z)` instead of `x + y * z`.

- Place curly brackets `{ }` alone on lines, and indent them with number of spaces used for line above opening curly bracket (the `if` in example):

    if (nicks_count == 1)
    {
        /* something */
    }

- Use empty lines to separate many different blocks inside functions, and if possible add a comment for each one, like this:

    /*
     * Sends a message from out queue.
     */

    void
    irc_server_outqueue_send (struct t_irc_server *server)
    {
        /* ... */

        /* send signal with command that will be sent to server */
        irc_server_send_signal (server, "irc_out",
                                server->outqueue[priority]->command,
                                server->outqueue[priority]->message_after_mod,
                                NULL);
        tags_to_send = irc_server_get_tags_to_send (server->outqueue[priority]->tags);
        irc_server_send_signal (server, "irc_outtags",
                                server->outqueue[priority]->command,
                                server->outqueue[priority]->message_after_mod,
                                (tags_to_send) ? tags_to_send : "");
        if (tags_to_send)
            free (tags_to_send);

        /* send command */
        irc_server_send (server, server->outqueue[priority]->message_after_mod,
                         strlen (server->outqueue[priority]->message_after_mod));
        server->last_user_message = time_now;

        /* start redirection if redirect is set */
        if (server->outqueue[priority]->redirect)
        {
            irc_redirect_init_command (server->outqueue[priority]->redirect,
                                       server->outqueue[priority]->message_after_mod);
        }

        /* ... */
    }

- Indent the `if` conditions, and use parentheses around conditions with an operator (not needed for single boolean), like this:

    if (something)
    {
        /* something */
    }
    else
    {
        /* something else */
    }

    if (my_boolean1 && my_boolean2 && (i == 10)
        && ((buffer1 != buffer2) || (window1 != window2)))
    {
        /* something */
    }
    else
    {
        /* something else */
    }

- Indent the `switch` statements like this:

    switch (string[0])
    {
        case 'A':  /* first case */
            foo ("abc", "def");
            break;
        case 'B':  /* second case */
            bar (1, 2, 3);
            break;
        default:  /* other cases */
            baz ();
            break;
    }

- Use `typedef` for function prototypes but not for structures:

    typedef int (t_hook_callback_fd)(void *data, int fd);

    struct t_hook_fd
    {
        t_hook_callback_fd *callback;      /* fd callback                       */
        int fd;                            /* socket or file descriptor         */
        int flags;                         /* fd flags (read,write,..)          */
        int error;                         /* contains errno if error occurred  */
                                           /* with fd                           */
    };

    /* ... */

    struct t_hook_fd *new_hook_fd;

    new_hook_fd = malloc (sizeof (*new_hook_fd));

- This Lisp code can be used in your ~/.emacs.el to indent properly if you are using Emacs as text editor:

    (add-hook 'c-mode-common-hook
              '(lambda ()
                 (c-toggle-hungry-state t)
                 (c-set-style "k&r")
                 (setq c-basic-offset 4)
                 (c-tab-always-indent t)
                 (c-set-offset 'case-label '+)))

### 3.3. Python style

See PEP 8 ↗.

## 4. Core internals

### 4.1. Naming convention

#### Files

File names are composed by letters and hyphens, with format: xxx-yyyyy.[ch], where xxx is directory/component (can be abbreviation) and yyyyy a name for the file.

The main file of a directory may have same name as directory, for example irc.c in irc plugin.

Examples:

Directory | Files
--- | ---
`src/core/` | weechat.c, core-backtrace.c, core-command.c, …​
`src/gui/` | gui-bar.c, gui-bar-item.c, gui-bar-window.c, …​
`src/gui/curses/` | gui-curses-bar.c, gui-curses-bar-window.c, gui-curses-chat.c, …​
`src/plugins/` | plugin.c, plugin-api.c, plugin-api-info.c, plugin-config.c, plugin-script.c, …​
`src/plugins/irc/` | irc.c, irc-bar-item.c, irc-buffer.c, …​
`src/plugins/python/` | weechat-python.c, weechat-python-api.c, …​

The headers of C files have same name as file, for example core-command.h for file core-command.c.

#### Structures

Structures have name t_X_Y or t_X_Y_Z:

- X: directory/component (can be abbreviation)

- Y: end of file name

- Z: name for structure (optional)

Example: an IRC nick (from src/plugins/irc/irc-nick.h):

    struct t_irc_nick
    {
        char *name;                     /* nickname                              */
        char *host;                     /* full hostname                         */
        char *prefixes;                 /* string with prefixes enabled for nick */
        char prefix[2];                 /* current prefix (higher prefix set in  */
                                        /* prefixes)                             */
        int away;                       /* 1 if nick is away                     */
        char *color;                    /* color for nickname in chat window     */
        struct t_irc_nick *prev_nick;   /* link to previous nick on channel      */
        struct t_irc_nick *next_nick;   /* link to next nick on channel          */
    };

#### Variables

Global variables (outside functions) have name X_Y_Z:

- X: directory/component (can be abbreviation)

- Y: end of file name

- Z: name for variable

Exception are variables for "last" node of a list, name is last_X (where X is name of variable, using singular form).

Example: windows (from src/gui/gui-window.c):

    struct t_gui_window *gui_windows = NULL;        /* first window             */
    struct t_gui_window *last_gui_window = NULL;    /* last window              */
    struct t_gui_window *gui_current_window = NULL; /* current window           */

There is no naming convention for local variables (in functions). The only recommendation is that name is explicit (not too short).
Nevertheless, pointers to structures are often named ptr_xxxx, for example a pointer on a struct t_gui_buffer * will be: *ptr_buffer.

#### Functions

Naming convention for functions is the same as variables.

Example: creation of a new window (from src/gui/gui-window.c):

    /*
     * Create a new window.
     *
     * Return pointer to new window, NULL if error.
     */

    struct t_gui_window *
    gui_window_new (struct t_gui_window *parent_window, struct t_gui_buffer *buffer,
                    int x, int y, int width, int height,
                    int width_pct, int height_pct)
    {
        /* ... */

        return new_window;
    }

### 4.2. Single thread

WeeChat is single threaded. That means every part of code should execute very fast, and that calls to functions like `sleep` are strictly forbidden (it is true for WeeChat core, but also C plugins and scripts).

If for some reasons you have to sleep a while, use `hook_timer` with a callback.

### 4.3. Doubly linked lists

Most of WeeChat lists are doubly linked lists: each node has pointer to previous and next node.

Example: list of buffers (from src/gui/gui-buffer.h):

    struct t_gui_buffer
    {
        /* data */

        /* ... */

        struct t_gui_buffer *prev_buffer;  /* link to previous buffer           */
        struct t_gui_buffer *next_buffer;  /* link to next buffer               */
    };

Then the two list pointers, to the head and tail of list:

    struct t_gui_buffer *gui_buffers = NULL;           /* first buffer          */
    struct t_gui_buffer *last_gui_buffer = NULL;       /* last buffer           */

### 4.4. Color codes in strings

WeeChat uses own color codes in strings to display attributes (bold, underline, …​) and colors on screen.

All attributes/colors are prefixed with a char in string, which can be:

- 0x19: color code (followed by color code(s))

- 0x1A: set attribute (followed by raw attribute on one char)

- 0x1B: remove attribute (followed by raw attribute on one char)

- 0x1C: reset (nothing after)

Possible colors are:

- standard color: optional attributes + number on 2 digits

- extended color: `@` + optional attributes + number on 5 digits

In following table, these conventions are used:

- `STD`: standard color (2 digits)

- `(ATTR)STD`: standard color with optional attributes (attributes + 2 digits)

- `EXT`: extended color (`@` + 5 digits)

- `(ATTR)EXT`: extended color with optional attributes (`@` + attributes + 5 digits)

- `(ATTR)`: one or more attribute chars:

  - `%`: blink

  - `.`: "dim" (half bright)

  - `*`: bold

  - `!`: reverse

  - `/`: italic

  - `_`: underline

  - `|`: keep attributes

- `(a)`: one raw attribute char:

  - 0x01: bold

  - 0x02: reverse

  - 0x03: italic

  - 0x04: underline

  - 0x05: blink

  - 0x06: "dim" (half bright)

All combinations are summarized in this table:

Code | Example | Areas | Description
--- | --- | --- | ---
19 + `STD` | 19 `01` | chat + bars | Set attributes and color using option, see table below.
19 + `EXT` | 19 `@00001` | chat | Set color with a ncurses pair (used only on `/color` buffer).
19 + `F` + `(ATTR)STD` | 19 `F*05` | chat + bars | Set foreground (WeeChat color).
19 + `F` + `(ATTR)EXT` | 19 `F@00214` | chat + bars | Set foreground (extended color).
19 + `B` + `STD` | 19 `B05` | chat + bars | Set background (WeeChat color).
19 + `B` + `EXT` | 19 `B@00124` | chat + bars | Set background (extended color).
19 + `*` + `(ATTR)STD` | 19 `*05` | chat + bars | Set foreground (WeeChat color).
19 + `*` + `(ATTR)EXT` | 19 `*@00214` | chat + bars | Set foreground (extended color).
19 + `*` + `(ATTR)STD` + `,` + `STD` (1) | 19 `*08,05` | chat + bars | Set foreground/background (WeeChat colors).
19 + `*` + `(ATTR)STD` + `,` + `EXT` (1) | 19 `*01,@00214` | chat + bars | Set foreground (WeeChat color) and background (extended color).
19 + `*` + `(ATTR)EXT` + `,` + `STD` (1) | 19 `*@00214,05` | chat + bars | Set foreground (extended color) and background (WeeChat color).
19 + `*` + `(ATTR)EXT` + `,` + `EXT` (1) | 19 `*@00214,@00017` | chat + bars | Set foreground/background (extended colors).
19 + `*` + `(ATTR)STD` + `~` + `STD` | 19 `*08~05` | chat + bars | Set foreground/background (WeeChat colors).
19 + `*` + `(ATTR)STD` + `~` + `EXT` | 19 `*01~@00214` | chat + bars | Set foreground (WeeChat color) and background (extended color).
19 + `*` + `(ATTR)EXT` + `~` + `STD` | 19 `*@00214~05` | chat + bars | Set foreground (extended color) and background (WeeChat color).
19 + `*` + `(ATTR)EXT` + `~` + `EXT` | 19 `*@00214~@00017` | chat + bars | Set foreground/background (extended colors).
19 + `b` + `F` | 19 `bF` | bars | Set bar foreground color.
19 + `b` + `D` | 19 `bD` | bars | Set bar delimiter color.
19 + `b` + `B` | 19 `bB` | bars | Set bar background color.
19 + `b` + `_` | 19 `b_` | input bar | Start input char (used only in item "input_text").
19 + `b` + `-` | 19 `b-` | input bar | Start input hidden char (used only in item "input_text").
19 + `b` + `#` | 19 `b#` | input bar | Move cursor char (used only in item "input_text").
19 + `b` + `i` | 19 `bi` | bars | Start item.
19 + `b` + `l` (lower L) | 19 `bl` | bars | Start line item.
19 + `E` | 19 `E` | chat + bars | Emphasize text (WeeChat ≥ 0.4.2).
19 + 1C | 19 1C | chat + bars | Reset color (keep attributes).
1A + `(a)` | 1A 01 | chat + bars | Set attribute.
1B + `(a)` | 1B 01 | chat + bars | Remove attribute.
1C | 1C | chat + bars | Reset attributes and color.

Note | (1) The use of comma as separator was used until WeeChat 2.5. With WeeChat ≥ 2.6, a tilde is used to separate foreground from background color. If you are developing a WeeChat relay client and want to be compatible with all WeeChat versions, you should support both separators (for example if a user with WeeChat ≤ 2.5 runs `/upgrade` to a version ≥ 2.6, both separators could be used at same time in buffers).

Color codes using options (see t_gui_color_enum, in file src/gui/gui-color.h):

Code | Option
--- | ---
`00` | weechat.color.separator
`01` | weechat.color.chat
`02` | weechat.color.chat_time
`03` | weechat.color.chat_time_delimiters
`04` | weechat.color.chat_prefix_error
`05` | weechat.color.chat_prefix_network
`06` | weechat.color.chat_prefix_action
`07` | weechat.color.chat_prefix_join
`08` | weechat.color.chat_prefix_quit
`09` | weechat.color.chat_prefix_more
`10` | weechat.color.chat_prefix_suffix
`11` | weechat.color.chat_buffer
`12` | weechat.color.chat_server
`13` | weechat.color.chat_channel
`14` | weechat.color.chat_nick
`15` | weechat.color.chat_nick_self
`16` | weechat.color.chat_nick_other
`17` | (not used anymore since WeeChat 0.3.4)
`18` | (not used anymore since WeeChat 0.3.4)
`19` | (not used anymore since WeeChat 0.3.4)
`20` | (not used anymore since WeeChat 0.3.4)
`21` | (not used anymore since WeeChat 0.3.4)
`22` | (not used anymore since WeeChat 0.3.4)
`23` | (not used anymore since WeeChat 0.3.4)
`24` | (not used anymore since WeeChat 0.3.4)
`25` | (not used anymore since WeeChat 0.3.4)
`26` | (not used anymore since WeeChat 0.3.4)
`27` | weechat.color.chat_host
`28` | weechat.color.chat_delimiters
`29` | weechat.color.chat_highlight
`30` | weechat.color.chat_read_marker
`31` | weechat.color.chat_text_found
`32` | weechat.color.chat_value
`33` | weechat.color.chat_prefix_buffer
`34` | weechat.color.chat_tags (WeeChat ≥ 0.3.6)
`35` | weechat.color.chat_inactive_window (WeeChat ≥ 0.3.6)
`36` | weechat.color.chat_inactive_buffer (WeeChat ≥ 0.3.6)
`37` | weechat.color.chat_prefix_buffer_inactive_buffer (WeeChat ≥ 0.3.6)
`38` | weechat.color.chat_nick_offline (WeeChat ≥ 0.3.9)
`39` | weechat.color.chat_nick_offline_highlight (WeeChat ≥ 0.3.9)
`40` | weechat.color.chat_nick_prefix (WeeChat ≥ 0.4.1)
`41` | weechat.color.chat_nick_suffix (WeeChat ≥ 0.4.1)
`42` | weechat.color.emphasized (WeeChat ≥ 0.4.2)
`43` | weechat.color.chat_day_change (WeeChat ≥ 0.4.2)
`44` | weechat.color.chat_value_null (WeeChat ≥ 1.4)
`45` | weechat.color.chat_status_disabled (WeeChat ≥ 4.0.0)
`46` | weechat.color.chat_status_enabled (WeeChat ≥ 4.0.0)

WeeChat colors are:

Code | Color
--- | ---
`00` | Default (terminal foreground/background)
`01` | Black
`02` | Dark gray
`03` | Dark red
`04` | Light red
`05` | Dark green
`06` | Light green
`07` | Brown
`08` | Yellow
`09` | Dark blue
`10` | Light blue
`11` | Dark magenta
`12` | Light magenta
`13` | Dark cyan
`14` | Light cyan
`15` | Gray
`16` | White

Examples of color codes:

Code | Description
--- | ---
19 `01` | Color of option "01" (chat text)
19 `*08,03` | Yellow on red
19 `*@00214` | Orange (extended color 214)
19 `*@*_00214,@00017` | Bold underlined orange (214) on dark blue (17)
1A `_` | Set underline
1B `_` | Remove underline
1C | Reset attributes and color

## 5. Plugin internals

The file src/plugins/weechat-plugin.h defines and exports all functions available in the API.

A structure called t_weechat_plugin is used to store info about plugin (filename, name, author, description, …​) and all API functions, as pointers to WeeChat functions.

Then some macros are defined to call these functions.

For example, function hook_timer is defined in structure t_weechat_plugin like this:

    struct t_hook *(*hook_timer) (struct t_weechat_plugin *plugin,
                                  long interval,
                                  int align_second,
                                  int max_calls,
                                  int (*callback)(void *data,
                                                  int remaining_calls),
                                  void *callback_data);

And the macro used to call this function is:

    #define weechat_hook_timer(__interval, __align_second, __max_calls,     \
                               __callback, __data)                          \
        weechat_plugin->hook_timer(weechat_plugin, __interval,              \
                                   __align_second, __max_calls,             \
                                   __callback, __data)

So in a plugin, the call to function will be for example:

    server->hook_timer_sasl = weechat_hook_timer (timeout * 1000,
                                                  0, 1,
                                                  &irc_server_timer_sasl_cb,
                                                  server);

## 6. Contribute to WeeChat

### 6.1. Git repository

Git repository is on GitHub ↗.

Any patch for bug or new feature must be done on branch `main`, preferred way is a GitHub pull request. A patch can also be sent by e-mail (made with `git diff` or `git format-patch`).

Format of commit message is the following (with automatic close of a GitHub issue):

    component: fix a problem (closes #123)

Where component is one of following:

Component | Files | Description
--- | --- | ---
`core` | `AUTHORS.md CHANGELOG.md CONTRIBUTING.md .github/FUNDING.yml .github/ISSUE_TEMPLATE/* icons/* po/* README.md UPGRADING.md src/core/* src/gui/* version.sh weechat.desktop` | WeeChat core
`build` | `CMakeLists.txt cmake/* tools/* weechat.cygport.in` | Build
`ci` | `.github/workflows/*` | Continuous integration
`debian` | `debian-devel/* debian-stable/*` | Debian packaging
`tests/fuzz` | `tests/fuzz/*` | Fuzz testing
`tests/unit` | `tests/unit/*` | Unit tests
`doc` | `doc/*` | General doc updates, for example build
`doc/man` | `doc/xx/weechat.1.xx.adoc doc/xx/weechat-headless.1.xx.adoc` | Man pages
`doc/faq` | `doc/xx/weechat_faq.xx.adoc` | Frequently asked questions (FAQ)
`doc/quickstart` | `doc/xx/weechat_quickstart.xx.adoc` | Quickstart guide
`doc/user` | `doc/xx/weechat_user.xx.adoc` | User’s guide
`doc/scripting` | `doc/xx/weechat_scripting.xx.adoc` | Scripting guide
`doc/api` | `doc/xx/weechat_plugin_api.xx.adoc` | Plugin API reference
`doc/relay` | `doc/xx/weechat_relay_api.xx.adoc doc/xx/weechat_relay_weechat.xx.adoc` | Relay protocols
`doc/dev` | `doc/xx/weechat_dev.en.adoc` | Developer’s guide
`irc python relay …` | `src/plugins/<name>/*` | Plugin

Some rules to follow:

- Use only English.

- Use infinitive form of verb.

- If commit is related to a GitHub issue, write it in parenthesis after the message, with this format: `(issue #123)` or `(closes #123)` to close it.

Examples of commit messages:

    core: add callback "nickcmp" for nick comparison in buffers
    core: update Japanese translations
    doc/user: add chapter on typing extension
    irc: add command /unquiet (closes #36)
    python: fix crash when unloading a script without pointer to interpreter
    ruby: add detection of ruby version 1.9.3 in CMake

### 6.2. Translations

#### Gettext

Gettext files are in directory po/.

If you want to initialize a new language, use command `msginit`. For example to create a file which is ready to translate to Dutch:

    cd po
    msginit -i weechat.pot -l nl_NL -o nl.po

Base language for WeeChat is English, so you must of course perfectly understand English in order to translate to your language.

After changes in sources, you can regenerate all translations files: run this command in the CMake "build" directory:

    make translations && make update-po

Then you can edit .po files (if you can translate in a language).

When done, you have to check your file with msgcheck ↗:

    msgcheck.py xx.po

And then you can recompile WeeChat to use the new translations.

#### Asciidoc

Asciidoc files are in directory doc/XX/ where XX is language (en, fr, de, it, …​).

First make a copy of an English asciidoc file (in directory doc/en/), then work on it.

The translations missing in files are indicated by this string:

    // TRANSLATION MISSING

You must translate whole file except links and special keywords for notes, warnings, …​ These words must be kept unchanged:

    [[link_name]]
    <<link_name>>

    [NOTE]
    [TIP]
    [IMPORTANT]
    [WARNING]
    [CAUTION]

When there is a name after `<<link_name>>`, then you must translate it:

    <<link_name,this text should be translated>>