HACKING
=======

If you want to contribute to herbstluftwm, this file is for you!

Contributing
------------
Beside writing code you can help herbstluftwm by testing, reporting bugs,
writing/fixing documentation (e.g. by fixing spelling mistakes) or packaging it
for distributions.

Coding style
------------
The coding style is similar to the Linux-kernel style with some changes:

  - Use 4 spaces instead of tabs.
  - Do not add any trailing spaces at the end of a line.
  - Data type names are CamelCase
  - Globals must be prefixed with g_
  - If a function returns success or failure, then encode it in a bool (from
    stdbool.h). Only use main()-like exit codes (0 = success, non zero =
    failure) for commands.
  - Always typedef struct, e.g.:

    typedef struct {
        int         first_member;
        long long   other_member;
    } MyStruct;

Build system
------------
The build system mainly is one Makefile. To check which source files depend on
which header files it uses dependency files src/*.d and ipc-client/*.d (one for
each C source file) which are generated by default.

Note: If you switch a branch, the dependency files are not marked as dirty!
This may cause unresolvable dependencies e.g. if you switch from a branch with
a new header file to a branch without it. So after switching the branch, you
always should remove dependency files by running:

    make cleandeps

Sending patches
---------------
You can use git to make commits and create patches from them via the command
git format-patch. Always specify your full name and a valid e-mail address in
the author field. The commit description must consist two parts, separated by
an empty line:

  - A mandatory short description in imperative form, e.g.: "Do things in this
    or that way". The description must not exceed 50 characters.
  - An optional longer description consisting of full sentences. This is only
    needed if the commit introduces non-trivial changes.

When introducing new features, always

  - add documentation for it in doc/herbstluftwm.txt (or doc/herbstclient.txt).
  - document the change (e.g. "new command ...") in the NEWS file.

You can send those patches to the mailing list[1] or via the irc[2].

[1] herbstluftwm-devel@lists.sourceforge.net +
[2] #herbstluftwm on irc.freenode.net

Mailing list
------------
The main mailing list for general development, discussion, release
announcements is:

    herbstluftwm-devel@lists.sourceforge.net

You can subscribe by sending a mail with subscribe in the subject to

    herbstluftwm-devel-request@lists.sourceforge.net

or by using the web interface at:

    https://lists.sourceforge.net/lists/listinfo/herbstluftwm-devel

Debugging with valgrind
-----------------------
If you use tools like valgrind, then it is needed to turn of the memory
optimization settings for glib. So export this before running herbstluftwm
within valgrind:

    export G_SLICE=always-malloc
    export G_DEBUG=gc-friendly

    valgrind --leak-check=full ./herbstluftwm  -c share/autostart


Internal structure
------------------
The main modules (i.e. source file + header file) communicate like this if a
key is pressed or if a command is called via herbstclient:

                 X11
                  |
                  V
              +--------+  key  +-----+ call  +---------+
              |  main  |------>| key |------>| command |
              +--------+ event +-----+       +---------+
                  \                    output /  ^
           IPC-Call\      +------------+<----'  / Execute
            -Window `---->| ipc-server |-------'  IPC-Call
              -Event      +------------+
                                 |
                                 V
                                X11

herbstclient is rather simple:

                 Command-Line-   +------+
                   Arguments --->| main |----.
                                 |      |   X11
                    stdout  <----|      |<---'
                                 +------+

// vim: nowrap ft=asciidoc
