Index: ossp-pkg/shtool/ChangeLog RCS File: /v/ossp/cvs/ossp-pkg/shtool/ChangeLog,v rcsdiff -q -kk '-r1.121' '-r1.122' -u '/v/ossp/cvs/ossp-pkg/shtool/ChangeLog,v' 2>/dev/null --- ChangeLog 2000/06/14 18:43:24 1.121 +++ ChangeLog 2000/06/14 19:01:26 1.122 @@ -10,6 +10,9 @@ ChangeLog Changes between 1.4.9 and 1.4.10 (16-Apr-2000 to xx-Jun-2000): + + *) Added Python support for `shtool version'. + [Benjamin Saller ] *) Fixed `here-document' handling in shtoolize: the whitespaces were incorrectly determined and so newlines were lost. Index: ossp-pkg/shtool/THANKS RCS File: /v/ossp/cvs/ossp-pkg/shtool/THANKS,v rcsdiff -q -kk '-r1.16' '-r1.17' -u '/v/ossp/cvs/ossp-pkg/shtool/THANKS,v' 2>/dev/null --- THANKS 2000/06/14 18:51:01 1.16 +++ THANKS 2000/06/14 19:01:26 1.17 @@ -20,6 +20,7 @@ o Jim Jagielski o Martin Kraemer o Markus F.X.J. Oberhumer + o Benjamin Saller o Sascha Schumann o Yitzchak Scott-Thoennes o Peter Simons Index: ossp-pkg/shtool/sh.version RCS File: /v/ossp/cvs/ossp-pkg/shtool/sh.version,v co -q -kk -p'1.21' '/v/ossp/cvs/ossp-pkg/shtool/sh.version,v' | diff -u /dev/null - -L'ossp-pkg/shtool/sh.version' 2>/dev/null --- ossp-pkg/shtool/sh.version +++ - 2024-05-14 20:44:23.948556796 +0200 @@ -0,0 +1,316 @@ +## +## version -- Generate and maintain a version information file +## Copyright (c) 1994-2000 Ralf S. Engelschall +## Originally written for ePerl +## +## This file is part of shtool and free software; you can redistribute +## it and/or modify it under the terms of the GNU General Public +## License as published by the Free Software Foundation; either version +## 2 of the License, or (at your option) any later version. +## +## This file 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 this program; if not, write to the Free Software +## Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, +## USA, or contact Ralf S. Engelschall . +## + +str_tool="version" +str_usage="[-l] [-n] [-p] [-s] [-i] [-d] " +arg_spec="1+" +opt_spec="l:n:p:s:i:d:" +opt_l="txt" +opt_n="unknown" +opt_p="unknown" +opt_s="unknown" +opt_i="P" +opt_d="NO" +gen_tmpfile=yes + +. ./sh.common + +LANGUAGE="$opt_l" +NAME="$opt_n" +PREFIX="$opt_p" +FULLVERSION="$opt_s" +INCREASE="$opt_i" +REPORT="$opt_d" +FILE="$1" + +# determine language +if [ ".$LANGUAGE" = .unknown ]; then + case $FILE in + *.txt ) LANGUAGE=txt ;; + *.c ) LANGUAGE=c ;; + *.pl | *.pm ) LANGUAGE=perl ;; + *.py) LANGUAGE=python ;; + * ) echo "$tool:Error: unknown language type" 1>&2; exit 1 ;; + esac +fi + +# determine prefix from name and vice versa +if [ ".$PREFIX" = . -o ".$PREFIX" = .unknown ]; then + if [ ".$NAME" != . -a ".$NAME" != .unknown ]; then + PREFIX="$NAME" + fi +fi +if [ ".$NAME" = . -o ".$NAME" = .unknown ]; then + if [ ".$PREFIX" != . -a ".$PREFIX" != .unknown ]; then + NAME="$PREFIX" + fi +fi + +# determine version +date=unknown +version=0 +revision=0 +bplevel=0 +if [ ".$FULLVERSION" = .unknown ]; then + if [ -r "$FILE" ]; then + # grep out current information + id=`grep 'Version [0-9]*.[0-9]*[.abps][0-9]* ([0-9]*-[a-zA-Z]*-[0-9]*)' $FILE | \ + head -1 | \ + sed -e 's%.*Version \([0-9]*\)\.\([0-9]*\)\([.abps]\)\([0-9]*\) (\([0-9]*-[a-zA-Z]*-[0-9]*\)).*%\1:\2:\3:\4:\5%'` + version=`echo $id | awk -F: '{ print $1 }'` + revision=`echo $id | awk -F: '{ print $2 }'` + bptype=`echo $id | awk -F: '{ print $3 }'` + bplevel=`echo $id | awk -F: '{ print $4 }'` + date=`echo $id | awk -F: '{ print $5 }'` + if [ .$REPORT = .NO ]; then + case $INCREASE in + b ) bplevel=`expr $bplevel + 1` + bptype=b + ;; + a ) bplevel=`expr $bplevel + 1` + bptype=a + ;; + s ) bplevel=`expr $bplevel + 1` + bptype=s + ;; + P ) bplevel=`expr $bplevel + 1` + bptype=. + ;; + p ) bplevel=`expr $bplevel + 1` + bptype=p + ;; + r ) revision=`expr $revision + 1` + bptype=. + bplevel=0 + ;; + v ) version=`expr $version + 1` + revision=0 + bptype=. + bplevel=0 + ;; + esac + date=calc + fi + FULLVERSION="$version.$revision$bptype$bplevel" + else + # intialise to first version + version=0 + revision=5 + bptype=b + bplevel=0 + date=calc + fi +else + # take given version + V=`echo $FULLVERSION | sed -e 's%\([0-9]*\)\.\([0-9]*\)\([.abps]\)\([0-9]*\).*%\1:\2:\3:\4%'` + version=`echo $V | awk -F: '{ print $1 }'` + revision=`echo $V | awk -F: '{ print $2 }'` + bptype=`echo $V | awk -F: '{ print $3 }'` + bplevel=`echo $V | awk -F: '{ print $4 }'` + date=calc +fi + +# determine hex value of version +case $FULLVERSION in + *.*a* ) + HEX=`echo "$FULLVERSION" | sed -e 's/a.*//' | awk -F. '{ printf("%d%02d", $1, $2); }' && + echo "$FULLVERSION" | sed -e 's/.*a//' | awk '{ printf("0%02d", $1); }'` + ;; + *.*b* ) + HEX=`echo "$FULLVERSION" | sed -e 's/b.*//' | awk -F. '{ printf("%d%02d", $1, $2); }' && + echo "$FULLVERSION" | sed -e 's/.*b//' | awk '{ printf("1%02d", $1); }'` + ;; + *.*.* ) + HEX=`echo "$FULLVERSION" | awk -F. '{ printf("%d%02d2%02d", $1, $2, $3); }'` + ;; +esac + +# determine libtool version +case $FULLVERSION in + *.*a* ) + LTV=`echo "$FULLVERSION" | sed -e 's/a.*//' | awk -F. '{ printf("%d:0", $1*10+$2); }'` + ;; + *.*b* ) + LTV=`echo "$FULLVERSION" | sed -e 's/b.*//' | awk -F. '{ printf("%d:0", $1*10+$2); }'` + ;; + *.*.* ) + LTV=`echo "$FULLVERSION" | awk -F. '{ printf("%d:%d", $1*10+$2, $3); }'` + ;; +esac + +# determine string out of filename +# (don't try to optimize this in any way - portability!) +FILESTR=`echo "$FILE" |\ + tr 'abcdefghijklmnopqrstuvwxyz./%+' \ + 'ABCDEFGHIJKLMNOPQRSTUVWXYZ____' | sed -e 's/-/_/g'` + +# determine date +if [ ".$date" = .calc ]; then + day=`date '+%d'` + month=`date '+%m'` + year=`date '+%Y' 2>/dev/null` + if [ ".$time_year" = . ]; then + year=`date '+%y'` + case $year in + [5-9][0-9]) year="19$year" ;; + [0-4][0-9]) year="20$year" ;; + esac + fi + case $month in + 1|01) month='Jan' ;; + 2|02) month='Feb' ;; + 3|03) month='Mar' ;; + 4|04) month='Apr' ;; + 5|05) month='May' ;; + 6|06) month='Jun' ;; + 7|07) month='Jul' ;; + 8|08) month='Aug' ;; + 9|09) month='Sep' ;; + 10) month='Oct' ;; + 11) month='Nov' ;; + 12) month='Dec' ;; + esac + date="${day}-${month}-${year}" +fi + +if [ .$REPORT != .NO ]; then + case $REPORT in + long ) + echo "$version.$revision$bptype$bplevel ($date)" + ;; + short ) + echo "$version.$revision$bptype$bplevel" + ;; + libtool ) + echo "$LTV" + ;; + hex ) + echo "0x$HEX" + ;; + esac + rm -f $tmpfile >/dev/null 2>&1 + exit 0 +fi + +# create the version file according the the selected language +echo "new version: $version.$revision$bptype$bplevel ($date)" +case $LANGUAGE in + txt ) + cat >$tmpfile <<'EOT' + + This is @NAME@, Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@) + +EOT + ;; + c ) + cat >$tmpfile <<'EOT' +/* +** @FILE@ -- Version Information +** [automatically generated and maintained by GNU shtool] +*/ + +#ifdef _AS_HEADER + +#ifndef _@FILESTR@ +#define _@FILESTR@ +#define @PREFIX@_VERSION 0x@HEX@ +extern const int @PREFIX@_Version; +extern const char @PREFIX@_VersionStr[]; +extern const char @PREFIX@_Hello[]; +extern const char @PREFIX@_GNUVersion[]; +extern const char @PREFIX@_WhatID[]; +extern const char @PREFIX@_RCSIdentID[]; +extern const char @PREFIX@_WebID[]; +extern const char @PREFIX@_PlainID[]; +#endif /* _@FILESTR@ */ + +#else + +const int @PREFIX@_Version = 0x@HEX@; +const char @PREFIX@_VersionStr[] = "@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)"; +const char @PREFIX@_Hello[] = "This is @NAME@, Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)"; +const char @PREFIX@_GNUVersion[] = "@NAME@ Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@"; +const char @PREFIX@_WhatID[] = "@(#)@NAME@ Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)"; +const char @PREFIX@_RCSIdentID[] = "$Id$"; +const char @PREFIX@_WebID[] = "@NAME@/@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@"; +const char @PREFIX@_PlainID[] = "@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@"; + +#endif + +EOT + ;; + perl ) + cat >$tmpfile <<'EOT' +## +## @FILE@ -- Version Information +## [automatically generated and maintained by GNU shtool] +## + +$@PREFIX@_Version = 0x@HEX@; +$@PREFIX@_VersionStr = "@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)"; +$@PREFIX@_Hello = "This is @NAME@, Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)"; +$@PREFIX@_GNUVersion = "@NAME@ Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@"; +$@PREFIX@_WhatID = "@(#)@NAME@ Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)"; +$@PREFIX@_RCSIdentID = "\$Id$/"; +$@PREFIX@_WebID = "@NAME@/@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@"; +$@PREFIX@_PlainID = "@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@"; + +1; +EOT + ;; + python ) + cat >$tmpfile <<'EOT' +## +## @FILE@ -- Version Information +## [automatically generated and maintained by GNU shtool] +## + +@PREFIX@_Version = 0x@HEX@ +@PREFIX@_VersionStr = "@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)" +@PREFIX@_Hello = "This is @NAME@, Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)" +@PREFIX@_GNUVersion = "@NAME@ Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@" +@PREFIX@_WhatID = "@(#)@NAME@ Version @VERSION@.@REVISION@@BPTYPE@@BPLEVEL@ (@DAY@-@MONTH@-@YEAR@)" +@PREFIX@_RCSIdentID = "$Id$" +@PREFIX@_WebID = "@NAME@/@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@" +@PREFIX@_PlainID = "@VERSION@.@REVISION@@BPTYPE@@BPLEVEL@" + +EOT + ;; +esac + +# now create the version file +rm -f $FILE >/dev/null 2>&1 +sed \ + -e "s|@FILE@|$FILE|g" \ + -e "s|@FILESTR@|$FILESTR|g" \ + -e "s|@PREFIX@|$PREFIX|g" \ + -e "s|@NAME@|$NAME|g" \ + -e "s|@HEX@|$HEX|g" \ + -e "s|@VERSION@|$version|g" \ + -e "s|@REVISION@|$revision|g" \ + -e "s|@BPTYPE@|$bptype|g" \ + -e "s|@BPLEVEL@|$bplevel|g" \ + -e "s|@YEAR@|$year|g" \ + -e "s|@MONTH@|$month|g" \ + -e "s|@DAY@|$day|g" <$tmpfile >$FILE +rm -f $tmpfile >/dev/null 2>&1 +exit 0 + Index: ossp-pkg/shtool/shtool.pod RCS File: /v/ossp/cvs/ossp-pkg/shtool/shtool.pod,v co -q -kk -p'1.41' '/v/ossp/cvs/ossp-pkg/shtool/shtool.pod,v' | diff -u /dev/null - -L'ossp-pkg/shtool/shtool.pod' 2>/dev/null --- ossp-pkg/shtool/shtool.pod +++ - 2024-05-14 20:44:23.951567933 +0200 @@ -0,0 +1,785 @@ +## +## shtool.pod -- Manual Page for shtool in POD format +## +## This file is part of shtool and free software; you can redistribute +## it and/or modify it under the terms of the GNU General Public +## License as published by the Free Software Foundation; either version +## 2 of the License, or (at your option) any later version. +## +## This file 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 this program; if not, write to the Free Software +## Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, +## USA, or contact Ralf S. Engelschall . +## + +=pod + +=head1 NAME + +B - The GNU Portable Shell Tool + +=head1 VERSION + +GNU shtool SHTOOL_VERSION_STR + +=head1 SYNOPSIS + +B +[ I ] +I +[ I ] +[ I ] + +=head1 DESCRIPTION + +B is a compilation of small but very stable and portable shell +scripts into a single shell tool. All ingredients were in successful use over +many years in various free software projects. The compiled B script is +intended to be used inside the source tree of those free software packages. +There it can take over various (usually non-portable) tasks related to the +building and installation of such packages. + +=head2 Context Background + +For the configuration, build and installation environment of modern free +software packages one nowadays uses GNU B and friends (i.e. +usually B, B and B). B covers the +configuration, B covers the generation of the build environment and +B covers most of a libraries build process. But at least when it +comes to the installation step one usually have to use a few auxiliary scripts +like C, C, etc. These scripts are usually replacements +for system tools and are required mainly for portability reasons. The result +is usually an C subdirectory in the source tree where over time a +lot shell scripts accumulate. + +=head2 Maintainance Problem + +The problem with those C shell scripts starts if one has to maintain +I of free software packages as it's the case for the author of B. +Then over time all C directories diverge and with every day it gets more +and more nasty to always keep them in sync. Especially if some scripts +were locally adjusted because no centralized maintainance location exists, of +course. For B no such problem exists, because the resulting +C script is generated on-the-fly. The same applies to B +and the various C files. + +Only for B one always has to grab the latest copy. But because it's +just two files (C and C), keeping a source trees in sync +is not too complicated (especially not if using the handy C +program). But the C shell script mess is nasty, especially because there +is no master version on the net. Additionally everytime one starts a new +project, one has to establish a new source tree. For a GNU hacker it's +immediately clear that B and friends are part of the game. But which +C shell scripts are needed this time? And from which existing source +tree to copy them from? Hmmm... the same procedure as last year?! + +=head2 The Aesthetic Problem + +When a free software package has a large source tree (say, more than 50 files +and especially with one or more subdirectories) it's usually no problem to +have an additional C subdirectory with some scripts. They then totally +go down. But for smaller packages, especially those living in a single source +directory (a degenerated tree), some people (like the author of B) +have aesthetic problems. Because it looks strange to them that 20% of the +files in the source tree are just auxiliary scripts. Sure, the actual amount +of script code even B cannot reduce, but B merges them +together into a single file and this way they optically totally disappear from +the source tree. + +This is a pure aesthetical issue, of course. But keep in mind that hacking is +a piece of art. And a well layouted source tree is a piece of art for real +hackers, too. Oh, and for those who really insist on a technical reason: it's +also easier to upgrade a single file than multiple files ;) + +=head2 Filling the gap + +So, wouldn't it be nice to have a fourth package (beside B, +B and B) which fills the gap, i.e. which provides the +functionality of the old files in C, is maintained at a centralized +location and even consists of just a single (perhaps large) script one can +threat as a black box the same way one already does this for B? The +author thought this I be actually very useful and the result is the +current GNU B package which at least successfully solved the above +problems of the author. + +=head2 The goals in detail + +To better understand the intentions behind B and to avoid confusion, +here are the original goals of the B script: + +=over 3 + +=item B<1. It has to be self-contained and reside in a single file> + +This was achieved by compiling the resulting B script out of the +ingredient source scripts. The advantage is that B is still easily +maintainable, because one can test each script separately. But the final +functionality then resides in an all-in-one script which can be easily spread +over multiple source trees. + +=item B<2. It has to cover all functionality of the old scripts> + +This was achieved by (re)implementing really all functionality which +experience showed is important in source trees of typical free software +packages. + +=item B<3. It has to be maximum portable over all Unix flavors> + +This was achieved by basing the ingredient shell scripts only on well-proven +code which already survived practice in other projects over more than a few +months. Especially this means that a lot of complicated emulations are done to +avoid the use of unportable Unix programs (like C, C, etc) or +unportable features of well-known Unix programs (like shell functions, special +C features, etc. pp). That's why B's code sometimes looks crazy +and like overkill to you. Don't think this is because of the authors +crazyness. Instead it's most of the time mainly for portability reasons. + +=item B<4. It has to be clean and fully documented> + +This was achieved by reimplementing too ugly functionality from scratch and +cleaning up old shell script code plus writing this complete manual page. + +=item B<5. It has to stay under a reasonable and common license> + +This was achieved by placing the B package under the GNU General +Public License (GPL). This way the B package itself is well protected +and is guarrantied to be kept free software, but the resulting B +script can be nevertheless I in I types of source trees. Notice +here: given that one includes GNU B verbatim into an own source tree, +one is justified in saying that it remains separate from the own package, and +that this way one is simply just I B. So, in this situation, +there is no requirement that the package itself is licensed under the GNU +General Public License in order to take advantage of B. Keep this in +mind ;) + +=item B<6. It has to be modularized for flexibility reasons> + +This was achieved by using an auxiliary tool shtoolize(1) which can be used to +build individual C scripts out of the ingredient shell scripts. This +way if one don't need all the available functionality one can assemble +together an individual C script. + +=back + +=head1 GLOBAL OPTIONS + +The following I are available for B. Any Is +are ignored if one of them is present on the B command line. + +=over 4 + +=item B<-h>, B<--help> + +Displays a short help page describing the usage of B and it's +ingredient Is in a compact way. + +=item B<-v>, B<--version> + +Displays the version number of B. + +=item B<-d>, B<--debug> + +Displays shell trace messages for debugging purposes. + +=back + +=head1 COMMANDS + +The following Is are provided by B. They are all called via +``C I''. Any trailing I are specific to the +particular I. They are listed (here and also below) sorted by topic, +i.e. related commands are listed side-by-side. + +=over 12 + +=item B + +echo(1) style print command providing special expansion constructs (terminal +bold mode, environment details, date) and newline control. + +=item B + +Pretty-prints the last modification time of a file or directory. + +=item B + +Pretty-prints a field-sperarated list as a table. + +=item B + +Display a processing indication though a running propeller. + +=item B + +mv(1) style command, but can rename/move multiple files at once and allows +source files just to be deleted if contents didn't change. + +=item B + +Install a program, script or datafile in a portable way. + +=item B + +mkdir(1) style command providing support for auto-parent-dir creation, +directory permission control and smart skipping if directory already +exists. + +=item B + +ln(1) style command providing automatic calculation and usage of relative +links if possible. + +=item B + +Create a shadow source tree by the help of symbolic links. + +=item B + +Fix file permissions inside a source tree by cleaning up the permission bits. + +=item B + +Roll standardized distribution tarballs. + +=item B + +Simple operating system and platform architecture guesser which +determines a GNU I style identification string. + +=item B + +Extended archive command which can even put existing archives into an archive. + +=item B + +Separate linker options by library class. + +=item B + +An additional C source file pre-processor for sharing cpp(1) code, internal +variables and internal functions. + +=item B + +Generate and maintain a version information file in either text, C or Perl +format. + +=item B + +Deal with shell path variables. + +=back + +=head1 COMMAND DESCRIPTION + +In the following the available I and their corresponding +I are described in detail. + +=over 4 + +=item B [B<-n>] [B<-e>] I + +This is an echo(1) style print command which provides special expansion +constructs (terminal bold mode, environment details, date) and newline +control. Per default I is written to I followed by a newline +character (``C<\n>''). When option ``B<-n>'' is used this newline character is +left out. + +The I can contain special ``B<%>I'' constructs which which are +expanded before the output is written if option ``B<-e>'' is used. +Currently the following constructs are recognized: ``B<%B>'' for switching to +terminal bold mode, ``B<%b>'' for switching terminal mode back to normal +display mode, ``B<%u>'' for the current user name, ``B<%U>'' for the current +user id (numerical), ``B<%h>'' for the current hostname, ``B<%d>'' for the +current domain name, ``B<%D>'' for the current day of the month, ``B<%M>'' for +the current month (numerical), ``B<%m>'' for the current month name and +``B<%Y>'' for the current year. + +The trick of this command is that it provides a portable ``B<-n>'' option and +hides the gory details needed to find out the environment details. + +Examples: + + # shell script + shtool echo -n -e "Enter your name [%B%u%b]: "; read name + shtool echo -e "Your Email address might be %u@%h%d" + shtool echo -e "The current date is %D-%m-%Y" + +=item B [B<-n>] [B<-z>] [B<-s>] [B<-d>] [B<-f> I] [B<-o> I] I + +This command pretty-prints the last modification time of a file or directory +I. Option ``B<-n>'' suppresses the output of a trailing newline +character, option ``B<-z>'' pads numeric day (and optionally month) with a +leading zero, option ``B<-s>'' shortens the months name to an abbreviation of +three characters, option ``B<-d>'' replaces the month name with the +corresponding digits, option ``B<-f>'' uses I as the field separator +(default is a single space character) and option ``B<-o>'' specified the order +in which the fields are printed. + +The default for I is ``C'' which means an output of `` +''. Any combination of the chars ``C'', ``C'' and ``C'' or +allowed for I. + +The trick of this command is that it provides a portable way to find out the +date of a file or directory while still allowing one to specify the format of +the date display. + +Examples: + + # shell script + shtool mdate -n / + shtool mdate -f '/' -z -d -o ymd foo.txt + shtool mdate -f '-' -s foo.txt + +=item B
[B<-F> I] [B<-w> I] [B<-c> I] [B<-s> I] IBI... + +This pretty-prints a I-sperarated list of Iings as a table. Per +default a colon-separated list (I=":") is pretty printed as a +three-column (=3) table no longer than 79 chars (I=79) is +generated where each column is 15 characters wide (I=15). + +The trick of this command is that it avoids to use the unportable tr(1) and +fmt(1) commands and instead is based entirely on sh(1), awk(1) and sed(1) +functionality. + +Example: + + # shell script + shtool table -F , -w 5 -c 4 "1,2,3,4,5,6,7,8,9,10,11,12" + +=item B [B<-p> I] + +This command displays a processing indication though a running propeller. The +option ``B<-p>'' can be used to set a particular prefix I which is +displayed in front of the propeller. The default is no prefix string, i.e. the +propeller is at the left border of the terminal. This command is intended to +be run at the end of a pipe (``C<|>'') sequence where on C +logging/processing informations found. For every line on C the +propeller cycles one step clock-wise. + +The trick of this command is that it provides a portable and easy to use way +to display such nice and psychologically important process indicators. + +Example: + + # shell script + configure 2>&1 |\ + tee logfile |\ + shtool prop -p "Configuring sources" + +=item B [-v] [-t] [-e] [-p] I I + +This is a mv(1) style command, but with two special features: First if +option ``B<-e>'' (`expand') is used and an asterisk occurs somewhere in I +one can use ``C<%>I'' (where I is C<1>,C<2>,...) in I. This is +useful for renaming multiple files at once. Second, if option ``B<-p>'' +(for `preserve') is used and I and I are byte-wise the +same it just deletes I. The intention is that the permissions and +time stamps on I are't changed which is important if I is +used in conjunction with Makefiles. Option ``B<-v>'' (verbose) can be used to +enable the output of extra processing information. Option ``B<-t>'' (trace) +can be used to enable the output of the essential shell commands which are +executed. + +The trick of this command is that it can rename multiple files at once and +preserves the timestamps if the contents isn't changed. + +Examples: + + # shell script + shtool move -v -e *.txt %1.asc + + # Makefile + scanner.c: scanner.l + lex scanner.l + shtool move -t -p lex.yy.c scanner.c + +=item B [B<-v>] [B<-t>] [B<-c>] [B<-C>] [B<-s>] [B<-m> I] [B<-o> I] [B<-g> I] [B<-e> I] I I + +This command installs a program, script or datafile (dependent on I) in +a portable way while providing all important options of the BSD install(1) +command. Per default I is moved to the target I, but with option +``B<-c>'' I is copied. The target file is created with owner/group set +to the current active uid/gid, but if this script is called as root (uid 0) +the options ``B<-o>'' and ``B<-g>'' can be used to override this. + +Additionally program executables is stripped with strip(1) after installation +if option ``B<-s>'' is used. Option ``B<-C>'' is like ``B<-c>'', except if +the destination file already exists and the files are the same, the source is +just removed. Option ``B<-e>'' can be used to set an implicit executable +extension. Option ``B<-v>'' (verbose) can be used to enable the output of +extra processing information. Option ``B<-t>'' (trace) can be used to enable +the output of the essential shell commands which are executed. + +The trick of this command is that it provides the functionality of BSD +install(1) in a portable emulated way. + +Example: + + # Makefile + install: + : + shtool install -c -s -m 4755 foo $(bindir)/ + shtool install -c -m 644 foo.man $(mandir)/man1/foo.1 + +=item B [B<-t>] [B<-f>] [B<-p>] [B<-m> I] I [I ...] + +This is a mkdir(1) style command providing support for auto-parent-dir +creation (if option ``B<-p>'' is used), directory permission control (with +option ``B<-m> I'' where I can be in any of the formats specified +to the chmod(1) command) and smart skipping if I already exists +(triggered by the force option ``B<-f>''). Option ``B<-t>'' (trace) can be +used to enable the output of the essential shell commands which are executed. + +The trick of this command is that it provides both a portable ``B<-p>'' +functionality and the ability to be smart if the directory already exists +which is important for installation procedures. + +Example: + + # Makefile + install: + shtool mkdir -f -p -m 755 $(bindir) + shtool mkdir -f -p -m 755 $(mandir)/man1 + : + +=item B [B<-t>] [B<-f>] [B<-s>] I [I ...] I + +This is a ln(1) style command which provides automatic calculation and usage +of relative links if possible, i.e. usually if I and I +are not absolute paths or at least they share a common prefix except the root +directory (``C''). When more than one I is specified, all of them +are linked into I. Options ``B<-f>'' and ``B<-s>'' are similar to +ln(1), i.e. they force the creation of the link (even if it exists) and +create a symbolic link instead of a hard-link. Option ``B<-t>'' (trace) can +be used to enable the output of the essential ``C'' command which is +executed. + +The trick of this command is that it tried hard to calculate the paths to get +the maximum possible relative paths. + +Example: + + # shell script + shtool mkln -s foo/bar baz/quux + +=item B [B<-v>] [B<-t>] [B<-a>] I I + +This command creates a shadow tree of I under I by +recreating the directory hierarchy of I under I and by +creating the files of I by linking them into the corresponding +directories under I via symbolic links. When I can be +reached via relative paths from I, relative symbolic links are used, +too. + +Option ``B<-v>'' (verbose) can be used to enable some displaying of processing +information. Option ``B<-t>'' (trace) can be used to display all commands +which are executed in order to construct I. Option ``B<-a>'' (all) +can be used to really shadow all files and directories in I. Per +default CVS related files and directories, backup files, object files, etc. +are not shadowed. + +The trick of this is that is provides such a high-level functionality with a +single command and hides all gory details. + +Example: + + # shell script + shtool mkshadow -v -a . /tmp/shadow + +=item B [B<-v>] [B<-t>] I [ I ... ] + +This command fixes file permissions inside a source tree under I by +cleaning up the permission bits. It determines the cleaned up permission from +the already set bits. It's intended to be run before a tarball is rolled out +of the source tree. Option ``B<-v>'' can be used to display some processing +information. Option ``B<-t>'' (trace) can be used to enable the output of the +essential shell commands which are executed. + +The trick is that this is more convinient that having to set the permissions +manually or with a large file list. + +Example: + + # Makefile.in + dist: + shtool fixperm -v * + ... + +=item B [B<-t>] [B<-v>] [B<-o> I] [B<-c> I] [B<-u> I] [B<-g> I] [B<-e> I] I [I ...] + +This command is for `rolling' distribution `tarballs', i.e. for the creation +of distribution files generated by `C'. The important aspects of +standardized free software tarballs are: first they have to unpack into a +single top-level directory; second this top-level directory should correspond +to the tarball filename (i.e. a tarball `C' per convention +unpacks into a top-level directory `C'); third the files in +the tarball should be sorted to allow users to use the `C' command +in a reasonable way; fourth the owner and group of the files in the tarball +for security reasons can be set to arbitrary names. + +The input files are given by the file or directory arguments I. +Directories are expanded before the comma-separated exclude (option B<-e>) +Is (B regular expressions) are used to filter the list. The +default filter is ``C''. Then the tarball is +created with its files owned by I (option B<-u>) and I (option +B<-g>). Finally the resulting tarball is piped through an optional compression +(option B<-c>) program and written to the output file I (option +B<-o>). Option ``B<-v>'' can be used to display the files which are stored in +the tarball. Option ``B<-t>'' (trace) can be used to enable the output of the +essential shell commands which are executed. + +The trick of this command is that it combines the complex process of rolling a +good tarball into a I command. + +Example: + + # Makefile.in + dist: + ... + V=`shtool version -d short ...'; \ + shtool tarball -o foobar-$$V.tar.gz -c 'gzip -9' \ + -u bar -g gnu -e 'CVS,\.cvsignore' . + +=item B + +This command is a simple operating system and platform architecture guesser +which determines a so-called ``GNU I'' style identification +string ``I-I-II''. For instance a FreeBSD 3.1 +running on a Pentium II is identified as ``C''. When you +need a more sophisticated platform guesser, use the GNU +C/C scripts, please. + + # configure.in + OS=`shtool guessos` + +=item B [B<-t>] [B<-C> I] I I I [I ...] + +This is a wrapper around the archive (``C'') tool. It provides the ability +to create archives out of existing archives, i.e. if one of I matches +``C<*.a>'' the archive member files of I are used instead of I +itself. When option ``B<-t>'' (trace) is given B shows the actually +involved shell commands. Option ``B<-C>'' can be used to set the ``ar'' +command to I. + +The trick of this command is the automatic handling of archive members which +is especially interesting if one wants to construct a (usually top-level) +library archive out of pre-build sub-library archives (usually staying inside +subdirs) in a large source tree. + +Example: + + # Makefile + AR=ar + RANLIB=ranlib + : + OBJS=foo.o bar.o + LIBS=baz/libbaz.a quux/libquux.a + : + libfoo.a: $(OBJS) $(LIBS) + shtool arx -C $(AR) rc libfoo.a $(OBJS) $(LIBS) + $(RANLIB) libfoo.a + +=item B [B<-p> I] -- B<-L>I B<-l>I [ B<-L>I B<-l>I ... ] + +This command separates the linker options ``B<-L>'' and ``B<-l>'' by library +class. It's argument line can actually be an abitrary command line where those +options are contained. B parses these two options only and ignores the +remaining contents. The result is a trivial shell script on C which +defines six variables containing the ``B<-L>'' and ``B<-l>'' options sorted by +class: + +``C'' and ``C'' contains the ``B<-L>'' and +``B<-l>'' options of static libraries, ``C'' and +``C'' contains the ``B<-L>'' and ``B<-l>'' options of static +libraries containing PIC ("Position Independent Code") and +``C'' and ``C'' contains the ``B<-L>'' and +``B<-l>'' options of shared libraries. The B<-p> option can be used to +change the default variable prefix from "C" to I. + +The intent of this separation is to provide a way between static and shared +libraries which is important if one wants to link custom DSOs against +libraries, because not all platforms all one to link these DSOs against shared +libraries. So one first has to separate out the shared libraries and link the +DSO only against the static libraries. One can use this command also to just +sort the options. + +Example: + + # configure.in + LINK_STD="$LDFLAGS $LIBS" + eval `shtool slo $LINK_STD` + LINK_DSO="$SLO_DIRS_OBJ $SLO_LIBS_OBJ $SLO_DIRS_PIC $SLO_LIBS_PIC" + : + +=item B [B<-v>] [B<-p>] [B<-f>] I] [B<-o> I] [B<-t> I] [B<-M> I] [B<-D> I] [B<-C> I] I [I ...] + +This command is an additional ANSI C source file pre-processor for sharing +cpp(1) code segments, internal variables and internal functions. The intention +for this comes from writing libraries in ANSI C. Here a common shared internal +header file is usually used for sharing information between the library +source files. + +The operation is to parse special constructs in Is, generate a few +things out of these constructs and insert them at position I in I +by writing the output to I. Additionally the Is are never touched +or modified. Instead the constructs are removed later by the cpp(1) phase of +the build process. The only prerequisite is that every I has a +``C<#include ">IC<">'' at the top. + +This command provides the following features: First it avoids namespace +pollution and reduces prototyping efforts for internal symbols by recognizing +functions and variables which are defined with the storage class identifier +``I''. For instance if I is ``intern'', a function ``C'' in one of the Is is translated into both a +``C<#define foobar __foobar>'' and a ``C'' in +I. Additionally a global ``C<#define> I C'' is also +created in I to let the compiler silently ignore this additional +storage class identifier. + +Second, the library source files usually want to share Cs, +C<#define>s, etc. over the source file boundaries. To achieve this one can +either place this stuff manually into I or use the second feature of +B: All code in Is encapsulated with ``C<#if >I ... +C<#endif>'' is automatically copied to I. Additionally a global +``C<#define> I C<0>'' is also created in I to let the compiler +silently skip this parts (because it was already found in the header). + +Option ``B<-v>'' can be used to enable some processing output. Option +``B<-p>'' can be used to make the decision whether to overwrite I +independent of the generated ``#line'' lines. This is useful for +Makefiles if the real contents of I will not change, just +line numbers. Option ``B<-f>'' (which can occur multiple times) can +be used to apply one or more pre-processing sed(1) I commands +(usually of type ``C'') to each input file before their +input is parsed. + +Example: + + # Makefile + SRCS=foo_bar.c foo_quux.c + foo_p.h: foo_p.h.in + shtool scpp -o foo_p.h -t foo_p.h.in \ + -M %%MARK%% -D cpp -C intern $(SRCS) + + /* foo_p.h.in */ + #ifndef FOO_P_H + #define FOO_P_H + %%MARK%% + #endif /* FOO_P_H */ + + /* foo_bar.c */ + #include "foo_p.h" + #if cpp + #define OURS_INIT 4711 + #endif + intern int ours; + static int myone = 0815; + intern int bar(void) + { + ours += myone; + } + + /* foo_quux.c */ + #include "foo_p.h" + int main(int argc, char *argv[]) + { + int i; + ours = OURS_INIT + for (i = 0; i < 10; i++) { + bar(); + printf("ours now %d\n", ours); + } + return 0; + } + +=item B [B<-l> I] [B<-n> I] [B<-p> I] [B<-s> I] [B<-i> I] [B<-d> I] I + +This command generates and maintains a version information file I +for program name I in either textual (I="C"), ANSI +C (I="c", Perl (I="perl") or Python (I="python") +language. The version is always described with a triple +EI,I,IE and is +represented by a string which always matches the regular expression +``C<[0-9]+\.[0-9]+[.abps][0-9]+>''. When the option ``B<-s>'' is given, +the contents of I is overridden with the specified I. + +When option ``B<-i>'' is used the version ingredients in I are updated +by adjusting one I of the version where I can be one of the +following: ``C'', ``C'', ``C

