ch52_08.htm

the unix power tools

>uncompress part0?.Z</B
></CODE
>
% <CODE
CLASS="userinput"
><B
>unshar part0?</B
></CODE
>
unshar:  Sending header to part01.hdr.
unshar:  Doing part01:
If this archive is complete, you will see the following message:
          &quot;shar: End of archive 1 (of 2).&quot;
shar: Extracting &quot;README&quot; (2200 characters)
shar: Extracting &quot;options.3&quot; (7383 characters)
shar: Extracting &quot;options.c&quot; (10901 characters)
shar: Extracting &quot;options.h&quot; (2592 characters)
shar: Extracting &quot;qterm.c&quot; (24777 characters)
shar: End of archive 1 (of 2).

You still must unpack the following archives:
         2
unshar:  Sending header to part02.hdr.
unshar:  Doing part02:
If this archive is complete, you will see the following message:
          &quot;shar: End of archive 2 (of 2).&quot;
shar: Extracting &quot;Makefile&quot; (1908 characters)
shar: Extracting &quot;qterm.1&quot; (5805 characters)
shar: Extracting &quot;qterm.h&quot; (3281 characters)
shar: Extracting &quot;qtermtab&quot; (3311 characters)
shar: End of archive 2 (of 2).
You have unpacked both archives.</PRE
></TD
></TR
></TABLE
></P
><P
CLASS="para"
>If you
don't have <EM
CLASS="emphasis"
>shar</EM
> and <EM
CLASS="emphasis"
>unshar</EM
>, it's on the CD-ROM; but
the true beauty of <EM
CLASS="emphasis"
>shar</EM
> archives is that you can always 
remove any headers and footers from the file and use
the Bourne shell (<EM
CLASS="emphasis"
>sh</EM
>) to unpack the files.  </P
><P
CLASS="para"
>To edit out the header, remove any lines at the top of the
file that don't resemble Bourne shell syntax.
Since many <EM
CLASS="emphasis"
>shar</EM
>
archives are distributed in email or in newsgroups, the files
might include the header of a mail message or news posting.
The author might also precede the actual <EM
CLASS="emphasis"
>shar</EM
> archive with 
some explanation of what the program does.
A good bet is to look for a line
reading <CODE
CLASS="literal"
>#!/bin/sh</CODE
> and remove all lines preceding it.
Even better, most shell archives contain directions right in the file:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
><I
CLASS="lineannotation"
>(text .... )</I
>

