mu/HACKING

* HACKING

  Here are some guidelines for hacking on the 'mu' source code.

  This is a fairly long list -- this is not meant to discourage anyone from
  working on mu; I think most of the rules are common sense anyway, and some of
  the more stylistic-aesthetic rules are clearly visible in current source code,
  so as long as any new code 'fits in', it should go a long way in satisfying
  them.

  I should add some notes for the Lisp/Scheme code as well...

** Coding style

   For consistency and, more important, to keep things understandable, mu
   attempts to follow the following rules:

   1. Basic code layout is like in the Linux kernel coding style. Keep the '{'
      on the same line as the statement, except for functions. We're slowly
      moving to use SPC for indentation: all new code should use that.

      While TABs are techically better, it seems that using SPCs is harder to
      get wrong.

   2. Lines should not exceed 100 characters

   3. Functions should be kept short.

   4. Source files should not exceed 1000 lines, with few exceptions.

   5. Non-static C-functions have the prefix based on their module, e.g.,
      ~mu-foo.h~ declares a function of 'mu_foo_bar (int a);', mu-foo.c implements
      this. C++ functions use the Mu namespace

   6. Non-global functions *don't* have the module prefix, and are declared
      static.

   7. Functions have their return type on a separate line before the function
      name, so:

#+BEGIN_EXAMPLE
      static int
      foo (const char *bar)
      {
	....
      }
#+END_EXAMPLE

   8. In C code, variable-declarations are at the beginning of a block.

      In C code, the declaration does *not* initialize the variable. This will
      give the compiler a chance to warn us if the variable is not initialized
      in a certain code path. Exception: autoptr & friends.

   9. Returned strings of type ~char*~ must be freed by the caller; if they are
      not to be freed, ~const char*~ should be used instead

   10. Functions calls have a space between function name and arguments, unless
       there are none, so:

	~foo (12, 3)~;

       and

	~bar();~

       after a comma, a space should follow.

   11. C-functions that do not take arguments are explicitly declared as f(void)
       and not f(). Reason: f() means that the arguments are /unspecified/ (in C)

   12. C-code should not use ~//~ comments.


** Logging

   For logging, mu uses the GLib logging functions/macros as listed below,
   except when logging may not have been initialized.

   The logging system redirects most logging to the log file (typically,
   =~/.cache/mu/mu.log, or to the systemd journal=). ~g_critical~ messages are
   written to stderr.

   - ~g_message~ is for non-error messages the user will see (unless running with
     ~--quiet~)
   - ~g_warning~ is for problems the user may be able to do something about (and
     they are written on ~stderr~)
   - ~g_critical~ is for mu bugs, serious, internal problems (~g_return_if_fail~ and
     friends use this). (and they are written on ~stderr~)
   - don't use ~g_error~

** Compiling from git

   For hacking, you're strongly advised to use the latest git version.
   Compilation from git should be straightforward, if you have the right tools
   installed.

*** dependencies

    You need to install a few dependencies; e.g. on Debian/Ubuntu:
#+BEGIN_EXAMPLE
    sudo apt-get install                 \
	automake                         \
	autoconf-archive                 \
	autotools-dev                    \
	libglib2.0-dev                   \
	libxapian-dev			 \
	libgmime-3.0-dev                 \
	m4                               \
	make                             \
	libtool                          \
	pkg-config
#+END_EXAMPLE

   Then, to compile straight from ~git~:

#+BEGIN_EXAMPLE
   $ git clone https://github.com/djcb/mu
   $ cd mu
   $ ./autogen.sh
   $ make
#+END_EXAMPLE

   You only need to run ~./autogen.sh~ the first time and after changes in the
   build system; otherwise you can use ~./configure~.

# Local Variables:
# mode: org; org-startup-folded: nofold
# fill-column: 80
# End: