From 91d9a42d3d2a8382f1b3729b2f4c6c2aafe4126d Mon Sep 17 00:00:00 2001 Message-Id: <91d9a42d3d2a8382f1b3729b2f4c6c2aafe4126d.1713516011.git.mdw@distorted.org.uk> From: Mark Wooding Date: Sun, 6 Jan 2008 18:27:54 +0000 Subject: [PATCH] New README.developers and README.freebsd. README.client improved. Don't put non-Linux READMEs in the Debian package! Organization: Straylight/Edgeware From: rjk@greenend.org.uk <> --- Makefile.am | 5 +- README | 22 ++----- README.client | 37 +++++------ README.developers | 160 ++++++++++++++++++++++++++++++++++++++++++++++ README.freebsd | 20 ++++++ README.mac | 5 +- debian/rules | 2 + 7 files changed, 208 insertions(+), 43 deletions(-) create mode 100644 README.developers create mode 100644 README.freebsd diff --git a/Makefile.am b/Makefile.am index 99d2fd2..c9a8116 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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 --- 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 ============ diff --git a/README.client b/README.client index fb55754..cec4e8c 100644 --- a/README.client +++ b/README.client @@ -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 index 0000000..6866e4d --- /dev/null +++ b/README.developers @@ -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 index 0000000..47399cc --- /dev/null +++ b/README.freebsd @@ -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 diff --git a/README.mac b/README.mac index a9a500c..2bb249a 100644 --- a/README.mac +++ b/README.mac @@ -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: diff --git a/debian/rules b/debian/rules index 805a5e0..44219c5 100755 --- a/debian/rules +++ b/debian/rules @@ -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 \ -- [mdw]