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