.rn '' }`
''' $RCSfile: shtool.1,v $$Revision: 1.1 $$Date: Thu, 23 Feb 2006 14:13:22 -0800 $
'''
''' $Log: shtool.1,v $
''' Revision 1.1.1.1  1999/11/20 21:55:28  lindig
''' imported
'''
''' Revision 1.2  1999/07/24 19:22:15  lindig
'''
'''
''' D: Makefile Makefile.ocaml - now generated by Autoconf
''' A: *.in install-sh for GNU autoconf support
''' A: etc/shtool for portable make install
'''
''' Revision 1.1.2.1  1999/07/18 11:34:54  lindig
'''
'''
''' A: Configuation with GNU autoconf added
''' D: Makefile and Makefile.in are now generated from *.in files through autoconf
''' A: shtool for porable shell operations
'''
''' Revision 1.1  1999/07/18 08:08:30  lindig
'''
'''
''' A: GNU Shtool for portable shell operations
'''
'''
.de Sh
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb
.ft CW
.nf
.ne \\$1
..
.de Ve
.ft R

.fi
..
'''
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Bell System Logo is used as a dummy character.
'''
.tr \(*W-|\(bv\*(Tr
.ie n \{\
.ds -- \(*W-
.ds PI pi
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
'''   \*(L" and \*(R", except that they are used on ".xx" lines,
'''   such as .IP and .SH, which do another additional levels of
'''   double-quote interpretation
.ds M" """
.ds S" """
.ds N" """""
.ds T" """""
.ds L' '
.ds R' '
.ds M' '
.ds S' '
.ds N' '
.ds T' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds M" ``
.ds S" ''
.ds N" ``
.ds T" ''
.ds L' `
.ds R' '
.ds M' `
.ds S' '
.ds N' `
.ds T' '
.ds PI \(*p
'br\}
.\"	If the F register is turned on, we'll generate
.\"	index entries out stderr for the following things:
.\"		TH	Title 
.\"		SH	Header
.\"		Sh	Subsection 
.\"		Ip	Item
.\"		X<>	Xref  (embedded
.\"	Of course, you have to process the output yourself
.\"	in some meaninful fashion.
.if \nF \{
.de IX
.tm Index:\\$1\t\\n%\t"\\$2"
..
.nr % 0
.rr F
.\}
.TH shtool 3 "02-Jul-1999" "shtool 1.4.0" "GNU Portable Shell Tool"
.UC
.if n .hy 0
.if n .na
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ          \" put $1 in typewriter font
.ft CW
'if n "\c
'if t \\&\\$1\c
'if n \\&\\$1\c
'if n \&"
\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
'.ft R
..
.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
.	\" AM - accent mark definitions
.bd B 3
.	\" fudge factors for nroff and troff
.if n \{\
.	ds #H 0
.	ds #V .8m
.	ds #F .3m
.	ds #[ \f1
.	ds #] \fP
.\}
.if t \{\
.	ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.	ds #V .6m
.	ds #F 0
.	ds #[ \&
.	ds #] \&
.\}
.	\" simple accents for nroff and troff
.if n \{\
.	ds ' \&
.	ds ` \&
.	ds ^ \&
.	ds , \&
.	ds ~ ~
.	ds ? ?
.	ds ! !
.	ds /
.	ds q
.\}
.if t \{\
.	ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.	ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.	ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.	ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.	ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.	ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
.\}
.	\" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.ds oe o\h'-(\w'o'u*4/10)'e
.ds Oe O\h'-(\w'O'u*4/10)'E
.	\" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.	\" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.	ds : e
.	ds 8 ss
.	ds v \h'-1'\o'\(aa\(ga'
.	ds _ \h'-1'^
.	ds . \h'-1'.
.	ds 3 3
.	ds o a
.	ds d- d\h'-1'\(ga
.	ds D- D\h'-1'\(hy
.	ds th \o'bp'
.	ds Th \o'LP'
.	ds ae ae
.	ds Ae AE
.	ds oe oe
.	ds Oe OE
.\}
.rm #[ #] #H #V #F C
.SH "NAME"
\fBGNU shtool\fR \- The GNU Portable Shell Tool
.SH "VERSION"
1.4.0 (02-Jul-1999)
.SH "SYNOPSIS"
\fBshtool\fR 
[ \fIglobal_options\fR ] 
\fIcommand\fR 
[ \fIcommand_options\fR ] 
[ \fIcommand_args\fR ]
.SH "DESCRIPTION"
The \fBGNU shtool\fR program 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 \fBshtool\fR program 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.
.Sh "Context Background"
For the configuration, build and installation environment of modern free
software packages one nowadays uses \s-1GNU\s0 \fBautoconf\fR and friends (i.e.
usually \fBautoconf\fR, \fBautomake\fR and \fBlibtool\fR). \fBAutoconf\fR covers the
configuration, \fBautomake\fR covers the generation of the build environment and
\fBlibtool\fR covers most of the build process itself. But at least when it comes
to the installation step one usually have to use a few auxiliary scripts like
\f(CWmkdir.sh\fR, \f(CWinstall.sh\fR, etc.  And these things are usually all the time
needed. The result is usually an \f(CWetc/\fR subdirectory in the source tree where
over time a lot shell scripts accumulate.
.Sh "Maintainance Problem"
The problem with those \f(CWetc/\fR shell scripts starts when one has to maintain
\fIlots\fR of free software packages as it's the case for the author of \fBshtool\fR.
Then over time all \f(CWetc/\fR directories diverge and with every day it gets more
and more nasty to always keep them in sync. Especially when some scripts
were locally adjusted because no centralized maintainance location exists, of
course. For \fBautoconf\fR no such problem exists, because the resulting
\f(CWconfigure\fR script is generated on-the-fly. The same applies to \fBautomake\fR
and the various \f(CWMakefiles\fR. 
.PP
Only for \fBlibtool\fR one always has to grab the latest copy. But because it's
just two files (\f(CWltmain.sh\fR and \f(CWltconfig\fR), keeping a source trees in sync
is not too complicated (especially not when using \f(CWlibtoolize\fR). But the
\f(CWetc/\fR 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 hacker it's immediately clear that
\fBautoconf\fR and friends are part of the game. But which \f(CWetc/\fR shell scripts
are needed this time? And from which existing source tree to copy them from?
Hmmm...
.Sh "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 \f(CWetc/\fR 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 \fBshtool\fR 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 \fBshtool\fR cannot reduce, but \fBshtool\fR merges them together into a
single file and this way they optically totally disappear from the source
tree. 
.PP
This is a pure aesthetical issue, of course. But hey, hacking is a piece of
art. And a source tree is a piece of art for hackers, too.  Oh, and those who
insist on a technical reason: it's also easier to upgrade a single file than
multiple files ;)
.Sh "Filling the gap"
So, wouldn't it be nice to have a fourth package (beside \fBautoconf\fR,
\fBautomake\fR and \fBlibtool\fR) which fills the gap, i.e.  which provides the
functionality of the old files in \f(CWetc/\fR, is maintained externally and at a
centralized location and even consists of just a single (perhaps large) script
one can overtake as a black box the same way one already does this for
\fBlibtool\fR? The author thought this \fIwould\fR be actually very useful and the
result is the current \fBshtool\fR package which at least successfully solved the
above problems of the author.
.Sh "The goals in detail"
To better understand the intentions behind \fBshtool\fR, here are the original
goals of the \fBshtool\fR script: 
.Ip "\fB1. It has to be self-contained and reside in a single file\fR" 3
This was achieved by compiling the resulting \fBshtool\fR script out of the
ingredient source scripts. The advantage is that \fBshtool\fR is still easily
maintainable, because one can test each script seperately. But the final
functionality then resides in an all-in-one script which can be easily spread
over multiple source trees.
.Ip "\fB2. It has to cover all functionality of the old scripts\fR" 3
This was achieved by (re)implementing really all functionality which
experience showed is important in source trees of typical free software
packages.  
.Ip "\fB3. It has to be maximum portable over all Unix flavors\fR" 3
This was achieved by using only well-proven shell 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 \f(CWfmt\fR, \f(CWtr\fR, etc) or unportable features of well-known
Unix programs (like shell functions, special \f(CWsed\fR features, etc. pp).
That's why \fBshtool\fR's code sometimes looks crazy and like overkill.  But it's
often this way mainly for portability reasons.
.Ip "\fB4. It has to be clean and fully documented\fR" 3
This was achieved by reimplementing too ugly functionality from scratch and
cleaning up old shell script code plus writing this manual page.  
.Ip "\fB5. It has to stay under a reasonable and common license\fR" 3
This was achieved by placing the \fBshtool\fR package under the \s-1GNU\s0 General
Public License (\s-1GPL\s0).  This way the \fBshtool\fR package itself is well protected
and will always be free software, but the resulting \fBshtool\fR script can be
nevertheless \fIused\fR in \fIall\fR types of source trees.  Notice here: given that
one includes \s-1GNU\s0 \fBshtool\fR 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 \fIusing\fR \fBshtool\fR.  So, in this situation, there is no
requirement that the package itself is licensed under the \s-1GNU\s0 General Public
License in order to take advantage of \fBshtool\fR. Keep this in mind ;)
.SH "GLOBAL OPTIONS"
The following \fIglobal options\fR are available for \fBshtool\fR. Any \fIcommand\fRs
are ignored when one of them is present on the \fBshtool\fR command line.
.Ip "\fB\-h\fR" 4
Displays a short help page describing the usage of \fBshtool\fR and it's
ingredient \fIcommand\fRs in a compact way.
.Ip "\fB\-v\fR" 4
Displays the version number of \fBshtool\fR.
.SH "COMMANDS"
The following \fIcommand\fRs are provided by \fBshtool\fR. They are all called via
``\f(CWshtool\fR \fIcommand\fR'\*(R'. Any trailing \fIcommand_options\fR are specific to the
particular \fIcommand\fR. 
.Ip "\fBecho\fR" 12
\fIecho\fR\|(1) style print command providing special expansion constructs (terminal
bold mode, environment details, date) and newline control.
.Ip "\fBmdate\fR" 12
Pretty-prints the last modification time of a file or directory.
.Ip "\fBtable\fR" 12
Pretty-print a field-sperarated list as a table.
.Ip "\fBprop\fR " 12
Display a processing indication though a running propeller.
.Ip "\fBmove\fR" 12
\fImv\fR\|(1) style command, but can rename/move multiple files at once and allows
source files just to be deleted when contents doesn't change.
.Ip "\fBinstall\fR" 12
Install a program, script or datafile in a portable way.
.Ip "\fBmkdir\fR" 12
\fImkdir\fR\|(1) style command providing support for auto-parent-dir creation,
directory permission control and smart skipping when directory already
exists.
.Ip "\fBmkln\fR" 12
\fIln\fR\|(1) style command providing automatic calculation and usage of relative
links when possible.
.Ip "\fBmkshadow\fR" 12
Create a shadow source tree by the help of symbolic links.
.Ip "\fBfixperm\fR" 12
Fix file permissions inside a source tree by cleaning up the permission bits.
.Ip "\fBguessos\fR" 12
Simple operating system and platform architecture guesser which
determines a \s-1GNU\s0 \fIplatform-triple\fR style identification string.
.Ip "\fBarx\fR" 12
Extended archive command which can even put existing archives into an archive.
.Ip "\fBslo\fR" 12
Separate linker options by library class.
.Ip "\fBscpp\fR" 12
An additional C source file pre-processor for sharing \fIcpp\fR\|(1) code, internal
variables and internal functions.
.Ip "\fBversion\fR" 12
Generate and maintain a version information file in either text, C or Perl
format.
.Ip "\fBpath\fR" 12
Deal with shell path variables.
.SH "COMMAND DESCRIPTION"
In the following the available \fIcommands\fR and their corresponding
\fIcommand_options\fR are described in detail.
.Ip "\fBecho\fR [\fB\-n\fR] [\fB\-e\fR] \fIstr\fR" 4
This is an \fIecho\fR\|(1) style print command which provides special expansion
constructs (terminal bold mode, environment details, date) and newline
control.  Per default \fIstring\fR is written to \fIstdout\fR followed by a newline
character (``\f(CW\en\fR''). When option ``\fB\-n\fR'\*(R' is used this newline character is
left out. 
.Sp
The \fIstr\fR can contain special ``\fB%\fR\fIx\fR'\*(R' constructs which which are
expanded before the output is written when option ``\fB\-e\fR'\*(R' is used.
Currently the following constructs are recognized: ``\fB%B\fR'\*(R' for switching to
terminal bold mode, ``\fB%b\fR'\*(R' for switching terminal mode back to normal
display mode, ``\fB%u\fR'\*(R' for the current user name, ``\fB%U\fR'\*(R' for the current
user id (numerical), ``\fB%h\fR'\*(R' for the current hostname, ``\fB%d\fR'\*(R' for the
current domain name, ``\fB%D\fR'\*(R' for the current day of the month, ``\fB%M\fR'\*(R' for
the current month (numerical), ``\fB%m\fR'\*(R' for the current month name and
``\fB%Y\fR'\*(R' for the current year.
.Sp
The trick of this command is that it provides a portable ``\fB\-n\fR'\*(R' option and
hides the gory details needed to find out the environment details.
.Sp
Examples:
.Sp
.Vb 4
\& #   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"
.Ve
.Ip "\fBmdate\fR [\fB\-n\fR] [\fB\-z\fR] [\fB\-s\fR] [\fB\-d\fR] [\fB\-f\fR \fIstr\fR] [\fB\-o\fR \fIspec\fR] \fIpath\fR" 4
This command pretty-prints the last modification time of a file or directory
\fIpath\fR. Option ``\fB\-n\fR'\*(R' suppresses the output of a trailing newline
character, option ``\fB\-z\fR'\*(R' pads numeric day (and optionally month) with a
leading zero, option ``\fB\-s\fR'\*(R' shortens the months name to an abbreviation of
three characters, option ``\fB\-d\fR'\*(R' replaces the month name with the
corresponding digits, option ``\fB\-f\fR'\*(R' uses \fIstr\fR as the field separator
(default is a single space character) and option ``\fB\-o\fR'\*(R' specified the order
in which the fields are printed. 
.Sp
The default for \fIspec\fR is ``\f(CWdmy\fR'\*(R' which means an output of ``<day> <month>
<year>'\*(R'.  Any combination of the chars ``\f(CWd\fR'\*(R', ``\f(CWm\fR'\*(R' and ``\f(CWy\fR'\*(R' or
allowed for \fIspec\fR.
.Sp
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.
.Sp
Examples:
.Sp
.Vb 4
\& #   shell script
\& shtool mdate -n /
\& shtool mdate -f '/' -z -d -o ymd foo.txt
\& shtool mdate -f '-' -s foo.txt
.Ve
.Ip "\fBtable\fR [\fB\-F\fR \fIsep\fR] [\fB\-w\fR \fIwidth\fR] [\fB\-c\fR \fIcols\fR] [\fB\-s\fR \fIstrip\fR] \fIstr\fR\fBsep\fR\fIstr\fR..." 4
This pretty-prints a \fIsep\fR\-sperarated list of \fIstr\fRings as a table.  Per
default a colon-seperated list (\fIsep\fR=":") is pretty printed as a
three-column (<cols>=3) table no longer than 79 chars (\fIstrip\fR=79) is
generated where each column is 15 characters wide (\fIwidth\fR=15). 
.Sp
The trick of this command is that it avoids to use the unportable \fItr\fR\|(1) and
\fIfmt\fR\|(1) commands and instead is based entirely on \fIsh\fR\|(1), \fIawk\fR\|(1) and \fIsed\fR\|(1)
functionality.
.Sp
Example:
.Sp
.Vb 2
\& #   shell script
\& shtool table -F , -w 5 -c 4 "1,2,3,4,5,6,7,8,9,10,11,12"
.Ve
.Ip "\fBprop\fR [\fB\-p\fR \fIstr\fR]" 4
This command displays a processing indication though a running propeller. The
option ``\fB\-p\fR'\*(R' can be used to set a particular prefix \fIstr\fR 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 (``\f(CW|\fR'') sequence where on \f(CWstdin\fR
logging/processing informations found.  For every line on \f(CWstdin\fR the
propeller cycles one step clock-wise.
.Sp
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.
.Sp
Example:
.Sp
.Vb 4
\& #   shell script
\& configure 2>&1 |\e
\&     tee logfile |\e
\&     shtool prop -p "Configuring sources"
.Ve
.Ip "\fBmove\fR [\-v] [\-t] [\-e] [\-p] \fIsrc-file\fR \fIdst-file\fR" 4
This is a \fImv\fR\|(1) style command, but with two special features: First when
option ``\fB\-e\fR'\*(R' (`expand') is used and an asterisk occurs somewhere in \fIsrc\fR
one can use ``\f(CW%\fR\fIn\fR'\*(R' (where \fIn\fR is \f(CW1\fR,\f(CW2\fR,...) in \fIdst-file\fR. This is
useful for renaming multiple files at once.  Second, when option ``\fB\-p\fR'\*(R'
(for `preserve') is used and \fIsrc-file\fR and \fIdst-file\fR are byte-wise the
same it just deletes \fIsrc-file\fR. The intention is that the permissions and
time stamps on \fIdst\fR are't changed which is important when \fIdst-file\fR is
used in conjunction with Makefiles.  Option ``\fB\-v\fR'\*(R' (verbose) can be used to
enable the output of extra processing information. Option ``\fB\-t\fR'\*(R' (trace)
can be used to enable the output of the essential shell commands which are
executed.
.Sp
The trick of this command is that it can rename multiple files at once and
preserves the timestamps when the contents isn't changed.
.Sp
Examples:
.Sp
.Vb 2
\& #   shell script
\& shtool move -v -e *.txt %1.asc
.Ve
.Vb 4
\& #   Makefile
\& scanner.c: scanner.l
\&     lex scanner.l
\&     shtool move -t -p lex.yy.c scanner.c
.Ve
.Ip "\fBinstall\fR [\fB\-v\fR] [\fB\-t\fR] [\fB\-c\fR] [\fB\-C\fR] [\fB\-s\fR] [\fB\-m\fR \fImode\fR] [\fB\-o\fR \fIowner\fR] [\fB\-g\fR \fIgroup\fR] [\fB\-e\fR \fIext\fR] <file> \fIpath\fR" 4
This command installs a program, script or datafile (dependent on \fImode\fR) in
a portable way while providing all important options of the \s-1BSD\s0 \fIinstall\fR\|(1)
command. Per default \fIfile\fR is moved to the target \fIpath\fR, but with option
``\fB\-c\fR'\*(R' \fIfile\fR is copied. The target file is created with owner/group set
to the current active uid/gid, but when this script is called as root (uid 0)
the options ``\fB\-o\fR'\*(R' and ``\fB\-g\fR'\*(R' can be used to override this. 
.Sp
Additionally program executables is stripped with \fIstrip\fR\|(1) after installation
when option ``\fB\-s\fR'\*(R' is used.  Option ``\fB\-C\fR'\*(R' is like ``\fB\-c\fR'\*(R', except if
the destination file already exists and the files are the same, the source is
just removed.  Option ``\fB\-e\fR'\*(R' can be used to set an implicit executable
extension.  Option ``\fB\-v\fR'\*(R' (verbose) can be used to enable the output of
extra processing information. Option ``\fB\-t\fR'\*(R' (trace) can be used to enable
the output of the essential shell commands which are executed.
.Sp
The trick of this command is that it provides the functionality of \s-1BSD\s0
\fIinstall\fR\|(1) in a portable emulated way.
.Sp
Example:
.Sp
.Vb 5
\& #   Makefile
\& install:
\&      :
\&     shtool install -c -s -m 4755 foo $(bindir)/
\&     shtool install -c -m 644 foo.man $(mandir)/man1/foo.1
.Ve
.Ip "\fBmkdir\fR [\fB\-t\fR] [\fB\-f\fR] [\fB\-p\fR] [\fB\-m\fR \fImode\fR] \fIdir\fR [\fIdir\fR ...]" 4
This is a \fImkdir\fR\|(1) style command providing support for auto-parent-dir
creation (when option ``\fB\-p\fR'\*(R' is used), directory permission control (with
option ``\fB\-m\fR \fImode\fR'\*(R' where \fImode\fR can be in any of the formats specified
to the \fIchmod\fR\|(1) command) and smart skipping when \fIdir\fR already exists
(triggered by the force option ``\fB\-f\fR'').  Option ``\fB\-t\fR'\*(R' (trace) can be
used to enable the output of the essential shell commands which are executed.
.Sp
The trick of this command is that it provides both a portable ``\fB\-p\fR'\*(R'
functionality and the ability to be smart when the directory already exists
which is important for installation procedures.
.Sp
Example:
.Sp
.Vb 5
\& #   Makefile
\& install:
\&     shtool mkdir -f -p -m 755 $(bindir)
\&     shtool mkdir -f -p -m 755 $(mandir)/man1
\&      :
.Ve
.Ip "\fBmkln\fR [\fB\-t\fR] [\fB\-f\fR] [\fB\-s\fR] \fIsrc-path\fR [\fIsrc-path\fR ...] \fIdst-path\fR" 4
This is a \fIln\fR\|(1) style command which provides automatic calculation and usage
of relative links when possible, i.e. usually when \fIsrc-path\fR and \fIdst-path\fR
are not absolute paths or at least they share a common prefix except the root
directory (``\f(CW/\fR''). When more than one \fIsrc-path\fR is specified, all of them
are linked into \fIdst-path\fR. Options ``\fB\-f\fR'\*(R' and ``\fB\-s\fR'\*(R' are similar to
\fIln\fR\|(1), i.e.  they force the creation of the link (even when it exists) and
create a symbolic link instead of a hard-link.  Option ``\fB\-t\fR'\*(R' (trace) can
be used to enable the output of the essential ``\f(CWln\fR'\*(R' command which is
executed.
.Sp
The trick of this command is that it tried hard to calculate the paths to get
the maximum possible relative paths.
.Sp
Example:
.Sp
.Vb 2
\& #   shell script
\& shtool mkln -s foo/bar baz/quux
.Ve
.Ip "\fBmkshadow\fR [\fB\-v\fR] [\fB\-t\fR] [\fB\-a\fR] \fIsrc-dir\fR \fIdst-dir\fR" 4
This command creates a shadow tree of \fIsrc-dir\fR under \fIdst-dir\fR by
recreating the directory hierarchy of \fIsrc-dir\fR under \fIdst-dir\fR and by
creating the files of \fIsrc-dir\fR by linking them into the corresponding
directories under \fIdst-dir\fR via symbolic links. When \fIsrc-dir\fR can be
reached via relative paths from \fIdst-dir\fR, relative symbolic links are used,
too. 
.Sp
Option ``\fB\-v\fR'\*(R' (verbose) can be used to enable some displaying of processing
information.  Option ``\fB\-t\fR'\*(R' (trace) can be used to display all commands
which are executed in order to construct \fIdst-dir\fR.  Option ``\fB\-a\fR'\*(R' (all)
can be used to really shadow all files and directories in \fIsrc-dir\fR. Per
default \s-1CVS\s0 related files and directories, backup files, object files, etc.
are not shadowed.
.Sp
The trick of this is that is provides such a high-level functionality with a
single command and hides all gory details.
.Sp
Example: 
.Sp
.Vb 2
\& #   shell script
\& shtool mkshadow -v -a . /tmp/shadow
.Ve
.Ip "\fBfixperm\fR [\fB\-v\fR] [\fB\-t\fR] \fIpath\fR [ \fIpath\fR ... ]" 4
This command fixes file permissions inside a source tree under \fIpath\fR 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 ``\fB\-v\fR'\*(R' can be used to display some processing
information.  Option ``\fB\-t\fR'\*(R' (trace) can be used to enable the output of the
essential shell commands which are executed.
.Sp
The trick is that this is more convinient that having to set the permissions
manually or with a large file list.
.Sp
Example:
.Sp
.Vb 3
\&  #  Makefile.in
\&  dist:
\&      shtool fixperm -v *
.Ve
.Ip "\fBguessos\fR" 4
This command is a simple operating system and platform architecture guesser
which determines a so-called ``\s-1GNU\s0 \fIplatform-triple\fR'\*(R' style identification
string ``\fIarch\fR\-\fIhardware\fR\-\fIos\fR\fIosversion\fR'\*(R'. For instance a FreeBSD 3.1
running on a Pentium \s-1II\s0 is identified as ``\f(CWi686-pc-freebsd3.1\fR'\*(R'.  When you
need a more sophisticated platform guesser, use the \s-1GNU\s0
\f(CWconfig.guess\fR/\f(CWconfig.sub\fR scripts, please.
.Sp
.Vb 2
\& #   configure.in
\& OS=`shtool guessos`
.Ve
.Ip "\fBarx\fR [\fB\-t\fR] [\fB\-C\fR \fIcmd\fR] \fIop\fR \fIarchive\fR \fIfile\fR [\fIfile\fR ...]" 4
This is a wrapper around the archive (``\f(CWar\fR'') tool. It provides the ability
to create archives out of existing archives, i.e.  when one of \fIfile\fR matches
``\f(CW*.a\fR'\*(R' the archive member files of \fIfile\fR are used instead of \fIfile\fR
itself. When option ``\fB\-t\fR'\*(R' (trace) is given \fBarx\fR shows the actually
involved shell commands. Option ``\fB\-C\fR'\*(R' can be used to set the ``ar'\*(R'
command to \fIcmd\fR.
.Sp
The trick of this command is the automatic handling of archive members which
is especially interesting when 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.
.Sp
Example:
.Sp
.Vb 10
\& #   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
.Ve
.Ip "\fBslo\fR -- \fB\-L\fR\fIdir\fR \fB\-l\fR\fIlib\fR [ \fB\-L\fR\fIdir\fR \fB\-l\fR\fIlib\fR ... ]" 4
This command separates the linker options ``\fB\-L\fR'\*(R' and ``\fB\-l\fR'\*(R' by library
class. It's argument line can actually be an abitrary command line where those
options are contained. \fBslo\fR parses these two options only and ignores the
remaining contents. The result is a trivial shell script on \f(CWstdout\fR which
defines six variables containing the ``\fB\-L\fR'\*(R' and ``\fB\-l\fR'\*(R' options sorted by
class: 
.Sp
``\f(CWSLO_DIRS_OBJ\fR'\*(R' and ``\f(CWSLO_LIBS_OBJ\fR'\*(R' contains the ``\fB\-L\fR'\*(R' and
``\fB\-l\fR'\*(R' options of static libraries,  ``\f(CWSLO_DIRS_PIC\fR'\*(R' and
``\f(CWSLO_LIBS_PIC\fR'\*(R' contains the ``\fB\-L\fR'\*(R' and ``\fB\-l\fR'\*(R' options of static
libraries containing \s-1PIC\s0 ("Position Independent Code") and ``\f(CWSLO_DIRS_DSO\fR'\*(R'
and ``\f(CWSLO_LIBS_DSO\fR'\*(R' contains the ``\fB\-L\fR'\*(R' and ``\fB\-l\fR'\*(R' options of shared
libraries. 
.Sp
The intent of this seperation is to provide a way between static and shared
libraries which is important when 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
\s-1DSO\s0 only against the static libraries.  One can use this command also to just
sort the options.
.Sp
Example:
.Sp
.Vb 5
\&  #   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"
\&    :
.Ve
.Ip "\fBscpp\fR [\fB\-v\fR] [\fB\-p\fR] [\fB\-o\fR \fIofile\fR] [\fB\-t\fR \fItfile\fR] [\fB\-M\fR \fImark\fR] [\fB\-D\fR \fIdname\fR] [\fB\-C\fR \fIcname\fR] \fIfile\fR [\fIfile\fR ...]" 4
This command is an additional \s-1ANSI\s0 C source file pre-processor for sharing
\fIcpp\fR\|(1) code segments, internal variables and internal functions. The intention
for this comes from writing libraries in \s-1ANSI\s0 C. Here a common shared internal
header file is usually used for sharing information between the library
source files. 
.Sp
The operation is to parse special constructs in \fIfile\fRs, generate a few
things out of these constructs and insert them at position \fImark\fR in \fItfile\fR
by writing the output to \fIofile\fR. Additionally the \fIfile\fRs are never touched
or modified. Instead the constructs are removed later by the \fIcpp\fR\|(1) phase of
the build process. The only prerequisite is that every \fIfile\fR has a
``\f(CW#include "\fR\fIofile\fR\f(CW"\fR'\*(R' at the top.
.Sp
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
``\fIcname\fR'\*(R'.  For instance when \fIcname\fR is ``intern'\*(R', a function ``\f(CWintern
void *foobar(int quux)\fR'\*(R' in one of the \fIfile\fRs is translated into both a
``\f(CW#define foobar __foobar\fR'\*(R' and a ``\f(CWextern void *foobar(int quux);\fR'\*(R' in
\fIofile\fR. Additionally a global ``\f(CW#define\fR \fIcname\fR \f(CW/**/\fR'\*(R' is also
created in \fIofile\fR to let the compiler silently ignore this additional
storage class identifier.
.Sp
Second, the library source files usually want to share \f(CWtypedef\fRs,
\f(CW#define\fRs, etc.  over the source file boundaries. To achieve this one can
either place this stuff manually into \fItfile\fR or use the second feature of
\fBscpp\fR: All code in \fIfile\fRs encapsulated with ``\f(CW#if \fR\fIdname\fR ...
\f(CW#endif\fR'\*(R' is automatically copied to \fIofile\fR. Additionally a global
``\f(CW#define\fR \fIdname\fR \f(CW0\fR'\*(R' is also created in \fIofile\fR to let the compiler
silently skip this parts (because it was already found in the header).
.Sp
Option ``\fB\-v\fR'\*(R' can be used to enable some processing output.  Option
``\fB\-p\fR'\*(R' can be used to make the decision whether to overwrite \fIofile\fR
independent of the generated ``#line'\*(R' lines. This is useful for Makefiles
when the real contents of \fIofile\fR will not change, just line numbers.
.Sp
Example:
.Sp
.Vb 5
\&  #   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 \e
\&                   -M %%MARK%% -D cpp -C intern $(SRCS)
.Ve
.Vb 5
\&  /* foo_p.h.in */
\&  #ifndef FOO_P_H
\&  #define FOO_P_H
\&  %%MARK%%
\&  #endif /* FOO_P_H */
.Ve
.Vb 11
\&  /* 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;
\&  }
.Ve
.Vb 12
\&  /* 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\en", ours);
\&      }
\&      return 0;
\&  }
.Ve
.Ip "\fBversion\fR [\fB\-l\fR \fIlang\fR] [\fB\-n\fR \fIname\fR] [\fB\-p\fR \fIprefix\fR] [\fB\-s\fR \fIversion\fR] [\fB\-i\fR \fIknob\fR] [\fB\-d\fR \fItype\fR] \fIfile\fR" 4
This command generates and maintains a version information file \fIfile\fR for
program name \fIname\fR in either textual (\fIlang\fR="\f(CWtxt\fR"), \s-1ANSI\s0 C
(\fIlang\fR="c") or Perl (\fIlang\fR="perl") language.  The version is always
described with a triple
<\fIversion\fR,\fIrevision\fR,\fIpatch/alpha/beta-level\fR> and is represented
by a string which always matches the regular expression
``\f(CW[0-9]+\e.[0-9]+[.abps][0-9]+\fR'\*(R'. When the option ``\fB\-s\fR'\*(R' is given, the
contents of \fIfile\fR is overridden with the specified \fIversion\fR. 
.Sp
When option ``\fB\-i\fR'\*(R' is used the version ingredients in \fIfile\fR are updated
by adjusting one \fIknob\fR of the version where \fIknob\fR can be one of the
following: ``\f(CWa\fR'\*(R', ``\f(CWb\fR'\*(R', ``\f(CWp\fR'\*(R', ``\f(CWP\fR'\*(R' and ``\f(CWs\fR'\*(R' just increase
the alpha/beta/patch/snap level by 1 (and set the seperator character between
version and the level position). ``\f(CWr\fR'\*(R' increases the revision by 1 and sets
the alpha/beta/patch/snap level to 0.  ``\f(CWv\fR'\*(R' increases the version by 1 and
sets both the revision and alpha/beta/patch/snap level to 0.  
.Sp
When option ``\fB\-d\fR'\*(R' is given the current version in \fIfile\fR is displayed
either in short (\fItype\fR="short") or long (\fItype\fR="long") texual format or in
a format suitable for use with \s-1GNU\s0 libtool (\fItype\fR="libtool") or in a
hexadecimal format (\fItype\fR="hex").
.Sp
When no option is given at all, ``\f(CW-i P\fR'\*(R' is assumed.
.Sp
Example:
.Sp
.Vb 2
\& #   shell script
\& shtool version -l c -n FooBar -p foobar -s 1.2b3 version.c
.Ve
.Vb 3
\& #   configure.in
\& V=`shtool version -l c -d long version.c`
\& echo "Configuring FooBar, Version $V"
.Ve
.Ip "\fBpath\fR [\fB\-s\fR] [\fB\-r\fR] [\fB\-d\fR] [\fB\-b\fR] [\fB\-m\fR] [\-p \fIpath\fR] \fIstr\fR [\fIstr\fR ...]" 4
This command deals with shell \f(CW$PATH\fR variables. It can find a program
executable in \f(CW$PATH\fR or \fIpath\fR through one or more filenames (given by one or
more \fIstr\fR arguments). The result is the absolute filesystem path to the
program displayed on \f(CWstdout\fR plus an exit code of 0 when it was really
found.  
.Sp
The option ``\fB\-s\fR'\*(R' 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 ``\fB\-m\fR'\*(R' enables some magic where currently for the programs
``\f(CWperl\fR'\*(R' and ``\f(CWcpp\fR'\*(R' an advanced magic search is done. The option
``\fB\-r\fR'\*(R' can be used to transform a forward path to a subdirectory into a
reverse path. Option ``\fB\-d\fR'\*(R' and ``\fB\-b\fR'\*(R' just output the directory or base
name of \fIstr\fR.
.Sp
Examples:
.Sp
.Vb 5
\& #   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`
.Ve
.SH "SEE ALSO"
\fIsh\fR\|(1), \fIcp\fR\|(1), \fIrm\fR\|(1), \fImkdir\fR\|(1), \fIawk\fR\|(1), \fIsed\fR\|(1).
.SH "HISTORY"
Some scripts contained in \fBshtool\fR were already written in 1994 by \fIRalf S.
Engelschall\fR 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'\*(R' (APACI).  In April 1999 the \fBshtool\fR package was
created out of the accumulated master versions of the scripts. In June 1999 it
finally entered the status of an official GNU program.
.SH "AUTHOR"
.PP
.Vb 3
\& Ralf S. Engelschall
\& rse@engelschall.com
\& www.engelschall.com
.Ve

.rn }` ''
.IX Title "shtool 3"
.IX Name "B<GNU shtool> - The GNU Portable Shell Tool"

.IX Header "NAME"

.IX Header "VERSION"

.IX Header "SYNOPSIS"

.IX Header "DESCRIPTION"

.IX Subsection "Context Background"

.IX Subsection "Maintainance Problem"

.IX Subsection "The Aesthetic Problem"

.IX Subsection "Filling the gap"

.IX Subsection "The goals in detail"

.IX Item "\fB1. It has to be self-contained and reside in a single file\fR"

.IX Item "\fB2. It has to cover all functionality of the old scripts\fR"

.IX Item "\fB3. It has to be maximum portable over all Unix flavors\fR"

.IX Item "\fB4. It has to be clean and fully documented\fR"

.IX Item "\fB5. It has to stay under a reasonable and common license\fR"

.IX Header "GLOBAL OPTIONS"

.IX Item "\fB\-h\fR"

.IX Item "\fB\-v\fR"

.IX Header "COMMANDS"

.IX Item "\fBecho\fR"

.IX Item "\fBmdate\fR"

.IX Item "\fBtable\fR"

.IX Item "\fBprop\fR "

.IX Item "\fBmove\fR"

.IX Item "\fBinstall\fR"

.IX Item "\fBmkdir\fR"

.IX Item "\fBmkln\fR"

.IX Item "\fBmkshadow\fR"

.IX Item "\fBfixperm\fR"

.IX Item "\fBguessos\fR"

.IX Item "\fBarx\fR"

.IX Item "\fBslo\fR"

.IX Item "\fBscpp\fR"

.IX Item "\fBversion\fR"

.IX Item "\fBpath\fR"

.IX Header "COMMAND DESCRIPTION"

.IX Item "\fBecho\fR [\fB\-n\fR] [\fB\-e\fR] \fIstr\fR"

.IX Item "\fBmdate\fR [\fB\-n\fR] [\fB\-z\fR] [\fB\-s\fR] [\fB\-d\fR] [\fB\-f\fR \fIstr\fR] [\fB\-o\fR \fIspec\fR] \fIpath\fR"

.IX Item "\fBtable\fR [\fB\-F\fR \fIsep\fR] [\fB\-w\fR \fIwidth\fR] [\fB\-c\fR \fIcols\fR] [\fB\-s\fR \fIstrip\fR] \fIstr\fR\fBsep\fR\fIstr\fR..."

.IX Item "\fBprop\fR [\fB\-p\fR \fIstr\fR]"

.IX Item "\fBmove\fR [\-v] [\-t] [\-e] [\-p] \fIsrc-file\fR \fIdst-file\fR"

.IX Item "\fBinstall\fR [\fB\-v\fR] [\fB\-t\fR] [\fB\-c\fR] [\fB\-C\fR] [\fB\-s\fR] [\fB\-m\fR \fImode\fR] [\fB\-o\fR \fIowner\fR] [\fB\-g\fR \fIgroup\fR] [\fB\-e\fR \fIext\fR] <file> \fIpath\fR"

.IX Item "\fBmkdir\fR [\fB\-t\fR] [\fB\-f\fR] [\fB\-p\fR] [\fB\-m\fR \fImode\fR] \fIdir\fR [\fIdir\fR ...]"

.IX Item "\fBmkln\fR [\fB\-t\fR] [\fB\-f\fR] [\fB\-s\fR] \fIsrc-path\fR [\fIsrc-path\fR ...] \fIdst-path\fR"

.IX Item "\fBmkshadow\fR [\fB\-v\fR] [\fB\-t\fR] [\fB\-a\fR] \fIsrc-dir\fR \fIdst-dir\fR"

.IX Item "\fBfixperm\fR [\fB\-v\fR] [\fB\-t\fR] \fIpath\fR [ \fIpath\fR ... ]"

.IX Item "\fBguessos\fR"

.IX Item "\fBarx\fR [\fB\-t\fR] [\fB\-C\fR \fIcmd\fR] \fIop\fR \fIarchive\fR \fIfile\fR [\fIfile\fR ...]"

.IX Item "\fBslo\fR -- \fB\-L\fR\fIdir\fR \fB\-l\fR\fIlib\fR [ \fB\-L\fR\fIdir\fR \fB\-l\fR\fIlib\fR ... ]"

.IX Item "\fBscpp\fR [\fB\-v\fR] [\fB\-p\fR] [\fB\-o\fR \fIofile\fR] [\fB\-t\fR \fItfile\fR] [\fB\-M\fR \fImark\fR] [\fB\-D\fR \fIdname\fR] [\fB\-C\fR \fIcname\fR] \fIfile\fR [\fIfile\fR ...]"

.IX Item "\fBversion\fR [\fB\-l\fR \fIlang\fR] [\fB\-n\fR \fIname\fR] [\fB\-p\fR \fIprefix\fR] [\fB\-s\fR \fIversion\fR] [\fB\-i\fR \fIknob\fR] [\fB\-d\fR \fItype\fR] \fIfile\fR"

.IX Item "\fBpath\fR [\fB\-s\fR] [\fB\-r\fR] [\fB\-d\fR] [\fB\-b\fR] [\fB\-m\fR] [\-p \fIpath\fR] \fIstr\fR [\fIstr\fR ...]"

.IX Header "SEE ALSO"

.IX Header "HISTORY"

.IX Header "AUTHOR"