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