ch52_08.htm

the unix power tools

% <CODE
CLASS="userinput"
><B
>mv pcal.man /usr/local/man/man1/pcal.1</B
></CODE
></PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>Note, however, that some programs may have extra steps in installing
the executable.
If all this worked as advertised, you can bail out now.
Otherwise,
you might need to know more about what goes on behind the scenes
before you can figure out what went wrong.</P
></DIV
><DIV
CLASS="sect3"
><H4
CLASS="sect3"
><A
CLASS="title"
NAME="UPT-ART-3840-SECT-1.2.7"
>52.8.2.7 Functions, Libraries, and Header Files </A
></H4
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63747"
></A
>To understand the compilation process, it helps to understand 
a little about libraries and header files.  </P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63750"
></A
>C programs are written almost entirely using <EM
CLASS="emphasis"
>functions</EM
>.
Article
<A
CLASS="xref"
HREF="ch15_03.htm"
TITLE="Adding { } Operators to Korn (and Bourne) Shells "
>15.3</A
>
shows an example of a function defined in the Bourne shell 
programming language.
C language functions are basically the same idea:
group together a series of commands, give them a name, and then 
you can execute those commands using that name whenever you want and
as many times as you want.
Functions are also sometimes referred to
as <EM
CLASS="emphasis"
>subroutines</EM
>, <EM
CLASS="emphasis"
>library functions</EM
>, or just <EM
CLASS="emphasis"
>routines</EM
>. </P
><P
CLASS="para"
>Now, you can define C functions in the same source file.
But the operating system also provides a vast collection of 
function definitions&nbsp;- which is very nice, because otherwise
you'd be building every program from scratch.
The function
definitions are kept in <EM
CLASS="emphasis"
>libraries</EM
>, which are generally 
installed on your system in <EM
CLASS="emphasis"
>/usr/lib/</EM
> with a <EM
CLASS="emphasis"
>lib</EM
> prefix
and a <EM
CLASS="emphasis"
>.a</EM
> suffix (for example, <EM
CLASS="emphasis"
>/usr/lib/libc.a</EM
>).</P
><P
CLASS="para"
>Functions also have to be <EM
CLASS="emphasis"
>declared</EM
> in the
program.
Function declarations are kept in <EM
CLASS="emphasis"
>header</EM
> or
<EM
CLASS="emphasis"
>include</EM
> files, which are generally installed on your system in
<EM
CLASS="emphasis"
>/usr/include/</EM
> with <EM
CLASS="emphasis"
>.h</EM
> suffixes (for example,
<EM
CLASS="emphasis"
>/usr/include/stdio.h</EM
>).</P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63772"
></A
>If you use functions that are defined in libraries (and you most
definitely will), you need to make sure that when the program is
compiled, it is <EM
CLASS="emphasis"
>linked</EM
> to the libraries it needs.
You also have
to make sure that the proper header files are read by your program,
since the program won't compile unless all functions have been
declared.  </P
><P
CLASS="para"
>For example, if you need to take the square root of a number in your
program, you need to use the <EM
CLASS="emphasis"
>sqrt()</EM
> function.
This function
resides in the Math library.
This means that
you need to link the program with <EM
CLASS="emphasis"
>libm.a</EM
> and you need to read in
the <EM
CLASS="emphasis"
>math.h</EM
> header file (which declares <EM
CLASS="emphasis"
>sqrt()</EM
>).
So

