chiark / gitweb /
De-dupe edit menu callbacks.
[disorder] / README
diff --git a/README b/README
index 267025d114193f1c24391db3c8027e9a0fe33e9e..acd06ee5b2ee690269849eaa0194b37259be5a8c 100644 (file)
--- a/README
+++ b/README
@@ -13,12 +13,15 @@ DisOrder is a multi-user software jukebox.
      GTK+ interface that runs on Linux and Mac systems.
    * Playing tracks can be paused or cancelled ("scratched").
 
-See CHANGES for details of recent changes to DisOrder and README.upgrades for
-upgrade instructions.
+See CHANGES.html for details of recent changes to DisOrder and README.upgrades
+for upgrade instructions.
 
-The server supports Linux and can be made to work on a Mac (see README.mac).
-The clients work on both Linux and the Mac.  It could probably be ported to
-some other UNIX variants without too much effort.  Things you will need:
+Platform support:
+  Linux            Well tested on Debian
+  Mac OS X         Disobedience well tested, server somewhat tested; use fink
+  FreeBSD          Scantily tested; use ports for dependencies
+It could probably be ported to some other UNIX variants without too much
+effort.
 
 Build dependencies:
   Name             Tested              Notes
@@ -41,23 +44,12 @@ 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)
+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.
 
-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
+Bug tracker, etc:
+  http://code.google.com/p/disorder/
 
 Mailing lists:
   http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-discuss
@@ -65,6 +57,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
 ============
@@ -74,18 +68,19 @@ Installation
 
 IMPORTANT: If you are upgrading from an earlier version, see README.upgrades.
 
-On a Debian or Ubuntu system, if you install from .deb files then you should be
-able to skip steps 1 to 6 and configure it via debconf.  This is strongly
-recommended!
+Debian/Ubuntu: steps 1 to 6 are dealt with automatically if you use the .deb
+files.
+
+OX X/FreeBSD/other Linux: after installation (step 1 and 2), running
+'sudo bash scripts/setup' will cover steps 3 to 6.  If it doesn't work on your
+platform, please get in touch.
 
 1. Build the software.  Do something like this:
 
-     ./configure --sysconfdir=/etc --localstatedir=/var
-     make
+     ./configure
+     make                   # on FreeBSD use gmake
 
-   See INSTALL for more details about driving configure.  The precise set of
-   options you pass to configure is up to you, if you like configuration being
-   in /usr/local/etc or wherever then that should work.
+   See INSTALL or ./configure --help for more details about driving configure.
 
    If you only want to build a subset of DisOrder, specify one or more of the
    following options:
@@ -93,15 +88,23 @@ recommended!
      --without-gtk          Don't build GTK+ client (Disobedience)
      --without-python       Don't build Python support
 
+   If configure cannot guess where your web server keeps its HTML documents and
+   CGI programs, you may have to tell it, for instance:
+
+     ./configure cgidir=/whatever/cgi-bin httpdir=/whatever/htdocs
+
    See README.client for setting up a standalone client (or read the
    disobedience man page).
 
+   To build .debs on Debian/Ubuntu, use:
+     fakeroot debian/rules binary
+
 2. Install it.  Most of the installation is done via the install target:
 
      make installdirs install
 
-   The CGI interface has to be installed separately; see under 'Web Interface'
-   below.
+   NB steps 3 to 6 are covered by scripts/setup.  It should work on FreeBSD, OS
+   X and Linux and could be adapted to other platforms.
 
 3. Create a 'jukebox' user and group, with the jukebox group being the default
    group of the jukebox user.  The server will run as this user and group.
@@ -173,6 +176,9 @@ recommended!
    Disobedience from some other host, File->Login allows hostnames, passwords
    etc to be configured.
 
+   Alternatively, after setting up the web interface (below), it's possible to
+   allow users to register themselves without operator involvement.
+
 9. Optionally source completion.bash from /etc/profile or similar, for
    example:
 
@@ -186,8 +192,10 @@ Web Interface
 
    "Thought I was a gonner baby, but I'm bullet proof"
 
-As above, if you install from a .deb, much of the work will be done
-automatically.
+Debian/Ubuntu: the .deb files will do the setup here automatically.
+
+OS X/FreeBSD/other Linux: scripts/setup as referred to above will do the setup
+here automatically.
 
 You need to configure a number of things to make this work:
 
@@ -198,12 +206,20 @@ You need to configure a number of things to make this work:
 
      mail_sender webmaster@example.com
 
-   By default the web interface sends mail by connecting to the SMTP port of
-   127.0.0.1.  You can override this with the smtp_server directive, for
-   exampler:
+   By default the web interface sends mail via the system sendmail executable
+   (typically /usr/sbin/sendmail or /usr/lib/sendmail).  You can override this
+   with the sendmail directive, for example:
+
+     sendmail /usr/sbin/my-sendmail
+
+   The executable you choose must support the -bs option.  Alternatively you
+   can tell it to connect to an SMTP server via TCP, with the smtp_server
+   directive.  For example:
 
      smtp_server mail.example.com
 
+   Use 'disorder reconfigure' to make sure the server knows these settings.
+
 2. The web interface depends on a 'guest' user existing.  You can create this
    with the following command:
 
@@ -213,31 +229,15 @@ You need to configure a number of things to make this work:
 
      disorder setup-guest --no-online-registration
 
-3. Make sure that DisOrder can find its icons and stylesheet.  For example in
-   your web server configuration:
-
-     Alias /disorder/ /usr/local/share/disorder/static/
-
-   Alternatively you could use a symlink from the right location in your
-   document root, provided your web server is configured to follow them.
-
-     cd /var/www
-     ln -s /usr/local/share/disorder/static disorder
-
-4. Install disorder.cgi in an appropriate location.  Remember to make it
-   executable.  Example:
-
-     install -m 755 server/disorder.cgi /usr/lib/cgi-bin/disorder
-
-5. Try it out.  You should be able to perform read-only operations straight
+3. Try it out.  You should be able to perform read-only operations straight
    away, and after visiting the 'Login' page to authenticate, perform other
    operations like adding a track to the queue.
 
-6. If you run into problems, always look at the appropriate error log; the
+4. If you run into problems, always look at the appropriate error log; the
    message you see in your web browser will usually not be sufficient to
    diagnose the problem all by itself.
 
-7. If you have a huge number of top level directories, then you might find
+5. If you have a huge number of top level directories, then you might find
    that the 'Choose' page is unreasonably large.  If so add the following line
    to /etc/disorder/options.user:
      label sidebar.choosewhich choosealpha
@@ -265,6 +265,7 @@ Portions copyright (C) 2007 Mark Wooding
 Portions extracted from MPG321, http://mpg321.sourceforge.net/
   Copyright (C) 2001 Joe Drew
   Copyright (C) 2000-2001 Robert Leslie
+Portions Copyright (C) 1997-2006 Free Software Foundation, Inc.
 Binaries may derive extra copyright owners through linkage (binary distributors
 are expected to do their own legwork)