Commit | Line | Data |
---|---|---|
91d9a42d | 1 | Dependencies: |
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 |
30 | Building: |
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 | 41 | Testing: |
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 | ||
52 | APIs 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 | ||
71 | The 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 | ||
124 | Web 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 | |
136 | Disobedience: | |
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 |
152 | New 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 | 161 | Code 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 | |
191 | Local Variables: | |
192 | mode:text | |
193 | fill-column:79 | |
194 | End: |