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 | |
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 |
19 | Building: |
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 | 30 | Testing: |
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 | ||
41 | APIs 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 | ||
65 | The 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 | ||
118 | Web 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 | ||
128 | Disobedience: | |
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 | ||
144 | Code 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 | ||
168 | Local Variables: | |
169 | mode:text | |
170 | fill-column:79 | |
171 | End: |