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