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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
The libnih source tree is available using Bazaar with the following
URL, if you plan to hack on libnih please work off this branch.
http://bazaar.launchpad.net/~scott/libnih/trunk
Releases are available from the FTP site:
ftp://ftp.netsplit.com/pub/libnih/
libnih uses Launchpad's bug tracking system:
http://bugs.launchpad.net/libnih/
If you want to contribute code or bug fixes, please either provide the
URL to your own Bazaar branch or use the ‘unified’ diff format
(diff -pu) and attach the patch to a bug. Please supply a suggested
ChangeLog entry with your patch.
Maintainer tools
----------------
The source tree for libnih uses the GNU Build System (sometimes known
as the GNU Autotools). You will need the following versions
installed.
* GNU Autoconf 2.62
* GNU Automake 1.11
* GNU Libtool 2.2.4
* GNU Gettext 0.17
After checking out libnih from Bazaar you will need to use these
tools to generate the build files. The correct way to do this is to
simply run ‘autoreconf -i’ from the top-level source directory.
Configure options
-----------------
There are some configure script options that you may find useful when
hacking on libnih.
* --enable-compiler-warnings: (GCC only) adds extra CFLAGS to
increase the source checking and treat all warnings as errors.
* --disable-compiler-optimisations: ensures that no compiler
optimisations are performed during compilation, easing
debugging.
* --disable-linker-optimisations: disables the usual linker
optimisations, slightly decreasing build time.
* --enable-compiler-coverage: (GCC only) enables coverage file
generation, useful for test suites.
The configure script also supports the Automake
‘--disable-maintainer-mode’ and ‘--disable-dependency-tracking‘ options
which may be useful to distribution maintainers.
Compilation output is normally “silent”, verbosity can be restored using
‘make V=1’ or with the ‘--disable-silent-rules’ configure option.
Coding style
------------
The coding style for libnih is roughly K&R with function names in
column 0, and variable names aligned in declarations.
The right results can be almost achieved by doing the following.
* GNU Emacs: if you're not using auto-newline, the following
should do the right thing:
(defun libnih-c-mode-common-hook ()
(c-set-style "k&r")
(setq indent-tabs-mode t
c-basic-offset 8))
* VIM: the default works except for the case labels in switch
statements. Set the following option to fix that:
setlocal cinoptions=:0
* Indent: can be used to reformat code in a different style:
indent -kr -i8 -psl
Documentation
-------------
All functions, typedefs, structures and file-level variables, whether
exported or not, must be preceded by a documentation comment
detailing their usage and behaviour. The format of that command is as
follows:
/**
* function_name:
* @foo: first parameter description,
* @bar: second parameter description,
* @baz: third parameter description.
*
* Describe the function here, when you reference parameters
* use the form above, e.g. give @foo or @bar.
*
* Other functions should be referenced by function-call
* syntax, e.g. call other_function() afterwards.
*
* Returns: if there is a return value, include this line and
* give the possible values returned.
**/
Structures should detail their members instead of function parameters.
Function Attributes
-------------------
Functions that allocate a structure and return it should use the
"warn_unused_result" and "malloc" attributes, even if the structure is
placed in a linked list. The former ensures a failure to allocate
memory is checked by the caller, and the latter allows some
optimisation.
Functions that raise errors, or call other functions that raise
errors, must indicate that an error has been raised in their return
value and also use the "warn_unused_result" attribute to ensure that
the caller doesn't ignore the error.
Functions that can return to indicate insufficient memory, even if
they don't return a pointer, should also use the "warn_unused_result"
attribute; unless it would be common to ignore this (e.g. shrinking a
buffer).
Test Cases
----------
Where possible, all code should be covered by test cases checking the
behaviour of that code. It's particularly important that any bug
fixes be accompanied by a test case which fails without the fix and
succeeds with it.
Tests should be placed in C files under the tests/ directory, and use
the macros defined in the nih/test.h header. See the existing test
examples to see how.
Any functions that allocate memory, or call any functions that
allocate memory (those marked with the "malloc" attribute) should be
tested using the TEST_ALLOC_FAIL macro to ensure that the case of
insufficient memory is handled properly.
|