NAME

toast - packageless package manager for Unix systems and non-root users

SYNOPSIS

toast [ OPTION ... ] [ COMMAND ] [ ARGUMENT ... ]

DESCRIPTION

toast is a simple, self-contained tool for downloading, building, installing, cleanly uninstalling, and managing software packages. Unprivileged users can use it to install software in their home directories. System administrators can use it to temporarily or permanently install software system-wide in a customizable location. Unlike traditional package-management systems, toast works directly with software distributed as source code rather than requiring precompiled binary packages from a central authority (though it can use those too).

Purpose

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:

  1. Installing and managing software in a non-root user's home directory. Need to grab something recent or obscure in a hurry? You don't need to bug your distribution's maintainers or the IT department at work, and you don't need to build it or even find and download it yourself; toast arm FOO does it all.

  2. Installing and managing software packages as root, in parallel to those installed by a conventional package manager. For instance, I can install the latest OpenSSH client system-wide (in /usr/local) with sudo toast arm openssh, then cleanly remove it after my distribution or vendor releases an official package with sudo toast remove openssh.

  3. Installing and managing all software for an entire Unix system; that is, using toast as the one true package manager for the system. Not a common use case, to be sure, but isn't it nice to know that the tool you're using is up to the task?

Requirements

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.

Setup

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(
      $h="toastball.net")||die("dns")))&&syswrite(S,"GET /toast/toast "
      ."HTTP/1.0\nHost: $h\n\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)

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.

Before using toast to install itself as root, it is recommended (but not required) that you create a toast user for building packages, or create a configuration file specifying an alternate username (fred in this example):

  echo 'username=fred' >> /etc/toast.conf

If you skip this step, toast will search for an unused UID and GID, which could conceivably cause security warnings or other problems.

If you want to use directories other than /toast for the package repository and /usr/local for symlinks to armed packages, 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.conf

Once 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 as needed.

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. DESTDIR also works as expected. 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.

Commands

toast find PACKAGE ...

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.

toast add PACKAGE ...

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.

toast get [ 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. If git is available, toast get can handle similar non-standard URLs of the form git:repository[#commit]; this feature is experimental and details of its behavior remain subject to change.

toast build [ PACKAGE ...]

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.

toast arm [ BUILD | PACKAGE ...]

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.

toast rebuild [ PACKAGE ...]

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.

toast upgrade [ PACKAGE ...]

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.

toast disarm BUILD | PACKAGE ...

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.

toast clean [ BUILD | PACKAGE ...]

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.

toast demolish BUILD | PACKAGE ...

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.

toast purge PACKAGE ...

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.

toast remove BUILD | PACKAGE ...

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.

toast rename PACKAGE ... NEWNAME

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.

toast change PACKAGE ...

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.

toast status [ BUILD | PACKAGE ] ...

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.

toast bug [ BUILD | PACKAGE ] ...

Sends a bug report about a broken build. Use this command to let me know when you think toast ought to be able to build a package, but it isn't working. If you would like to hear back from me about your bug report, or if there's anything else you think I should know, email me at toast-bugs@toastball.net. If invoked without arguments, sends build output from the most recent broken build; otherwise, sends build output from the most recent broken build for each argument. Build output for each broken build is stored in a file called broken.log somewhere under STOREDIR; each file contains full output from the build subprocess (the indented lines printed by toast build unless the quiet option is in force).

toast env

Prints shell commands to make armed packages usable. This command is normally invoked with eval $(toast env) 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), PKG_CONFIG_PATH (used by pkg-config to find .pc files), XML_CATALOG_FILES (used by DocBook and other tools to locate XML catalogs), LIBRARY_PATH (used by GNU ld to find libraries), and LD_LIBRARY_PATH (which has the same effect as LIBRARY_PATH and additionally affects all shared library loading at run time; see toast help libvar for less drastic alternatives). 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).

toast help [ TOPIC ] ...

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.

toast man

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.

Arguments

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.

NAME[/VERSION]

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

NAME/VERSION/BUILDNUM

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.

[ NAME/VERSION: ] URL

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.

[ NAME/VERSION: ] PATH

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.

[ NAME/VERSION: ] [ URL | PATH ... ]

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.

Options

--storedir=STOREDIR

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.

--armdir=ARMDIR

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.

--altarmdirs=ALTARMDIR[:ALTARMDIR]...

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).

--username=USER

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.

--fallbackuid=UID

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.

--nice=N

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.

--postarmprog=PROG

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.

--defaultcmd=COMMAND

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.

--stickyopts=OPTNAMES

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 compilecmd installcmd.

--findsites=SITELIST

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, googlecode, 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.

--httpproxy=URL

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.

--ftpproxy=URL

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.

--confappend=ARGS

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, use toast bug to 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.

--makeappend=ARGS

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.

--compilecmd=CMD

Specifies an alternate shell command to compile (but not install) a package. See the installcmd option for further discussion of what this option does and does not do. If CMD is the empty string, toast build uses built-in heuristics to figure out what to do based on the package contents. Otherwise, it will execute CMD as a shell command according to Perl's usual conventions, which is to say that CMD may contain multiple words, shell metacharacters, and so on. CMD will be invoked from the top-level source directory, unless that directory contains nothing but a single subdirectory, in which case toast will change to that directory first, repeating if necessary. A reasonable value for CMD might look something like ./configure && make; a similarly reasonable value for the installcmd option might be make install. You probably wouldn't want to specify exactly those commands, of course, since toast could figure those out on its own; if it tries something fancier instead, the noreconfigure option might do what you want. These options are intended to make it easier to customize specific packages; if you encounter a package that won't compile at all without them, I'd appreciate a bug report. If all you really need is to pass an extra argument or two to a configure script or set a make variable, consider using confappend or makeappend instead. Default: empty string (compile automatically).