in 
the program, you need to have the following line near the top of the
source file:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>#include &lt;math.h&gt;</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>and when you compile the program, you need to use the <EM
CLASS="emphasis"
>-l</EM
>
(lowercase L) command-line option to link with <EM
CLASS="emphasis"
>libm</EM
>:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>cc -o </B
></CODE
><CODE
CLASS="replaceable"
><I
>file file</I
></CODE
><CODE
CLASS="userinput"
><B
>.c -lm</B
></CODE
></PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>&#13;Note the following facts:</P
><UL
CLASS="itemizedlist"
><LI
CLASS="listitem"
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63795"
></A
>Unless you name the executable file with <CODE
CLASS="literal"
>-o&nbsp;</CODE
><CODE
CLASS="replaceable"
><I
>file</I
></CODE
>,
<EM
CLASS="emphasis"
>cc</EM
> will name it <EM
CLASS="emphasis"
>a.out</EM
>.</P
></LI
><LI
CLASS="listitem"
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63803"
></A
>The source filename must end with a <EM
CLASS="emphasis"
>.c</EM
> suffix.</P
></LI
><LI
CLASS="listitem"
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63808"
></A
><A
CLASS="indexterm"
NAME="AUTOID-63811"
></A
>Since <EM
CLASS="emphasis"
>math.h</EM
> lives in <EM
CLASS="emphasis"
>/usr/include</EM
>, you don't need to give
its absolute pathname on the <CODE
CLASS="literal"
>#include</CODE
> line, just put the name
of the header file between angle brackets as shown.
<SPAN
CLASS="link"
>Relative pathnames (<A
CLASS="linkend"
HREF="ch14_02.htm"
TITLE="Using Relative and Absolute Pathnames "
>14.2</A
>)</SPAN
>
starting at <EM
CLASS="emphasis"
>/usr/include</EM
> can be used in angle brackets.
For instance, <CODE
CLASS="literal"
>&lt;sys/foo.h&gt;</CODE
> means <EM
CLASS="emphasis"
>/usr/include/sys/foo.h</EM
>.</P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63822"
></A
><A
CLASS="indexterm"
NAME="AUTOID-63824"
></A
>By default,
<EM
CLASS="emphasis"
>cc</EM
> looks for header files in <EM
CLASS="emphasis"
>/usr/include</EM
>, and you can
have it look automatically in other directories by specifying
them with the <EM
CLASS="emphasis"
>-I</EM
> command-line option.
If you want to use a header file in directory that isn't
searched by default, supply its
absolute or relative pathname in double quotes instead.</P
></LI
><LI
CLASS="listitem"
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63832"
></A
>When linking with a library on the command line, you should put
the <EM
CLASS="emphasis"
>-l</EM
> options at the end. 
If you use more than one library, you'll need more than one
<EM
CLASS="emphasis"
>-l</EM
> option.
The order of the <EM
CLASS="emphasis"
>-l</EM
> options is important; check the
documentation or look for a comment in the source code.</P
></LI
><LI
CLASS="listitem"
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63840"
></A
>The compiler found <EM
CLASS="emphasis"
>libm.a</EM
> because it was in <EM
CLASS="emphasis"
>/usr/lib</EM
>,
which it searches by default.
If you want it to use a library
in another directory, you may need to supply the directory using the <EM
CLASS="emphasis"
>-L</EM
>
command-line option.</P
></LI
></UL
><P
CLASS="para"
>As you can imagine, there's much more to know.
But that's the
general idea of compiling C programs on UNIX systems, and it's
about as much as we can tell you without starting to teach you C.</P
></DIV
><DIV
CLASS="sect3"
><H4
CLASS="sect3"
><A
CLASS="title"
NAME="UPT-ART-3840-SECT-1.2.8"
>52.8.2.8 The make Program </A
></H4
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63850"
></A
>When you're writing a simple C program, you can simply compile the
program using <EM
CLASS="emphasis"
>cc</EM
>:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>cc test.c</B
></CODE
></PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>But more complicated programs (like many of the programs on 
the CD-ROM) require a bit more work.
More complicated
programs are easier to handle if you write them in <EM
CLASS="emphasis"
>modules</EM
>.
So, for example, the <EM
CLASS="emphasis"
>pcal</EM
> source tree on the CD-ROM
contains several <EM
CLASS="emphasis"
>.c</EM
> files: <EM
CLASS="emphasis"
>exprpars.c</EM
>, <EM
CLASS="emphasis"
>moonphas.c</EM
>, 
<EM
CLASS="emphasis"
>pcalinit.c</EM
>, <EM
CLASS="emphasis"
>pcalutil.c</EM
>, <EM
CLASS="emphasis"
>readfile.c</EM
>,
<EM
CLASS="emphasis"
>writefil.c</EM
>, and, of course, <EM
CLASS="emphasis"
>pcal.c</EM
>.
Each of these
source files needs to be compiled separately into <EM
CLASS="emphasis"
>object files</EM
>
(with <EM
CLASS="emphasis"
>.o</EM
> suffixes).
If you give the <EM
CLASS="emphasis"
>-c</EM
> option, <EM
CLASS="emphasis"
>cc</EM
> will compile
&quot;<EM
CLASS="emphasis"
>.c</EM
> files&quot; into &quot;<EM
CLASS="emphasis"
>.o</EM
> files&quot; and stop without making the
finished executable.
When you run <EM
CLASS="emphasis"
>cc</EM
> again&nbsp;- but give it the <EM
CLASS="emphasis"
>.o</EM
> filenames
(<EM
CLASS="emphasis"
>exprpars.o</EM
>, <EM
CLASS="emphasis"
>moonphas.o</EM
>, and so on)
it will link all those object files with the libraries and make the
executable file.</P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63879"
></A
>This makes compilation a bit harder to keep track of.
There are a lot
more steps.
Furthermore, it means that whenever a file is changed, 
you have to remember not only to recompile it but also to relink
the entire program.  </P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63882"
></A
><A
CLASS="indexterm"
NAME="AUTOID-63884"
></A
>This is a job for the <EM
CLASS="emphasis"
>make</EM
> program.
We showed uses for <EM
CLASS="emphasis"
>make</EM
>
in articles 
<A
CLASS="xref"
HREF="ch21_09.htm"
TITLE="Keep File Printouts Up-to-Date Automatically with make"
>21.9</A
>
and 
<A
CLASS="xref"
HREF="ch28_13.htm"
TITLE="make Isn't Just for Programmers! "
>28.13</A
>,
but this is what it was really meant for.
The <EM
CLASS="emphasis"
>pcal</EM
> source tree comes with a file called <EM
CLASS="emphasis"
>Makefile</EM
>.
(Actually, it comes with several different <EM
CLASS="emphasis"
>Makefile</EM
>s for
different platforms, but that's another issue.)
The <EM
CLASS="emphasis"
>Makefile</EM
>
keeps track of each of the programs and each of their dependencies.
It also keeps track of any command-line options you might want passed
to <EM
CLASS="emphasis"
>cc</EM
>, including libraries to link to.
The result is that when you want to make the <EM
CLASS="emphasis"
>pcal</EM
> program,
all you need to do is type:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>make pcal</B
></CODE
></PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>Or, even better, just:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>% <CODE
CLASS="userinput"
><B
>make</B
></CODE
></PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>This is a lot easier than trying to keep track of all the modules and
command-line options yourself.</P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63906"
></A
>So if you can't compile a program because the header file it needs is
installed in a non-standard place, you'd specify that in the
<EM
CLASS="emphasis"
>Makefile</EM
>.
You could add the appropriate <EM
CLASS="emphasis"
>-I</EM
>
option to the <CODE
CLASS="literal"
>COPTS</CODE
> declaration line:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>COPTS    = -I/usr/include/sys</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
>Or if you want to use a different compiler than <EM
CLASS="emphasis"
>cc</EM
>, you could
redefine that variable:</P
><P
CLASS="para"
><BLOCKQUOTE
CLASS="screen"
><PRE
CLASS="screen"
>CC       = /usr/local/bin/gcc</PRE
></BLOCKQUOTE
></P
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="AUTOID-63919"
></A
><A
CLASS="indexterm"
NAME="AUTOID-63921"
></A
><A
CLASS="indexterm"
NAME="AUTOID-63922"
></A
>Again, this is only the tip of the iceberg.
But a basic understanding
of libraries, header files, and
<EM
CLASS="emphasis"
>make</EM
> has helped me build many programs that wouldn't compile
the first time.
For help with <EM
CLASS="emphasis"
>make</EM
>, see O'Reilly &amp; Associates' <EM
CLASS="emphasis"
>Managing Projects
with make</EM
> by Andrew Oram and Steve Talbott.</P
></DIV
></DIV
><DIV
CLASS="sect1info"
><P
CLASS="SECT1INFO"
>- <SPAN
CLASS="authorinitials"
>LM</SPAN
>, <SPAN
CLASS="authorinitials"
>EP</SPAN
></P
></DIV
></DIV
><DIV
CLASS="htmlnav"
><P
></P
><HR
ALIGN="LEFT"
WIDTH="515"
TITLE="footer"><TABLE
WIDTH="515"
BORDER="0"
CELLSPACING="0"
CELLPADDING="0"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="172"
><A
CLASS="SECT1"
HREF="ch52_07.htm"
TITLE="52.7 Other Ways to Get the Software "
><IMG
SRC="gifs/txtpreva.gif"
SRC="gifs/txtpreva.gif"
ALT="Previous: 52.7 Other Ways to Get the Software "
BORDER="0"></A
></TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
WIDTH="171"
><A
CLASS="book"
HREF="index.htm"
TITLE="UNIX Power Tools"
><IMG
SRC="gifs/txthome.gif"
SRC="gifs/txthome.gif"
ALT="UNIX Power Tools"
BORDER="0"></A
></TD
><TD
ALIGN="RIGHT"
VALIGN="TOP"
WIDTH="172"
><A
CLASS="SECT1"
HREF="ch52_09.htm"
TITLE="52.9 Software Support from RTR "
><IMG
SRC="gifs/txtnexta.gif"
SRC="gifs/txtnexta.gif"
ALT="Next: 52.9 Software Support from RTR "
BORDER="0"></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="172"
>52.7 Other Ways to Get the Software </TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
WIDTH="171"
><A
CLASS="index"
HREF="index/idx_0.htm"
TITLE="Book Index"
><IMG
SRC="gifs/index.gif"
SRC="gifs/index.gif"
ALT="Book Index"
BORDER="0"></A
></TD
><TD
ALIGN="RIGHT"
VALIGN="TOP"
WIDTH="172"
>52.9 Software Support from RTR </TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="515"
TITLE="footer"><IMG
SRC="gifs/smnavbar.gif"
SRC="gifs/smnavbar.gif"
USEMAP="#map"
BORDER="0"
ALT="The UNIX CD Bookshelf Navigation"><MAP
NAME="map"
><AREA
SHAPE="RECT"
COORDS="0,0,73,21"
HREF="../index.htm"
ALT="The UNIX CD Bookshelf"><AREA
SHAPE="RECT"
COORDS="74,0,163,21"
HREF="index.htm"
ALT="UNIX Power Tools"><AREA
SHAPE="RECT"
COORDS="164,0,257,21"
HREF="../unixnut/index.htm"
ALT="UNIX in a Nutshell"><AREA
SHAPE="RECT"
COORDS="258,0,321,21"
HREF="../vi/index.htm"
ALT="Learning the vi Editor"><AREA
SHAPE="RECT"
COORDS="322,0,378,21"
HREF="../sedawk/index.htm"
ALT="sed &amp; awk"><AREA
SHAPE="RECT"
COORDS="379,0,438,21"
HREF="../ksh/index.htm"
ALT="Learning the Korn Shell"><AREA
SHAPE="RECT"
COORDS="439,0,514,21"
HREF="../lrnunix/index.htm"
ALT="Learning the UNIX Operating System"></MAP
></DIV
></BODY
></HTML
>