X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/d558cce2164e78cae49f55a73c95fa4ce24df7c3..HEAD:/README.developers diff --git a/README.developers b/README.developers index 9e73d01..0f9809b 100644 --- a/README.developers +++ b/README.developers @@ -4,24 +4,35 @@ Dependencies: Automake 1.10 1.7 is no good; 1.8/9 might work Autoconf 2.61 Slightly older might work too Libtool 1.5.22 1.4 is no good - Bazaar (bzr) You might be able to manage without - Python 2.4 + git You might be able to manage without + Python 2.5.2 2.4 won't work * On Debian and derivatives this should work: - apt-get install gcc libc-dev automake autoconf libtool libgtk2.0-dev \ + apt-get install gcc libc6-dev automake autoconf libtool libgtk2.0-dev \ libgc-dev libgcrypt-dev libpcre3-dev libvorbis-dev \ - libao-dev libmad0-dev libasound2-dev libdb4.3-dev \ - libflac-dev + libmad0-dev libasound2-dev libdb4.5-dev \ + libflac-dev vorbis-tools wget libsamplerate0-dev + + libdb4.6 does not work (and configure will refuse to use it). + + * On FreeBSD you'll need at least these packages: + autotools bash flac mad boehm-gc db43 gmake gsed libgcrypt wget + vorbis-tools + + * On OS X with Fink: + + fink install gtk+2-dev gc libgrypt pcre flac vorbis-tools libmad wget \ + sed libsamplerate0-dev * Please report unstated dependencies (here, README or debian/control). Building: - * Compiled versions of configure and the makefiles are including in bzr, so - if you didn't use a source tarball, you must start as follows: + * Compiled versions of configure and the makefiles are not included in git, + so if you didn't use a source tarball, you must start as follows: - bash ./prepare + bash ./autogen.sh ./configure -C make @@ -42,16 +53,11 @@ APIs And Formats: * To support a new sound API: 1) Teach configure.ac how to detect any libraries required. - 2) Define a new BACKEND_ value and update configuration.[ch] for it. - 3) Create a suitable server/speaker-*.c along the pattern of the existing - ones. - 4) If possible create a suitable lib/mixer-*.c. This doesn't make sense - for all APIs (e.g. network), but even for those it does, playback - support without volume control support is likely to be acceptable (even - if inferior to full support). + 2) Create lib/uaudio-.c; see uaudio.h for the interface. + 3) Update the list in lib/uaudio-apis.c + 4) Add a new option to clients/playrtp.c and document it in + doc/disorder-playrtp.1.in (if appropriate). 5) Update doc/disorder_config.5.in. - 6) If relevant, create a suitable clients/playrtp-*.c and update - doc/disorder-playrtp.1.in. * To support a new file format: 1) Teach configure.ac how to detect any libraries required. @@ -65,10 +71,13 @@ APIs And Formats: The Server: * The server's command implementations must not block. Waiting for a little - disk IO is OK but blocking on long-lasting transactions or external - resources is not acceptable. Long-running subprocesses should use - subprograms (rather than forking but not execing) if reasonably possible; - see c_stats() for an example. c_reminder() is probably in the grey area. + disk IO is OK but blocking for extended periods on long-lasting + transactions or external resources is not acceptable; it will wedge the + server for all other users. + + Long-running subprocesses should use subprograms (rather than forking but + not execing) if reasonably possible; see c_stats() for an example. + c_reminder() is probably in the grey area. * The server process does not use threads and I would like to keep it that way. @@ -97,14 +106,11 @@ The Server: * To add a new command: 1) Add a new c_ function and table entry in server/server.c 2) Document the new command in doc/disorder_protocol.5.in - 3) Add a new function to lib/client.c + 3) Add a new function to scripts/protocol. 4) Add a new function to lib/eclient.c 5) Add a new function to python/disorder.py.in 6) Add a new command to clients/disorder.c and update doc/disorder.1.in 7) Add a new test somewhere in tests/*.py - Depending on the purpose of the command it may be acceptable to leave out - some of the client side work - for instance commands only ever used by the - web interface are not implemented in lib/eclient.c. * See disorder_protocol(5) for details of how the status code is constructed, and the existing commands for examples. @@ -117,13 +123,15 @@ The Server: Web Interface: - * The web interface does not use Javascript or Flash and I would like to - keep it that way. + * The support targets are current Firefox, Chrome, IE and Safari. Obscure, + obsolete or text-only browsers are not of significant interest. - * I know that the web template syntax is rather nasty. Perhaps it will be - improved in a future version. + * The web interface does not use Javascript or Flash and I would like to + keep it that way. Javascript is likely to be acceptable if useful, but it + should degrade gracefuly if unavailable. Clever use of CSS is OK provided + it works well on the mainstream browsers. - * Update templates/help.html for any changes you make. + * Update templates/help.tmpl for any changes you make. Disobedience: @@ -139,7 +147,16 @@ Disobedience: a problem for Disobedience than the server. Use the GLIB event loop to deal with long-running operations if you do need any. - * Update doc/disobedience.1.in for any changes you make. + * Update the contents of disobedience/manual/ for any changes you make. + +New Platforms: + + * It is not mandatory to have an entry in configure's 'case $host' section, + but may well be convenient. + + * Complete support for a new platform implies updating scripts/setup.in and + scripts/teardown.in as well as getting the software to build and work (but + this doesn't mean that patches that don't achieve this will be rejected). Code And Patches: @@ -147,7 +164,9 @@ Code And Patches: * Please try to write doc comments for new functions, types, etc using the same syntax as the existing ones. Doxygen can be used to turn this into - reference documentation. + reference documentation (see http://www.stack.nl/~dimitri/doxygen/) but + really the point is to have good inline code documentation, not the + Doxygen output as such. * More importantly, new configuration directives, protocol commands, interface features etc should be documented in the relevant places. @@ -159,11 +178,15 @@ Code And Patches: (But if your new feature only makes sense on a given platform then obviously its new dependencies don't need to be available elsewhere.) - * Please submit patches either using 'diff -u', or by publishing a bzr + * GCCisms such as typeof and C99isms such as mixed declarations and named + structure initializers are used; the configure script asks for -std=gnu99 + by default. Some supported platforms are still on GCC 4.0. + + * Please submit patches either using 'diff -u', or by publishing a git branch somewhere I can get at it. * Please make it clear that your changes can be distributed under DisOrder's - licence (which is "GPL v2 or later"). + licence (which is "GPL v3 or later"). Local Variables: mode:text