File: HACKING

package info (click to toggle)
balsa 2.3.13-2
  • links: PTS
  • area: main
  • in suites: etch-m68k
  • size: 16,028 kB
  • ctags: 7,261
  • sloc: ansic: 79,348; sh: 8,731; xml: 4,721; makefile: 485; awk: 60
file content (104 lines) | stat: -rw-r--r-- 3,420 bytes parent folder | download | duplicates (10)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
The following are some general guidelines for adding code to Balsa:
-------------------------------------------------------------------

The prefered address for reaching Balsa developers is 
 balsa-maintainer@theochem.kth.se
The prefered place to discuss general Balsa development is
 balsa-list@gnome.org
Refer to AUTHORS for the list of active developers.


The code has generally three layers:

  |--------------------|
  |        src         |
  |    |---------------|
  |    |    libbalsa   |
  |    |  |------------|
  |    |  |  libmutt   |
  ----------------------

- src contains balsa specific code.  

- libbalsa contains object definitions code that in principle can be
  reused. Good examples are address books, or AddressEntries.

- libmutt is a mailbox backend code.


Use FIXME in comments to make a note of things which need looking at.

All GtkObject derivatives should live in there own .c and .h files. In
general functionality should be split in a sensible way amoung files.

respect the libbalsa_ namespace.

commited code should compile with --enable-more-warnings - this
enables some extra warnings and -Werror which makes warnings into
errors.

libmutt
-------

All changes to libmutt/* should be marked with a comment beginning
BALSA: and describing the change and the reason for it.

Source files
------------

All files should have a magic emacs mode line at the top (note older
files will have c-basic-offset as 2 or 8):

/* -*-mode:c; c-style:k&r; c-basic-offset:4; -*- */

following this a GPL copyright header. Copyright should be attributed as:

(c) 1997-2000 Stuart Parmenter and others, see AUTHORS for a list of people

Following this should be a brief description of what the file
contains.

See existing source for a general idea.

Threads
-------

Their are three locks which are important to balsa: 

1) The GDK lock - this protects GDK and GTK+. 

2) The lock on each mailbox.

3) The libmutt lock - this is maintained by libbalsa and is used
because libmutt is not threadsafe.

libbalsa API functions expect to always be called with the GDK lock
held and the mutt lock not held (remember this when calling API funcs
from within libbalsa). The GDK lock may be released, but you must be
careful and should relock it before returning. You must be careful
when the GDK lock is not held that libmutt doesn't call mutt_error or
anything which calls GTK functions.

In order to avoid deadlocks it is important that the locks are always
taken in the same order. That is gdk lock first, then any mailbox
lock, then libmutt lock. Note that this doesn't mean you must take all
those locks - but if you do take them it must be in that order.

If you want just the mutt lock and not the GDK lock this is OK - but
you may not try to take the GDK lock whilst holding the mutt lock -
you must release the mutt lock first.

Be careful to avoid deadlock when locking multiple mailboxes (FIXME:
This sentance isn't much help to anyone ;-)

Coding Style
------------

The coding style used in Balsa currently is a bit of a mess. When
adding a new file to Balsa, please use the standard GNOME indentation
style, rather than the one used in the rest of Balsa. A good place to
read is the file HACKING included with Gnumeric. The magin emacs
comment (as mentioned above) should help you to follow the formatting
guidelines but you can indent explicitly your file with

indent -kr -i4 -psl <filename>