#! /bin/sh
# This is a shell archive.  Remove anything before this line,
# then feed it into a shell via &quot;sh file&quot; or similar.
# To overwrite existing files, type &quot;sh file -c&quot;.</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63581"
></A
>To remove the footer, look for anything resembling a user's mail
signature.  (<EM
CLASS="emphasis"
>shar</EM
> archives usually have an <EM
CLASS="emphasis"
>exit</EM
> message
at the end, so editing out the footer isn't always needed ... but 
it doesn't hurt.)</P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63586"
></A
>After editing out the header and footer, just run the files through
<EM
CLASS="emphasis"
>sh</EM
> individually:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>vi part0?</B
></CODE
>
   <I
CLASS="lineannotation"
>edit out headers</I
>
% <CODE
CLASS="userinput"
><B
>sh part01; sh part02</B
></CODE
>
   ...</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>&#13;Note that it's especially important to install and unpack 
<EM
CLASS="emphasis"
>shar</EM
> archives in discrete, well-named directories 
(such as <EM
CLASS="emphasis"
>qterm_src</EM
>, in this case).
Since <EM
CLASS="emphasis"
>shar</EM
> files are almost always given generic names of
<EM
CLASS="emphasis"
>part01</EM
>, <EM
CLASS="emphasis"
>part02</EM
>, etc.,
it's easy to overwrite files or to get confused if you
accidentally unpack more than one package in the same directory.&#13;</P
></DIV
><DIV
CLASS="sect3"
><H4
CLASS="sect3"
><A
CLASS="title"
NAME="UPT-ART-3840-SECT-1.2.5"
>52.8.2.5 Applying Patches </A
></H4
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63603"
></A
>
When I copied the <EM
CLASS="emphasis"
>pcal</EM
> sources using the <EM
CLASS="emphasis"
>source.pt</EM
>
shell script, I also got two
<SPAN
CLASS="link"
><EM
CLASS="emphasis"
>patch</EM
> files (<A
CLASS="linkend"
HREF="ch33_09.htm"
TITLE="patch: Generalized Updating of Files that Differ "
>33.9</A
>)</SPAN
>:
<EM
CLASS="emphasis"
>rtrpatch.pcal</EM
> and <EM
CLASS="emphasis"
>RS6000patch.pcal</EM
>.
These are patches prepared by Ready-to-Run Software for 
compiling the <EM
CLASS="emphasis"
>pcal</EM
> package. </P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63614"
></A
>The <EM
CLASS="emphasis"
>RS6000patch.pcal</EM
> file is a patch for compilng on IBM's
RS6000 platform.  If you aren't on a RS6000, then you probably don't
need this file.  When building other packages, you might see other
platform-specific patch files, with prefixes like <EM
CLASS="emphasis"
>i386</EM
>,
<EM
CLASS="emphasis"
>xenix</EM
>, <EM
CLASS="emphasis"
>hp700</EM
>, <EM
CLASS="emphasis"
>sun3</EM
>, <EM
CLASS="emphasis"
>sun4</EM
>, etc.  Naturally, you
shouldn't use these packages if you aren't on one of these platforms.</P
><P
CLASS="para"
>The <EM
CLASS="emphasis"
>rtrpatch.pcal</EM
> file is
a general-purpose patch for all platforms.
You should apply this patch for all platforms.</P
><P
CLASS="para"
>Before you apply any of Ready-to-Run's patches, you should first
make sure that there aren't any patch files in the untarred source
directory.
If the sources did come with patch files, they would
have to be applied before Ready-to-Run's.
In the <EM
CLASS="emphasis"
>pcal-4.3</EM
> directory, list the directory contents:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>ls -aF</B
></CODE
>
./              Makefile.VMS    calendar        pcal.man        protos.h
../             Orig.ReadMe     exprpars.c      pcaldefs.h      readfile.c
Descrip.mms     Pcal.TEX        moon91          pcalglob.h      troffman.sty
Make_Pcal.com   Pcal.hlp        moon92          pcalinit.c      writefil.c
Makefile        ReadMe          moonphas.c      pcalinit.ps
Makefile.Amiga  SetUp.com       noprotos.h      pcallang.h
Makefile.DOS    VaxCrtl.opt     pcal.c          pcalutil.c</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>A <EM
CLASS="emphasis"
>patch</EM
> file generally has the string <EM
CLASS="emphasis"
>patch</EM
> or <EM
CLASS="emphasis"
>pch</EM
>
in it.  There are no patch files in this directory. Now that I'm sure
that there aren't any other patches, I run the <EM
CLASS="emphasis"
>patch</EM
>
command. (Naturally, if you don't already have <EM
CLASS="emphasis"
>patch</EM
>, you can
get its sources off the CD-ROM.)  To run <EM
CLASS="emphasis"
>patch</EM
>, make
sure you're in the source directory (in this case, the <EM
CLASS="emphasis"
>pcal-4.3</EM
>
subdirectory created when I ran <EM
CLASS="emphasis"
>tar</EM
>).  Then run <EM
CLASS="emphasis"
>patch</EM
>,
taking input from the patch file in the parent directory:</P
><P
CLASS="para"
><TABLE
CLASS="screen.co"
BORDER="1"
><TR
><TH
VALIGN="TOP"
><PRE
CLASS="calloutlist"
>
<A
CLASS="co"
HREF="ch13_01.htm"
TITLE="13.1 Using Standard Input and Output"
>&lt;</A
> <A
CLASS="co"
HREF="ch01_21.htm"
TITLE="1.21 Making Pathnames "
>../</A
> 








