chiark / gitweb /
cgi/cgimain.c: Make the CGI program be (a little) locale-aware.
[disorder] / README.developers
index 9e73d01..0f9809b 100644 (file)
@@ -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-<name>.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