NAME
build - the equivalent of "make" of "Build'n'Play" (BnP)
SYNOPSIS
build
[-g] - use "genopt" installation method
[-n] - use "normal" installation method
[-p <path>] - the absolute prefix of the installation hierarchy
[-r <path>] - optional relative path ("category") for target
[-s <path>] - add search path(s) for local source directory(ies)
[-u <url>] - add URL(s) for remote source directory(ies)
<target> - the command or software package to install
(clean, bnp, perl, tools, sfio, gimp, imagick, ...)
build [-h] - print help screen and exit
build -v - print version information and exitDESCRIPTION
Think of "Build'n'Play" as something very similar to "make" and "Makefiles":
There is a command called "build" (the equivalent of "make") and several "Buildfiles" (called "perl.bnp", "gimp.bnp" and so on) for the different "targets" you can "build". Just say "build perl" for building and installing Perl and its modules, for instance.
Just like "make", which doesn't re-create the files that are "up to date" when you invoke "make" more than once, the "build" command does not re-execute the commands that have already been executed successfully in the previous call of "build".
This automatic recovery mechanism is the central idea behind "Build'n'Play":
If something goes wrong during the installation (for instance, if a compiler error occurs), or if you abort it with "Ctrl-C", you can simply re-run "build" (after you resolved the problem in question) with the same options (important!) and "Build'n'Play" will automatically continue the installation where it left off (thereby attempting to re-execute the command which failed previously or which was interrupted).
There is also a command "build clean" (the equivalent of "make clean") for deleting the internal temporary workspace, which should always be used between different builds (but not when restarting an aborted installation, of course!).
For a complete list of available targets you can build, just call "build" without parameters:
% ./buildNote that it is possible to install subsets of a given target if such subsets have been defined in the corresponding "Buildfile" ("<target>.bnp").
To do so, just append the name(s) of the desired subset(s) (or "subtarget(s)") to the name of the (main) target using dots ("."), as in the following example:
% ./build perl.core.fox(Note that the order of the subtargets after the main target does not matter.)
This will install Perl itself ("core") plus those modules ("fox") which are discussed more thoroughly in the book "Programmieren mit Perl-Modulen" (by O'Reilly Verlag Koeln, 1999) accompanying the CD-ROM on which "Build'n'Play" was first published (the fox is the animal on the cover of that book).
If you want to know which subtargets are available, use the tool "tags" from the "misc" subdirectory in the "Build'n'Play" distribution, e.g.
% ./misc/tags perlWhen working with "build", two files will be especially important for you (unless the installation succeeds without any errors, which it is unlikely to do when you run it for the first time):
The installation script (or "Buildfile") "<target>.bnp" and the automatic recovery file "recover.bnp".
Both files are located in the directory "<prefix>/lib/BnP/lib/<target>" (when using the "normal" installation method) or "<prefix>/lib/BnP/<target>" (when using the "genopt" installation method), where "<prefix>" is the installation prefix such as "/usr/local", "/opt" or the like, as specified via the "-p" option, and "<target>" is the name of the software package to be installed.
(For a discussion of the two installation methods and their corresponding command line options, as well as the "-p" option, see the section "OPTIONS" below.)
If the "build" command is run from the original distribution's directory or from the CD-ROM, the file "<target>.bnp" is automatically copied from that directory to the directory mentioned above, as soon as an error occurs during the installation (but not if you interrupt it manually using "Ctrl-C").
After that this copy takes precedence over its original in the distribution directory or on the CD-ROM, i.e., the "build" command will execute this copy rather than the original file when invoked again subsequently with the same "<target>".
(If you don't want that, simply delete this copy.)
This is done because you will most likely need to change this file after an error occurred, and you obviously can't do that on a CD-ROM, and you probably don't want to do that in the original distribution.
(If you don't want this to happen and if you actually want to edit the file in the original distribution, simply delete the file ".cdrom" from the distribution directory BEFORE using the "build" command.)
When you make any changes to that copy of the installation script, you may also need to change the corresponding commands in the automatic recovery file (this file is used by the automatic recovery mechanism (see BnP(3) for more details) in order to determine which commands have already been executed successfully and which are hence to be skipped in any later runs).
You may also want to use this automatic recovery file for looking up which was the last command in your installation script that was successfully executed.
In addition to these two files, you may want to check the temporary internal workspace (in "<prefix>/lib/BnP/tmp/" or "<prefix>/pkg/BnP/tmp/") where the software packages are unpacked and compiled, in order to find out what went wrong (in case of an error) and how to fix it.
OPTIONS
Note that option letters cannot be condensed into a single option letter string in this script, i.e., an option string such as "-gp/opt" would be illegal and result in an error message.
Note however that whitespace between the option letter and its argument (if it takes one) is optional.
If the (mutually exclusive) options "-g" and "-n" are both specified, the last one overrides all previous ones, unless the option "-r" is used, in which case the "-g" option is implicitly assumed, regardless of wether any "-g" or "-n" option has been specified or not.
-g
This option enables the "genopt" installation method.
Use this option if you don't want to have your software packages installed all into the same directory (such as "/usr/local/bin"), trampling over one another and making the de-installation almost impossible (except for trivial cases), but each into a separate directory subtree of their own.
See genopt(1) for more details.
(Note that you can still use the prefix "/usr/local" in combination with this installation method, but this is actually not recommended, because possible name conflicts can be resolved much more easily (automatically, through a command line option) if a completely new installation directory tree is used, such as "/opt" or "/sw" or whatever you choose.)
-n
This option enables the "normal" or standard Unix installation method, in which software packages are all installed into the same installation directories (such as "/usr/local/bin", "/usr/local/man" and so on).
Note that you can use any installation prefix you want in combination with this installation method; you are not limited to using "/usr/local".
You will usually not need this option, though, because this is the default setting.
However, if you set the default to the "genopt" installation method (by changing the corresponding configuration constant in the script "build"), you can use this option to temporarily disable the "genopt" installation method and to revert the behaviour to the usual Unix installation method.
-p <path>
Use this option to specify the installation prefix to be used.
The default is "/usr/local", in case you don't specify any prefix explicitly.
-r <path>
This option can be used in combination with the "genopt" installation method in order to specify a subdirectory path (a "category") relative to the physical software packages installation directory subtree, usually "<prefix>/packages" (e.g. "/opt/packages").
This allows you to group related software packages into categories and subcategories (i.e., subdirectories and subsubdirectories) of your own choosing (as many levels deep as you wish).
Note that using this option automatically implies the "genopt" installation method, i.e., this option is automatically treated as though the option "
-g" had been specified as well (this also overrides any "-n" option which may have been specified).
-s <path>
Use this option for specifying any additional directories containing source distribution files which are relevant to your installation.
You may use this option multiple times on the same command line in order to add more than one directory.
You may also concatenate several directories using colons ("
:"), e.g.-s dir1:dir2:dir3You may also combine these two forms, e.g.
-s d1:d2:d3 -s d4:d5Use this option to indicate the path to your CD-ROM drive (e.g. "
-s /cd") if this path is NOT "/cdrom" or "/cdrec" AND if you are not starting the "build" command from the "BnP" directory on the CD-ROM (in which case "build" already knows (implicitly) about the path to your CD-ROM drive).You can also use this option to indicate the path to a mirror of a software archive (such as "CPAN", for example) on your hard disk, e.g. "
-s /pub/mirrors/CPAN", in order to avoid desnecessary downloads.Files not found on your local file system (i.e., all the default directories already configured into the "build" command plus any additional source directories you may have specified with this option) will continue to be downloaded automatically, though.
Note that the directory paths given should not end in a slash ("
/").Note also that you do not need to specify the "generic" subdirectories "CPAN", "BnP/src", "BnP" and "src", i.e., you may (and should) specify "
-s /cd" instead of "-s /cd/CPAN:/cd/BnP:/cd/BnP/src" and "-s /pub/mirrors" instead of "-s /pub/mirrors/CPAN", for instance.Finally, note that the directories you specify will be searched in the given order (from left to right).
-u <url>
Use this option for specifying any additional (or alternative) URLs needed for downloading source distribution files which are relevant to your installation.
You may use this option multiple times on the same command line in order to add more than one URL.
You may also concatenate several URLs using whitespace - but don't forget to enclose the whole argument in (single or double) quotes in this case:
-u 'ftp://ftp.engelschall.com/pub/bnp ftp://ftp.netsw.org/netsw'You may also combine these two forms, e.g. you may also write
-u 'url1 url2 url3' -u 'url4 url5'This option is especially useful if you have a server on your local network with a mirror of some software archive you need, e.g.
-u ftp://instserv.yourdomain.com/pub/mirrors/CPANNote that the given URLs should always end in the name of a directory, but they should nevertheless not end in a slash ("
/").Note also that (in contrast to the "
-s" option described above) you DO need to specify the "CPAN" directory in the URLs of "CPAN" mirror servers (unless the server doesn't use that name, then use its equivalent instead), e.g.-u ftp://ftp.cdrom.com/pub/perl/CPAN -u ftp://ftp.metronet.com/pub/perlHowever, do NOT specify any subdirectory BELOW the "CPAN" directory level (or its equivalent on that host).
For servers other than "CPAN" mirror servers you will usually specify the URL up to the directory containing the file of interest, unless you need more than one file from the same server but from different directories, in which case you should specify the path common to all files in the URL and the differing paths to the different subdirectories in the "RELPATH" argument of the corresponding "
fetch()" method call in your installation script (see BnP(3) for more details).Finally, note that the URLs you specify will be tried in the given order (from left to right).
-h
If this option is found among the options to the "build" command, the internal processing of command line options is terminated immediately, a help screen is printed to STDOUT and the program stops (with exit code "1").
Note that this option is optional in the sense that calling the "build" command without any parameters produces exactly the same result.
-v
If this option is found among the options to the "build" command, the internal processing of command line options is terminated immediately, the name and current version number of the "build" command is printed to STDOUT and the program stops (with exit code "1").
FILES
build - the equivalent of "make" of "Build'n'Play"
genopt - a tool for maintaining a software package
installation hierarchy which allows complete
de-installation (without residues whatsoever)
using a symbolic link access layer
BnP.pm - the library which provides the automatic recovery
mechanism which allows you to simply re-run the
"build" command after an error occurred during
the installation; the installation will auto-
matically resume where it left off
miniperl - a "stripped down" version of the Perl interpreter
provided in the original Perl distribution, which
is used here for bootstrapping Perl in case no
Perl 5 is installed yet on your system
<target>.bnp - the "Buildfile" (in analogy to "Makefile") or
installation script for the installation target
recover.bnp - the command log file needed for the automatic
recovery of the installation process
recover.000 - safeguarded copies of the "recover.bnp" file
recover.001 of previous installation runs (you might need
... to re-use one of these!)DIRECTORIES
On the CD-ROM from O'Reilly Verlag ("Programmieren mit Perl-Modulen"):
/cdrom/CPAN/ - contains the CPAN snapshot
/cdrom/BnP/ - contains the BnP distribution
/cdrom/BnP/misc/ - contains miscellaneous tools
/cdrom/BnP/src/ - contains other source files(The latter directory contains source files not found in CPAN (anymore), as well as tools like "bzip2", "snarf", GNU "make" and "patch".)
When using the "normal" installation method with a prefix such as "/usr/local":
/usr/local/lib/BnP/arc/ - contains all BnP files
/usr/local/bin/ - contains build and genopt
/usr/local/lib/BnP/lib/ - contains BnP.pm and miniperl
/usr/local/lib/BnP/lib/perl/ - contains perl.bnp
and recover.* files
/usr/local/lib/BnP/lib/perl/src/ - contains source files
/usr/local/lib/BnP/lib/<target>/ - contains <target>.bnp
and recover.* files
/usr/local/lib/BnP/lib/<target>/src/ - contains source files
/usr/local/man/... - contains BnP's manpages
/usr/local/lib/BnP/tmp/ - contains internal workspaceWhen using the "genopt" installation method with a prefix such as "/opt":
/opt/pkg/BnP/arc/ - contains all BnP files
/opt/pkg/BnP/bin/ - contains build and genopt
/opt/lib/BnP/ - contains BnP.pm and miniperl
/opt/lib/BnP/perl/ - contains perl.bnp
and recover.* files
/opt/lib/BnP/perl/src/ - contains source files
/opt/lib/BnP/<target>/ - contains <target>.bnp
and recover.* files
/opt/lib/BnP/<target>/src/ - contains source files
/opt/pkg/BnP/man/... - contains BnP's manpages
/opt/pkg/BnP/tmp/ - contains internal workspaceNote that "/opt/lib/BnP/" is exactly the same directory as "/opt/pkg/BnP/lib/", but via a different symbolic link.
DIAGNOSTICS
"Can't find the indispensable tool '<tool>'!"One of the absolutely indispensable Unix tools (like sh, gunzip, tar etc.) could not be found in the search path (as given by the "$PATH" environment variable).
This occurs if the "$PATH" environment variable is not set properly or if your Unix installation is seriously incomplete or broken.
Check your "$PATH" environment variable to see wether it includes all necessary paths, or install the missing tool.
"Can't find '<item>' in '<list>'!""Can't find '<item>' neither in '<path>'nor in '<list>'using offsets '<subdirs>'!""Can't find '<item>' neither in '<path>'nor in '<list>'using offsets '<subdirs>' and '<subsubdir>'!"Neither the expected directory(ies) nor your current search path (i.e., the directories listed in your environment variable "
$PATH") contain the requested file "<item>", not even in certain default subdirectories of these directories.Your search path "
$PATH" may need to be adjusted, or you may need to specify the path to your CD-ROM drive using the command line option "-s" (see also the section "OPTIONS" above).Maybe you didn't start the "build" command from the CD-ROM or the original distribution.
If in doubt, "cd" to the "BnP" directory on your CD-ROM (e.g. "cd /cdrom/BnP") or into the directory of the original distribution and start the "build" command from there, i.e., with "./build".
"Can't find any tool (snarf, lynx) for downloading!"You probably forgot to mount your CD-ROM drive.
May also be caused by starting copies of "build" from different places. If in doubt, cd to the "BnP" directory on the CD-ROM or the original distribution directory and use "./build" instead of "build".
Moreover, you do not seem to have either "snarf" or "lynx" installed.
You might want to install one of these (or change the configuration in "BnP.pm" for another tool) in order for automatic downloads to work in the future, which will benefit you as soon as you will attempt to install a module newer than the CPAN snapshot included on the CD-ROM.
(Note that you can install "snarf" with "Build'n'Play" itself via the command "build tools.snarf". If you don't have "Build'n'Play" on a CD-ROM, you may need to create a subdirectory named "src" in your original distribution directory first and then to manually download the file "snarf-1.6.1b.tar.gz" from the URL "ftp://ftp.engelschall.com/pub/bnp/packages/" into that subdirectory before actually doing so.)
"Download of '<file>' with '<tool>' failed!"The program was unable to load the mentioned file from any of the URLs specified by you on the command line or configured in "<target>.bnp".
This means that either there was no connection, or the file was not found on any of the specified or configured servers.
Try again later or try a different URL if everything else seems to be correct.
Note that this error message can also occur when you forget to mount your CD-ROM drive, in case you have one of the configured download tools (currently "snarf" and "lynx") installed on your system but no working network access.
"Can't install the "Build'n'Play" (BnP) package;please re-run this command ('build bnp')from the CD-ROM or the original distribution!"Be sure to start "build" from the CD-ROM or the original distribution.
If in doubt, "cd" to the "BnP" directory on your CD-ROM (e.g. "cd /cdrom/BnP") or into the directory of the original distribution and start the "build" command from there, i.e., with "./build".
"<Error> in patch command!"An error (more closely described by "<Error>") occurred in one of the Perl expressions given as arguments to the "patch()" method in "BnP.pm".
This is usually a Perl syntax error.
Check your "<target>.bnp" installation script.
Watch out for proper quoting and escaping!
"Next command deviates from the automatic recovery file -discarding the remainder of the automatic recovery file!"This warning message appears whenever you apply changes to the "<target>.bnp" installation script (after an error with program abortion) which cause the installation to take a different course than in previous runs.
This happens for instance if you comment out some part in the installation script, if you insert new commands or if you alter existing ones.
This warning message might show that the installation is not doing what you intended.
In such a case you can always abort with "Ctrl-C", make the necessary changes, and re-run "build".
Note that you can always go back to the recovery files of all previous installation attempts, which are kept for exactly this purpose (with ascending numbers in their filename extensions, i.e., "recover.000" is the recovery file from the first installation attempt, "recover.001" from the second, and so on).
All other error messages indicate that something is wrong either with your command line parameters (and the corresponding error message should help you to correct the problem), or with the installation (compiler errors and the like - again, the corresponding error message should help you to fix this problem), or with your system (most probably a problem with file permissions in your file system, or a disk capacity overrun).
SEE ALSO
genopt(1), BnP(3), make(1), CPAN(3).
VERSION
This man page documents "build" version 2.1.0.
AUTHOR
Steffen Beyer
sb@engelschall.com
www.engelschall.com/u/sb/download/COPYRIGHT
Copyright (c) 1998 by Steffen Beyer.
All rights reserved.LICENSE
This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e., under the terms of the "Artistic License" or the "GNU General Public License".
Please refer to the files "Artistic.txt" and "GNU_GPL.txt" in this distribution for details!
DISCLAIMER
This package 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.