&#13;</PRE
></TH
><TD
VALIGN="TOP"
><PRE
CLASS="screen"
>
% <CODE
CLASS="userinput"
><B
>patch &lt; ../rtrpatch.pcal</B
></CODE
>
Hmm...  Looks like a new-style context diff to me...
The text leading up to this was:
--------------------------------
|*** Makefile.orig      Tue Dec 17 05:34:19 1991
|-- Makefile   Mon Nov 23 05:59:49 1992
--------------------------------
Patching file Makefile using Plan A...
Hunk #1 succeeded at 5.
Hunk #2 succeeded at 46.
done</PRE
></TD
></TR
></TABLE
></P
><P
CLASS="para"
>&#13;The patch is now applied.&#13;</P
></DIV
><DIV
CLASS="sect3"
><H4
CLASS="sect3"
><A
CLASS="title"
NAME="UPT-ART-3840-SECT-1.2.6"
>52.8.2.6 An Easy Build </A
></H4
><P
CLASS="para"
>Up to now, all we've been doing is just getting the source tree
together. Now we're up to the part where we actually build
the package. </P
><P
CLASS="para"
>First of all, if there's any universal rule about compiling
sources, it's:<A
CLASS="indexterm"
NAME="AUTOID-63649"
></A
>
<BLOCKQUOTE
CLASS="blockquote"
><P
CLASS="para"
><B
CLASS="emphasis.bold"
>If there's a file called README, read it!</B
></P
></BLOCKQUOTE
></P
><P
CLASS="para"
><EM
CLASS="emphasis"
>README</EM
> files often contain esoteric details about the history
of the program and what improvements could be made, etc.
But they
might also contain details about how to build the package.
Reading a
<EM
CLASS="emphasis"
>README</EM
> can save you hours of frustration trying to figure out 
what to tweak to make the program build on your platform.</P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63658"
></A
>Another file to look for is one called <EM
CLASS="emphasis"
>Configure</EM
>.
<EM
CLASS="emphasis"
>Configure</EM
> is a shell script that tries to figure
out what sort of platform you're on and how to build the
package for you, and it's remarkably effective.
The sources
for <EM
CLASS="emphasis"
>perl</EM
> and <EM
CLASS="emphasis"
>patch</EM
> both come with <EM
CLASS="emphasis"
>Configure</EM
> scripts.</P
><P
CLASS="para"
><EM
CLASS="emphasis"
>pcal</EM
> doesn't come with a <EM
CLASS="emphasis"
>README</EM
> or with a <EM
CLASS="emphasis"
>Configure</EM
>
script.
But it does
come with a file called <EM
CLASS="emphasis"
>Makefile</EM
>.
(Actually, it comes with several <EM
CLASS="emphasis"
>Makefiles</EM
>, for different
platforms&nbsp;- but the default <EM
CLASS="emphasis"
>Makefile</EM
> is the one for UNIX
systems, which is what you want.)
The <EM
CLASS="emphasis"
>Makefile</EM
> is used by 
<SPAN
CLASS="link"
>the <EM
CLASS="emphasis"
>make</EM
> program (<A
CLASS="linkend"
HREF="ch28_13.htm"
TITLE="make Isn't Just for Programmers! "
>28.13</A
>)</SPAN
>.
There have been entire books written about <EM
CLASS="emphasis"
>make</EM
>, but if
you're lucky, all you need to know about it is that if you see
a <EM
CLASS="emphasis"
>Makefile</EM
>, then all you need to compile a program is to
type <EM
CLASS="emphasis"
>make</EM
>.</P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63679"
></A
>First, though, scan through the <EM
CLASS="emphasis"
>Makefile</EM
> to see if there
are any comments there.
You might have to make some changes
in the <EM
CLASS="emphasis"
>Makefile</EM
> to configure it for your system.
For
example, the <EM
CLASS="emphasis"
>qterm</EM
> <EM
CLASS="emphasis"
>Makefile</EM
> has the following 
very helpful lines:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>#
# Add &quot;-DUSG5&quot; to DEFS below, if your system is UNIX System V.
# Add &quot;-DHAS_VARARGS&quot; if your system supports varargs.
# Add &quot;-DOPT_COMPAT&quot; to support old command line options.
#
DEFS    = -DTABFILE=\&quot;$(TABFILE)\&quot; -DOPT_COMPAT</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>You probably know whether your system is System V-based or not.
If you never used this program before, you probably don't care about
old command line options.
And if you don't know what <EM
CLASS="emphasis"
>varargs</EM
>
are or whether your system supports it ... try seeing if there's
a
<SPAN
CLASS="link"
>manpage (<A
CLASS="linkend"
HREF="ch50_01.htm#UPT-ART-4910"
TITLE="UNIX Online Documentation "
>50.1</A
>)</SPAN
>
for it.
(You might even find out what it is!)</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>man varargs</B
></CODE
>

