toast - simple source-and-symlinks package manager for root and non-root users
toast [ OPTION ... ] [ COMMAND ] [ ARGUMENT ... ]
toast is a simple, self-contained tool for downloading, building, installing, uninstalling and managing software packages. Unlike traditional package-management systems, toast is primarily intended to work directly with software distributed as source code, rather than in some precompiled or specialized binary format, such as RPM. Binary packages are also supported.
toast is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
toast is designed to be used in any of three ways:
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.
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 /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.
Installing and managing all software for an entire Unix system; that is, using toast as the one true package manager for the system. This is what I do on my (single-user) Linux box at home.
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 toast to replace it or go behind its back.
toast itself has been known to work with Perl 5.005_03 through 5.8.x under Linux, FreeBSD, Solaris, MacOS X, and Cygwin, without relying on the presence or absence of any Perl modules or other tools. Perl is available for download at http://www.cpan.org/src/stable.tar.gz. Although it isn't required, toast get works better if you have GNU wget; you can use toast arm wget to download and install it if necessary. Additional requirements for toast build vary according to the package being built.
To have the latest version of toast download and install itself in your home directory, run one of the following commands as a non-root user. (See below for instructions to install as root.) The first command requires GNU wget. The second relies on the GET utility that comes with the LWP Perl module. The third command is broken over three lines, though your shell should let you paste it exactly as written; it relies only on Perl with no modules at all.
wget -O- http://toastball.net/toast/toast|perl -x - arm toast
GET http://toastball.net/toast/toast|perl -x - arm toast
perl -e 'socket(S,2,1,0)&&connect(S,pack("Sna4x8",2,80,gethostbyname(
"toastball.net")||die("dns")))&&syswrite(S,"GET /toast/toast\n")&&
open(STDIN,"<&S")&&exec($^X,qw(-x - arm toast))||die($!)'Of course, if you already have a previous version of toast up and running, just type toast upgrade toast. If toast is installed system-wide, but you want to install the latest version in your home directory, try toast arm toast.
toast should now have installed itself and everything it needs under $HOME/.toast. You'll probably need to add $HOME/.toast/armed/bin to your PATH environment variable in order to be able to use toast and any other packages it installs. You can adjust PATH (and a few other useful variables) with this command:
eval `$HOME/.toast/armed/bin/toast env`(Note that those are backticks, not single quotes.) It probably makes sense to add the above command to your .zshenv or .profile or whatnot, so that your environment variables will be set up automatically whenever you log in. For more information, run toast help env, or just toast env to see what variables would be set.
To have toast install itself as root under /toast with symlinks in /usr/local, you should first either create a user called toast whose UID and GID will be used when building packages, or create a configuration file specifying an alternate username (fred in this example):
echo 'username=fred' >> /etc/toast.confIf you want to use directories other than /toast and /usr/local, now would be a good time to specify those as well, since relocating armed packages can be tricky and time-consuming:
echo 'storedir=/path/to/use/to/store/files' >> /etc/toast.conf
echo 'armdir=/place/to/put/symlinks/to/armed/packages' >> /etc/toast.confOnce the toast user and/or /etc/toast.conf configuration file has been created, just execute as root one of the same three download/install commands given above for non-root users. When using the default armdir location of /usr/local, you probably won't need to bother with the toast env stuff described above, but when using another location, you may wish to put some variation on the toast env command given above in /etc/profile or something.
The above procedure is by no means required in order to install or use toast. Both the uncompressed toast script and an official compressed tarball distribution containing toast are available for download at http://www.toastball.net/toast/. The unmodified toast script can be copied to and run from any location, and you can use 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 configure program (OK, symbolic link) is also provided with the official toast distribution for your convenience. You can supply an alternate installation directory prefix with ./configure --prefix=foo, or keep the default prefix of /usr by running ./configure without arguments. Then run make, become root if necessary, and run make install, which will install both the toast program and a man page. Sadly, toast's configure script does not support most of the other command-line options and features of configure scripts produced by the real GNU autoconf.
Locates URLs from which a package could be downloaded. This command does not write to the disk at all. The output format is similar to that of toast status, but all information comes from the network rather than the on-disk package database. If a given package has not been added and no URLs were specified on the command line, toast find looks for an exact name match on the web sites specified by the findsites option; otherwise it attempts to list the directory or directories to which the package's URL(s) belong. If an explicit version number is given, only that version is listed; otherwise all versions are listed from oldest to newest.
Adds new packages to the repository by storing URLs. Use this command to store package file locations without actually downloading anything. Each PACKAGE must specify at least one URL or file unless the autofind option is enabled. Absolute and relative pathnames are automatically translated into file URLs. If the given package has already been added, the command merely compares the given URLs against those already stored and gives an error if they don't match; use toast remove or toast change to specify new URLs for an existing package.
Ensures that the given packages have been downloaded. Implies toast add. If no arguments are given, acts on the latest version of every existing package. After this command completes successfully, other commands will be able to operate on the package without downloading any additional files from the network. If a given package is already stored, the existing downloaded files are silently preserved; use toast purge to force them to be downloaded afresh. If GNU wget is installed, toast get will use it to fetch http, https, and ftp URLs; otherwise, if LWP is installed, toast get will use the GET utility to fetch those types of URLs; otherwise toast get will try to fetch http and ftp URLs itself using rudimentary built-in routines. toast get always handles file URLs itself. If ssh is available, toast get can use it to fetch (non-standard) URLs of the form ssh://[username@]hostname/absolute/path/to/file. If cvs is available, toast get can also handle (even less standard) URLs of the form cvsroot[+ssh]:$CVSROOT/module[#unixtime]; note that $CVSROOT often starts with a colon, resulting in two colons in a row.
Ensures that the given packages are compiled and ready. If no arguments are given, acts on the latest version of every existing package. Packages that already have at least one built or armed build (as reported by toast status) are skipped by this command without causing an error; use toast rebuild to force such packages to be rebuilt. Building may involve implicitly invoking toast get, decompressing and extracting archives, applying patch files, compiling a new build of the package and installing it in a build-specific directory tree. Supported archive formats include compress, gzip, bzip2, zip, rpm, deb, cpio, tar, shar, patch, and most combinations of the above. You don't need to have RPM installed to extract .rpm files; cpio should usually suffice. Similarly, only tar should be required to extract .deb files. Note that toast completely ignores dependencies and other meta-information in .rpm and .deb files; only the raw binaries are extracted and used. Archives should contain either precompiled binaries or source code, which will be identified and/or built according to heuristics too mind-numbing to describe completely; in the case of source files, a configure script, Makefile or similar is often required. Many options can influence this command's behavior; see the options reference for full details.
Installs symbolic links to allow builds to be used. This is perhaps the most frequently used toast command. It is normally required before programs compiled by toast build or toast rebuild can be run. If no arguments are given, acts on the latest version of every existing package. If no explicit build number is supplied for a given package, toast build is implied, and the latest built or armed build is armed. If a build to be armed is already in the armed state, this command has no effect. The armdir option controls where the symbolic links to the files in each armed build will be installed; the default location is /usr/local (for root) or $HOME/.toast/armed (for everyone else). Non-root users might want to add $HOME/.toast/armed/bin to the $PATH environment variable to make it easier to run armed packages. Existing links to other builds are moved out of the way if necessary, and the corresponding builds are still considered to be armed.
Forces packages to be built or rebuilt. If no arguments are given, acts on the latest version of every existing package. A new build will be created as if by toast build for every package given, even if the package has already been successfully built. Each package can have any number of independent builds. Builds for a given package are automatically assigned sequential numbers starting from 1. Many options can influence this command's behavior; see the options reference for complete details.
Checks for a later version of an existing package. If no arguments are given, this command acts on the latest version of every existing package. The existing package's URLs are used as a starting point to locate the new version. If the filename component of a given URL doesn't appear to contain the package's version number, that URL will be left unmodified for the new version; otherwise, the directory portion of the URL will be immediately downloaded and searched for a similar URL containing a higher version number. The command fails if no URLs would change or if no single consistent newer version for all version-containing URLs can be found; otherwise, the highest eligible version is used for all modified URLs and the package itself. The command performs an implicit add, get, build or arm on the extrapolated URLs so as to match the state of the given existing version, except that an implicit arm will become an implicit build if the autoarm option is disabled.
Deletes symlinks created by toast arm. This works by removing symbolic links to the given build and replacing any links that had been moved out of the way. No error occurs if no such links exist. If no build number is given, all armed builds, including mismatched builds reported to be armed, are disarmed. If the package version number is also omitted, all armed builds belonging to packages with the given name are disarmed. Disarming a build always removes links from the ARMDIR specified by the armdir option at the time the package was built, the ARMDIR currently specified by the armdir option, and any ALTARMDIRS currently specified by the altarmdirs option. Disarming a build only removes hard or symbolic links to the actual build files stored in STOREDIR.
Removes intermediate files and broken builds. If no arguments are given, all builds are cleaned. If no explicit version and/or build number is given, all matching versions and/or builds are cleaned. Cleaning a broken build removes the build entirely; otherwise only files that are not required by toast arm are removed from the build. These typically consist of files created directly by toast as part of the build environment, extracted source files, and intermediate files created by the package itself during compilation. Some kinds of binary packages that do not involve intermediate files never require cleaning, and toast build and toast build may automatically perform this step if the autoclean option is enabled. Builds that are still in the building state (as reported by toast status) are silently ignored by this command.
Deletes one or more builds. If no version and/or build number is given, all matching builds are disarmed. If one of the builds to be demolished is currently armed and the autodisarm option is disabled, toast demolish reports an error and no builds are deleted; otherwise, toast disarm is implied. Demolishing a package reverses the effects of toast build or toast rebuild (and, optionally, toast arm), but never those of toast get or toast add.
Deletes files downloaded by toast get. Deletes toast's local copy of the original archive used to build the given package or set of packages. Existing builds are not affected by this command, but creating a new build will implicitly reinvoke toast get. If the autopurge option is enabled, toast build or toast rebuild may implicitly invoke this command.
Deletes a build, a package, or a set of packages. Removing a build has the same effect as toast demolish. Removing a package deletes all of its builds and additionally reverses the effects of toast get and toast add. If any of the builds to be deleted is currently armed, and the autodisarm option is disabled, toast remove reports an error and nothing is removed; otherwise toast disarm is implied.
Renames an existing package or set of packages. The package or packages must already exist. NEWNAME uses the same syntax used to refer to an existing package or build, except that the destination package must not already exist and must contain the same number of slash characters as PACKAGE. This command can also be used to renumber builds. Currently, armed packages or builds must be disarmed before they can be renamed.
Changes the stored URLs for an existing package or packages. Use with caution! Each package must already exist, and at least one URL must be given explicitly for each. The URL or URLs previously stored for each package by toast add will be discarded and replaced by the given URL or URLs. No further action is taken; in particular, neither toast get nor toast purge is implied. Note that it is often simpler and safer to remove and then re-create a package than it would be to use this command.
Displays information about packages and builds. If invoked without arguments, displays information about all packages and builds. A package is marked as stored only if the original files have been downloaded by toast get and haven't been deleted by toast purge. The package URLs may also be listed; see the showurls option. Every package has zero or more builds, each of which is either building (if toast build or toast rebuild is still running), broken (if it failed), built (if it succeeded), or armed (by toast arm). In the last two cases, the build will be marked (not clean) if intermediate files created by toast build have not yet been removed by toast clean.
Prints shell commands to make armed packages usable. This command is normally invoked with eval `toast env` (note the backticks) from a shell initialization file such as .zshenv or .profile. This will add ALTARMDIR/bin to the front of PATH for each ALTARMDIR, in order. (By default, ALTARMDIR is the same as ARMDIR, which usually defaults to ~/.toast/armed; this is the directory that contains a merged view of all armed packages.) If a particular ALTARMDIR/bin already appears anywhere in PATH, it will remain in its current position instead of being added or moved to the front of PATH. Other environment variables are similarly affected: MANPATH (used to find man pages), INFOPATH (used by GNU info), CPATH (used by gcc to find include files), XML_CATALOG_FILES (used by DocBook and other tools to locate XML catalogs), and LIBRARY_PATH (used by GNU ld to find libraries; not to be confused with LD_LIBRARY_PATH, which also affects shared library loading at run time). Note that if MANPATH in particular is unset, toast env will run man -w to try to get the default value; if this causes problems, it may help to ensure that MANPATH is set before invoking toast env. This command assumes a Bourne-like shell -- zsh and bash will work, tcsh won't. None of this is likely to be necessary if ARMDIR is /usr or /usr/local (the default when running as root).
Summarizes usage information from the toast man page. If invoked without arguments, displays a one-line summary of every command. If invoked with an argument, displays a longer summary of the given topic, which may be a command name, an option name, commands or options. If toast itself is invoked without any arguments, toast help is assumed. Note that most information displayed by this command is taken directly from a subset of the toast man page.
Displays the complete toast man page. You're either reading the man page now, or reading something that was derived from it (such as the output of toast help). This command is supposed to behave about the same way man toast would, but it doesn't require the man program or the toast man page to be installed. If standard output is a tty, the man page is formatted using Pod::Text::Overstrike, Pod::Termcap, Pod::Text or the rudimentary internal formatting routine used by toast help, and the formatted page is piped to $MANPAGER, $PAGER, less -ir, or more, or dumped directly to the terminal as a last resort. If output is redirected to a file or pipe, the man page is rendered as plain text using Pod::Text if available or the internal routine otherwise. If you want more control over the output, try feeding the toast script itself to pod2text, pod2html, pod2man, or pod2latex, all of which are command-line utilities that accepts lots of exciting switches and things and that come bundled with recent versions of Perl.
Most commands take one or more arguments denoting packages or builds. Such arguments usually follow one or more of the forms below. Note that not all commands accept all of these forms; in fact, some commands (like toast help) accept none of them.
This syntax can be used to refer to an existing package. If the package does not exist and the autofind option is set, it will be located automatically; if VERSION is omitted, the latest available version will be used. If NAME matches a previously-added package and VERSION is omitted, the latest existing version is used, except when the documentation for the command specifically says that it affects all versions or operates on sets of packages, in which case all versions are affected. Examples: wget, gcc/3.2.2, openssl/0.9.7b
This syntax is used to refer to an existing build of an existing package. Builds are numbered consecutively starting from 1. Many commands don't accept individual builds as arguments; the usage information for those commands that do accept builds always uses the term BUILD explicitlly. Examples: xdaliclock/2.19/1, glibc/2.3.2/4.
This syntax is most often used to implicitly add a new package by URL, though many commands also allow it to be used to refer to an existing package. If the package name and version are omitted, they will be guessed based on the filename portion of the URL; if the package already exists, it will be found only if the guessed name and version match those used to add it. An error will occur if the given package exists but has different URLs. Examples: ftp://alpha.gnu.org/gnu/tar/tar-1.13.25.tar.gz, ps/3.1.8: http://procps.sf.net/procps-3.1.8.tar.gz.
This syntax can be used to add a new package from a local file. The given path is automatically translated into an absolute file URL. Unlike a file URL, the path will be checked as soon as it is parsed to ensure that it refers to a readable file; if it does not, a fatal parse error will occur and the entire command will not be invoked, even if previous arguments were parsed without error, the package already exists, or the stoponerror option is disabled. Examples: myprog/0.1test: myprog.zip, /home/anandam/gdb-5.3.tar.gz, ../../mnt/ain/ain/opt/stow/xplanet/xplanet-1.0.1.tar.gz.
This syntax can be used to add a package that requires multiple URLs and/or local files by grouping them between literal square brackets. As with the previous two forms, the name and version number may be omitted, in which case they will be guessed from the given filenames. If the filenames are very dissimilar, only the first will be used to guess the package name and version number. Otherwise, the order of URLs and/or paths is not significant. Examples: [ http://www.kernel.org/pub/linux/kernel/v2.4/linux-2.4.20.tar.bz2 linux-2.4.20-config.tgz ssh://vulture/home/matt/linux-2.4.20.patch ], [ http://ftp.gnu.org/gnu/glibc/glibc-{,linuxthreads-}2.3.2.tar.bz2 ], XFree86/4.3.0: [ X430src-[1-7].tgz ]. (The last two examples respectively involve brace and glob expansion performed by your shell).
Every command that accepts a PACKAGE argument will accept several PACKAGE arguments in sequence, so multiple files or URLs will always be treated as distinct packages unless they are explicitly grouped into a single package using square brackets as shown above. For instance, toast add * puts each file in the current directory in its own package, while toast add [ * ] tries to combine them all into a single package.
Defines the root of the directory tree toast uses to store and build all packages. STOREDIR must be given as an absolute path or a fatal error will result. toast add and commands that explicitly invoke it will create STOREDIR if it doesn't already exist. Default: /toast if invoked by root, $HOME/.toast otherwise.
Defines the directory under which toast arm creates symlinks to compiled package files in STOREDIR. toast build also tries to use this value as a prefix when compiling most packages. With few exceptions, ARMDIR should point to the same directory when arming a given package that was used when building that package. If ARMDIR is not given as an absolute path, it is taken to be relative to STOREDIR. ARMDIR and should probably not contain STOREDIR, and should probably not be contained by STOREDIR either unless ARMDIR is armed, though these restrictions are not enforced. It's usually a good idea for ARMDIR to be /usr or /usr/local if feasible, since some broken packages may not work if installed in a different location. Default: /usr/local if invoked by root, armed otherwise.
Optionally specifies one or more colon-separated directories to use instead of or in addition to the ARMDIR given by the armdir option. An empty list or an empty list item stands for the current value of ARMDIR. Commands that check to see if a package is already armed look for links back into STOREDIR in the current ARMDIR and all current ALTARMDIRS, as well as the ARMDIR stored by toast build when the package was built. toast disarm additionally removes any such links it finds. toast env is the only command that uses ALTARMDIRs but ignores ARMDIR. The reverse is true of toast build, which uses and stores ARMDIR only, ignoring ALTARMDIRS. Note that toast will never write to any ALTARMDIR except for ARMDIR unless the ALTARMDIR actually contains hard or symbolic links to files in STOREDIR. Default: empty list (equivalent to listing ARMDIR alone).
When invoked as root, toast build will unpack, compile, and install packages under USER's UID and GID as returned by getpwnam(3). Note that any additional groups (such as those in /etc/groups) will be ignored, as will USER's password, home directory, shell, and so on. Default: toast.
If toast is invoked as root and needs to do something as a non-root user, it normally runs as the user given by the username option. However, if no such user exists, toast will search for an unused UID to use instead, starting at UID. Use 0 to disable this feature. Default: 23.
If N is a nonzero integer, the build subprocess spawned by toast build will silently attempt to adjust its sheduling priority ("niceness") by the given delta. In keeping with wacky Unix tradition, positive N causes the build process to run at a lower priority, while negative N denotes a higher priority. Negative N works only when toast is invoked as root. Usually N ought to be between 20 and -20, but other values might be useful if toast is invoked on a strange platform or at an unusual initial priority. Note that toast will not fail or even warn if N is non-numeric, or too small, or if the priority cannot be adjusted for any other reason, except that if N is too large, it will be silently demoted to the largest useful value. Default: 10.
If PROG is non-empty, toast arm and toast disarm will execute it immediately after arming or disarming one or more packages. PROG can contain multiple words and/or shell metacharacters and will be parsed and executed according to Perl's usual conventions, so it can actually refer to more than one program. If PROG returns non-zero (failure), the command will also fail. Default: /sbin/ldconfig if invoked by root, empty string otherwise.
Sets an implicit command to be assumed if toast is invoked with at least one command-line option or argument but no explicit command. COMMAND may be the name of any valid toast command. As a special case, the value help causes toast to print an error message and a list of valid commands if no explicit command is given. Note that invoking toast without command-line options or arguments is always equivalent to running toast help, regardless of this option's setting. Default: help.
Sets the list of per-package command-line options implicitly stored in storedir for automatic re-use by later invocations of toast. OPTNAMES is either a whitespace- and/or punctuation-separated list of option names. The word all may also appear on the list; it stands for the names of all options except for the stickyopts option itself. The empty list is allowed. Case is not significant. Note that stickyopts only determines which options are stored (or removed from storage); it can not be used to prevent previously stored options from being implicitly loaded and re-used. toast will implicitly store an option listed in OPTNAMES only if it is specifically mentioned on the command line; options read from the environment or from files on disk are never implicitly stored. If the value explicitly given on the command line is the same value that would otherwise have been used if no command-line options had been given and no per-package options were stored, and that option is already stored, the option is removed from storage instead of being stored. If crossversion is enabled, this option writes to a file that applies equally to all same-name packages, regardless of version number; otherwise, this option writes to a different file that applies only to a single package name and version number taken together. Values stored in the more specific file (name and version) always override values stored in the less-specific file (name only). Default: reconfigure confappend makeappend.
Set the list of web sites or other locations searched by toast find for packages that have not already been added. SITELIST is a space-separated list of URLs and/or special words taken from the following list: freshmeat, sourceforge, gnu, cpan, or all (which stands for all of the preceding words in the order given). The * character will be replaced by the name of the package to find wherever it occurs. If you want a literal * character, too bad. Default: all.
If URL is non-empty, toast get will use the given URL as the proxy server for http and https URLs. When using wget or GET, the given URL will be exported in the http_proxy environment variable without further checking if non-empty. When using built-in HTTP, the proxy URL should be of the form hostname:port or http://hostname:port/; other forms may also work. Note that using an empty URL will not cause http_proxy to be removed from the environment of wget or GET. The proxy string is not exported during toast build. Default: the current value of the http_proxy environment variable, or the empty string if that variable is not set.
The ftpproxy option is just like the httpproxy option, but applies to ftp URLs. Note that this really refers to an FTP-to-HTTP gateway, rather than a true FTP proxy server. Default: the current value of the ftp_proxy environment variable, or the empty string if that variable is not set.
Specifies additional arguments for toast build to pass to a package's configure script or equivalent, if any. This should never be necessary in order to build a package correctly (if it is, send me a bug report!), but it can be awfully handy at times. The ARGS string is treated as a list of space-separated words, each of which may be optionally quoted with single or double quotes with backslash acting as an escape character; the resulting words are added to the end of the command line. Note that by default, this option's value may be saved with the package and reused by future invocations of toast; see the stickyopts option for details. Default: empty string.
The makeappend option is just like the confappend option except that it applies to the make command or commands (if any) invoked by toast build. As with confappend, use of this option should never be necessary; if you find a package that won't build without it, please send me a bug report! Default: empty string.
When quiet is enabled, most commands will produce output only on failure. Some commands, such as toast status, are not affected by this flag. Default: disabled.
When expand is enabled, any URL ending in a slash encountered while parsing the command line that will be treated as a pointer to a directory listing whose contents are to be fetched, parsed, filtered, and interpolated into the command line. The filtering heuristic scans for links that seem likely to be package URLs, without actually retrieving anything other than the single directory URL given. If a package name and/or version number are given on the command line, those are taken into account by the filter. Use square brackets on the command line or specify an explicit name or version number to force all of the resulting URLs to be grouped into a single package, or omit brackets and name to let toast decide for itself whether and how to group the new URLs into packages. If expand is disabled, URLs ending in slashes will not receive any special treatment, and toast will never attempt to fetch anything from the network while it is still parsing the command line. Default: enabled.
When autofind is enabled, toast add and other commands will automatically look up package URLs as if by toast find when none have been added previously or given explicitly. If no version number is given either, the latest version found will be used. Default: enabled.
When autochange is enabled, toast get may replace the URLs stored by toast add with the actual URLs of the files it downloaded. When it is disabled, URLs stored by toast add will never change without warning. This only matters in cases where the URL stored by toast add actually points to an HTML page or FTP directory, which used to happen all the time back when the toast find heuristic was more naive and the expand option didn't exist. Enabling this option now seems more likely to cause problems than to solve them. Default: disabled.
When autorename is enabled, toast get may try to use information gained after downloading files to attempt to guess a new name for any implicitly added package for which no name and/or version number was specified on the command line or could be guessed from the URLs given. If autochange is also enabled, new URLs are first used to try to guess a new name; if this fails, the contents of the downloaded files are examined. If either method results in a new name being guessed, the package is renamed automatically as if by toast rename, and any further processing continues under the new name. If autorename is disabled, packages with unguessed or partially guessed names always keep the unique names automatically assigned by toast add based on URLs alone (version number will be unknown optionally followed by a serial number for uniqueness; name may have been guessed or may also be unknown). Default: enabled.
When autoenv is enabled, toast will automatically export the environment variable settings printed by toast env to any programs invoked while building a package. This may help the package being built to locate other armed packages on which it depends. Default: enabled.
When autoclean is enabled, commands that create a new build for a package (such as toast rebuild) implicitly remove any pre-existing broken builds from that package before creating the new build; also, whenever a new build succeeds, it is implicitly cleaned as if by toast clean. Note that newly created broken builds will not be immediately cleaned or removed, even if this option is enabled, so as to make it easier to diagnose build problems. Default: enabled.
When autopurge is enabled, an implicit toast purge will be performed on a package as soon as it is successfully built. Default: disabled.
When autoarm is enabled, toast upgrade and toast rebuild perform an implicit toast arm on every newly created non-broken build whose package already contains another armed build. Default: enabled.
When autodisarm is enabled, toast arm, toast demolish and toast remove each perform an implicit toast disarm on their armed arguments or, in the case of toast arm, on all builds belonging to the same package as its arguments, or to any package with the same name as its arguments if crossversion is enabled. Default: enabled.
When autodemolish is enabled, toast rebuild performs an implicit toast demolish on every other build belonging to the same package as a newly-created, non-broken build. If crossversion is also enabled, other packages with the same name will also be demolished. Default: enabled.
When both autoremove and crossversion are enabled, every time a command creates a new non-broken build, it will also perform an implicit toast remove on every other package with the same name as the package containing a newly-created, non-broken build. If crossversion is disabled, this option has no effect. Default: disabled.
When crossversion is enabled, the autodisarm, autodemolish and autoremove options will extend their effects to other packages with the same name when appropriate. See the descriptions of those options for details. Default: disabled.
When skipmismatched is enabled, some operations will ignore any pre-existing build that was built with a value of armdir different than the current one and is therefore reported as mismatched by toast status. Specifically, toast build will ignore mismatched builds when deciding whether or not to create a new build; toast upgrade will ignore mismatched builds when deciding whether to build or arm the new version; and the autodemolish option will not demolish mismatched builds. All other checks are unaffected by this option. For example, toast remove will never remove an armed build without completely disarming it first, even if thie build is mismatched and this option is enabled. When skipmismatched is disabled, mismatched builds are never treated specially. Default: enabled.
When ccache is enabled and a program called ccache is present, toast build and toast rebuild will try to use it to speed up compilation of C/C++ programs. Read about ccache at ccache.samba.org; install it with toast arm ccache. If invoked as root, the cache directory defaults to the ccache subdirectory of storedir; for non-root users, the default is $HOME/ccache. The location can always be overridden by setting the CCACHE_DIR environment variable. If ccache is not installed, this option has no effect. Disabling this option prevents toast from taking any special steps to take advantage of ccache, but it does not guarantee that ccache will not be used, though it may prevent it from finding a user's home directory. Default: enabled.
When preload is enabled, toast build will attempt to compile a shared library for use with LD_PRELOAD during the make install phase. This library may help some packages install themselves into the correct location. If preload is disabled, toast build will skip this step. Note that this may cause some packages to build incorrectly in some situations. To build the shared library only if a suitable C compiler is present, leave this option enabled, but disable the strictpreload option. Default: enabled.
When strictpreload is enabled, failure to build the shared library described under the preload option is treated as a fatal error. When strictpreload is disabled, a compile error while attempting to build the shared library causes toast build to behave as if the preload option were disabled. This may allow toast build to succeed in the absence of a suitable C compiler, but it may allow some packages to build incorrectly in some situations. Default: enabled under Linux, disabled elsewhere.
When useflock is enabled, some commands (such as toast arm) may try to use Perl's built-in flock() to prevent multiple concurrent invocations of toast from modifying the repository in ways that might corrupt it. Disabling this option is probably not a good idea, but may be necessary in some environments. Note that Perl's flock() will not necessarily use C's flock() routine; see the Perl manual for details. Note also that toast's locking strategy probably isn't foolproof, especially under NFS. Default: disabled under Cygwin, enabled elsewhere.
When reconfigure is enabled, toast build may attempt to pass extra arguments to a package's configure script (such as --enable-shared) and/or Makefile (such as install.man) in order to build or install extra files that the package itself might not build or install by default. This produces improved results for many specific packages (such as QT and XFree86), and may make subsequent packages more likely to build, but it can sometimes break things (usually in a straightforward way), or it may be undesirable for other reasons. If reconfigure is disabled, toast build does not try to do anything beyond the minimum steps required to correctly build and install whatever files the package builds and installs by default. Note that by default, this option's value may be saved with the package and reused by future invocations of toast; see the stickyopts option for details. Default: enabled.
When fixliblinks is enabled, toast build may create symbolic links to shared libraries whose names contain version numbers and follow a certain naming convention. For example, when built under Linux with the reconfigure option enabled, zlib version 1.2.1 creates a shared library called libz.so.1.2.1 along with two symbolic links that point back to that file: libz.so (required to link new packages with the shared library) and libz.so.1 (required to run programs linked with the shared library). When this option is enabled, toast build will create a third link called libz.so.1.2, which happens to be completely useless, but if the other two links had been missing for whatever reason, it would have created them as well. Binary packages that contain shared libraries are especially likely to benefit from this behavior. Default: enabled.
When interactive is enabled, toast upgrade will display a list of candidates (the same information as toast find, but presented in a different form) and prompt the user to choose one of them. If autofind is enabled, toast add and other commands do the same thing. Note that if only one candidate is found, that candidate will be used automatically, without prompting. Default: disabled.
When stoponerror is enabled, toast aborts and returns failure as soon as any error occurs. If stoponerror is disabled, only the processing of the current command argument is aborted; any subsequent arguments will still be processed, but toast still issues an error message and returns failure after processing the last argument, even if the last argument was processed successfully. Note that certain types of errors, such as errors parsing the command line, will always cause toast to abort completely, before processing the first argument, regardless of this setting. Default: enabled.
If ignorecase is enabled, package names and version numbers given on the command line are always case-sensitive. If ignorecase is disabled, package names and version numbers that refer to existing packages are treated as if they were case-insensitive only when failing to do so would cause an error. Note that case is always preserved in URLs and when explicitly naming new packages. Note also that it is always legal for two distinct packages to have names and/or version numbers that differ only in case, and that such packages are never treated as if they were related, even if crossversion is enabled. Default: enabled.
When showurls is enabled, toast status always displays the stored URLs associated with each displayed package. If showurls is disabled, toast status only displays a package's URLs if a different list of URLs for that package was given explicitly on the command line. Default: enabled.
When showopts is enabled, toast status always displays any stored options associated with each displayed package. If showopts is disabled, toast status never displays this information. Default: enabled.
When infodir is enabled, toast arm and toast disarm will create a file in armdir called info/dir; if the file already exists, it will be replaced with an updated version. When this option is set, toast env sets INFODIR to point to this file, so that the "info" command can display a list of installed info pages. If infodir is disabled, toast arm and toast disarm will delete the info/dir file, if present, instead of rebuilding it. Default: enabled.
When xmlcatalog is enabled, toast arm and toast disarm will maintain a catalog file in armdir called etc/xml/toast-xml-catalog, whose presence and contents depend on the contents of armdir's share/xml and etc/xml subdirectories. If the catalog already exists, it may be overwritten or deleted. The toast env command will set XML_CATALOG_FILES to point to this file when this option is set, which helpds things like DocBook operate correctly. If xmlcatalog is disabled, toast arm and toast disarm will delete the toast-xml-catalog file, if present, instead of rebuilding it. Default: enabled.
When hspkg is enabled, toast build will generate various terrible wrapper scripts for ghc and related commands, and toast arm and toast disarm will maintain a Haskell package database armdir called etc/xml/toast-hs-package.conf, whose presence and contents depend on the contents of armdir's hspkg subdirectory, which in turn will be automatically populated by a wrapper script whenever a Haskell library built via toast build tries to register itself in the package database. If the package database already exists, it may be overwritten or deleted. The toast env command will set GHC_PKG_PATH to point to this file when this option is set, which will cause wrapper scripts installed with ghc and/or Haskell libraries to insert a --package-conf argument into the command lines of some of the appropriate programs. This approach has many flaws and is not unlikely to cause more problems than it solves. If hspkg is disabled, toast build will not attempt to generate any Haskell-specific wrapper scripts (which may prevent Haskell libraries from building, at least with GHC 6.4); toast arm and toast disarm will delete the toast-hs-package.conf file, if present, instead of rebuilding it. Poorly tested against GHC 6.4 only. Default: disabled.
If protect is enabled, toast build will make some of the directories it creates in storedir read-only, and toast arm will attempt to ensure that armdir and all of its subdirectories are read-only, changing existing modes if necessary. If protect is disabled, toast build will create read-write directories in storedir (though existing subdirectories will be unaffected), and toast arm will make armdir and its subdirectories read-write, assuming the current umask allows it. This option never affects the permissions of files or symbolic links. Default: disabled.
If relative is enabled, symbolic links created by toast arm will use canonical relative paths computed from the actual layout of the filesystem when the command runs. If relative is disabled, the target of each symbolic link will start with the absolute path to storedir, exactly as given on the command line (or configuration file or whatnot), even if the resulting path is not canonical. A "canonical path" means a path that follows the "real" filesystem layout without going through any links. Both methods should work just fine except in unusual situations, so feel free to use whichever setting you think looks nicer. This option only affects newly-created links, never existing links, even when an existing link is moved to change the stacking order of a package. Default: disabled.
If debugrewrite is enabled, toast build will always generate broken builds. The builds will contain extra debugging information that can be used to help diagnose problems involving packages that build correctly outside of toast, but refuse to build or build incorrect files due to bugs in toast's path-rewriting mechanism. This option currently requires that the strace program be available (or ktrace for *BSD). Default: disabled.
Each option's value is taken from the first of the following sources that assigns it a value:
The command line. All options support standard --NAME=VALUE and --NAME VALUE syntax. For boolean options, VALUE can be true, yes, on, enabled, or 1 to enable the option or false, no, off, disabled, or 0 to disable it. Alternately, --NAME can be used to enable a boolean option or --noNAME to disable it. In all cases, the leading double dash (--) may be replaced by a single dash (-), and NAME is case-insensitive (as is the no prefix used to disable boolean options). VALUE is case-sensitive, except for boolean options.
Package-specific configuration files. If they exist at all, these files are normally created and updated by toast. Package-specific configuration files can live in two different places: the first applies to a specific package with a given name and version number, the second applies to all packages with the given name. If both files exist, both are checked in that order, and the first one to supply a value for the option in question wins. See the stickyopts option for details.
The environment. If option NAME is not given a value on the command line, will be read from the environment variable TOAST_NAME (all uppercase) if it exists. Note that environment variables whose names contain lowercase letters will be silently ignored! In the case of a boolean option, one of the explicit values listed in item 1 must be given.
The main configuration file. If option NAME has not been assigned a value through any of the above methods, its value will be taken from a line of the form NAME=VALUE in the configuration file, if such a line exists. NAME is case-insensitive in this context. Any whitespace before or after NAME or VALUE will be ignored, as will any blank line, any line containing only whitespace, and any line with # as its first non-whitespace character. toast looks for its configuration file in $HOME/.toast/conf, /toast/conf, /etc/toast.conf, and /usr/local/etc/toast.conf; if any of those files exist, only the first is used. (Here, $HOME specifically represents the value of the HOME environment variable.) If a configuration file exists but cannot be read or has invalid syntax, an invalid NAME, or an illegal VALUE for a boolean option (an explicit value must be given; see item 1 for allowed forms), toast will normally give an error message at startup and refuse to execute any commands.
The built-in default value. See the full list of options elsewhere in this document for the specific default value used for each option.
Any COMMAND can also be written as if it were a command-line option by preceding it with one or two dashes. For example, toast --help and toast help mean the same thing. Commands do not behave like options in the environment or the configuration file, but see the defaultcmd option above for an alternative.
Environment variables whose names start with TOAST_ may be interpreted as option settings as described above. In addition, various standard environment variables such as PATH, LD_LIBRARY_PATH, CFLAGS and others may directly or indirectly influence toast's behavior, especially when building new packages.
By default, when invoked by a non-root user, toast writes only to the $HOME/.toast directory, which will be created automatically if needed.
toast may be downloaded from http://toastball.net/toast/ under the terms of the GNU GPL.
Please report any bugs, unexpected behavior, unsurprising but inconvenient failures, feature requests, comments, and so on to toast-bugs at the hostname of the toast distribution site, toastball.net.
Known bugs:
- autofind hangs in httphead() when going through tinyproxy?
- gtk+ doesn't seem to build properly when it is already armed
- opera and sleepycat db refuse to build when already armed
- gimp will load plugins from other armed versions despite .off suffix
- antiword 0.35 and unison 0.9.20 end up in armdir/helpers/home/bin/
- "toast upgrade gcc" doesn't work (ftp site has a subdir per version)
- find fails for: sleepycat db, gcc, latex, GNU arch (?), ogle
- autofind chooses "libraries only" version of xfig
- build fails for: jikes, sirc, netcat, lcab, gv, bittorrent, xmlcatmgr
- "toast edit" leaves things in an odd state if you hang up on it
- "toast rename" is more case-sensitive than it ought to be
- "toast get" prevents wget from truncating output if transfer restarts
- "toast get" should support resuming, but doesn't
- "toast get" no longer displays progress under many circumstances
- "toast env" doesn't set PYTHONPATH
- "toast build linux" may fail during install phase w/o --nopreload
- "toast remove" leaves cruft behind after removing last package
- "toast status mail::spamassassin" is too case-sensitiveWish list:
- deal better with missing gcc: clearer error msg? (email 7/21/04)
- error messages that explain command usage (gale 2004-05-06 17:08:20)
- convenient way to specify storedir, etc. during first time setup
- work around lack of getenv(), mkdir(), etc. in microperl...?
- "toast upgrade" w/o args should imply --nostoponerror or something
- "toast arm" should move armed packages to top of stacking order
- "toast status" should give information about stacking order
- "toast rename" should rename armed packages by rewriting symlinks
- "toast clean" should optionally remove old versions/builds
- add "toast check": verify storedir and armdir integrity (and fix?)
- 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
- 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)
- let the user give a hash for each explicit URL; verify hashes
- find, download, and verify hashes, PGP signatures, etc.
- store checksums after build for later tripwire-like verification
- find a way to rebuild indices for apropos by default
- allow package name/version as URL; expand w/ autofind iff missing
- optionally have toast add imply change, then make get+build smarter
- toast status should allow multiple storedirs
- toast get should support cvs, svn (e.g. GNU Emacs, Xapian, Ruby)
- add "toast confhelp" or something to run ./configure --help?
- have toast status show/sort by size/timestamp
- add support for Ruby's install.rb
- fold archives by URL and/or hash?
- zsh completions!Questions left unanswered by this documentation:
- What are some realistic examples of toast commands?
- 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?
- How might I set up toast in a multi-architecture environment? /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.htmlJacques Frechet
This manual is part of toast. Copyright (C) 2003-2006 Jacques Frechet.
toast is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
toast is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with toast; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA