source: trunk/debathena/third/schroot/HACKING @ 24167

Revision 24167, 4.1 KB checked in by broder, 15 years ago (diff)
Import schroot upstream into subversion.
Line 
1Working on schroot                           -*- text -*-
2==================
3
4This document is a short guide to the conventions used in the schroot
5project.
6
7
8Coding
9------
10
11The style should be apparent from the source.  It is the default Emacs
12c++-mode style, with paired brackets aligned vertically.
13
14* Use 0 rather than NULL.
15* Use C++ casts rather than C-style casts.
16* Don't use void * unless there is no alternative.
17* Add doxygen comments for everything; use EXTRACT_ALL = NO in
18  doc/schroot.dox to check for missing or incomplete documentation.
19
20
21Format strings
22--------------
23
24The sources use boost::format for type-safe formatted output.  Make
25sure that the maximum number of options passed is the same as the
26highest %n% in the format string.
27
28The following styles are used
29
30  Style                  Formatting                Syntax
31  --------------------------------------------------------------------
32  Values                 Single quotes             '
33  Example text           Double quotes             \"
34  User input             Double quotes             \"
35
36These are transformed into proper UTF-8 quotes with gettext.
37
38
39Documentation
40-------------
41
42All the documentation is in UNIX manual page format.  GNU roff
43extensions are permitted, as is use of tbl.  Make sure the printed
44output is as good as terminal display.  Run "make ps" or "make pdf" to
45build the printed documentation.
46
47
48The following styles are used:
49
50  Style                  Formatting                Syntax
51  --------------------------------------------------------------------
52  New term               Bold                      .B or \fB
53  Option definition      Bold, args in italic      .BR and \fI
54  Option reference       Italic                    .I or \fI
55  File definition        Bold italic               \f[BI]
56  File reference         Italic                    .I or \fI
57  Config key definition  Courier bold italic       \f[CBI]
58  Config key reference   Courier italic            \f[CI]
59  Values                 Single quotes             \[oq] and \[cq]
60  Example text           Double quotes             \[lq] and \[rq]
61  Cross references       Italics in double quotes  \[lq]\fI...\fP\[rq]
62  Verbatim examples      Courier                   \f[CR]
63  Verbatim user input    Courier bold              \f[CB]
64
65
66Releasing
67---------
68
69The code must pass the testsuite (make check).  It must also pass some
70tests which must be run by hand:
71
72Chdir fallback behaviour:
73
74  schroot [login shell]
75    CWD → CWD            Normal behaviour
76    CWD → $HOME          If CWD nonexistent and -p used
77    CWD → passwd pw_dir  If CWD nonexistent (or -p used and no $HOME exists)
78    CWD → /              None of the above exist
79    *FAIL*               If / nonexistent
80
81  schroot [command]
82    CWD → CWD            Normal behaviour
83    *FAIL*               If CWD nonexistent
84
85    No fallbacks should exist under any circumstances.
86
87  schroot [--directory used]
88    CWD → DIR            Normal behaviour
89    *FAIL*               If DIR nonexistent
90
91    No fallbacks should exist under any circumstances.
92
93  dchroot [login shell or command]
94    CWD → passwd pw_dir  Normal behaviour (not if -d used)
95    CWD → CWD            If -d used
96    CWD → /              If CWD nonexistent and -d used
97    *FAIL*               If / nonexistent
98
99  dchroot [--directory used]
100    CWD → DIR            Normal behaviour
101    *FAIL*               If DIR nonexistent
102
103    No fallbacks should exist under any circumstances.
104
105  dchroot-dsa [login shell or command]
106    CWD → passwd pw_dir  Normal behaviour
107    CWD → /              If no passwd_pw dir
108    *FAIL*               If / nonexistent
109
110  dchroot-dsa [--directory used]
111    CWD → DIR            Normal behaviour
112    *FAIL*               If DIR nonexistent
113
114    No fallbacks should exist under any circumstances.
115
116  Note that --debug=notice will show the internal fallback list
117  computed for the session.
118
119
120Setup script behaviour:
121
122  To check if process termination works:
123  schroot -v -c sid -- sh -c "trap '' INT; trap '' TERM; sleep 2 &"
124
125  To check if process killing works:
126  schroot -v -c sid -- sh -c "trap '' INT; trap '' TERM; sleep 20 &"
Note: See TracBrowser for help on using the repository browser.