toast - build and install programs from source
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.
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.
Downloads the given packages' files into the repository. Implies toast add. After this command completes successfully, other commands will be able to operate on the package without downloading any additional files from the network.
Creates a new build for one or more packages. This may involve implicitly invoking toast add, extracting archives, applying patch files, compiling a new build of the package and "installing" it in a build-specific directory tree. Each package can have any number of independent builds. Builds for a given package are automatically assigned sequential numbers starting from 1. If the package is not stored, or if URLs are given, toast get is implied. Many options can influence this command's behavior; see the options reference for complete details.
Deletes and intermediate files created by toast build. 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. The toast build command may perform this step automatically for some kinds of binary packages that do not involve intermediate files, as well as for other packages if the autoclean option is enabled. Only builds that are not in the building state (as reported by toast status) may be cleaned. If no arguments are given, all eligible builds are cleaned.
Creates symbolic links to each file in a build. This step is normally required before a package can be used. The links are typically created under a directory such as /usr/local. Existing links to other builds are moved out of the way if necessary, and the corresponding builds are still considered to be armed. A build must be in the built state (as reported by toast status) before it can be armed. If no explicit build number is supplied on the command line, this command implicitly creates a new build (as if by toast build) if the package has no builds, or arms the latest built build if such a build exists and was created later (numbered higher) than the latest armed build for that package (if any). If the latest build is already armed, the command fails; you probably meant to invoke toast build with the autoarm option set.
Checks for a later version of an 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 the new package will never be armed 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. If no build number is given, all armed builds are disarmed. If the package version number is also omitted, all armed builds belonging to packages with the given name are disarmed.
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 (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 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. Attempting to rename an armed package causes toast rename to report an error. Otherwise, renaming a package that contains builds should be OK, though it could conceivably break ill-behaved packages. This command can also be used to renumber builds.
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 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.
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.
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 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.
Enables or disables verbose command output. When disabled, most commands will produce output only on failure. Some commands, such as toast status, are not affected by this flag. Default: enabled.
When autofind is enabled, toast add and other commands will automatically look up package URLs on freshmeat.net when none have been added previously or given explicitly. If no version number is given either, the latest version listed on freshmeat.net 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. This matters if an URL given on the command line points to an HTML page or FTP directory rather than to an actual archive to be extracted and built. In order to ensure consistent results, it is often desirable to store the more specific URLs, especially if autopurge is enabled. If this option is disabled, toast get will still follow links in the usual way, but stored URLs will be left untouched, and future invocations of toast get may end up downloading different files for the same package if new files or links have since been added to a page or directory. Default: enabled.
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 autoclean is enabled, toast build performs an implicit toast clean on every newly created non-broken build. Default: enabled.
When autopurge is enabled, toast build performs an implicit toast purge on every package with a newly created non-broken build. Default: disabled.
When autoarm is enabled, toast build performs 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 build performs an implicit toast demolish on every other build belonging to the same package as a newly-created, non-broken build. Default: disabled.
When both autoremove and crossversion are enabled, toast build performs an implicit toast remove on every other package with the same name as the package containing a newly-created, non-broken build. 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 strictpreload is enabled, toast build will fail unless it can successfully compile a shared library for use with LD_PRELOAD during the "make install" phase. If strictpreload is disabled, toast build still tries to build and use the shared library, but will do the best it can otherwise. 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.
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 may not build or install itself 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 includes by default. Default: enabled.
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.
When showurls is enabled, toast show always displays the stored URLs associated with each displayed package. If showurls is disabled, toast show only displays a package's URLs if a different list of URLs for that package was given explicitly on the command line.
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).
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.
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 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, if such a line exists, in $HOME/.toast/conf, if that file exists. ($HOME specifically represents the value of the HOME environment variable.) 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. If the 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.
Jacques Frechet