VARARGS(3)             C LIBRARY FUNCTIONS             VARARGS(3)

NAME
     varargs - handle variable argument list

SYNOPSIS
     #include &lt;varargs.h&gt;
   ...</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>What do you know, I have <EM
CLASS="emphasis"
>varargs</EM
>.
So I add the <CODE
CLASS="literal"
>-DHAS_VARARGS</CODE
>
command-line option to the <CODE
CLASS="literal"
>DEFS=</CODE
> line:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>DEFS    = -DTABFILE=\&quot;$(TABFILE)\&quot; -DOPT_COMPAT -DHAS_VARARGS</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>The <EM
CLASS="emphasis"
>pcal</EM
> <EM
CLASS="emphasis"
>Makefile</EM
>, on the other hand, only includes a
single line of instruction towards the top: </P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
># Set the configuration variables below to taste.</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>This isn't particularly helpful, but scan the <EM
CLASS="emphasis"
>Makefile</EM
>
anyway for anything obviously wrong.
When you're satisfied, just cross your fingers and run <EM
CLASS="emphasis"
>make</EM
>:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>make</B
></CODE
>
/bin/cc   -c pcal.c
/bin/cc   -c exprpars.c
/bin/cc   -c moonphas.c
/bin/cc   -c pcalutil.c
/bin/cc   -c readfile.c
/bin/cc    -o pcalinit pcalinit.c
pcalinit pcalinit.ps pcalinit.h
/bin/cc   -c writefil.c
/bin/cc  -o pcal pcal.o exprpars.o moonphas.o pcalutil.o readfile.o
writefil.o -lm</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63711"
></A
>There were no error or warning messages, so you're fine.
Errors mean that the program package probably didn't build completely;
you'll have to find the cause and fix them.
If there were warnings, the programs may not work right or have
a subtle flaw.
For a program like a spreadsheet, where hidden flaws
can be a disaster, you'd better find out what the warnings mean and
fix them.
Otherwise, just cross your fingers some more and see if the program works.</P
><P
CLASS="para"
>When you list the <EM
CLASS="emphasis"
>pcal</EM
> source directory now, you should
see several new files with a <EM
CLASS="emphasis"
>.o</EM
> suffix, but the most
important thing is that the <EM
CLASS="emphasis"
>pcal</EM
> executable is now built
and ready to be installed on your system.</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>ls -aF</B
></CODE
>
./              Orig.ReadMe     moon91          pcaldefs.h      protos.h
../             Pcal.TEX        moon92          pcalglob.h      readfile.c
Descrip.mms     Pcal.hlp        moonphas.c      pcalinit*       readfile.o
Make_Pcal.com   ReadMe          moonphas.o      pcalinit.c      troffman.sty
Makefile        SetUp.com       noprotos.h      pcalinit.h      writefil.c
Makefile.Amiga  VaxCrtl.opt     pcal*           pcalinit.ps     writefil.o
Makefile.DOS    calendar        pcal.c          pcallang.h
Makefile.VMS    exprpars.c      pcal.man        pcalutil.c
Makefile.orig   exprpars.o      pcal.o          pcalutil.o</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>You can now try out the program, and once you're sure it works, 
install it.
To install the program, many <EM
CLASS="emphasis"
>Makefiles</EM
> provide
an <EM
CLASS="emphasis"
>install</EM
> target.  </P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>make install</B
></CODE
></PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63728"
></A
>On many machines, you'll need to be logged in as
<EM
CLASS="emphasis"
>root</EM
> to be able to install the binary and manpage system-wide.
If so, it might be a good idea to run <EM
CLASS="emphasis"
>make</EM
> with the <EM
CLASS="emphasis"
>-n</EM
>
option first.
The <EM
CLASS="emphasis"
>-n</EM
> option says to just show what commands
would be executed without actually executing them.</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>make -n install</B
></CODE
></PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>Or if you prefer to just install the program by hand, just 
move the executable and the manpage to the right
directories (be sure to rename the manpage as appropriate):</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>mv pcal /usr/local/bin</B
></CODE
>