| 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 | * 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 | |
| 33 | Building: |
| 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 | |
| 44 | Testing: |
| 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 | |
| 55 | APIs 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 | |
| 79 | The 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 | |
| 135 | Web 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 | |
| 146 | Disobedience: |
| 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 | |
| 162 | New 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 | |
| 171 | Code 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 | |
| 204 | Local Variables: |
| 205 | mode:text |
| 206 | fill-column:79 |
| 207 | End: |