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