--installcmd=CMD

Specifies an alternate shell command to install a compiled package. This option is analogous to the compilecmd option; see that option's description for important details. toast build always installs a package in a separate step immediately after successfully compiling it. The compilation step must not attempt to write to any directory outside the source directory (with a few exceptions, such as /tmp and /dev/null). Before invoking the install command, toast build will set a special environment variable, DESTDIR, to the path of a private directory tree (containing subdirectories such as bin and lib) under which the package should install itself. In principle, the install step should write only to DESTDIR. If the install step attempts to write outside of DESTDIR, the source directory, or a few other exceptional filesystem locations, toast may attempt to redirect the write to DESTDIR using a variety of means including (but not limited to) that described under the preload option. Because these rewriting mechanisms can sometimes be prone to failure, it's best to restrict actions taken during the install step to the minimum required. Default: empty string (install automatically).

--quiet | --noquiet

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.

--expand | --noexpand

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.

--autofind | --noautofind

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.

--autochange | --noautochange

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.

--autorename | --noautorename

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.

--autoenv | --noautoenv

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.

--autoclean | --noautoclean

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.

--autopurge | --noautopurge

When autopurge is enabled, an implicit toast purge will be performed on a package as soon as it is successfully built. Default: disabled.

--autoarm | --noautoarm

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.

--autodisarm | --noautodisarm

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.

--autodemolish | --noautodemolish

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.

--autoremove | --noautoremove

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.

--crossversion | --nocrossversion

When crossversion is enabled, the autodisarm, autodemolish, autoremove and stickyopts options will extend their effects to other packages with the same name when appropriate. See the descriptions of those options for details. Default: disabled.

--skipmismatched | --noskipmismatched

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.

--ccache | --noccache

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.

--preload | --nopreload

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.

--strictpreload | --nostrictpreload

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.

--useflock | --nouseflock

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.

--reconfigure | --noreconfigure

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.

--interactive | --nointeractive

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.

--stoponerror | --nostoponerror

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.

--ignorecase | --noignorecase

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.

--showurls | --noshowurls

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.

--showopts | --noshowopts

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.

--libvar=VAR

Optionally tells toast env to set an additional variable VAR that points into the lib subdirectory of each ALTARMDIR. You would typically set this to the empty string, LD_RUN_PATH, or LD_LIBRARY_PATH. LD_RUN_PATH typically instructs ld to compile the current ALTARMDIRs into any newly-built programs, such that those programs will search those directories for shared libraries. LD_LIBRARY_PATH has a more radical effect: in addition to influencing ld, it essentially instructs all dynamically linked programs to search the ALTARMDIRs for shared libraries. (This often works, but can cause terrible problems if you use toast to build a library that is sufficiently similar to a pre-existing library installed in one of the default locations.) If VAR is the empty string, toast env sets neither variable. Note that toast env always sets the relatively uncontroversial LIBRARY_PATH environment variable, which will at least allow ld to find both shared and static libraries in ALTARMDIRs at compile time. Default: LD_LIBRARY_PATH.

--infodir | --noinfodir

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 or the install-info program is missing or broken (e.g. the fake install-info command bundled with dpkg), toast arm and toast disarm will delete the info/dir file, if present, instead of rebuilding it, which will likely prevent the info command from giving you a correctly-populated menu when invoked without arguments, though it should still work fine when invoked with a program name as an argument. Default: enabled.

--xmlcatalog | --noxmlcatalog

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 helps 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.

--hspkg | --nohspkg

When hspkg is enabled, toast build will attempt to intercept information about Haskell packages registered with ghc-pkg and store it in strangely-named files in a special hspkg subdirectory; toast arm and toast disarm will rebuild a Haskell package database in armdir called etc/xml/toast-hs-package.conf, whose presence and contents depend on the contents of armdir's hspkg subdirectory; and toast env will add this package database to the GHC_PACKAGE_PATH environment variable used by GHC 6.6 and later. If hspkg is disabled, toast build will not attempt to intercept calls to ghc-pkg, which may prevent Haskell libraries from building at all, at least with GHC 6.6 and earlier; and toast arm and toast disarm will delete the toast-hs-package.conf file, if present, instead of rebuilding it. Essentially untested. Default: disabled.

--protect | --noprotect

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.

--relative | --norelative>

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.

--debugrewrite | --nodebugrewrite

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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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

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.

FILES

By default, when invoked by a non-root user, toast writes only to the $HOME/.toast directory, which will be created automatically if needed.

AVAILABILITY

toast may be downloaded from http://toastball.net/toast/ under the terms of the GNU GPL.

BUGS

Please report any bugs, unexpected behavior, unsurprising but inconvenient failures, feature requests, comments, and so on to toast-bugs@toastball.net. You can also use toast bug to report problems with specific packages that refuse to build.

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
  - build (w/ --preload) fails for python 2.5.2 if ~/.toast is a symlink
  - "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-sensitive
  - "--stickyopts=crossversion" suffers from chicken-and-egg problem

Wish list:

  - purge inaccessible dirs from env upon setting toast UID? (6/3/07)
  - 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?)
  - track runtime dependencies (e.g. ldd output); trigger auto rebuild
  - 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?
  - make lemonade somehow when given dpkg's install-info
  - 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?

SEE ALSO

  /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

AUTHOR

Jacques Frechet

COPYRIGHT

This manual is part of toast. Copyright (C) 2003-2016 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 3 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, see http://www.gnu.org/licenses/.