chiark / gitweb /
New README.developers and README.freebsd. README.client improved.
authorrjk@greenend.org.uk <>
Sun, 6 Jan 2008 18:27:54 +0000 (18:27 +0000)
committerrjk@greenend.org.uk <>
Sun, 6 Jan 2008 18:27:54 +0000 (18:27 +0000)
Don't put non-Linux READMEs in the Debian package!

Makefile.am
README
README.client
README.developers [new file with mode: 0644]
README.freebsd [new file with mode: 0644]
README.mac
debian/rules

index 99d2fd2..c9a8116 100644 (file)
@@ -1,6 +1,6 @@
 #
 # This file is part of DisOrder.
-# Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
+# Copyright (C) 2004-2008 Richard Kettlewell
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -19,7 +19,8 @@
 #
 
 EXTRA_DIST=TODO CHANGES README.streams BUGS ChangeLog.d        \
-README.upgrades README.client README.mac README.raw README.vhost
+README.upgrades README.client README.mac README.raw README.vhost \
+README.freebsd README.developers
 SUBDIRS=@subdirs@
 
 check-report: before-check check make-coverage-reports
diff --git a/README b/README
index d1e235e..f0f67ea 100644 (file)
--- a/README
+++ b/README
@@ -41,23 +41,9 @@ Build dependencies:
 "Tested" means I've built against that version; earlier or later versions will
 often work too.
 
-Runtime dependencies:
- * Web server:
-   + Apache 1.3.x works for me, but anything that supports CGI and
-     authentication should be suitable.
- * Separate player programs are no longer required (but may still be used)
-
-Development dependencies (only developers will need these):
-  Automake         1.10                AM_PATH_PYTHON not good enough in 1.7
-  Autoconf         2.61
-  Libtool          1.5.22              1.4 not good enough
-  Bazaar (bzr)
-
-On Debian you might ensure you have the required packages as follows:
-  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
+For the web interface to work you will additionally need a web server.  I've
+had both Apache 1.3.x and 2.x working.  Anything that supports CGI should be
+OK.
 
 Mailing lists:
   http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-discuss
@@ -65,6 +51,8 @@ Mailing lists:
   http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-announce
    - announcements of new versions of DisOrder
 
+Developers should read README.developers.
+
 
 Installation
 ============
index fb55754..cec4e8c 100644 (file)
@@ -6,37 +6,30 @@ has a 'listen PORT' directive in its configuration file.
 
 There is currently no standard DisOrder port number.
 
+ 1. Configure the software with --without-server (and, optionally,
+    --without-python) and build and install it.
 
-1. Configure the software with --without-server (and, optionally,
---without-python) and build and install it.  Set up a stub config in
-/etc/disorder/config (or /usr/local/etc/disorder/config if you didn't
-set a nondefault --prefix) with the following contents:
+ 2. Set up a stub config in /etc/disorder/config (or
+    /usr/local/etc/disorder/config if you didn't set a nondefault --prefix)
+    with the following contents:
 
-   connect jukebox PORT
+      connect jukebox PORT
 
-where PORT is the same as 'listen PORT' on the server.
+    where PORT is the same as 'listen PORT' on the server.
 
+ 3. Copy the password file for each user to ~USER/.disorder/passwd, the
+    contents being:
 
-2. Copy the password file for each user to /etc/disorder/config.USER,
-the contents being:
+      password PASSWORD
 
-  password PASSWORD
+    If the DisOrder username differs from the local username then use a
+    'username' directive.
 
-Alternatvely, each user can use ~/.disorder/passwd, with the same contents.  If
-the DisOrder username differs from the local username then use a 'username'
-directive.
+ 4. Test by issuing 'disorder playing'.
 
+ 5. Run 'disobedience' for the GUI client.
 
-3. Test by issuing 'disorder playing'.
-
-
-4. Run 'disobedience' for the GUI client.
-
-
-The web interface could in principle be made to work on a separate
-machine from the main server, though it is unlikely to be efficient
-and at the moment it is built whenever the server is, so you will have
-to unpick them a bit yourself if you wish to do this.
+Alternatively, skip steps 2-4 and use Disobedience's login dialog.
 
 
 Local Variables:
diff --git a/README.developers b/README.developers
new file mode 100644 (file)
index 0000000..6866e4d
--- /dev/null
@@ -0,0 +1,160 @@
+Dependencies:
+
+   * You'll need, in addition to the packages mentioned in README:
+     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
+
+   * 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
+
+   * Please report unstated dependencies (here, README or debian/control).
+
+Testing:
+
+   * There is an extensive test suite in lib/test.c and tests/*.py.  You can
+     run the tests with 'make check'.  If possible please add tests for new
+     code to at least one of these.  At the very least the existing tests
+     should continue to pass.
+
+   * The tests will not currently pass in an ASCII locale.  This is essentially
+     unavoidable given the need to test Unicode support.  ISO 8859-1 or UTF-8
+     locales should be OK for the time being.
+
+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).
+     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.
+     2) Add a new section to server/decode.c.  NB this file may be split into
+        several bits one day.
+     3) Add a new section to plugins/tracklength.c.  Again this file may be
+        split up in a future version.
+     4) Update default_players[] in lib/configuration.c.
+     5) Update doc/disorder_config.5.in.
+
+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.
+
+   * The server process does not use threads and I would like to keep it that
+     way.
+
+   * The server uses the Boehm garbage collector.  This eliminates the need to
+     call free() and similar functions in many cases, though teardown calls to
+     that do more than free GC-allocated memory (such as fclose()) are still
+     required.
+
+   * DisOrder's *printf calls, such as byte_xasprintf(), are mostly preferred
+     within the server to the ones built into libc.  An important distinction
+     is that they will always accept UTF-8 strings whereas the built-in ones
+     may reject them in non-UTF-8 locales (for instance Glibc does this) with
+     EILSEQ.  Only where the data is guaranteed to be ASCII may the libc
+     functions be used.
+
+   * To add a new configuration directive:
+     1) Add a new entry to the struct in lib/configuration.h
+     2) Add a new table entry to conf[] in lib/configuration.c
+     3) If the directive is entirely unlike existing ones add a new type_
+        to lib/configuration.c
+     4) Set the default if non-0 in config_default().  In some cases
+        config_postdefaults() may be more appropriate.
+     5) Document the new directive in doc/disorder_config.5.in
+
+   * 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
+     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.
+
+   * If the command needs a new right to be defined then update lib/rights.[ch]
+     and doc/disorder_config.5.in.  New rights should definitely be mentioned
+     in README.upgrades as existing users will not automatically get new rights
+     even if they are in default_rights.  If the new right should not be in
+     default_rights by default then you must update config_postdefaults().
+
+Web Interface:
+
+   * The web interface does not use Javascript or Flash and I would like to
+     keep it that way.
+
+   * 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.
+
+Disobedience:
+
+   * Disobedience does not currently use threads and I'd prefer to keep it that
+     way.
+
+   * Disobedience uses the Boehm garbage collector but not for GTK+/GLIB's
+     memory allocation, as they are incompatible with it.  So you still have to
+     do somewhat manual memory management for GTK+ objects.  Fortunately it has
+     its own refcounting system which does most of the work for you.
+
+   * Lengthy operations must not block.  In practice this seems to be a less of
+     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.
+
+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.
+
+   * More importantly, new configuration directives, protocol commands,
+     interface features etc should be documented in the relevant places.
+
+   * If you add new dependencies please update README, README.developers and
+     debian/control.
+
+   * New dependencies that are not in Debian stable are likely to be rejected.
+     (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
+     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").
+
+Local Variables:
+mode:text
+fill-column:79
+End:
diff --git a/README.freebsd b/README.freebsd
new file mode 100644 (file)
index 0000000..47399cc
--- /dev/null
@@ -0,0 +1,20 @@
+DisOrder on FreeBSD
+===================
+
+The server builds on FreeBSD, using the ports system to supply many of
+its dependencies.  It is not well tested in this environment.  In
+particular, since my FreeBSD VM lacks sound support, only network play
+has been tested.  Please report successes and failures!
+
+
+Things you will need to do:
+
+* Create the jukebox user and group
+
+  sudo pw groupadd -n jukebox
+  sudo pw useradd -n jukebox
+  sudo pw groupmod jukebox -m jukebox
+
+* Arrange for the server to start at boot time
+
+* Start the server
index a9a500c..2bb249a 100644 (file)
@@ -1,8 +1,9 @@
 DisOrder on OS X
 ================
 
-The server builds on OS X.  It is not well tested in this environment.
-Please report successes and failures!
+The server builds on OS X, using Fink to supply many of its
+dependencies.  It is not well tested in this environment.  Please
+report successes and failures!
 
 
 Things you will need to do:
index 805a5e0..44219c5 100755 (executable)
@@ -104,6 +104,8 @@ pkg-disorder: build
        $(INSTALL_DATA) CHANGES README debian/README.Debian \
                BUGS README.* \
                debian/disorder/usr/share/doc/disorder/.
+       rm -f debian/disorder/usr/share/doc/disorder/README.mac
+       rm -f debian/disorder/usr/share/doc/disorder/README.freebsd
        bzr log > debian/disorder/usr/share/doc/disorder/changelog
        gzip -9f debian/disorder/usr/share/doc/disorder/changelog \
                 debian/disorder/usr/share/doc/disorder/CHANGES \