STOWES(1) stowES STOWES(1) NNNNAAAAMMMMEEEE stowES - the stow Enhancement Script SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ssssttttoooowwwwEEEESSSS command[,command[,...]] [options] [expressions] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN This manual page documents the stow Enhancement Script, short ssssttttoooowwwwEEEESSSS. ssssttttoooowwwwEEEESSSS is a perl script which tries to ease the use of the stow packaging program and software which can be compiled and installed with autoconf. RRRREEEEQQQQUUUUIIIIRRRREEEEMMMMEEEENNNNTTTTSSSS ssssttttoooowwwwEEEESSSS should run on all platforms where stow is running what means that these platform should know perl and supply soft links (have I missed something?). CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS ssssttttoooowwwwEEEESSSS supplies the following commands which may be abbre- viated to uniqueness (some of them have shorter aliases as well). lllliiiisssstttt,,,,llllssss [regexp] List all packages in StowDir (usually /usr/local). The package names are prefixed with a char of the fol- lowing meaning: I ... package is installed s ... package can be checked in without any conflict - ... package cannot be checked in because there is a conflict with an already installed package, the file in parentheses is the first conflicting found You may give regexps to only show specific packages, if no arguments are given all packages are shown. cccchhhheeeecccckkkkssssttttoooowwww,,,,ccccssss [regexp] Does the same as the list command but also checks for broken packages and lists the size of each package scanned in blocks (normally 1KB). This is signifi- cantly slower than _l_i_s_t. There is an additional pre- fixed char: X ... package is broken, i.e. package was not fully checked in (some files missing) or something other is weird, in the following parentheses all conflicting/missing files/directories are shown (relative to the target dir). Otherwise _c_h_e_c_k will behave in the same way as the _l_i_s_t command. cccchhhheeeecccckkkkttttaaaarrrrggggeeeetttt,,,,cccctttt [regexp] Checks if the targetdir only contains links and dirs. Displays the files and the wrong links it found. iiiinnnnssssttttaaaallllllll _d_i_r(s)|_f_i_l_e(s) Calls command "untar" if the argument is a file. Then calls "make", "makeinst" and "checkin" with the appropriate arguments. uuuunnnnttttaaaarrrr _f_i_l_e(s) Unpacks a {tar,tar.gz,tar.bz2,tgz}-source-archiv to the "dumpdir" directory. ccccoooonnnnffffhhhheeeellllpppp,,,,cccchhhhllllpppp _d_i_r(s)|_f_i_l_e(s) Call 'configure --help' from a directory or {tar,tar.gz,tar.bz2,tgz}-source-archiv. mmmmaaaakkkkeeee,,,,mmmmkkkk _d_i_r(s) The directory specified as a argument should contain a "configure"-script which is called with the arguments "--prefix=TargetDir" and the arguments you gave on the command line. After this "make" and "make check" are called (of course with the optional paramaters you gave). "make check" is only called if the root-Make- file of the package contains a rule "check". mmmmaaaakkkkeeeeiiiinnnnsssstttt,,,,mmmmkkkkiiiinnnn _d_i_r(s) This command checks for a file "config.status" which should be left by the call of "configure". Then "make install prefix=StowDir/packagename" is called to install the package in the appropriate place. After the make run the "config.status" file is copied to "$stowdir/package/.config/package" and a file with basic information on the creator, date and host machine is also stored there. Furthermore the commands "depends", "strip" and "checksums" are called for the package. Note that stripping is switched off per default. When the "--removesource" option was given, the source code is removed. If something during this procedure failed the possibly installed package will be removed since it may be bro- ken (the package will not be delete if the `--force' option was given!). The following commands take regular expressions or the option _-_a as arguments. cccchhhheeeecccckkkkssssuuuummmmssss This command creates the checksums for the packages. cccchhhhkkkkcccchhhhkkkkssssuuuummmmssss This command verifies the checksums given in the pack- age with the ones calculated for each file. ddddeeeeppppeeeennnnddddssss This command calculates some basic dependency informa- tion. It only checks binaries and libraries via _l_d_d(1) for needed libraries. cccchhhheeeecccckkkkiiiinnnn,,,,cccciiii Calls """"ssssttttoooowwww"""" for the package if the package is not checked in. cccchhhheeeecccckkkkoooouuuutttt,,,,ccccoooo Calls """"ssssttttoooowwww ----DDDD"""" for the package if the packges is checked in. ssssttttrrrriiiipppp Strips all files in the package. The checksums will be recalculated by calling the command `checksums'. Note that stripping is switched off per default. rrrreeeemmmmoooovvvveeee,,,,rrrrmmmm Removes a package. The use of the _-_a-option is switched off here. ppppaaaacccckkkkaaaaggggeeee Creates an archive of the specified package and stores it in the _D_u_m_p_D_i_r. The filename of the created pack- age(s) can be influenced the the `--packagesuffix' option. ccccoooonnnntttteeeennnnttttssss Lists the contents of packages. The first column dis- plays the type of item (d:file, l:link, p:pipe, s:socket, b:block special file, c:character special file). The second column shows the name of file/dir. If the item happens to be a file, the size of it is shown in the third column (in Bytes). ccccoooonnnnttttsssseeeeaaaarrrrcccchhhh Searches all files in the packages for a specified pattern. Useful to check if a path containing """"ssssttttoooowwww"""" was compiled into the binaries/libraries. Specify a search pattern (regular expression) with the `--con- tentpattern' option. cccchhhheeeecccckkkklllliiiibbbbssss Check if all libs for package are available. If stowES thinks there's something wrong that may be so but must not be so. Some programs hide special libs in special directories which are not know when testing with _l_d_d(1). Futhermore all files with the execution bit set are checked. This normally includes libraries which are installed this way. sssshhhhoooowwwwccccoooonnnnffff Show the configuration of the specified packages. These are the arguments given to the configuration script when the program is installed and are saved in the config.status file. Misc commands: rrrreeeebbbbuuuuiiiilllldddd Rebuilds the whole stow-archive. Deletes everything except the stowdir from the targetdir and checks in again all packages which were previously checked in. Only package marked with a "I" in the list mode will be checked in again (i.e. broken packages will not be checked in again). rrrreeeennnnaaaammmmeeee regexp newname Renames a package. This includes the information in .config/package as well. eeeexxxxcccchhhhaaaannnnggggeeee oldpackregexp newpackregexp Exchange two package with one call. oldpack is checked out and newpack is checked in immediately. oldpackreg- exp and newpackregexp are regular expressions which have to match exactly one package. iiiinnnnssssttttppppaaaacccckkkk _f_i_l_e(s) Installs and checks in a package created by the "pack- age"-command. If you don't want to check in the pack- age immediately use the option `--nocheckin'. sssshhhheeeellllllll Starts a sub shell (taken from the environment vari- able $SHELL). This is useful when something during a `stowES' run fails and you want it to correct by hand. So you have the same environment set as when `stowES' would do the job (environment variables etc.). hhhheeeellllpppp,,,,hhhhllllpppp Print a help screen. ccccoooonnnnffffiiiigggg,,,,ccccnnnnffff,,,,ccccffffgggg Print the actual configuration of all interesting variables. vvvveeeerrrrssssiiiioooonnnn Print a version information. And remember: The commands (the options as well) may be abbreviated to uniqueness! Commands which take the same parameters may be combined with a comma. E.g. to to check the target and the stow dir one may use: stowES cs,ct OOOOPPPPTTTTIIIIOOOONNNNSSSS The following options are available (do "perldoc Getopt::Long" for a precise explanation on how to syntac- tically specify options). Some options have two options (--bar and --nobar). You may use these to override a set option in a configure file or environment variable. ----ssss,,,, --------ssssttttoooowwwwddddiiiirrrr dir Default: /usr/local/stow Stow dir. This directory contains all the packages. ----tttt,,,, --------ttttaaaarrrrggggeeeettttddddiiiirrrr dir Default: /usr/local Target directory. This directory is the target direc- tory for all the packages installed in the stow direc- tory. The links will be created from the stow direc- tory to this target directory. _S_e_e _l_a_t_e_r in this document on a further explanation of the use of the stow and target dir. --------ssssttttoooowwwwnnnnaaaammmmeeee name Default: stow Name of the stow directory. ----pppp,,,, --------ppppaaaacccckkkkaaaaggggeeeennnnaaaammmmeeee name Default: none Alternate package name. When installing a package you may specify an alternative name for the package. This only works if you only give one package on the command line. ----aaaa,,,, --------aaaallllllllppppaaaacccckkkkaaaaggggeeeessss Default: unset. Proceed all packages found in $StowDir. This is the same as giving the regular expression "." but will not work for the `remove' command. ----vvvv,,,, --------vvvveeeerrrrbbbboooosssseeee [level] Default: 0 Verbose mode. You may give the option _-_v to urge stowES to print out more messages. Theoretically it is possible to give the _-_v option a value (greater zero) to increase the verbosity level but this isn't used in stowES currently. qqqq,,,, --------qqqquuuuiiiieeeetttt,,,, --------nnnnooooqqqquuuuiiiieeeetttt Default: noquiet Quiet mode. Do not produce any output except error messages. Use noquiet to switch the quiet mode off. ----kkkk,,,, --------ccccoooonnnnttttiiiinnnnuuuueeee,,,, --------nnnnooooccccoooonnnnttttiiiinnnnuuuueeee Default: nocontinue Continue after error if possible. When processing mul- tiple files/dirs (e.g. in `install'-mode) stowES will not stop processing, it will go on with the next argu- ment on the command line. ----ffff,,,, --------ffffoooorrrrcccceeee Default: noforce Force certain operation although there may be unusual conditions. E.g. install a package even if it already exists. StowES will not complain that there's already a package with the same name. Useful for packages which could not be installed successfully in the first try. ----dddd,,,, --------dddduuuummmmppppddddiiiirrrr dir Default: /tmp Directory to store all the stuff. Sources are unpacked to this directory. Packages created by the `pack- age'-command are also stored there. ----mmmm,,,, --------aaaammmmbbbbiiiigggguuuuoooouuuussss,,,, --------mmmmuuuullllttttiiiipppplllleeee,,,, --------nnnnooooaaaammmmbbbbiiiigggguuuuoooouuuussss,,,, --------nnnnoooommmmuuuullllttttiiiipppplllleeee Default: noambiguous Regexps may match more than one package. Normally one regular expression on the command line may only match one package in the stow directory. This options allows the regular expression to match to more than one package. This option is only valid to some com- mands, mostly these changing data somewhere (currently these are: checksums, depends, checkin, checkout, strip, remove). ----nnnn,,,, --------ddddrrrryyyyrrrruuuunnnn,,,, --------nnnnooooddddrrrryyyyrrrruuuunnnn Default: nodryrun Only show what to do. Affects only commands which change data on the disk. This options does not mean that stowES wont cause any disk access, it may check if packages are checked in or not. ----jjjj,,,, --------ppppaaaarrrraaaalllllllleeeelllljjjjoooobbbbssss [number] Default: 1 Pass a _-_j option to make which causes make to do builds in parallel. For convinience the optional num- ber behind the option differs from the meaning it has for make! When giving a number greater or equal to one that number will be given as is to the _-_j option of make causing it to start as many sub-processes in par- allel. If no number or zero is given, stowES tries to figure out how many processors are installed on the machine it is currently running on and uses this num- ber for make. So if you've got a quad-box you'll auto- matically get four parallel sub-processes. Of course stowES needs to know how to find out how many proces- sors are installed. It has support for some platforms but not for that many. If your platform is not sup- ported you can use the _-_j option with an appropriate number or send the author of stowES (me ;) a patch (see getCPUNumber sub routine in the script) or at least a detailed description how to find out that num- ber. If stowES cannot find out the number it will default to one. ----cccc,,,, --------ccccoooonnnnffffiiiiggggffffiiiilllleeee file Default: none Specify a configfile (may be used multiple times). ----oooo,,,, --------oooouuuuttttppppuuuuttttffffiiiilllleeee file Default: STDOUT Output file. With this option it is possible to redi- rect the output to something else than STDOUT. ----llll,,,, --------llllooooggggffffiiiilllleeee Default: /dev/null Log file, prints short messages what stowES is doing currently. Great for use with `--rotatinginstall'. --------ssssuuuubbbbddddiiiirrrr name Default: none This option can be primarily used with the make and makeinst commands. With this option it is possible to install a package into a sub directory inside your targetdir, e.g. you have some beta software you want to install into your stowdir but you do not want it to mess up with your stable packages. stowES make foo-cvs-latest --subdir beta will install this package into $TargetDir/beta but will check it in in your normal stow dir. --------ccccoooonnnntttteeeennnnttttppppaaaatttttttteeeerrrrnnnn pattern Default: \Wstow\W Search pattern for the search in packages with command `contsearch'. --------ccccoooonnnntttteeeennnnttttsssseeeeaaaarrrrcccchhhhffffiiiilllleeee file Default: /dev/null Filelist of matches The given file will contain all files which matched the `contentpattern'. --------ccccoooonnnnffffiiiiggggddddiiiirrrrnnnnaaaammmmeeee dirname Default: .config Name of the directory where configuration data is stored inside each package (or target dir). It is sane to start this name with a ".". --------ddddeeeeppppeeeennnnddddeeeennnnccccyyyyffffiiiilllleeeennnnaaaammmmeeee file Default: dependencies Filename for dependencies in the configuration direc- tory. --------cccchhhheeeecccckkkkssssuuuummmmffffiiiilllleeeennnnaaaammmmeeee file Default: md5sums Filename for checksums in the configuration directory. --------ccccrrrreeeeaaaattttoooorrrriiiinnnnffffooooffffiiiilllleeeennnnaaaammmmeeee file Default: creatorinfo Filename for creatorinfo in the configuration direc- tory. --------ppppaaaacccckkkkaaaaggggeeeessssuuuuffffffffiiiixxxx string Default: none. Additional name for packages (e.g. architecture) when in command `package'. --------rrrreeeemmmmoooovvvveeeessssoooouuuurrrrcccceeee,,,, --------nnnnoooorrrreeeemmmmoooovvvveeeessssoooouuuurrrrcccceeee Default: noremovesource Remove unpacked source after built. This is especially useful when using `--rotatingintall' with lots of packages (else you would need lots of disk space). Only applies for commands `makeinst' and `install'. --------mmmmaaaakkkkeeeecccchhhheeeecccckkkk,,,, --------nnnnoooommmmaaaakkkkeeeecccchhhheeeecccckkkk Default: makecheck Will switch on or on the call of "make check". --------ccccoooonnnnffffiiiigggguuuurrrreeee,,,, --------nnnnooooccccoooonnnnffffiiiigggguuuurrrreeee Default: configure Will switch the call of "configure" on or off. It's usefull to switch configure off when a "make"-call failed and you have to repeat the `make' or `install' comamnd. --------mmmmaaaakkkkeeee,,,, --------nnnnoooommmmaaaakkkkeeee Default: make Will switch the call of "make" on or off. It's useful to switch make off when a "configure"-call did not fail but produced an undesired result and you want to try to find the right setting. --------uuuusssseeee----ssssaaaavvvveeeedddd----ooooppppttttiiiioooonnnnssss,,,, --------nnnnoooouuuusssseeee----ssssaaaavvvveeeedddd----ooooppppttttiiiioooonnnnssss Default: --nouse-saved-options This option is used in the _m_a_k_e and _m_a_k_e_i_n_s_t commands and tries to reuse a configuration from an already installed package. The algorithm seems to work for the most common versioning schemes of packages but may fail on more obscure ones. It should not happen that another package is taken, normally it should fail in a way that simply no configuration could be found. If you have any better ideas for the algorithm (see in function GetSavedOptionsFromOlderPackage) I'd love to receive patches :). Furthermore, if output isn't sur- pressed, stowES will wait three seconds before contin- uing so that you have a chance to check if the right options were taken. --------ddddeeeeppppeeeennnnddddssss,,,, --------nnnnooooddddeeeeppppeeeennnnddddssss Default: depends Do (or do not) create the the dependencies when installing a package. --------cccchhhheeeecccckkkkiiiinnnn,,,, --------nnnnoooocccchhhheeeecccckkkkiiiinnnn Default: checkin You may switch off the check in of a package when in command `makeinst' or `install'. --------cccchhhhkkkkcccchhhhkkkkssssuuuummmmssss,,,, --------nnnnoooocccchhhhkkkkcccchhhhkkkkssssuuuummmmssss Default: chkchksums Switch on or off the check of checksums. --------cccchhhheeeecccckkkkssssuuuummmmssss,,,, --------nnnnoooocccchhhheeeecccckkkkssssuuuummmmssss Default: checksums Switch on or off the creation of checksum when doing command `makeinst' or `install'. --------ssssttttrrrriiiipppp,,,, --------nnnnoooossssttttrrrriiiipppp Default: nostrip Switch on or off the call of the "strip"-program to strip a package. --------pppprrrroooogggg key=program Default: key==program (see `stowES config | grep ^%Progs`) Specify alternate programs. With this option you may specify alternative programs to be used by stowES. The Program-param may contain additional arguments (e.g. --prog foo='bla arg1 arg2'). For keys see %Progs in the config screen. --------pppprrrrmmmm----ccccoooonnnnffff regexp=param | param =item --------pppprrrrmmmm----mmmmaaaakkkkeeee reg- exp=param | param Default: none Specify extra parameters for the call of `configure' and `make'. The parameter is used when the regexp matches the package currently proceeded. When giving no regexp the parameters will be used for every call of `configure' or `make'. If you only specify a parameter which contains a '=' (e.g. CC=gcc) you have to proceed a '=' to avoid splitting up the parameter itself. Examples: Using one paramter: stowES ... --prm-conf --disable-static Using more than one: stowES ... --prm-conf '--enable-foo --enable-bar' Using a parameter with '=': stowES ... --prm-make==CC=gcc or stowES ... --prm-make =CC=gcc Use two (or more) params for one package with '=' in the options: stowES ... --prm-conf emacs="--with-dialogs=xy --dynamic=no" Use them for all packages: stowES ... --prm-conf ="--with-dialogs=xy --dynamic=no" ----rrrr,,,, --------rrrroooottttaaaattttiiiinnnnggggiiiinnnnssssttttaaaallllllll,,,, --------nnnnoooorrrroooottttaaaattttiiiinnnnggggiiiinnnnssssttttaaaallllllll Default: norotatinginstall Loop over the packages to install as long as possible. When specifying this option the packages given on the command line will be tried to install again and again until they can be compiled. If the remaining packages all fail within one run stowES will give up. This options only applies to the `install' command. That effictively means that you do not need to pay attention on the order of the packages given on the command line when installing packages. As you may imagine, this method will not work in all cases, there are several problems involved (e.g. fail- ing configures etc., maybe more later here on). But it is good for trying out a new bunch of software with the least possible waste of your energy :-). If it fails you can go the old way of installing things... See the examples entry elsewhere in this document for more. As already mentioned the options can be abbreviated to uniqueness. OOOOPPPPTTTTIIIIOOOONNNN HHHHAAAANNNNDDDDLLLLIIIINNNNGGGG There are three way to specify options for ssssttttoooowwwwEEEESSSS: o config file o environment variable o command line First the environment variable and the command line are checked for the `load config file'-option. Then the options in the config file are processed at first, then the options in the environment variable and at last the options on the command line. Config files are processed in the order they are given and config files given in the environment variable are processed before the config files given on the command line. _-_c-options given in a config file are not used (so, no recursion is possible here). The last options set is valid (overwriting the previously set ones). EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt----vvvvaaaarrrriiiiaaaabbbblllleeee ````SSSSTTTTOOOOWWWWEEEESSSS'''' You can specify an environment variable `STOWES' and store options in it in the same way you would do on the command line. These options are processed after the config-file was read and before the options on the command line. That means that options on the command line will override options given in the variable `STOWES' and in the config file. --------ssssttttoooowwwwddddiiiirrrr aaaannnndddd --------ttttaaaarrrrggggeeeettttddddiiiirrrr ooooppppttttiiiioooonnnnssss If you only use the "stowdir"-option, the target directory will be the parent directory of the stow directory. On the other hand, if you only specify the target directory, the stow directory will be "targetdir/stowname". StowDir and TargetDir options can only be used in pairs, i.e. a TargetDir or StowDir option will override both val- ues from a lower level (e.g. a _`_-_t_'-option on the command line will override a given _`_-_s_'-option set in a config or in the environment variable). Why? It happened to me that I had something like _"_-_t _/_t_m_p_/_f_" in my config file and specified something like _"_-_s _._" on the command line (forgetting what was in the config file) while working on some other packages. Since these option do not overwrite themselves ugly target- and stowdirs are used... CCCCoooonnnnffffiiiigggg ffffiiiilllleeeessss You may store any option you would write on the command line in a config file. These options are pushed before the arguments you gave on the command line, so you can over- write options given in a config file. Standard configs may be placed in "/usr/local/etc/stowESrc" and/or "~/.stowESrc". The system wide configuration file is read first. PPPPaaaacccckkkkaaaaggggeeee mmmmaaaattttcccchhhhiiiinnnngggg By default, commands which take regexps as params are only executed if they match exactly one package (this counts per regexp). This should help to avoid messing up your packages ("stowES remove glib" would remove more than just glib, at least on my system...). If you want to supply a command to more packages you may use the `m'-option. LLLLooooccccaaaalllleeee Currently locale information are only used to get the thousands seperator for figures. Nevertheless your locale environment should be properly set up. AAAAbbbbbbbbrrrreeeevvvviiiiaaaattttiiiioooonnnnssss The paramters may be abbreviated to uniqueness (see docs for GetOpt::Long.pm). The same applies for commands. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE ssssttttoooowwwwEEEESSSS return with 0 if operation was successful and with 1 otherwise. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Suppose you would like to install gnome... lots of work? Consider this: > cd /plenty/space; mkdir gnome; cd gnome > ncftpget ftp://ftp.gnome.org/pub/GNOME/stable/latest/sources/* > stowES install -r --removesource -t /some/space * Now have a cup of coffee or tea or make something else, this will take some time to finish. When your prompt reap- pears you should have gnome installed from source (with all the default options for each package taken). Now a bit smaller: > stowES install store/src/autoconf/autoconf-2.14.tar.gz will unpack, compile and install autoconf in /usr/local. If you have only autoconf installed a call of chkchksums may give this output. > stowES chkchksums -a Checking checksums for package autoconf-2.14...ok. Use this if you want to get rid of autoconf. > stowES remove autoconf Here you see that I have three packages matching "window" installed. Two of them a checked in and can be used. The WindowMaker-0.61.1 package is currently not checked in, it conflicts with some other package, so it can't even be checked in if wanted. > S ls window Listing packages in /usr/local/stow matching [ window ] (3 matches): - WindowMaker-0.61.1 (GNUstep/Apps/WPrefs.app/WPrefs) I WindowMaker-0.62.1 I WindowMaker-extra-0.1 AAAAUUUUTTTTHHHHOOOORRRR Adam Lackorzynski SSSSEEEEEEEE AAAALLLLSSSSOOOO _l_d_d(1), _s_t_o_w(1) 2004-01-08 0.5.2 STOWES(1)