ossp-adm/autotools/shtool.html
<HTML>
<HEAD>
<TITLE>shtool> - The GNU Portable Shell Tool</TITLE>
<LINK REV="made" HREF="mailto:root@en1.engelschall.com">
</HEAD>
<BODY>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#name">NAME</A></LI>
<LI><A HREF="#version">VERSION</A></LI>
<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
<LI><A HREF="#description">DESCRIPTION</A></LI>
<UL>
<LI><A HREF="#context background">Context Background</A></LI>
<LI><A HREF="#maintainance problem">Maintainance Problem</A></LI>
<LI><A HREF="#the aesthetic problem">The Aesthetic Problem</A></LI>
<LI><A HREF="#filling the gap">Filling the gap</A></LI>
<LI><A HREF="#the goals in detail">The goals in detail</A></LI>
</UL>
<LI><A HREF="#global options">GLOBAL OPTIONS</A></LI>
<LI><A HREF="#commands">COMMANDS</A></LI>
<LI><A HREF="#command description">COMMAND DESCRIPTION</A></LI>
<LI><A HREF="#see also">SEE ALSO</A></LI>
<LI><A HREF="#history">HISTORY</A></LI>
<LI><A HREF="#author">AUTHOR</A></LI>
</UL>
<!-- INDEX END -->
<HR>
<P>
<HR>
<H1><A NAME="name">NAME</A></H1>
<P><STRONG>GNU shtool</STRONG> - The GNU Portable Shell Tool</P>
<P>
<HR>
<H1><A NAME="version">VERSION</A></H1>
<P>GNU shtool SHTOOL_VERSION_STR</P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<P><STRONG>shtool</STRONG>
[ <EM>global_options</EM> ]
<EM>command</EM>
[ <EM>command_options</EM> ]
[ <EM>command_args</EM> ]</P>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P><STRONG>GNU shtool</STRONG> 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 <STRONG>shtool</STRONG> 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.</P>
<P>
<H2><A NAME="context background">Context Background</A></H2>
<P>For the configuration, build and installation environment of modern free
software packages one nowadays uses GNU <STRONG>autoconf</STRONG> and friends (i.e.
usually <STRONG>autoconf</STRONG>, <STRONG>automake</STRONG> and <STRONG>libtool</STRONG>). <STRONG>Autoconf</STRONG> covers the
configuration, <STRONG>automake</STRONG> covers the generation of the build environment and
<STRONG>libtool</STRONG> 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 <CODE>mkdir.sh</CODE>, <CODE>install.sh</CODE>, etc. These scripts are usually replacements
for system tools and are required mainly for portability reasons. The result
is usually an <CODE>etc/</CODE> subdirectory in the source tree where over time a
lot shell scripts accumulate.</P>
<P>
<H2><A NAME="maintainance problem">Maintainance Problem</A></H2>
<P>The problem with those <CODE>etc/</CODE> shell scripts starts if one has to maintain
<EM>lots</EM> of free software packages as it's the case for the author of <STRONG>shtool</STRONG>.
Then over time all <CODE>etc/</CODE> 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 <STRONG>autoconf</STRONG> no such problem exists, because the resulting
<CODE>configure</CODE> script is generated on-the-fly. The same applies to <STRONG>automake</STRONG>
and the various <CODE>Makefile.in</CODE> files.</P>
<P>Only for <STRONG>libtool</STRONG> one always has to grab the latest copy. But because it's
just two files (<CODE>ltmain.sh</CODE> and <CODE>ltconfig</CODE>), keeping a source trees in sync
is not too complicated (especially not if using the handy <CODE>libtoolize</CODE>
program). But the <CODE>etc/</CODE> 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 <STRONG>autoconf</STRONG> and friends are part of the game. But which
<CODE>etc/</CODE> shell scripts are needed this time? And from which existing source
tree to copy them from? Hmmm... the same procedure as last year?!</P>
<P>
<H2><A NAME="the aesthetic problem">The Aesthetic Problem</A></H2>
<P>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 <CODE>etc/</CODE> 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 <STRONG>shtool</STRONG>)
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 <STRONG>shtool</STRONG> cannot reduce, but <STRONG>shtool</STRONG> merges them
together into a single file and this way they optically totally disappear from
the source tree.</P>
<P>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 ;)</P>
<P>
<H2><A NAME="filling the gap">Filling the gap</A></H2>
<P>So, wouldn't it be nice to have a fourth package (beside <STRONG>autoconf</STRONG>,
<STRONG>automake</STRONG> and <STRONG>libtool</STRONG>) which fills the gap, i.e. which provides the
functionality of the old files in <CODE>etc/</CODE>, 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 <STRONG>libtool</STRONG>? The
author thought this <EM>would</EM> be actually very useful and the result is the
current GNU <STRONG>shtool</STRONG> package which at least successfully solved the above
problems of the author.</P>
<P>
<H2><A NAME="the goals in detail">The goals in detail</A></H2>
<P>To better understand the intentions behind <STRONG>shtool</STRONG> and to avoid confusion,
here are the original goals of the <STRONG>shtool</STRONG> script:</P>
<OL>
<LI><STRONG><A NAME="item_It_has_to_be_self%2Dcontained_and_reside_in_a_sing"><STRONG>1. It has to be self-contained and reside in a single file</STRONG></A></STRONG><BR>
This was achieved by compiling the resulting <STRONG>shtool</STRONG> script out of the
ingredient source scripts. The advantage is that <STRONG>shtool</STRONG> 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.
<P></P>
<LI><STRONG><A NAME="item_It_has_to_cover_all_functionality_of_the_old_scrip"><STRONG>2. It has to cover all functionality of the old scripts</STRONG></A></STRONG><BR>
This was achieved by (re)implementing really all functionality which
experience showed is important in source trees of typical free software
packages.
<P></P>
<LI><STRONG><A NAME="item_It_has_to_be_maximum_portable_over_all_Unix_flavor"><STRONG>3. It has to be maximum portable over all Unix flavors</STRONG></A></STRONG><BR>
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 <CODE>fmt</CODE>, <CODE>tr</CODE>, etc) or
unportable features of well-known Unix programs (like shell functions, special
<CODE>sed</CODE> features, etc. pp). That's why <STRONG>shtool</STRONG>'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.
<P></P>
<LI><STRONG><A NAME="item_It_has_to_be_clean_and_fully_documented"><STRONG>4. It has to be clean and fully documented</STRONG></A></STRONG><BR>
This was achieved by reimplementing too ugly functionality from scratch and
cleaning up old shell script code plus writing this complete manual page.
<P></P>
<LI><STRONG><A NAME="item_It_has_to_stay_under_a_reasonable_and_common_licen"><STRONG>5. It has to stay under a reasonable and common license</STRONG></A></STRONG><BR>
This was achieved by placing the <STRONG>shtool</STRONG> package under the GNU General
Public License (GPL). This way the <STRONG>shtool</STRONG> package itself is well protected
and is guarrantied to be kept free software, but the resulting <STRONG>shtool</STRONG>
script can be nevertheless <EM>used</EM> in <EM>all</EM> types of source trees. Notice
here: given that one includes GNU <STRONG>shtool</STRONG> 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 <EM>using</EM> <STRONG>shtool</STRONG>. 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 <STRONG>shtool</STRONG>. Keep this in
mind ;)
<P></P>
<LI><STRONG><A NAME="item_It_has_to_be_modularized_for_flexibility_reasons"><STRONG>6. It has to be modularized for flexibility reasons</STRONG></A></STRONG><BR>
This was achieved by using an auxiliary tool <CODE>shtoolize(1)</CODE> which can be used to
build individual <CODE>shtool</CODE> scripts out of the ingredient shell scripts. This
way if one don't need all the available functionality one can assemble
together an individual <CODE>shtool</CODE> script.
<P></P></OL>
<P>
<HR>
<H1><A NAME="global options">GLOBAL OPTIONS</A></H1>
<P>The following <EM>global options</EM> are available for <STRONG>shtool</STRONG>. Any <EM>command</EM>s
are ignored if one of them is present on the <STRONG>shtool</STRONG> command line.</P>
<DL>
<DT><STRONG><A NAME="item_%2Dh%2C_%2D%2Dhelp"><STRONG>-h</STRONG>, <STRONG>--help</STRONG></A></STRONG><BR>
<DD>
Displays a short help page describing the usage of <STRONG>shtool</STRONG> and it's
ingredient <EM>command</EM>s in a compact way.
<P></P>
<DT><STRONG><A NAME="item_%2Dv%2C_%2D%2Dversion"><STRONG>-v</STRONG>, <STRONG>--version</STRONG></A></STRONG><BR>
<DD>
Displays the version number of <STRONG>shtool</STRONG>.
<P></P>
<DT><STRONG><A NAME="item_%2Dd%2C_%2D%2Ddebug"><STRONG>-d</STRONG>, <STRONG>--debug</STRONG></A></STRONG><BR>
<DD>
Displays shell trace messages for debugging purposes.
<P></P>
<DT><STRONG><A NAME="item_%2Dr%2C_%2D%2Drecreate"><STRONG>-r</STRONG>, <STRONG>--recreate</STRONG></A></STRONG><BR>
<DD>
Recreate the <STRONG>shtool</STRONG> script with its own individual <CODE>shtoolize(1)</CODE> call.
<P></P></DL>
<P>
<HR>
<H1><A NAME="commands">COMMANDS</A></H1>
<P>The following <EM>command</EM>s are provided by <STRONG>shtool</STRONG>. They are all called via
``<CODE>shtool</CODE> <EM>command</EM>''. Any trailing <EM>command_options</EM> are specific to the
particular <EM>command</EM>. They are listed (here and also below) sorted by topic,
i.e. related commands are listed side-by-side.</P>
<DL>
<DT><STRONG><A NAME="item_echo"><STRONG>echo</STRONG></A></STRONG><BR>
<DD>
<A HREF="#item_echo"><CODE>echo(1)</CODE></A> style print command providing special expansion constructs (terminal
bold mode, environment details, date) and newline control.
<P></P>
<DT><STRONG><A NAME="item_mdate"><STRONG>mdate</STRONG></A></STRONG><BR>
<DD>
Pretty-prints the last modification time of a file or directory.
<P></P>
<DT><STRONG><A NAME="item_table"><STRONG>table</STRONG></A></STRONG><BR>
<DD>
Pretty-prints a field-separately list as a table.
<P></P>
<DT><STRONG><A NAME="item_prop"><STRONG>prop</STRONG></A></STRONG><BR>
<DD>
Display a processing indication though a running propeller.
<P></P>
<DT><STRONG><A NAME="item_move"><STRONG>move</STRONG></A></STRONG><BR>
<DD>
<CODE>mv(1)</CODE> style command, but can rename/move multiple files at once and allows
source files just to be deleted if contents didn't change.
<P></P>
<DT><STRONG><A NAME="item_install"><STRONG>install</STRONG></A></STRONG><BR>
<DD>
Install a program, script or datafile in a portable way.
<P></P>
<DT><STRONG><A NAME="item_mkdir"><STRONG>mkdir</STRONG></A></STRONG><BR>
<DD>
<A HREF="#item_mkdir"><CODE>mkdir(1)</CODE></A> style command providing support for auto-parent-dir creation,
directory permission control and smart skipping if directory already
exists.
<P></P>
<DT><STRONG><A NAME="item_mkln"><STRONG>mkln</STRONG></A></STRONG><BR>
<DD>
<CODE>ln(1)</CODE> style command providing automatic calculation and usage of relative
links if possible.
<P></P>
<DT><STRONG><A NAME="item_mkshadow"><STRONG>mkshadow</STRONG></A></STRONG><BR>
<DD>
Create a shadow source tree by the help of symbolic links.
<P></P>
<DT><STRONG><A NAME="item_fixperm"><STRONG>fixperm</STRONG></A></STRONG><BR>
<DD>
Fix file permissions inside a source tree by cleaning up the permission bits.
<P></P>
<DT><STRONG><A NAME="item_rotate"><STRONG>rotate</STRONG></A></STRONG><BR>
<DD>
Rotate a logfile.
<P></P>
<DT><STRONG><A NAME="item_tarball"><STRONG>tarball</STRONG></A></STRONG><BR>
<DD>
Roll standardized distribution tarballs.
<P></P>
<DT><STRONG><A NAME="item_subst"><STRONG>subst</STRONG></A></STRONG><BR>
<DD>
Apply <CODE>sed(1)</CODE> substitution operations.
<P></P>
<DT><STRONG><A NAME="item_guessos"><STRONG>guessos</STRONG></A></STRONG><BR>
<DD>
Simple operating system and platform architecture guesser which
determines a GNU <EM>platform-triple</EM> style identification string.
<P></P>
<DT><STRONG><A NAME="item_arx"><STRONG>arx</STRONG></A></STRONG><BR>
<DD>
Extended archive command which can even put existing archives into an archive.
<P></P>
<DT><STRONG><A NAME="item_slo"><STRONG>slo</STRONG></A></STRONG><BR>
<DD>
Separate linker options by library class.
<P></P>
<DT><STRONG><A NAME="item_scpp"><STRONG>scpp</STRONG></A></STRONG><BR>
<DD>
An additional C source file pre-processor for sharing <CODE>cpp(1)</CODE> code, internal
variables and internal functions.
<P></P>
<DT><STRONG><A NAME="item_version"><STRONG>version</STRONG></A></STRONG><BR>
<DD>
Maintain a version information file in either Text, C/C++, Perl or Python.
format.
<P></P>
<DT><STRONG><A NAME="item_path"><STRONG>path</STRONG></A></STRONG><BR>
<DD>
Deal with shell path variables.
<P></P></DL>
<P>
<HR>
<H1><A NAME="command description">COMMAND DESCRIPTION</A></H1>
<P>In the following the available <EM>commands</EM> and their corresponding
<EM>command_options</EM> are described in detail.</P>
<DL>
<DT><STRONG><A NAME="item_echo_%5B%2Dn%7C%2D%2Dnewline%5D_%5B%2De%7C%2D%2Dex"><STRONG>echo</STRONG> [<STRONG>-n</STRONG>|<STRONG>--newline</STRONG>] [<STRONG>-e</STRONG>|<STRONG>--expand</STRONG>] <EM>str</EM></A></STRONG><BR>
<DD>
This is an <A HREF="#item_echo"><CODE>echo(1)</CODE></A> style print command which provides special expansion
constructs (terminal bold mode, environment details, date) and newline
control. Per default <EM>string</EM> is written to <EM>stdout</EM> followed by a newline
character (``<CODE>\n</CODE>''). When option ``<STRONG>-n</STRONG>'' is used this newline character is
left out.
<P>The <EM>str</EM> can contain special ``<STRONG>%</STRONG><EM>x</EM>'' constructs which which
are expanded before the output is written if option ``<STRONG>-e</STRONG>'' is
used. Currently the following constructs are recognized: ``<STRONG>%B</STRONG>''
for switching to terminal bold mode, ``<STRONG>%b</STRONG>'' for switching terminal
mode back to normal display mode, ``<STRONG>%u</STRONG>'' for the current user name,
``<STRONG>%U</STRONG>'' for the current user id (numerical), ``<STRONG>%g</STRONG>'' for the current
group name, ``<STRONG>%G</STRONG>'' for the current group id (numerical), ``<STRONG>%h</STRONG>''
for the current hostname, ``<STRONG>%d</STRONG>'' for the current domain name,
``<STRONG>%D</STRONG>'' for the current day of the month, ``<STRONG>%M</STRONG>'' for the current
month (numerical), ``<STRONG>%m</STRONG>'' for the current month name and ``<STRONG>%Y</STRONG>''
for the current year.</P>
<P>The trick of this command is that it provides a portable ``<STRONG>-n</STRONG>'' option and
hides the gory details needed to find out the environment details.</P>
<P>Examples:</P>
<PRE>
# 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"</PRE>
<P></P>
<DT><STRONG><A NAME="item_mdate_%5B%2Dn%7C%2D%2Dnewline%5D_%5B%2Dz%7C%2D%2Dz"><STRONG>mdate</STRONG> [<STRONG>-n</STRONG>|<STRONG>--newline</STRONG>] [<STRONG>-z</STRONG>|<STRONG>--zero</STRONG>] [<STRONG>-s</STRONG>|<STRONG>--shorten</STRONG>] [<STRONG>-d</STRONG>|<STRONG>--digits</STRONG>] [<STRONG>-f</STRONG>|<STRONG>--field-sep</STRONG> <EM>str</EM>] [<STRONG>-o</STRONG>|<STRONG>--order</STRONG> <EM>spec</EM>] <EM>path</EM></A></STRONG><BR>
<DD>
This command pretty-prints the last modification time of a file or directory
<EM>path</EM>. Option ``<STRONG>-n</STRONG>'' suppresses the output of a trailing newline
character, option ``<STRONG>-z</STRONG>'' pads numeric day (and optionally month) with a
leading zero, option ``<STRONG>-s</STRONG>'' shortens the months name to an abbreviation of
three characters, option ``<STRONG>-d</STRONG>'' replaces the month name with the
corresponding digits, option ``<STRONG>-f</STRONG>'' uses <EM>str</EM> as the field separator
(default is a single space character) and option ``<STRONG>-o</STRONG>'' specified the order
in which the fields are printed.
<P>The default for <EM>spec</EM> is ``<CODE>dmy</CODE>'' which means an output of ``<day> <month>
<year>''. Any combination of the chars ``<CODE>d</CODE>'', ``<CODE>m</CODE>'' and ``<CODE>y</CODE>'' or
allowed for <EM>spec</EM>.</P>
<P>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.</P>
<P>Examples:</P>
<PRE>
# shell script
shtool mdate -n /
shtool mdate -f '/' -z -d -o ymd foo.txt
shtool mdate -f '-' -s foo.txt</PRE>
<P></P>
<DT><STRONG><A NAME="item_table_%5B%2DF%7C%2D%2Dfield%2Dsep_sep%5D_%5B%2Dw%7"><STRONG>table</STRONG> [<STRONG>-F</STRONG>|<STRONG>--field-sep</STRONG> <EM>sep</EM>] [<STRONG>-w</STRONG>|<STRONG>--width</STRONG> <EM>width</EM>] [<STRONG>-c</STRONG>|<STRONG>--columns</STRONG> <EM>cols</EM>] [<STRONG>-s</STRONG>|<STRONG>--strip</STRONG> <EM>strip</EM>] <EM>str</EM><STRONG>sep</STRONG><EM>str</EM>...</A></STRONG><BR>
<DD>
This pretty-prints a <EM>sep</EM>-separated list of <EM>str</EM>ings as a table. Per
default a colon-separated list (<EM>sep</EM>=``:'') is pretty printed as a
three-column (<cols>=3) table no longer than 79 chars (<EM>strip</EM>=79) is
generated where each column is 15 characters wide (<EM>width</EM>=15).
<P>The trick of this command is that it avoids to use the unportable <CODE>tr(1)</CODE> and
<CODE>fmt(1)</CODE> commands and instead is based entirely on sh(1), <CODE>awk(1)</CODE> and <CODE>sed(1)</CODE>
functionality.</P>
<P>Example:</P>
<PRE>
# shell script
shtool table -F , -w 5 -c 4 "1,2,3,4,5,6,7,8,9,10,11,12"</PRE>
<P></P>
<DT><STRONG><A NAME="item_prop_%5B%2Dp%7C%2D%2Dprefix_str%5D"><STRONG>prop</STRONG> [<STRONG>-p</STRONG>|<STRONG>--prefix</STRONG> <EM>str</EM>]</A></STRONG><BR>
<DD>
This command displays a processing indication though a running propeller. The
option ``<STRONG>-p</STRONG>'' can be used to set a particular prefix <EM>str</EM> 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 (``<CODE>|</CODE>'') sequence where on <CODE>stdin</CODE>
logging/processing informations found. For every line on <CODE>stdin</CODE> the
propeller cycles one step clock-wise.
<P>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.</P>
<P>Example:</P>
<PRE>
# shell script
configure 2>&1 |\
tee logfile |\
shtool prop -p "Configuring sources"</PRE>
<P></P>
<DT><STRONG><A NAME="item_move_%5B%2Dv%7C%2D%2Dverbose%5D_%5B%2Dt%7C%2D%2Dtr"><STRONG>move</STRONG> [<STRONG>-v</STRONG>|<STRONG>--verbose</STRONG>] [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-e</STRONG>|<STRONG>--expand</STRONG>] [<STRONG>-p</STRONG>|<STRONG>--preserve</STRONG>] <EM>src-file</EM> <EM>dst-file</EM></A></STRONG><BR>
<DD>
This is a <CODE>mv(1)</CODE> style command, but with two special features: First if
option ``<STRONG>-e</STRONG>'' (`expand') is used and an asterisk occurs somewhere in <EM>src</EM>
one can use ``<CODE>%</CODE><EM>n</EM>'' (where <EM>n</EM> is <CODE>1</CODE>,<CODE>2</CODE>,...) in <EM>dst-file</EM>. This is
useful for renaming multiple files at once. Second, if option ``<STRONG>-p</STRONG>''
(for `preserve') is used and <EM>src-file</EM> and <EM>dst-file</EM> are byte-wise the
same it just deletes <EM>src-file</EM>. The intention is that the permissions and
time stamps on <EM>dst</EM> aren't changed which is important if <EM>dst-file</EM> is
used in conjunction with Makefiles. Option ``<STRONG>-v</STRONG>'' (verbose) can be used to
enable the output of extra processing information. Option ``<STRONG>-t</STRONG>'' (trace)
can be used to enable the output of the essential shell commands which are
executed.
<P>The trick of this command is that it can rename multiple files at once and
preserves the timestamps if the contents isn't changed.</P>
<P>Examples:</P>
<PRE>
# shell script
shtool move -v -e '*.txt' %1.asc</PRE>
<PRE>
# Makefile
scanner.c: scanner.l
lex scanner.l
shtool move -t -p lex.yy.c scanner.c</PRE>
<P></P>
<DT><STRONG><A NAME="item_install_%5B%2Dv%7C%2D%2Dverbose%5D_%5B%2Dt%7C%2D%2"><STRONG>install</STRONG> [<STRONG>-v</STRONG>|<STRONG>--verbose</STRONG>] [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-c</STRONG>|<STRONG>--copy</STRONG>] [<STRONG>-C</STRONG>|<STRONG>--compare-copy</STRONG>] [<STRONG>-s</STRONG>|<STRONG>--strip</STRONG>] [<STRONG>-m</STRONG>|<STRONG>--mode</STRONG> <EM>mode</EM>] [<STRONG>-o</STRONG>|<STRONG>--owner</STRONG> <EM>owner</EM>] [<STRONG>-g</STRONG>|<STRONG>--group</STRONG> <EM>group</EM>] [<STRONG>-e</STRONG>|<STRONG>--exec</STRONG> <EM>sed-cmd</EM>] <EM>file</EM> <EM>path</EM></A></STRONG><BR>
<DD>
This command installs a program, script or datafile (dependent on <EM>mode</EM>) in
a portable way while providing all important options of the BSD <A HREF="#item_install"><CODE>install(1)</CODE></A>
command. Per default <EM>file</EM> is moved to the target <EM>path</EM>, but with option
``<STRONG>-c</STRONG>'' <EM>file</EM> 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 ``<STRONG>-o</STRONG>'' and ``<STRONG>-g</STRONG>'' can be used to override this.
<P>Additionally program executables is stripped with <CODE>strip(1)</CODE> after
installation if option ``<STRONG>-s</STRONG>'' is used. Option ``<STRONG>-C</STRONG>'' is like
``<STRONG>-c</STRONG>'', except if the destination file already exists and the files
are the same, the source is just removed. Option ``<STRONG>-e</STRONG>'' can be used
one or multiple times to apply one or more <CODE>sed(1)</CODE> commands on-the-fly
to the contents of the input <EM>file</EM> before the output file is created.
Option ``<STRONG>-v</STRONG>'' (verbose) can be used to enable the output of extra
processing information. Option ``<STRONG>-t</STRONG>'' (trace) can be used to enable
the output of the essential shell commands which are executed.</P>
<P>The trick of this command is that it provides the functionality of BSD
<A HREF="#item_install"><CODE>install(1)</CODE></A> in a portable emulated way.</P>
<P>Example:</P>
<PRE>
# Makefile
install:
:
shtool install -c -s -m 4755 foo $(bindir)/
shtool install -c -m 644 foo.man $(mandir)/man1/foo.1
shtool install -c -m 644 -e "s/@p@/$prefix/g" foo.conf $(etcdir)/</PRE>
<P></P>
<DT><STRONG><A NAME="item_mkdir_%5B%2Dt%7C%2D%2Dtrace%5D_%5B%2Df%7C%2D%2Dfor"><STRONG>mkdir</STRONG> [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-f</STRONG>|<STRONG>--force</STRONG>] [<STRONG>-p</STRONG>|<STRONG>--parents</STRONG>] [<STRONG>-m</STRONG>|<STRONG>--mode</STRONG> <EM>mode</EM>] <EM>dir</EM> [<EM>dir</EM> ...]</A></STRONG><BR>
<DD>
This is a <A HREF="#item_mkdir"><CODE>mkdir(1)</CODE></A> style command providing support for automatic parent
directory creation (if option ``<STRONG>-p</STRONG>'' is used), directory permission
control (with option ``<STRONG>-m</STRONG> <EM>mode</EM>'' where <EM>mode</EM> can be in any of
the formats specified to the <CODE>chmod(1)</CODE> command) and smart skipping if
<EM>dir</EM> already exists (triggered by the force option ``<STRONG>-f</STRONG>''). Option
``<STRONG>-t</STRONG>'' (trace) can be used to enable the output of the essential
shell commands which are executed.
<P>The trick of this command is that it provides both a portable ``<STRONG>-p</STRONG>''
functionality and the ability to be smart if the directory already exists
which is important for installation procedures.</P>
<P>Example:</P>
<PRE>
# Makefile
install:
shtool mkdir -f -p -m 755 $(bindir)
shtool mkdir -f -p -m 755 $(mandir)/man1
:</PRE>
<P></P>
<DT><STRONG><A NAME="item_mkln_%5B%2Dt%7C%2D%2Dtrace%5D_%5B%2Df%7C%2D%2Dforc"><STRONG>mkln</STRONG> [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-f</STRONG>|<STRONG>--force</STRONG>] [<STRONG>-s</STRONG>|<STRONG>--symbolic</STRONG>] <EM>src-path</EM> [<EM>src-path</EM> ...] <EM>dst-path</EM></A></STRONG><BR>
<DD>
This is a <CODE>ln(1)</CODE> style command which provides automatic calculation and usage
of relative links if possible, i.e. usually if <EM>src-path</EM> and <EM>dst-path</EM>
are not absolute paths or at least they share a common prefix except the root
directory (``<CODE>/</CODE>''). When more than one <EM>src-path</EM> is specified, all of them
are linked into <EM>dst-path</EM>. Options ``<STRONG>-f</STRONG>'' and ``<STRONG>-s</STRONG>'' 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 ``<STRONG>-t</STRONG>'' (trace) can
be used to enable the output of the essential ``<CODE>ln</CODE>'' command which is
executed.
<P>The trick of this command is that it tried hard to calculate the paths to get
the maximum possible relative paths.</P>
<P>Example:</P>
<PRE>
# shell script
shtool mkln -s foo/bar baz/quux</PRE>
<P></P>
<DT><STRONG><A NAME="item_mkshadow_%5B%2Dv%7C%2D%2Dverbose%5D_%5B%2Dt%7C%2D%"><STRONG>mkshadow</STRONG> [<STRONG>-v</STRONG>|<STRONG>--verbose</STRONG>] [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-a</STRONG>|<STRONG>--all</STRONG>] <EM>src-dir</EM> <EM>dst-dir</EM></A></STRONG><BR>
<DD>
This command creates a shadow tree of <EM>src-dir</EM> under <EM>dst-dir</EM> by
recreating the directory hierarchy of <EM>src-dir</EM> under <EM>dst-dir</EM> and by
creating the files of <EM>src-dir</EM> by linking them into the corresponding
directories under <EM>dst-dir</EM> via symbolic links. When <EM>src-dir</EM> can be
reached via relative paths from <EM>dst-dir</EM>, relative symbolic links are used,
too.
<P>Option ``<STRONG>-v</STRONG>'' (verbose) can be used to enable some displaying of processing
information. Option ``<STRONG>-t</STRONG>'' (trace) can be used to display all commands
which are executed in order to construct <EM>dst-dir</EM>. Option ``<STRONG>-a</STRONG>'' (all)
can be used to really shadow all files and directories in <EM>src-dir</EM>. Per
default CVS related files and directories, backup files, object files, etc.
are not shadowed.</P>
<P>The trick of this is that is provides such a high-level functionality with a
single command and hides all gory details.</P>
<P>Example:</P>
<PRE>
# shell script
shtool mkshadow -v -a . /tmp/shadow</PRE>
<P></P>
<DT><STRONG><A NAME="item_fixperm_%5B%2Dv%7C%2D%2Dverbose%5D_%5B%2Dt%7C%2D%2"><STRONG>fixperm</STRONG> [<STRONG>-v</STRONG>|<STRONG>--verbose</STRONG>] [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] <EM>path</EM> [ <EM>path</EM> ... ]</A></STRONG><BR>
<DD>
This command fixes file permissions inside a source tree under <EM>path</EM> 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 ``<STRONG>-v</STRONG>'' can be used to display some processing
information. Option ``<STRONG>-t</STRONG>'' (trace) can be used to enable the output of the
essential shell commands which are executed.
<P>The trick is that this is more convenient that having to set the permissions
manually or with a large file list.</P>
<P>Example:</P>
<PRE>
# Makefile.in
dist:
shtool fixperm -v *
...</PRE>
<P></P>
<DT><STRONG><A NAME="item_rotate_%5B%2Dv%7C%2D%2Dverbose%5D_%5B%2Dt%7C%2D%2D"><STRONG>rotate</STRONG> [<STRONG>-v</STRONG>|<STRONG>--verbose</STRONG>] [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-f</STRONG>|<STRONG>--force</STRONG>] [<STRONG>-n</STRONG>|<STRONG>--num-files</STRONG> <EM>count</EM>] [<STRONG>-s</STRONG>|<STRONG>--min-size</STRONG> <EM>size</EM>] [<STRONG>-c</STRONG>|<STRONG>--copy</STRONG>] [<STRONG>-r</STRONG>|<STRONG>--remove</STRONG>] [<STRONG>-a</STRONG>|<STRONG>--archive-dir</STRONG> <EM>dir</EM>] [<STRONG>-z</STRONG>|<STRONG>--compress</STRONG> [<EM>tool</EM>:]<EM>level</EM>] [<STRONG>-b</STRONG>|<STRONG>--background</STRONG>] [<STRONG>-d</STRONG>|<STRONG>--delay</STRONG>] [<STRONG>-p</STRONG>|<STRONG>--pad</STRONG> <EM>len</EM>] [<STRONG>-o</STRONG>|<STRONG>--owner</STRONG> <EM>owner</EM>] [<STRONG>-g</STRONG>|<STRONG>--group</STRONG> <EM>group</EM>] [<STRONG>-m</STRONG>|<STRONG>--mode</STRONG> <EM>mode</EM>] [<STRONG>-M</STRONG>|<STRONG>--migrate</STRONG> <EM>cmd</EM>] [<STRONG>-P</STRONG>|<STRONG>--prolog</STRONG> <EM>cmd</EM>] [<STRONG>-E</STRONG>|<STRONG>--epilog</STRONG> <EM>cmd</EM>] <EM>file</EM> [...]</A></STRONG><BR>
<DD>
This command rotates a logfile <EM>file</EM> by subsequently creating up to
<EM>count</EM> (optionally compressed) archive files of it. Archive files are
named ``<EM>file</EM>.<EM>number</EM>[<EM>compress-suffix]</EM>'' where <EM>number</EM> is the
version number, 0 being the newest and ``<EM>count</EM>-1'' the oldest.
<P>A rotation step consists of the following steps: 1. remove archive file
number <EM>count</EM>-1; 2. move archive file number <EM>N</EM>-1 to <EM>N</EM> for <EM>N</EM>
counting from 1 to <EM>count</EM>-1; 3. move <EM>file</EM> to archive file number 0;
4. creating a new and empty instance of <EM>file</EM>.</P>
<P>Option ``<STRONG>-s</STRONG>'' can be used to only start a rotation step if <EM>file</EM> is
at least <EM>size</EM> bytes long. The argument <EM>size</EM> can be specified also
with the trailing units <CODE>K</CODE> (kilo), <CODE>M</CODE> (mega) or <CODE>G</CODE> (giga).</P>
<P>Option ``<STRONG>-c</STRONG>'' changes the approach of moving <EM>file</EM> to archive file
number 0: instead of a move followed by the creation of a new <EM>file</EM>, a
copy is performed followed by a truncation of <EM>file</EM>. The difference is
that in the first case (the default), if an application has <EM>file</EM>
still opened, after the rotation step it will have archive file number
0 opened and usually has to reopen the new <EM>file</EM>, while in the second
case the application can keep its open file handles to <EM>file</EM>. The
drawback of the second approach is that logfile entries are lost when
they are written to <EM>file</EM> between the execution of the copy and the
subsequent truncation operation.</P>
<P>Option ``<STRONG>-r</STRONG>'' removes <EM>file</EM> after rotation instead of providing a
new empty file. Option ``<STRONG>-a</STRONG>'' forces archive files to be created in
the separate directory <EM>dir</EM>.</P>
<P>Option ``<STRONG>-z</STRONG>'' enables compression of archive files with compression
level <EM>level</EM> (if option ``<STRONG>-b</STRONG>'' is present, compression takes place in
background). By default, the tools bzip2(1), <CODE>gzip(1)</CODE> and <CODE>compress(1)</CODE> are
searched for in <CODE>$PATH</CODE> (in this order), but one also can override this
by prefixing the compression level with one of the three particular tool
names. Option ``<STRONG>-d</STRONG>'' delays the compression of archive file number 0.
This is useful if option ``<STRONG>-c</STRONG>'' is not used, because an application
might still write to archive file 0 (through an open file handle).</P>
<P>Option ``<STRONG>-p</STRONG>'' enables padding with leading zeros in the <EM>number</EM>
part of the filename ``<EM>file</EM>.<EM>number</EM><EM>compress-suffix</EM>''. The default
padding <EM>len</EM> is 1. This is interesting if more than 10 archive files
are used, because it leads to still sorted directory listings.</P>
<P>Options ``<STRONG>-o</STRONG>'', ``<STRONG>-g</STRONG>'' and ``<STRONG>-m</STRONG>'' can be used to make sure that
the created files have particular file attributes. The valid arguments
are the same as for chown(1), <CODE>chgrp(1)</CODE> and chmod(1). Be aware that using
options ``<STRONG>-o</STRONG>'' and ``<STRONG>-g</STRONG>'' require root privileges.</P>
<P>Option ``<STRONG>-M</STRONG>'' allows one to execute a ``migration'' command just before
the archive file number <EM>count</EM>-1 is removed from the filesystem. The
specified <EM>cmd</EM> gets the archive filename as an argument appended.
Options ``<STRONG>-P</STRONG>'' (prolog) and ``<STRONG>-E</STRONG>'' (epilog) can be used to execute
commands before and after the rotation step. They are interesting in
conjunction with option ``<STRONG>-s</STRONG>'', because they are not executed at all
if it is decided that no rotation step is performed.</P>
<P>Option ``<STRONG>-f</STRONG>'' (force) can be used to allow the archive directory
(option ``<STRONG>-a</STRONG>'') to be silently created if it still does not exist and
that still not existing intermediate logfiles are silently skipped in
the rotation step.</P>
<P>Option ``<STRONG>-v</STRONG>'' (verbose) can be used to display the files which are
rotated. Option ``<STRONG>-t</STRONG>'' (trace) can be used to enable the output of
the essential shell commands which are executed for the rotation step.</P>
<P>Example:</P>
<PRE>
# shell script
shtool rotate -n10 -s1M -zbzip2:9 -d -r /var/log/ap.access.log
shtool rotate -n5 -s128K -zbzip2:9 -d -r /var/log/ap.error.log
apachectl graceful</PRE>
<P></P>
<DT><STRONG><A NAME="item_tarball_%5B%2Dt%7C%2D%2Dtrace%5D_%5B%2Dv%7C%2D%2Dv"><STRONG>tarball</STRONG> [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-v</STRONG>|<STRONG>--verbose</STRONG>] [<STRONG>-o</STRONG>|<STRONG>--output</STRONG> <EM>tarball</EM>] [<STRONG>-c</STRONG>|<STRONG>--compress</STRONG> <EM>prog</EM>] [<STRONG>-u</STRONG>|<STRONG>--user</STRONG> <EM>user</EM>] [<STRONG>-g</STRONG>|<STRONG>--group</STRONG> <EM>group</EM>] [<STRONG>-e</STRONG>|<STRONG>--exclude</STRONG> <EM>pattern</EM>] <EM>path</EM> [<EM>path</EM> ...]</A></STRONG><BR>
<DD>
This command is for `rolling' distribution `tarballs', i.e. for the creation
of distribution files generated by `<CODE>tar</CODE>'. 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 `<CODE>foobar-0.8.15.tar</CODE>' per convention
unpacks into a top-level directory `<CODE>foobar-0.8.15/</CODE>'); third the files in
the tarball should be sorted to allow users to use the `<CODE>tar tvf -</CODE>' 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.
<P>The input files are given by the file or directory arguments <EM>path</EM>.
Directories are expanded before the comma-separated exclude (option <STRONG>-e</STRONG>)
<EM>pattern</EM>s (<STRONG>grep</STRONG> regular expressions) are used to filter the list. The
default filter is ``<CODE>CVS,\\.cvsignore,\\.[oa]\$</CODE>''. Then the tarball is
created with its files owned by <EM>user</EM> (option <STRONG>-u</STRONG>) and <EM>group</EM> (option
<STRONG>-g</STRONG>). Finally the resulting tarball is piped through an optional compression
(option <STRONG>-c</STRONG>) program and written to the output file <EM>tarball</EM> (option
<STRONG>-o</STRONG>). Option ``<STRONG>-v</STRONG>'' can be used to display the files which are stored in
the tarball. Option ``<STRONG>-t</STRONG>'' (trace) can be used to enable the output of the
essential shell commands which are executed.</P>
<P>The trick of this command is that it combines the complex process of rolling a
good tarball into a <EM>single</EM> command.</P>
<P>Example:</P>
<PRE>
# 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' .</PRE>
<P></P>
<DT><STRONG><A NAME="item_subst_%5B%2Dv%7C%2D%2Dverbose%5D_%5B%2Dt%7C%2D%2Dt"><STRONG>subst</STRONG> [<STRONG>-v</STRONG>|<STRONG>--verbose</STRONG>] [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-n</STRONG>|<STRONG>--nop</STRONG>] [<STRONG>-s</STRONG>|<STRONG>--stealth</STRONG>] [<STRONG>-i</STRONG>|<STRONG>--interactive</STRONG>] [<STRONG>-b</STRONG>|<STRONG>--backup</STRONG> <EM>ext</EM>] [<STRONG>-e</STRONG>|<STRONG>--exec</STRONG> <EM>cmd</EM>] [<STRONG>-f</STRONG>|<STRONG>--file</STRONG> <EM>cmd-file</EM>] [<EM>file</EM>] [<EM>file</EM> ...]</A></STRONG><BR>
<DD>
This command applies one or more <CODE>sed(1)</CODE> substitution operations to
<EM>stdin</EM> or any number of files. The <CODE>sed(1)</CODE> operations are either
specified on the command line with option ``<STRONG>-e</STRONG>'' or are contained
in a file <EM>cmd-file</EM> and are specified with option ``<STRONG>-f</STRONG>''. The
original untouched <EM>file</EM> is usually overridden. If option ``<STRONG>-b</STRONG>''
is given and specifies a file extension, the original file is preserved
as ``<EM>file</EM>.<EM>ext</EM>''. If option ``<STRONG>-s</STRONG>'' (stealth) is specified,
the timestamp is preserved on <EM>file</EM>, too. Option ``<STRONG>-i</STRONG>'' enables
interactive mode where the user has to approve each operation. Option
``<STRONG>-n</STRONG>'' (no operation) can be used to disable the actual execution of
the essential shell commands which would be executed. Option ``<STRONG>-t</STRONG>''
(trace) can be used to enable the output of the essential shell commands
which are executed. Option ``<STRONG>-v</STRONG>'' (verbose) can be used to display
the files which are patched.
<P>Example:</P>
<PRE>
# interactive shell
shtool subst -i -e 's;(c) \([0-9]*\)-2000;(c) \1-2001;' *.[ch]</PRE>
<PRE>
# RPM spec-file
%install
shtool subst -v -n \
-e 's;^\(prefix=\).*;\1 $RPM_BUILD_ROOT%{_prefix};g' \
-e 's;^\(sysconfdir=\).*;\1 $RPM_BUILD_ROOT%{_prefix}/etc;g' \
`find . -name Makefile -print`
make install</PRE>
<P></P>
<DT><STRONG><STRONG>guessos</STRONG></STRONG><BR>
<DD>
This command is a simple operating system and platform architecture guesser
which determines a so-called ``GNU <EM>platform-triple</EM>'' style identification
string ``<EM>arch</EM>-<EM>hardware</EM>-<EM>os</EM><EM>osversion</EM>''. For instance a FreeBSD 3.1
running on a Pentium II is identified as ``<CODE>i686-pc-freebsd3.1</CODE>''. When you
need a more sophisticated platform guesser, use the GNU
<CODE>config.guess</CODE>/<CODE>config.sub</CODE> scripts, please.
<PRE>
# configure.in
OS=`shtool guessos`</PRE>
<P></P>
<DT><STRONG><A NAME="item_arx_%5B%2Dt%7C%2D%2Dtrace%5D_%5B%2DC%7C%2D%2Dcomma"><STRONG>arx</STRONG> [<STRONG>-t</STRONG>|<STRONG>--trace</STRONG>] [<STRONG>-C</STRONG>|<STRONG>--command</STRONG> <EM>cmd</EM>] <EM>op</EM> <EM>archive</EM> <EM>file</EM> [<EM>file</EM> ...]</A></STRONG><BR>
<DD>
This is a wrapper around the archive (``<CODE>ar</CODE>'') tool. It provides the ability
to create archives out of existing archives, i.e. if one of <EM>file</EM> matches
``<CODE>*.a</CODE>'' the archive member files of <EM>file</EM> are used instead of <EM>file</EM>
itself. When option ``<STRONG>-t</STRONG>'' (trace) is given <STRONG>arx</STRONG> shows the actually
involved shell commands. Option ``<STRONG>-C</STRONG>'' can be used to set the ``ar''
command to <EM>cmd</EM>.
<P>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.</P>
<P>Example:</P>
<PRE>
# 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</PRE>
<P></P>
<DT><STRONG><A NAME="item_slo_%5B%2Dp%7C%2D%2Dprefix_str%5D_%2D%2D_%2DLdir_%"><STRONG>slo</STRONG> [<STRONG>-p</STRONG>|<STRONG>--prefix</STRONG> <EM>str</EM>] -- <STRONG>-L</STRONG><EM>dir</EM> <STRONG>-l</STRONG><EM>lib</EM> [ <STRONG>-L</STRONG><EM>dir</EM> <STRONG>-l</STRONG><EM>lib</EM> ... ]</A></STRONG><BR>
<DD>
This command separates the linker options ``<STRONG>-L</STRONG>'' and ``<STRONG>-l</STRONG>'' by library
class. It's argument line can actually be an arbitrary command line where those
options are contained. <STRONG>slo</STRONG> parses these two options only and ignores the
remaining contents. The result is a trivial shell script on <CODE>stdout</CODE> which
defines six variables containing the ``<STRONG>-L</STRONG>'' and ``<STRONG>-l</STRONG>'' options sorted by
class:
<P>``<CODE>SLO_DIRS_OBJ</CODE>'' and ``<CODE>SLO_LIBS_OBJ</CODE>'' contains the ``<STRONG>-L</STRONG>'' and
``<STRONG>-l</STRONG>'' options of static libraries, ``<CODE>SLO_DIRS_PIC</CODE>'' and
``<CODE>SLO_LIBS_PIC</CODE>'' contains the ``<STRONG>-L</STRONG>'' and ``<STRONG>-l</STRONG>'' options of static
libraries containing PIC (``Position Independent Code'') and
``<CODE>SLO_DIRS_DSO</CODE>'' and ``<CODE>SLO_LIBS_DSO</CODE>'' contains the ``<STRONG>-L</STRONG>'' and
``<STRONG>-l</STRONG>'' options of shared libraries. The <STRONG>-p</STRONG> option can be used to
change the default variable prefix from ``<CODE>SLO_</CODE>'' to <EM>str</EM>.</P>
<P>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.</P>
<P>Example:</P>
<PRE>
# 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"
:</PRE>
<P></P>
<DT><STRONG><A NAME="item_scpp_%5B%2Dv%7C%2D%2Dverbose%5D_%5B%2Dp%7C%2D%2Dpr"><STRONG>scpp</STRONG> [<STRONG>-v</STRONG>|<STRONG>--verbose</STRONG>] [<STRONG>-p</STRONG>|<STRONG>--preserve</STRONG>] [<STRONG>-f</STRONG>|<STRONG>--filter</STRONG> <EM>filter</EM>] [<STRONG>-o</STRONG>|<STRONG>--output</STRONG> <EM>ofile</EM>] [<STRONG>-t</STRONG>|<STRONG>--template</STRONG> <EM>tfile</EM>] [<STRONG>-M</STRONG>|<STRONG>--mark</STRONG> <EM>mark</EM>] [<STRONG>-D</STRONG>|<STRONG>--define</STRONG> <EM>dname</EM>] [<STRONG>-C</STRONG>|<STRONG>--class</STRONG> <EM>cname</EM>] <EM>file</EM> [<EM>file</EM> ...]</A></STRONG><BR>
<DD>
This command is an additional ANSI C source file pre-processor for sharing
<CODE>cpp(1)</CODE> 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.
<P>The operation is to parse special constructs in <EM>file</EM>s, generate a few
things out of these constructs and insert them at position <EM>mark</EM> in <EM>tfile</EM>
by writing the output to <EM>ofile</EM>. Additionally the <EM>file</EM>s are never touched
or modified. Instead the constructs are removed later by the <CODE>cpp(1)</CODE> phase of
the build process. The only prerequisite is that every <EM>file</EM> has a
``<CODE>#include "</CODE><EM>ofile</EM><CODE>"</CODE>'' at the top.</P>
<P>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
``<EM>cname</EM>''. For instance if <EM>cname</EM> is ``intern'', a function ``<CODE>intern
void *foobar(int quux)</CODE>'' in one of the <EM>file</EM>s is translated into both a
``<CODE>#define foobar __foobar</CODE>'' and a ``<CODE>extern void *foobar(int quux);</CODE>'' in
<EM>ofile</EM>. Additionally a global ``<CODE>#define</CODE> <EM>cname</EM> <CODE>/**/</CODE>'' is also
created in <EM>ofile</EM> to let the compiler silently ignore this additional
storage class identifier.</P>
<P>Second, the library source files usually want to share <CODE>typedef</CODE>s,
<CODE>#define</CODE>s, etc. over the source file boundaries. To achieve this one can
either place this stuff manually into <EM>tfile</EM> or use the second feature of
<STRONG>scpp</STRONG>: All code in <EM>file</EM>s encapsulated with ``<CODE>#if </CODE><EM>dname</EM> ...
<CODE>#endif</CODE>'' is automatically copied to <EM>ofile</EM>. Additionally a global
``<CODE>#define</CODE> <EM>dname</EM> <CODE>0</CODE>'' is also created in <EM>ofile</EM> to let the compiler
silently skip this parts (because it was already found in the header).</P>
<P>Option ``<STRONG>-v</STRONG>'' can be used to enable some processing output. Option
``<STRONG>-p</STRONG>'' can be used to make the decision whether to overwrite <EM>ofile</EM>
independent of the generated ``#line'' lines. This is useful for
Makefiles if the real contents of <EM>ofile</EM> will not change, just
line numbers. Option ``<STRONG>-f</STRONG>'' (which can occur multiple times) can
be used to apply one or more pre-processing <CODE>sed(1)</CODE> <EM>filter</EM> commands
(usually of type ``<CODE>s/.../.../</CODE>'') to each input file before their
input is parsed.</P>
<P>Example:</P>
<PRE>
# 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)</PRE>
<PRE>
/* foo_p.h.in */
#ifndef FOO_P_H
#define FOO_P_H
%%MARK%%
#endif /* FOO_P_H */</PRE>
<PRE>
/* 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;
}</PRE>
<PRE>
/* 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;
}</PRE>
<P></P>
<DT><STRONG><A NAME="item_version_%5B%2Dl%7C%2D%2Dlanguage_lang%5D_%5B%2Dn%7"><STRONG>version</STRONG> [<STRONG>-l</STRONG>|<STRONG>--language</STRONG> <EM>lang</EM>] [<STRONG>-n</STRONG>|<STRONG>--name</STRONG> <EM>name</EM>] [<STRONG>-p</STRONG>|<STRONG>--prefix</STRONG> <EM>prefix</EM>] [<STRONG>-s</STRONG>|<STRONG>--set</STRONG> <EM>version</EM>] [<STRONG>-e</STRONG>|<STRONG>--edit</STRONG>] [<STRONG>-i</STRONG>|<STRONG>--increase</STRONG> <EM>knob</EM>] [<STRONG>-d</STRONG>|<STRONG>--display</STRONG> <EM>type</EM>] <EM>file</EM></A></STRONG><BR>
<DD>
This command generates and maintains a version information
file <EM>file</EM> for program name <EM>name</EM> in either textual
(<EM>lang</EM>=``<CODE>txt</CODE>''), ANSI C (<EM>lang</EM>=``c''), Perl (<EM>lang</EM>=``perl'') or
Python (<EM>lang</EM>=``python'') language. The version is always described
with a triple <<EM>version</EM>,<EM>revision</EM>,<EM>level</EM>> and is
represented by a string which always matches the regular expression
``<CODE>[0-9]+\.[0-9]+[sabp.][0-9]+</CODE>''. When the option ``<STRONG>-s</STRONG>'' is given,
the contents of <EM>file</EM> is overridden with the specified <EM>version</EM>.
<P>When option ``<STRONG>-i</STRONG>'' is used, the current version in <EM>file</EM> is updated
by increasing one element of the version where <EM>knob</EM> can be one of
the following: ``<CODE>v</CODE>'' for increasing the version by 1 (and resetting
revision and level to 0), ``<CODE>r</CODE>'' for increasing the revision by 1 (and
resetting level to 0) or ``<CODE>l</CODE>'' for increasing the level by 1. Option
``<STRONG>-e</STRONG>'' can be used to interactively enter a new version.</P>
<P>Unless option ``<STRONG>-e</STRONG>'', ``<STRONG>-i</STRONG>'' or ``<STRONG>-s</STRONG>'' is specified, the performed
action is to display the current version. Option ``<STRONG>-d</STRONG>'' then can be used
to control the display type: ``<CODE>short</CODE>'' for a short version display, ``<CODE>long</CODE>''
for a longer version display, ``<CODE>hex</CODE>'' for a hexadecimal display of the version
and ``<CODE>libtool</CODE>'' for a format suitable for use with GNU libtool.</P>
<P>The hexadecimal format for a version <CODE>v.rtl</CODE> is <CODE>VVRRTLL</CODE> where <CODE>VV</CODE>
and <CODE>RR</CODE> directly correspond to <CODE>v</CODE> and <CODE>r</CODE>, <CODE>T</CODE> encodes the level
type as <CODE>9</CODE>, <CODE>2</CODE>, <CODE>1</CODE>, <CODE>0</CODE> (representing <CODE>s</CODE>, <CODE>p</CODE>/<CODE>.</CODE>, <CODE>b</CODE>, <CODE>a</CODE>
in this order) and <CODE>LL</CODE> is either directly corresponding to <CODE>l</CODE> or set
to <CODE>99</CODE> if level type is <CODE>s</CODE>.</P>
<P>Example:</P>
<PRE>
# shell script
shtool version -l c -n FooBar -p foobar -s 1.2b3 version.c</PRE>
<PRE>
# configure.in
V=`shtool version -l c -d long version.c`
echo "Configuring FooBar, Version $V"</PRE>
<P></P>
<DT><STRONG><A NAME="item_path_%5B%2Ds%7C%2D%2Dsuppress%5D_%5B%2Dr%7C%2D%2Dr"><STRONG>path</STRONG> [<STRONG>-s</STRONG>|<STRONG>--suppress</STRONG>] [<STRONG>-r</STRONG>|<STRONG>--reverse</STRONG>] [<STRONG>-d</STRONG>|<STRONG>--dirname</STRONG>] [<STRONG>-b</STRONG>|<STRONG>--basename</STRONG>] [<STRONG>-m</STRONG>|<STRONG>--magic</STRONG>] [<STRONG>-p</STRONG>|<STRONG>--path</STRONG> <EM>path</EM>] <EM>str</EM> [<EM>str</EM> ...]</A></STRONG><BR>
<DD>
This command deals with shell <CODE>$PATH</CODE> variables. It can find a program
executable in $PATH or <EM>path</EM> through one or more filenames (given by one or
more <EM>str</EM> arguments). The result is the absolute filesystem path to the
program displayed on <CODE>stdout</CODE> plus an exit code of 0 if it was really
found.
<P>The option ``<STRONG>-s</STRONG>'' 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 ``<STRONG>-m</STRONG>'' enables some magic where currently for the programs
``<CODE>perl</CODE>'' and ``<CODE>cpp</CODE>'' an advanced magic search is done. The option
``<STRONG>-r</STRONG>'' can be used to transform a forward path to a subdirectory into a
reverse path. Option ``<STRONG>-d</STRONG>'' and ``<STRONG>-b</STRONG>'' just output the directory or base
name of <EM>str</EM>.</P>
<P>Examples:</P>
<PRE>
# shell script
awk=`shtool path -p "${PATH}:." gawk nawk awk`
perl=`shtool path -m perl`
cpp=`shtool path -m cpp`
revpath=`shtool path -r path/to/subdir`</PRE>
<P></P></DL>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P>sh(1), cp(1), rm(1), mkdir(1), awk(1), sed(1).</P>
<P>
<HR>
<H1><A NAME="history">HISTORY</A></H1>
<P>Some scripts contained in GNU <STRONG>shtool</STRONG> were already written in 1994 by
<EM>Ralf S. Engelschall</EM> 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) for
Apache 1.3. In April 1999 the <STRONG>shtool</STRONG> 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 GNU <STRONG>autoconf</STRONG>, GNU <STRONG>automake</STRONG> and GNU <STRONG>libtool</STRONG>.</P>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<PRE>
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com</PRE>
</BODY>
</HTML>
