--- toast 2003/11/08 21:52:54 1.238 +++ toast 2003/11/09 23:43:26 1.239 @@ -4454,6 +4454,93 @@ in some precompiled or specialized binary format, such as RPM. Binary packages are also supported. +=head2 Purpose + +B<toast> is designed to be used in any of three ways: + +=over 4 + +=item 1. + +Installing and managing software in the home directory of a non-root user +on a multi-user system. For example, I like to be able to run valgrind, +xdaliclock, Opera, and a few other programs on the Linux cluster at work +without having to bother the IT department about installing or supporting +those packages. + +=item 2. + +Installing and managing software packages in parallel to those installed +by a conventional package manager. For example, if I were maintaining a +computer system running some kind of mainstream Unix-like OS, it might be +convenient to be able to quickly install the latest OpenSSH from source +into C</usr/local> in order to work around a security vulnerability, +and then conveniently remove it once my vendor or distribution releases +an official package for that version. + +=item 3. + +Installing and managing all software for an entire Unix system; that is, +using B<toast> as the one true package manager for the system. This is +what I do on my (single-user) Linux box at home. + +=back + +Use #1 seems to be by far the most common in practice. As far as I know, +I'm the only one crazy enough to attempt #3, and no one bothers with #2. +In general, it's probably a good idea to use a real distribution (such +as Debian), and to use its native package management system whenever +possible, rather than using B<toast> to replace it or go behind its back. + +=head2 Requirements + +B<toast> itself is known to work with Perl 5.005_03 through 5.8.x under +Linux, FreeBSD and Cygwin, without relying on the presence or absence +of any Perl modules or other tools. Additional requirements for B<toast +build> vary according to the package being built. + +=head2 Setup + +To have the latest version of B<toast> download and install itself, +run one of the following commands. The first requires GNU wget; the +second relies on the C<GET> utility that comes with the LWP Perl module. + + sh -c 'u=http://toastball.net/toast;wget -O- $u/toast|perl - arm $u/' + sh -c 'u=http://toastball.net/toast;GET $u/toast|perl - arm $u/' + +If you ran either of the above commands as root, B<toast> should now be +installed in C</toast> with appropriate symlinks under C</usr/local>, +and you should be all set. If you ran either command as a non-root +user, B<toast> will have installed itself and everything it needs under +C<$HOME/.toast>, and you'll probably need to add C<$HOME/.toast/armed/bin> +to your PATH environment variable in order to be able to use B<toast> +and any other packages it installs. For example, in a Bourne-like shell: + + PATH=$HOME/.toast/armed/bin:$PATH + +If you would like to use any man pages, info pages, libraries or header +files installed by B<toast>, you may also want to adjust MANPATH, +INFOPATH, LD_LIBRARY_PATH, or CFLAGS as appropriate. Note that setting +LD_LIBRARY_PATH may have unintended consequences; for more information, +search the Web for <LD_LIBRARY_PATH considered harmful>. If your C +compiler is gcc, you may be able to use the CPATH environment variable +instead of messing with CFLAGS; see the gcc documentation for details. + +The above procedure is by no means required in order to install or +use B<toast>. The unmodified script can be copied to and run from any +location, and you can use B<toast man> to view the man page without +having to install it first. The default option settings should be +sensible, and any necessary directories will be created on demand. + +A GNU-like C<configure> wrapper script is also provided with the official +B<toast> distribution for your convenience. You can supply an alternate +installation directory prefix with C<./configure --prefix=foo>, or keep +the default prefix of C</usr> by running C<./configure> without arguments. +Then run C<make>, become root if necessary, and run C<make install>, which +will install both the B<toast> script and a man page. Sadly, B<toast>'s +C<configure> script does not support the other command-line options and +features of B<configure> scripts produced by the real GNU autoconf. + =head2 Commands =over 4 @@ -5017,10 +5104,7 @@ =head1 AVAILABILITY B<toast> may be downloaded from C<http://toastball.net/toast/> under -the terms of the GNU GPL. B<toast> itself is known to work with Perl -5.005_03 through 5.8.x under Linux, FreeBSD and Cygwin, without relying -on the presence or absence of any Perl modules or other tools. Additional -requirements for B<toast build> vary according to the package being built. +the terms of the GNU GPL. =head1 BUGS @@ -5063,8 +5147,6 @@ Questions left unanswered by this documentation: - - For what purposes might one actually use toast? - - What environment variables should I set? - What are some realistic examples of toast commands? - What kinds of packages can be expected to build? - What protocols and archive formats are supported?