New file describing installation and things. Important now that the CGI

interface needs configuring before use.

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..03d49e0
--- /dev/null
+++ b/README
@@ -0,0 +1,91 @@
+SW-TOOLS
+~~~~~~~~
+
+Quick introduction
+
+       A few tools for maintaining user-contributed software at a site.
+       There are currently two main bits:
+
+         * A tool for building programs on multiple machines
+           simultaneously.  This saves time and effort and makes proper
+           support for multiple architectures more realistic.
+
+         * A CGI script for navigating the documentation provided in
+           the contributed software area.
+
+       There are also some other bits which aren't as interesting.
+
+
+Installation
+
+       The software comes with a `configure' script which should be
+       able to work out how to set the software up.  You need an ANSI C
+       compiler (GCC would be best, probably), a POSIX-ish system, and
+       Perl 5.003 or later.
+
+       Since it's designed to work in a heterogeneous environment,
+       here's how I'd do an initial build.  First, unpack the
+       distribution archive (the thing this file came in) on some
+       network filesystem which all your hosts can see.  Then make a
+       directory for each architecture.  Now, once for each
+       architecture, change into the directory you made for it, and run
+
+         ../configure --prefix=PREFIX --exec-prefix=EXEC-PREFIX
+
+       where PREFIX is where you want your installed software to end
+       up, and EXEC-PREFIX is where architecture-specific things should
+       go for this architecture.  (They can be the same if you like; I
+       don't recommend this).  Then run `make', and `make install'.
+       You should now be ready.
+
+
+Configuration
+
+       The next thing to do is tell `sw' which architectures you have
+       and which machines compilations should be done on.  Edit
+       PREFIX/share/archtab in a text editor, and fill it in, one entry
+       per line, architecture space hostname.  Architecture names are
+       displayed by the configuration script as it goes, and can be
+       discovered by typing `sw arch' on the appropriate host.
+
+       The main `sw' program should just work now.  Read the manual to
+       find out how it works.  The rest of this document assumes you've
+       done that.
+
+       You can set up site policy by editing a script
+       PREFIX/share/sw-precommit if you like: if this script returns
+       failure, a `commit' command will fail.  We use it here to ensure
+       that a user has written a documentation file for the package.
+
+       The CGI script needs a little more work.  You need to tell the
+       web server where to find it (by default it's gone into
+       EXEC-PREFIX/cgi-bin).  You also need to edit its configuration
+       file, which is in PREFIX/share/sw.conf.  The most important
+       thing to do is to uncomment the line saying that you've edited
+       the file; otherwise the script will complain at your users.  You
+       should also fill in a value for `domain'.
+
+       Then just publish the URL for the CGI, and everyone will be
+       happy.
+
+       The script is described in sw-cgi(1).
+
+
+Other stuff
+
+       All of this was written by Mark Wooding.  It's available under
+       the GNU General Public License, which you have a copy of in the
+       file called `COPYING' included with the distribution.  You don't
+       get a warranty, not of any kind.  If it doesn't work, that's
+       your hard luck.  (Send me a bug report and I might fix it,
+       though.)
+
+       Cheers,
+
+               Mark Wooding, <mdw@nsict.org>
+
+\f
+Local variables:
+mode: text
+End:
+