2009-12-02 22:27:56 +01:00
|
|
|
* HACKING
|
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
Here are some guidelines for hacking on the 'mu' source code.
|
2014-10-19 17:48:48 +02:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
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.
|
2010-01-06 00:21:28 +01:00
|
|
|
|
2012-03-24 10:17:11 +01:00
|
|
|
I should add some notes for the Lisp/Scheme code as well...
|
|
|
|
|
2009-12-02 22:27:56 +01:00
|
|
|
** Coding style
|
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
For consistency and, more important, to keep things understandable, mu
|
|
|
|
attempts to follow the following rules:
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
1. Basic code layout is like in the Linux kernel coding style. Keep the '{'
|
|
|
|
on the same line as the statement, except for functions. Tabs for
|
2019-11-06 16:13:39 +01:00
|
|
|
indentation, space for alignment; use 8-char tabs.
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
2. Lines should not exceed 80 characters (C) or 100 characters (C++)
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
3. Functions should not exceed 35 lines (with few exceptions). You can easily
|
|
|
|
check if any functions violate this rule with 'make line35', which lists
|
|
|
|
all functions with more than 35 non-comment lines.
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2014-10-19 17:48:48 +02:00
|
|
|
4. Source files should not exceed 1000 lines
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
5. A function's cyclomatic complexity should not exceed 10 (there could be
|
|
|
|
rare exceptions, see the toplevel ~Makefile.am~). You can test the
|
|
|
|
cyclomatic complexity with the ~pmccabe~ tool; if you installed that, you
|
|
|
|
can use 'make cc10' to list all functions that violate this rule; there
|
|
|
|
should be none.
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
6. Filenames have their components separated with dashes (e.g, ~mu-log.h~), and
|
|
|
|
start with ~mu-~ where appropriate.
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
7. Global functions have the prefix based on their module, e.g., ~mu-foo.h~
|
2009-12-02 22:27:56 +01:00
|
|
|
declares a function of 'mu_foo_bar (int a);', mu-foo.c implements this.
|
|
|
|
|
2014-10-19 17:48:48 +02:00
|
|
|
8. Non-global functions *don't* have the module prefix, and are declared
|
2012-07-24 02:29:34 +02:00
|
|
|
static.
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
9. Functions have their return type on a separate line before the function
|
|
|
|
name, so:
|
|
|
|
#+BEGIN_EXAMPLE
|
2010-01-16 14:28:40 +01:00
|
|
|
int
|
2012-11-18 21:10:05 +01:00
|
|
|
foo (const char *bar)
|
2010-01-16 14:28:40 +01:00
|
|
|
{
|
|
|
|
....
|
|
|
|
}
|
2019-04-07 09:43:34 +02:00
|
|
|
#+END_EXAMPLE
|
2010-01-16 14:28:40 +01:00
|
|
|
|
2010-09-05 11:40:13 +02:00
|
|
|
There is no non-aesthetic reason for this.
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
10. In C code, variable-declarations are at the beginning of a block; in
|
|
|
|
principle, C++ follows that same guideline, unless for heavy yet
|
|
|
|
uncertain initializations following RAII.
|
|
|
|
|
|
|
|
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.
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
11. Returned strings of type char* must be freed by the caller; if they are
|
|
|
|
not to be freed, 'const char*' should be used instead
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
12. Functions calls have a space between function name and arguments, unless
|
|
|
|
there are none, so:
|
2010-10-25 23:25:14 +02:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
~foo (12, 3)~;
|
2010-10-25 23:25:14 +02:00
|
|
|
|
|
|
|
and
|
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
~bar();~
|
2010-10-25 23:25:14 +02:00
|
|
|
|
|
|
|
after a comma, a space should follow.
|
|
|
|
|
2014-10-19 17:48:48 +02:00
|
|
|
13. 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)
|
2019-04-07 09:43:34 +02:00
|
|
|
|
|
|
|
14. C-code should not use ~//~ comments.
|
2012-03-24 10:17:11 +01:00
|
|
|
|
2010-01-06 00:21:28 +01:00
|
|
|
|
2014-10-19 17:48:48 +02:00
|
|
|
** Logging
|
2010-01-06 00:21:28 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
For logging, mu uses the GLib logging functions/macros as listed below,
|
|
|
|
except when logging may not have been initialized.
|
2014-10-19 17:48:48 +02:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
The logging system redirects most logging to the log file (typically,
|
|
|
|
~/.mu/mu.log). g_warning, g_message and g_critical are shown to the user,
|
|
|
|
except when running with --quiet, in which case g_message is *not* shown.
|
2014-10-19 17:48:48 +02:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
- ~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~
|
2010-01-06 00:21:28 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
If you just want to log something in the log file without writing to screen,
|
|
|
|
use ~MU_LOG_WRITE~, as defined in ~mu-util.h~.
|
2010-01-06 00:21:28 +01:00
|
|
|
|
2010-11-20 13:39:43 +01:00
|
|
|
** Compiling from git
|
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
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.
|
2010-11-20 13:39:43 +01:00
|
|
|
|
2016-12-15 07:18:00 +01:00
|
|
|
*** dependencies
|
|
|
|
|
|
|
|
You need to install a few dependencies; e.g. on Debian/Ubuntu:
|
2019-04-07 09:43:34 +02:00
|
|
|
#+BEGIN_EXAMPLE
|
2016-12-15 07:18:00 +01:00
|
|
|
sudo apt-get install \
|
|
|
|
automake \
|
|
|
|
autoconf-archive \
|
|
|
|
autotools-dev \
|
|
|
|
libglib2.0-dev \
|
|
|
|
libxapian-dev \
|
2019-04-07 09:43:34 +02:00
|
|
|
libgmime-3.0-dev \
|
2016-12-15 07:18:00 +01:00
|
|
|
m4 \
|
|
|
|
make \
|
2018-06-22 20:22:24 +02:00
|
|
|
libtool \
|
2016-12-15 07:18:00 +01:00
|
|
|
pkg-config
|
2019-04-07 09:43:34 +02:00
|
|
|
#+END_EXAMPLE
|
2016-12-15 07:18:00 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
Then, to compile straight from ~git~:
|
2010-11-20 13:39:43 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
#+BEGIN_EXAMPLE
|
2012-03-24 10:17:11 +01:00
|
|
|
$ git clone https://github.com/djcb/mu
|
2011-07-31 11:59:16 +02:00
|
|
|
$ cd mu
|
2016-12-15 07:18:00 +01:00
|
|
|
$ ./autogen.sh
|
2010-11-20 13:39:43 +01:00
|
|
|
$ make
|
2019-04-07 09:43:34 +02:00
|
|
|
#+END_EXAMPLE
|
2010-11-20 13:39:43 +01:00
|
|
|
|
2019-04-07 09:43:34 +02:00
|
|
|
You only need to run ~./autogen.sh~ the first time and after changes in the
|
|
|
|
build system; otherwise you can use ~./configure~.
|
2009-12-02 22:27:56 +01:00
|
|
|
|
2010-10-25 23:25:14 +02:00
|
|
|
# Local Variables:
|
2012-07-24 02:29:34 +02:00
|
|
|
# mode: org; org-startup-folded: nofold
|
2019-04-07 09:43:34 +02:00
|
|
|
# fill-column: 80
|
2010-10-25 23:25:14 +02:00
|
|
|
# End:
|