alx/mu4e
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update HACKING

Browse Source 
Update HACKING; mention gmime-3.0 and some cosmetics.
This commit is contained in:
djcb
2019-04-07 10:43:34 +03:00
parent 66a988f0f2
commit 817425392c
1 changed files with 68 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
HACKING
View File

@ -1,148 +1,144 @@
* HACKING * HACKING
Here are some guidelines for hacking on the 'mu' source code. Here are some guidelines for hacking on the 'mu' source code.
This is a fairly long list -- this is not meant to discourage anyone This is a fairly long list -- this is not meant to discourage anyone from
from working on mu; I think most of the rules are common sense working on mu; I think most of the rules are common sense anyway, and some of
anyway, and some of the more stylistic-aesthetic rules are clearly the more stylistic-aesthetic rules are clearly visible in current source code,
visible in current source code, so as long as any new code 'fits so as long as any new code 'fits in', it should go a long way in satisfying
in', it should go a long way in satisfying them. them.
I should add some notes for the Lisp/Scheme code as well... I should add some notes for the Lisp/Scheme code as well...
** Coding style ** Coding style
For consistency and, more important, to keep things understandable, For consistency and, more important, to keep things understandable, mu
mu attempts to follow the following rules: attempts to follow the following rules:
1. Basic code layout is like in the Linux kernel coding style. Keep 1. Basic code layout is like in the Linux kernel coding style. Keep the '{'
the '{' on the same line as the statement, except for on the same line as the statement, except for functions. Tabs for
functions. Tabs for indentation, space for aligment; use 8-char indentation, space for aligment; use 8-char tabs.
tabs.
2. Lines should not exceed 80 characters (C) or 100 characters 2. Lines should not exceed 80 characters (C) or 100 characters (C++)
(C++)
3. Functions should not exceed 35 lines (with few exceptions). You 3. Functions should not exceed 35 lines (with few exceptions). You can easily
can easily check if any functions violate this rule with 'make check if any functions violate this rule with 'make line35', which lists
line35', which lists all functions with more than 35 non-comment all functions with more than 35 non-comment lines.
lines.
4. Source files should not exceed 1000 lines 4. Source files should not exceed 1000 lines
5. A function's cyclomatic complexity should not exceed 10 (there 5. A function's cyclomatic complexity should not exceed 10 (there could be
could be rare exceptions, see the toplevel Makefile.am). You can rare exceptions, see the toplevel ~Makefile.am~). You can test the
test the cyclomatic complexity with the pmccabe tool; if you cyclomatic complexity with the ~pmccabe~ tool; if you installed that, you
installed that, you can use 'make cc10' to list all functions can use 'make cc10' to list all functions that violate this rule; there
that violate this rule; there should be none. should be none.
6. Filenames have their components separated with dashes (e.g, 'mu-log.h'), 6. Filenames have their components separated with dashes (e.g, ~mu-log.h~), and
and start with 'mu-' where appropriate. start with ~mu-~ where appropriate.
7. Global functions have the prefix based on their module, e.g., mu-foo.h 7. Global 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. declares a function of 'mu_foo_bar (int a);', mu-foo.c implements this.
8. Non-global functions *don't* have the module prefix, and are declared 8. Non-global functions *don't* have the module prefix, and are declared
static. static.
9. Functions have their return type on a separate line before the 9. Functions have their return type on a separate line before the function
function name, so: name, so:
#+BEGIN_EXAMPLE
int int
foo (const char *bar) foo (const char *bar)
{ {
.... ....
} }
#+END_EXAMPLE
There is no non-aesthetic reason for this. There is no non-aesthetic reason for this.
10. In C code, variable-declarations are at the beginning of a 10. In C code, variable-declarations are at the beginning of a block; in
block; in principle, C++ follows that same guideline, unless principle, C++ follows that same guideline, unless for heavy yet
for heavy yet uncertain initializations following RAII. 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.
11. Returned strings of type char* must be freed by the caller; if In C code, the declaration does *not* initialize the variable. This will
they are not to be freed, 'const char*' should be used instead give the compiler a chance to warn us if the variable is not initialized
in a certain code path.
12. Functions calls have a space between function name and 11. Returned strings of type char* must be freed by the caller; if they are
arguments, unless there are none, so: not to be freed, 'const char*' should be used instead
foo (12, 3); 12. Functions calls have a space between function name and arguments, unless
there are none, so:
~foo (12, 3)~;
and and
bar(); ~bar();~
after a comma, a space should follow. after a comma, a space should follow.
13. Functions that do not take arguments are explicitly declared as 13. Functions that do not take arguments are explicitly declared as
f(void) and not f(). Reason: f() means that the arguments are f(void) and not f(). Reason: f() means that the arguments are
/unspecified/ (in C) /unspecified/ (in C)
14. C-code should use /* comments */, not // commments 14. C-code should not use ~//~ comments.
** Logging ** Logging
For logging, mu uses the GLib logging functions/macros as listed For logging, mu uses the GLib logging functions/macros as listed below,
below, except when logging may not have been initialized. except when logging may not have been initialized.
The logging system redirects most logging to the log file The logging system redirects most logging to the log file (typically,
(typically, ~/.mu/mu.log). g_warning, g_message and g_critical are ~/.mu/mu.log). g_warning, g_message and g_critical are shown to the user,
shown to the user, except when running with --quiet, in which case except when running with --quiet, in which case g_message is *not* shown.
g_message is *not* shown.
- g_message is for non-error messages the user will see (unless - ~g_message~ is for non-error messages the user will see (unless running with
running with --quiet) ~--quiet~)
- g_warning is for problems the user may be able to do something - ~g_warning~ is for problems the user may be able to do something about (and
about (and they are written on stderr) they are written on ~stderr~)
- g_critical is for mu bugs, serious, internal problems - ~g_critical~ is for mu bugs, serious, internal problems (~g_return_if_fail~ and
(g_return_if_fail and friends use this). (and they are written on friends use this). (and they are written on ~stderr~)
stderr) - don't use ~g_error~
- don't use g_error
If you just want to log something in the log file without writing If you just want to log something in the log file without writing to screen,
to screen, use MU_LOG_WRITE, as defined in mu-util.h use ~MU_LOG_WRITE~, as defined in ~mu-util.h~.
** Compiling from git ** Compiling from git
For hacking, you're strongly advised to use the latest git For hacking, you're strongly advised to use the latest git version.
version. Compilation from git should be straightforward, if you Compilation from git should be straightforward, if you have the right tools
have the right tools installed. installed.
*** dependencies *** dependencies
You need to install a few dependencies; e.g. on Debian/Ubuntu: You need to install a few dependencies; e.g. on Debian/Ubuntu:
#+BEGIN_EXAMPLE
sudo apt-get install \ sudo apt-get install \
automake \ automake \
autoconf-archive \ autoconf-archive \
autotools-dev \ autotools-dev \
libglib2.0-dev \ libglib2.0-dev \
libxapian-dev \ libxapian-dev \
libgmime-2.6-dev \ libgmime-3.0-dev \
m4 \ m4 \
make \ make \
libtool \ libtool \
pkg-config pkg-config
#+END_EXAMPLE
Then, to compile straight from git: Then, to compile straight from ~git~:
#+BEGIN_EXAMPLE
$ git clone https://github.com/djcb/mu $ git clone https://github.com/djcb/mu
$ cd mu $ cd mu
$ ./autogen.sh $ ./autogen.sh
$ make $ make
#+END_EXAMPLE
You only need to run ./autogen.sh the first time and after changes You only need to run ~./autogen.sh~ the first time and after changes in the
in the build system; otherwise you can use ./configure. build system; otherwise you can use ~./configure~.
# Local Variables: # Local Variables:
# mode: org; org-startup-folded: nofold # mode: org; org-startup-folded: nofold
# fill-column: 80
# End: # End: