--- /dev/null
+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:
+