HACKING 6.69 KB
Newer Older
1
2
Bootstraping from CVS:
======================
3
4
5
6
7
8
9
10

Some files in SPOT's source tree are generated.  They are distributed
so that users do not need to tools to rebuild them, but we don't keep
all of them under CVS because it can generate lots of changes or
conflicts.

Here are the tools you need to bootstrap the CVS tree, or more
generally if you plan to regenerate some of the generated files.
11

12
13
  GNU Autoconf >= 2.61
  GNU Automake >= 1.10
14
  GNU Flex (the version seems to matters, we used 2.5.31)
15
  GNU Bison >= 2.3
16
  SWIG >= 1.3.31
17
  Doxygen >= 1.4.0
18
19
20

Bootstrap the CVS tree by running

21
  autoreconf -vi
22

23
and then go on with the usual
24
25
26
27

  ./configure
  make

28

29
30
31
32
33
34
35
36
37
38
39
40
We also use

  GNU Libtool >= 1.4

however since many distributions modify their version, some
(e.g. Debian) in a way that break Spot, we have our own copy of
ltmain.sh and libtool.m4 in the CVS repository of Spot.  That means
you do not need an installed copy of Libtool.  If you want to
overwrite these files with those from your copy of Libtool, use
`autoreconf -vfi' instead of `autoreconf -vi'.


41
42
43
44
Coding conventions:
===================

Here are the conventions we follow in Spot, so that the code looks
45
46
47
48
49
50
homogeneous.  Please follow these strictly.  Since this is free
software, uniformity of the code matters a lot.  Most of these
conventions are derived from the GNU Coding Standards
(http://www.gnu.org/prep/standards.html) with the notable exception
that we do not put a space before the opening parenthesis in function
calls (this is hardly readable when chaining method calls).
51
52
53
54
55
56
57
58
59
60

Comments
--------

  * The language to use is American.

  * When comments are sentences, they should start with a capital and
    end with a dot.  Dots that end sentences should be followed by two
    spaces (i.e., American typing convention), like in this paragraph.

61
62
63
  * Prefer C++-style comments (// foo) to C-style comments (/* foo */).
    Use /// for Doxygen comments.

64
65
66
Formating
---------

67
  * Braces are always on their own line.
68
69
70
71
72

  * Text within braces is two-space indented.

    {
      f(12);
73

74
75
76
77
78
79
80
81
82
83
84
85
    }

  * Anything after a control statement is two-space indented.  This
    includes braces.

    if (test)
      {
        f(123);
	while (test2)
	  g(456);
      }

86
  * Braces from function/structure/enum/class/namespace definitions
87
88
89
90
91
92
93
94
95
96
97
    are not indented.

    class foo
    {
    public:
      Foo();
    protected:
      static int get_mumble();
    };

  * The above corresponds to the `gnu' indentation style under Emacs.
98
99
100

  * Put return types and linkage specifiers on their own line in
    function/method _definitions_:
101
102
103
104
105
106
107
108
109

    static int
    Foo::get_mumble()
    {
      return 2;
    }

    This makes it easier to grep functions in the code.

110
111
112
    Function/method declaration are usually written on one line:

    int get_bar(int i);
113

114
  * Put a space before the opening parenthesis in control statements
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

    if (test)
      {
        do
	  {
	    something();
	  }
	while (0);
      }

  * No space before parentheses in function calls.
    (`some()->foo()->bar()' is far more readable than
    `some ()->foo ()->bar ()' is)

  * No space after opening or before closing parentheses, however
    put a space after commas (as in english).
131

132
    func(arg1, arg2, arg3);
133

134
135
136
137
138
139
140
141
142
  * No useless parentheses in return statements.

    return 2;    (not `return (2);')

  * Spaces around infix binary or ternary operators:

    2 + 2;
    a = b;
    a <<= (3 + 5) * 3 + f(67 + (really ? 45 : 0));
143

Alexandre Duret-Lutz's avatar
typo    
Alexandre Duret-Lutz committed
144
145
  * No space after prefix unary operators, or before postfix unary
    operators:
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

    if (!test && y++ != 0)
      {
        ++x;
      }

  * When an expression spans over several lines, split it before
    operators.  If it's inside a parenthesis, the following lines
    should be 1-indented w.r.t. the opening parenthesis.

    if (foo_this_is_long && bar > win(x, y, z)
        && !remaining_condition)
      {
        ...
      }

162
163
  * `else if' can be put as-is on a single line.

164
165
  * No line should be larger than 80 columns.
    If a line takes more than 80 columns, split it or rethink it.
166

167
  * Labels or case statements are back-indented by two spaces,
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
168
    without space before the `:'.
169

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
    if (something)
      {
      top:
        bar = foo();
        switch (something_else)
	  {
	  case first_case:
	    f();
	    break;
	  case second_case:
	    g();
	    break;
	  default:
	    goto top;
	  }
      }

187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
  * Pointers and references are part of the type, and should be put
    near the type, not near the variable.

      int* p;        // not `int *p;'
      list& l;       // not `list &l;'
      void* magic(); // not `void *magic();'

  * Do not declare many variables on one line.
    Use
      int* p;
      int* q;
    instead of
      int *p, *q;
    The former declarations also allow you to describe each variable.

  * The include guard for src/somedir/foo.hh is
    SPOT_SOMEDIR_FOO_HH


206
207
208
209
210
211
212
213
214
Naming
======

  * Functions, methods, types, classes, etc. are named with lowercase
    letters, using an underscore to separate words.

      int compute_this_and_that();

      class this_is_a_class;
215

216
217
218
219
      typedef int int_array[];

    That is the style used in STL.

220
  * Private members end with an underscore.
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241

    class my_class
    {
    public:
      ...
      int get_val() const;
    private:
      int name_;
    };

  * Identifiers (even internal) starting with `_' are best avoided
    to limit clashes with system definitions.

  * Template arguments use capitalized name, with joined words.

    template <class T, int NumberOfThings>
    class foo
    {
      ...
    };

242
  * Enum members also use capitalized name, with joined words.
243
244
245

  * C Macros are all uppercase.

246
247
  * Use *.hxx for the implementation of templates that are private
    to Spot (i.e. not installed) and need to be included multiple times.
248

249
250
Other style recommandations
===========================
251

252
253
  * Do not use the NULL macro, it is not always implemented in a way
    which is compatible with all pointer types.  Always use 0 instead.
254

255
256
257
258
259
  * Limit the scope of local variables by defining them as late as
    possible.  Do not reuse a local variables for two different things.

  * Do not systematically initialise local variables with 0 or other
    meaningless values.  This hides errors to valgrind.
260
261
262
263
264

  * Avoid <iostream>, <ostream>, etc. in headers whenever possible.
    Prefer <iosfwd> when predeclarations are sufficient, and then
    use for instance use just <ostream> in the corresponding .cc file.
    (A plain <iostream> is needed when using std::cout, std::cerr, etc.)
265
266
267
268
269
270

  * Always declare helper functions and other local class definitions
    (used in a single .cc files) in anonymous namespaces.  (The risk
    otherwise is to declare two classes with the same name: the linker
    will ignore one of the two silently.  The resulting bugs are often
    difficult to understand.)