'', ``C

'' and ``C'' just increase +the alpha/beta/patch/snap level by 1 (and set the separator character between +version and the level position). ``C'' increases the revision by 1 and sets +the alpha/beta/patch/snap level to 0. ``C'' increases the version by 1 and +sets both the revision and alpha/beta/patch/snap level to 0. + +When option ``B<-d>'' is given the current version in I is displayed +either in short (I="short") or long (I="long") texual format or in +a format suitable for use with GNU libtool (I="libtool") or in a +hexadecimal format (I="hex"). + +When no option is given at all, ``C<-i P>'' is assumed. + +Example: + + # shell script + shtool version -l c -n FooBar -p foobar -s 1.2b3 version.c + + # configure.in + V=`shtool version -l c -d long version.c` + echo "Configuring FooBar, Version $V" + +=item B [B<-s>] [B<-r>] [B<-d>] [B<-b>] [B<-m>] [-p I] I [I ...] + +This command deals with shell C<$PATH> variables. It can find a program +executable in $PATH or I through one or more filenames (given by one or +more I arguments). The result is the absolute filesystem path to the +program displayed on C plus an exit code of 0 if it was really +found. + +The option ``B<-s>'' can be used to suppress the output which is useful to +just test whether a program exists with the help of the return code. The +option ``B<-m>'' enables some magic where currently for the programs +``C'' and ``C'' an advanced magic search is done. The option +``B<-r>'' can be used to transform a forward path to a subdirectory into a +reverse path. Option ``B<-d>'' and ``B<-b>'' just output the directory or base +name of I. + +Examples: + + # shell script + awk=`shtool path -p "${PATH}:." gawk nawk awk` + perl=`shtool path -m perl5 perl` + cpp=`shtool path -m cpp` + revpath=`shtool path -r path/to/subdir` + +=back + +=head1 SEE ALSO + +sh(1), cp(1), rm(1), mkdir(1), awk(1), sed(1). + +=head1 HISTORY + +Some scripts contained in B were already written in 1994 by I for use inside some private source trees. Then they evolved +into more elaborated versions over the years and were used in various free +software projects like ePerl, WML, iSelect, gFONT, etc. They were complemented +with other scripts from the author which he wrote in March 1998 for the +``Apache Autoconf-style Interface'' (APACI). In April 1999 the B +package was created out of the accumulated master versions of the scripts and +in June 1999 it entered the status of an official GNU program and this way +finally joined the group of B, B and B. + +=head1 AUTHOR + + Ralf S. Engelschall + rse@engelschall.com + www.engelschall.com + +=cut +