--- toast 2003/10/25 22:43:34 1.227 +++ toast 2003/10/26 02:04:12 1.228 @@ -4555,8 +4555,8 @@ The configuration file. If option I<NAME> has not been assigned a value through any of the above methods, its value will be taken -from a line of the form I<NAME>B<=>I<VALUE>, if such a line exists, -in C<$HOME/.toast/conf>, if that file exists. (C<$HOME> specifically +from a line of the form I<NAME>B<=>I<VALUE>, if such a line exists, in +C<I<$HOME>/.toast/conf>, if that file exists. (C<I<$HOME>> specifically represents the value of the C<HOME> environment variable.) I<NAME> is case-insensitive in this context. Any whitespace before or after I<NAME> or I<VALUE> will be ignored, as will any blank line, any @@ -4580,29 +4580,105 @@ in the environment or the configuration file, but see the B<defaultcmd> option above for an alternative. +=head1 ENVIRONMENT + +Environment variables whose names start with C<TOAST_> may be interpreted +as option settings as described above. In addition, various standard +environment variables such as C<PATH>, C<LD_LIBRARY_PATH>, C<CFLAGS> +and others may directly or indirectly influence B<toast>'s behavior, +especially when building new packages. + +=head1 FILES + +By default, B<toast> writes only to the C<I<$HOME>/.toast> directory, +which will be created automatically if needed. + +=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. + +=head1 BUGS + +Please report any bugs, unexpected behavior, unsurprising but inconvenient +failures, and so on to C<pub.comp.toast> on the ofb.net Gale system +(preferred; see C<http://gale.org>), or via email to "toast-bugs" at +the hostname of the toast distribution site, toastball.net. + +Known bugs: + + - "toast add [ ftp://bar/bar.tar.gz bar.patch ]" guesses "f/unknown" + - autofind mishandles http redirects (e.g. http://toastball.net/toast) + - "toast --noautoarm build foo" disarms and demolishes old foo builds + - __END__ causes trouble when piping toast to perl for bootstrapping + - gtk+ doesn't seem to build properly when it is already armed + - sleepycat db utterly fails to build when already armed + - toast arm/disarm can leave info.dir in the wrong state + - gimp will load plugins from other armed versions despite .off suffix + - "toast rename a/b c/d" doesn't remove a if b was the only version + - "toast upgrade gcc" doesn't work (ftp site has a subdir per version) + - can't extract nss-tools-3.4.1-2.i686.rpm in some environments (?) + - build overrides LD_PRELOAD instead of appending [space-separated] + - autofind fails for: sleepycat db, gcc, latex, gv, arch (?) + - build fails for: jikes, sirc, netcat, lcab, busybox (ow!), gv + +Wish list: + + - add "toast rebuild" command; "toast build" should just ensure built + - "toast build" w/o arguments should build all unbuilt packages + - "toast arm" should move armed packages to top of stacking order + - "toast status" should give information about stacking order + - directories in armdir should be read-only (mode 0555) by default + - add "toast check": verify storedir and armdir integrity (and fix?) + - improve name-guessing: gtk+, mozilla-source, jpegsrc, X/430src (?) + - toast get could be more robust w/r/t failures and concurrency + - configure packages to use alternate /etc, /var, etc. when possible + - share rewriting code between command wrappers and shared library + - wrap toast in #!/bin/sh: "sh configure" will work, find perl, etc. + - come up with a better way to deal with gnome (guess dependencies?) + - figure out where to go with "toast edit" (or document it as-is) + - fold archives by URL and/or hash? + - zsh completions! + +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? + - How are storedir and armdir structured? + - How does this tool differ from similar tools? + - How can I address common problems not directly caused by toast? + =head1 AUTHOR Jacques Frechet -=cut +=head1 SEE ALSO -# questions still unanswered by man page: -# what protocols and archive formats are supported? -# what kinds of packages can be expected to build? -# how are storedir and armdir structured? -# how does this tool differ from similar tools? -# how might people actually use this thing? + /package http://cr.yp.to/slashpackage/management.html + Alien http://kitenet.net/programs/alien/ + autopackage http://autopackage.org/ + CheckInstall http://asic-linux.com.mx/~izto/checkinstall + Debian http://www.debian.org/ + Encap http://www.encap.org/ + fakeroot http://packages.debian.org/stable/utils/fakeroot.html + FreeBSD Ports http://www.freebsd.org/ports/ + GAR http://www.lnx-bbc.org/garchitecture.html + GARStow http://offog.org/code/garstow.html + Gentoo http://www.gentoo.org/ + GNU stow http://www.gnu.org/software/stow + Graft http://www.gormand.com.au/peters/tools/graft/graft.html + LFS http://www.linuxfromscratch.org/ + Linuxports http://linuxports.sourceforge.net/ + RPM http://www.rpm.org/ + Source Mage http://www.sourcemage.org/ + spasm http://www.linux.org/apps/AppId_6909.html -# other ideas (stolen from real man pages observed in the wild): -# RETURN VALUE -# TIPS -# NOTES -# AVAILABILITY -# URL -# ENVIRONMENT -# FILES -# SEE ALSO -# DIAGNOSTICS -# BUGS -# VERSIONS +=cut +# toast: EOF