Hands-off reading for FLAC.

[disorder] / README.developers

diff --git a/README.developers b/README.developers
index f7d9cfd5d6654977c0b31d28f04a876c716e1eae..5c71b07bbdc75f26fb2e6e3e1592c07bdb2fbc9e 100644 (file)
--- a/README.developers
+++ b/README.developers
@@ -5,23 +5,36 @@ Dependencies:
      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
      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
+     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 \
                     libgc-dev libgcrypt-dev libpcre3-dev libvorbis-dev \
                     libao-dev libmad0-dev libasound2-dev libdb4.3-dev \
 
    * On Debian and derivatives this should work:
 
      apt-get install gcc libc-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
+                    libflac-dev vorbis-tools wget libsamplerate0-dev
+
+     On lenny use libdb4.5-deb.  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 libao 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:
 
 
    * 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 bzr,
+     so if you didn't use a source tarball, you must start as follows:

 
 

-        bash ./prepare -C
+        bash ./autogen.sh
+        ./configure -C

         make
 
    * On FreeBSD you must use gmake.
         make
 
    * On FreeBSD you must use gmake.


@@ -41,16 +54,11 @@ APIs And Formats:
 
    * To support a new sound API:
      1) Teach configure.ac how to detect any libraries required.
 
    * 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.
      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.
 
    * To support a new file format:
      1) Teach configure.ac how to detect any libraries required.


@@ -64,10 +72,13 @@ APIs And Formats:
 The Server:
 
    * The server's command implementations must not block.  Waiting for a little
 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.
 
    * The server process does not use threads and I would like to keep it that
      way.


@@ -117,12 +128,11 @@ The Server:
 Web Interface:
 
    * The web interface does not use Javascript or Flash and I would like to
 Web Interface:
 
    * The web interface does not use Javascript or Flash and I would like to

-     keep it that way.
+     keep it that way; Javascript might be acceptable but it must degrade
+     gracefuly if disabled.  Clever use of CSS is OK provided it works well on
+     the mainstream browsers.

 
 

-   * I know that the web template syntax is rather nasty.  Perhaps it will be
-     improved in a future version.
-
-   * Update templates/help.html for any changes you make.
+   * Update templates/help.tmpl for any changes you make.

 
 Disobedience:
 
 
 Disobedience:
 


@@ -140,13 +150,24 @@ Disobedience:
 
    * Update doc/disobedience.1.in for any changes you make.
 
 
    * Update doc/disobedience.1.in 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:
 
    * Please follow the existing layout conventions.
 
    * 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
 Code And Patches:
 
    * Please follow the existing layout conventions.
 
    * 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.
 
    * More importantly, new configuration directives, protocol commands,
      interface features etc should be documented in the relevant places.


@@ -158,11 +179,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.)
 
      (But if your new feature only makes sense on a given platform then
      obviously its new dependencies don't need to be available elsewhere.)
 

+   * 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 bzr
      branch somewhere I can get at it.
 
    * Please make it clear that your changes can be distributed under DisOrder's
    * Please submit patches either using 'diff -u', or by publishing a bzr
      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
 
 Local Variables:
 mode:text