chiark / gitweb /
cgi/cgimain.c: Make the CGI program be (a little) locale-aware.
[disorder] / README.developers
CommitLineData
91d9a42d 1Dependencies:
2
3 * You'll need, in addition to the packages mentioned in README:
4 Automake 1.10 1.7 is no good; 1.8/9 might work
5 Autoconf 2.61 Slightly older might work too
6 Libtool 1.5.22 1.4 is no good
4255c180 7 git You might be able to manage without
9918a94b 8 Python 2.5.2 2.4 won't work
91d9a42d 9
10 * On Debian and derivatives this should work:
11
22debf83 12 apt-get install gcc libc6-dev automake autoconf libtool libgtk2.0-dev \
91d9a42d 13 libgc-dev libgcrypt-dev libpcre3-dev libvorbis-dev \
5cd650e5 14 libmad0-dev libasound2-dev libdb4.5-dev \
c3feb35b 15 libflac-dev vorbis-tools wget libsamplerate0-dev
91d9a42d 16
22debf83 17 libdb4.6 does not work (and configure will refuse to use it).
db8ab224 18
42f43a11 19 * On FreeBSD you'll need at least these packages:
5cd650e5 20 autotools bash flac mad boehm-gc db43 gmake gsed libgcrypt wget
128962e0 21 vorbis-tools
42f43a11 22
495f9857
RK
23 * On OS X with Fink:
24
128962e0
RK
25 fink install gtk+2-dev gc libgrypt pcre flac vorbis-tools libmad wget \
26 sed libsamplerate0-dev
495f9857 27
91d9a42d 28 * Please report unstated dependencies (here, README or debian/control).
29
b30155e3
RK
30Building:
31
4255c180 32 * Compiled versions of configure and the makefiles are not included in git,
db8ab224 33 so if you didn't use a source tarball, you must start as follows:
b30155e3 34
af5de747 35 bash ./autogen.sh
d558cce2 36 ./configure -C
b30155e3
RK
37 make
38
39 * On FreeBSD you must use gmake.
40
91d9a42d 41Testing:
42
43 * There is an extensive test suite in lib/test.c and tests/*.py. You can
44 run the tests with 'make check'. If possible please add tests for new
45 code to at least one of these. At the very least the existing tests
46 should continue to pass.
47
48 * The tests will not currently pass in an ASCII locale. This is essentially
49 unavoidable given the need to test Unicode support. ISO 8859-1 or UTF-8
50 locales should be OK for the time being.
51
52APIs And Formats:
53
54 * To support a new sound API:
55 1) Teach configure.ac how to detect any libraries required.
b116feb0
RK
56 2) Create lib/uaudio-<name>.c; see uaudio.h for the interface.
57 3) Update the list in lib/uaudio-apis.c
58 4) Add a new option to clients/playrtp.c and document it in
59 doc/disorder-playrtp.1.in (if appropriate).
91d9a42d 60 5) Update doc/disorder_config.5.in.
91d9a42d 61
62 * To support a new file format:
63 1) Teach configure.ac how to detect any libraries required.
64 2) Add a new section to server/decode.c. NB this file may be split into
65 several bits one day.
66 3) Add a new section to plugins/tracklength.c. Again this file may be
67 split up in a future version.
68 4) Update default_players[] in lib/configuration.c.
69 5) Update doc/disorder_config.5.in.
70
71The Server:
72
73 * The server's command implementations must not block. Waiting for a little
0590cedc
RK
74 disk IO is OK but blocking for extended periods on long-lasting
75 transactions or external resources is not acceptable; it will wedge the
76 server for all other users.
77
78 Long-running subprocesses should use subprograms (rather than forking but
79 not execing) if reasonably possible; see c_stats() for an example.
80 c_reminder() is probably in the grey area.
91d9a42d 81
82 * The server process does not use threads and I would like to keep it that
83 way.
84
85 * The server uses the Boehm garbage collector. This eliminates the need to
86 call free() and similar functions in many cases, though teardown calls to
87 that do more than free GC-allocated memory (such as fclose()) are still
88 required.
89
90 * DisOrder's *printf calls, such as byte_xasprintf(), are mostly preferred
91 within the server to the ones built into libc. An important distinction
92 is that they will always accept UTF-8 strings whereas the built-in ones
93 may reject them in non-UTF-8 locales (for instance Glibc does this) with
94 EILSEQ. Only where the data is guaranteed to be ASCII may the libc
95 functions be used.
96
97 * To add a new configuration directive:
98 1) Add a new entry to the struct in lib/configuration.h
99 2) Add a new table entry to conf[] in lib/configuration.c
100 3) If the directive is entirely unlike existing ones add a new type_
101 to lib/configuration.c
102 4) Set the default if non-0 in config_default(). In some cases
103 config_postdefaults() may be more appropriate.
104 5) Document the new directive in doc/disorder_config.5.in
105
106 * To add a new command:
107 1) Add a new c_ function and table entry in server/server.c
108 2) Document the new command in doc/disorder_protocol.5.in
22debf83 109 3) Add a new function to scripts/protocol.
91d9a42d 110 4) Add a new function to lib/eclient.c
111 5) Add a new function to python/disorder.py.in
112 6) Add a new command to clients/disorder.c and update doc/disorder.1.in
113 7) Add a new test somewhere in tests/*.py
91d9a42d 114
115 * See disorder_protocol(5) for details of how the status code is
116 constructed, and the existing commands for examples.
117
118 * If the command needs a new right to be defined then update lib/rights.[ch]
119 and doc/disorder_config.5.in. New rights should definitely be mentioned
120 in README.upgrades as existing users will not automatically get new rights
121 even if they are in default_rights. If the new right should not be in
122 default_rights by default then you must update config_postdefaults().
123
124Web Interface:
125
22debf83
RK
126 * The support targets are current Firefox, Chrome, IE and Safari. Obscure,
127 obsolete or text-only browsers are not of significant interest.
128
91d9a42d 129 * The web interface does not use Javascript or Flash and I would like to
22debf83
RK
130 keep it that way. Javascript is likely to be acceptable if useful, but it
131 should degrade gracefuly if unavailable. Clever use of CSS is OK provided
132 it works well on the mainstream browsers.
91d9a42d 133
50450a00 134 * Update templates/help.tmpl for any changes you make.
91d9a42d 135
136Disobedience:
137
138 * Disobedience does not currently use threads and I'd prefer to keep it that
139 way.
140
141 * Disobedience uses the Boehm garbage collector but not for GTK+/GLIB's
142 memory allocation, as they are incompatible with it. So you still have to
143 do somewhat manual memory management for GTK+ objects. Fortunately it has
144 its own refcounting system which does most of the work for you.
145
146 * Lengthy operations must not block. In practice this seems to be a less of
147 a problem for Disobedience than the server. Use the GLIB event loop to
148 deal with long-running operations if you do need any.
149
22debf83 150 * Update the contents of disobedience/manual/ for any changes you make.
91d9a42d 151
0590cedc
RK
152New Platforms:
153
154 * It is not mandatory to have an entry in configure's 'case $host' section,
155 but may well be convenient.
156
157 * Complete support for a new platform implies updating scripts/setup.in and
158 scripts/teardown.in as well as getting the software to build and work (but
159 this doesn't mean that patches that don't achieve this will be rejected).
160
91d9a42d 161Code And Patches:
162
163 * Please follow the existing layout conventions.
164
165 * Please try to write doc comments for new functions, types, etc using the
166 same syntax as the existing ones. Doxygen can be used to turn this into
0590cedc
RK
167 reference documentation (see http://www.stack.nl/~dimitri/doxygen/) but
168 really the point is to have good inline code documentation, not the
169 Doxygen output as such.
91d9a42d 170
171 * More importantly, new configuration directives, protocol commands,
172 interface features etc should be documented in the relevant places.
173
174 * If you add new dependencies please update README, README.developers and
175 debian/control.
176
177 * New dependencies that are not in Debian stable are likely to be rejected.
178 (But if your new feature only makes sense on a given platform then
179 obviously its new dependencies don't need to be available elsewhere.)
180
1b8ed51f
RK
181 * GCCisms such as typeof and C99isms such as mixed declarations and named
182 structure initializers are used; the configure script asks for -std=gnu99
183 by default. Some supported platforms are still on GCC 4.0.
f0a76a4a 184
4255c180 185 * Please submit patches either using 'diff -u', or by publishing a git
91d9a42d 186 branch somewhere I can get at it.
187
188 * Please make it clear that your changes can be distributed under DisOrder's
7751df38 189 licence (which is "GPL v3 or later").
91d9a42d 190
191Local Variables:
192mode:text
193fill-column:79
194End: