svn commit: r52141 - head/en_US.ISO8859-1/books/developers-handbook/tools
Benedict Reuschling
bcr at FreeBSD.org
Thu Aug 16 15:59:01 UTC 2018
Author: bcr
Date: Thu Aug 16 15:59:00 2018
New Revision: 52141
URL: https://svnweb.freebsd.org/changeset/doc/52141
Log:
Cleanup this file:
- wrap overlong lines
- proper indentation of elements
- capitalization in title tags
Modified:
head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
Modified: head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml Thu Aug 16 15:34:22 2018 (r52140)
+++ head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml Thu Aug 16 15:59:00 2018 (r52141)
@@ -4,16 +4,31 @@
$FreeBSD$
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools">
- <info><title>Programming Tools</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="tools">
+ <info>
+ <title>Programming Tools</title>
+
<authorgroup>
- <author><personname><firstname>James</firstname><surname>Raynard</surname></personname><contrib>Contributed by </contrib></author>
- <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author>
+ <author>
+ <personname>
+ <firstname>James</firstname>
+ <surname>Raynard</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+ <author>
+ <personname>
+ <firstname>Murray</firstname>
+ <surname>Stokely</surname>
+ </personname>
+ </author>
</authorgroup>
</info>
-
- <sect1 xml:id="tools-synopsis"><title>Synopsis</title>
+ <sect1 xml:id="tools-synopsis">
+ <title>Synopsis</title>
<para>This chapter is an introduction to using some of the
programming tools supplied with FreeBSD, although much of it
@@ -22,24 +37,24 @@
detail. Most of the chapter assumes little or no previous
programming knowledge, although it is hoped that most
programmers will find something of value in it.</para>
-
</sect1>
- <sect1 xml:id="tools-intro"><title>Introduction</title>
+ <sect1 xml:id="tools-intro">
+ <title>Introduction</title>
<para>FreeBSD offers an excellent development environment.
- Compilers for C and C++ and an assembler come with the
- basic system, not to mention classic &unix;
- tools such as <command>sed</command> and <command>awk</command>.
- If that is not enough, there are many more compilers and
- interpreters in the Ports collection. The following section,
- <link linkend="tools-programming">Introduction to Programming</link>,
- lists some of the available options. FreeBSD is very
- compatible with standards such as <acronym>&posix;</acronym> and
- <acronym>ANSI</acronym> C, as well with its own BSD heritage, so
- it is possible to write applications that will compile and run
- with little or no modification on a wide range of
- platforms.</para>
+ Compilers for C and C++ and an assembler come with the basic
+ system, not to mention classic &unix; tools such as
+ <command>sed</command> and <command>awk</command>. If that is
+ not enough, there are many more compilers and interpreters in
+ the Ports collection. The following section, <link
+ linkend="tools-programming">Introduction to
+ Programming</link>, lists some of the available options.
+ FreeBSD is very compatible with standards such as
+ <acronym>&posix;</acronym> and <acronym>ANSI</acronym> C, as
+ well with its own BSD heritage, so it is possible to write
+ applications that will compile and run with little or no
+ modification on a wide range of platforms.</para>
<para>However, all this power can be rather overwhelming at first
if you have never written programs on a &unix; platform before.
@@ -95,26 +110,26 @@
start if you have not done any programming before. This kind
of environment is typically found with languages like Lisp,
Smalltalk, Perl and Basic. It could also be argued that the
- &unix; shell (<command>sh</command>, <command>csh</command>) is itself an
- interpreter, and many people do in fact write shell
- <quote>scripts</quote> to help with various
- <quote>housekeeping</quote> tasks on their machine. Indeed, part
- of the original &unix; philosophy was to provide lots of small
- utility programs that could be linked together in shell
+ &unix; shell (<command>sh</command>, <command>csh</command>)
+ is itself an interpreter, and many people do in fact write
+ shell <quote>scripts</quote> to help with various
+ <quote>housekeeping</quote> tasks on their machine. Indeed,
+ part of the original &unix; philosophy was to provide lots of
+ small utility programs that could be linked together in shell
scripts to perform useful tasks.</para>
</sect2>
<sect2>
- <title>Interpreters available with FreeBSD</title>
+ <title>Interpreters Available with FreeBSD</title>
- <para>Here is a list of interpreters that are available from
- the &os; Ports Collection, with a brief discussion of
- some of the more popular interpreted languages.</para>
+ <para>Here is a list of interpreters that are available from the
+ &os; Ports Collection, with a brief discussion of some of the
+ more popular interpreted languages.</para>
- <para>Instructions on how to get and install applications
- from the Ports Collection can be found in the
- <link xlink:href="&url.books.handbook;/ports-using.html">
- Ports section</link> of the handbook.</para>
+ <para>Instructions on how to get and install applications from
+ the Ports Collection can be found in the <link
+ xlink:href="&url.books.handbook;/ports-using.html">Ports
+ section</link> of the handbook.</para>
<variablelist>
<varlistentry>
@@ -126,14 +141,13 @@
University students to program and provided with every
self-respecting personal computer in the 1980s,
<acronym>BASIC</acronym> has been the first programming
- language for many programmers. It is also the foundation
- for Visual Basic.</para>
+ language for many programmers. It is also the
+ foundation for Visual Basic.</para>
<para>The Bywater Basic Interpreter can be found in the
- Ports Collection as
- <package>lang/bwbasic</package>
- and the Phil Cockroft's Basic Interpreter
- (formerly Rabbit Basic) is available as
+ Ports Collection as <package>lang/bwbasic</package> and
+ the Phil Cockroft's Basic Interpreter (formerly Rabbit
+ Basic) is available as
<package>lang/pbasic</package>.</para>
</listitem>
</varlistentry>
@@ -153,16 +167,16 @@
<para>Lisp is an extremely powerful and sophisticated
language, but can be rather large and unwieldy.</para>
- <para>Various implementations of Lisp that can run on &unix;
- systems are available in the Ports Collection for &os;.
- GNU Common Lisp can be found as
- <package>lang/gcl</package>. CLISP
- by Bruno Haible and Michael Stoll is available as
- <package>lang/clisp</package>.
- For CMUCL, which includes a highly-optimizing compiler too, or
- simpler Lisp implementations like SLisp, which implements most
- of the Common Lisp constructs in a few hundred lines of C code,
- <package>lang/cmucl</package> and
+ <para>Various implementations of Lisp that can run on
+ &unix; systems are available in the Ports Collection for
+ &os;. GNU Common Lisp can be found as
+ <package>lang/gcl</package>. CLISP by Bruno Haible and
+ Michael Stoll is available as
+ <package>lang/clisp</package>. For CMUCL, which
+ includes a highly-optimizing compiler too, or simpler
+ Lisp implementations like SLisp, which implements most
+ of the Common Lisp constructs in a few hundred lines of
+ C code, <package>lang/cmucl</package> and
<package>lang/slisp</package> are available
respectively.</para>
</listitem>
@@ -221,11 +235,12 @@
<para>Logo is a language that is easy to learn, and has
been used as an introductory programming language in
various courses. It is an excellent tool to work with
- when teaching programming to smaller age groups, as it makes
- creation of elaborate geometric shapes an easy task.</para>
+ when teaching programming to smaller age groups, as it
+ makes creation of elaborate geometric shapes an easy
+ task.</para>
- <para>The latest version of Logo for &os; is available from
- the Ports Collection in
+ <para>The latest version of Logo for &os; is available
+ from the Ports Collection in
<package>lang/logo</package>.</para>
</listitem>
</varlistentry>
@@ -239,8 +254,9 @@
to start programming with, since it is relatively easy
to start with, but is not limited in comparison to other
popular interpreted languages that are used for the
- development of large, complex applications (Perl and
- Tcl are two other languages that are popular for such tasks).</para>
+ development of large, complex applications (Perl and Tcl
+ are two other languages that are popular for such
+ tasks).</para>
<para>The latest version of Python is available from the
Ports Collection in
@@ -252,11 +268,11 @@
<term>Ruby</term>
<listitem>
- <para>Ruby is an interpreter, pure object-oriented programming
- language. It has become widely popular because of its easy
- to understand syntax, flexibility when writing code, and the
- ability to easily develop and maintain large, complex
- programs.</para>
+ <para>Ruby is an interpreter, pure object-oriented
+ programming language. It has become widely popular
+ because of its easy to understand syntax, flexibility
+ when writing code, and the ability to easily develop and
+ maintain large, complex programs.</para>
<para>Ruby is available from the Ports Collection as
<package>lang/ruby25</package>.</para>
@@ -268,14 +284,14 @@
<listitem>
<para>Tcl is an embeddable, interpreted language, that has
- become widely used and became popular mostly because of its portability to many
- platforms. It can be used both for quickly writing
- small, prototype applications, or (when combined with
- Tk, a GUI toolkit) fully-fledged, featureful
- programs.</para>
+ become widely used and became popular mostly because of
+ its portability to many platforms. It can be used both
+ for quickly writing small, prototype applications, or
+ (when combined with Tk, a GUI toolkit) fully-fledged,
+ featureful programs.</para>
- <para>Various versions of Tcl are available as ports
- for &os;. The latest version, Tcl 8.5, can be found in
+ <para>Various versions of Tcl are available as ports for
+ &os;. The latest version, Tcl 8.5, can be found in
<package>lang/tcl87</package>.</para>
</listitem>
</varlistentry>
@@ -291,13 +307,9 @@
not compile, grit your teeth and go back to the editor; if it
did compile and gave you a program, you can run it either at a
shell command prompt or in a debugger to see if it works
- properly.
+ properly.<footnote><para>If you run it in the shell, you may
+ get a core dump.</para></footnote></para>
- <footnote>
- <para>If you run it in the shell, you may get a core
- dump.</para>
- </footnote></para>
-
<para>Obviously, this is not quite as direct as using an
interpreter. However it allows you to do a lot of things
which are very difficult or even impossible with an
@@ -315,11 +327,11 @@
using separate programs, many commercial compiler makers have
produced Integrated Development Environments
(<acronym>IDE</acronym>s for short). FreeBSD does not include
- an IDE in the base system, but <package>devel/kdevelop</package> is
- available in the Ports Collection and many use
- <application>Emacs</application> for this purpose. Using
- <application>Emacs</application> as an IDE is discussed in
- <xref linkend="emacs"/>.</para>
+ an IDE in the base system, but
+ <package>devel/kdevelop</package> is available in the Ports
+ Collection and many use <application>Emacs</application> for
+ this purpose. Using <application>Emacs</application> as an
+ IDE is discussed in <xref linkend="emacs"/>.</para>
</sect2>
</sect1>
@@ -331,11 +343,10 @@
and <application>clang</application> compilers for C and C++,
since they come with the &os; base system. Starting with
&os; 10.X <command>clang</command> is installed as
- <command>cc</command>. The
- details of producing a program with an interpreter vary
- considerably between interpreters, and are usually well covered
- in the documentation and on-line help for the
- interpreter.</para>
+ <command>cc</command>. The details of producing a program with
+ an interpreter vary considerably between interpreters, and are
+ usually well covered in the documentation and on-line help for
+ the interpreter.</para>
<para>Once you have written your masterpiece, the next step is to
convert it into something that will (hopefully!) run on FreeBSD.
@@ -390,21 +401,22 @@
</step>
</procedure>
- <para>The word <firstterm>compiling</firstterm> is often used to refer to
- just steps 1 to 4—the others are referred to as
- <firstterm>linking</firstterm>. Sometimes step 1 is referred to as
- <firstterm>pre-processing</firstterm> and steps 3-4 as
+ <para>The word <firstterm>compiling</firstterm> is often used to
+ refer to just steps 1 to 4—the others are referred to as
+ <firstterm>linking</firstterm>. Sometimes step 1 is referred to
+ as <firstterm>pre-processing</firstterm> and steps 3-4 as
<firstterm>assembling</firstterm>.</para>
<para>Fortunately, almost all this detail is hidden from you, as
- <command>cc</command> is a front end that manages calling all these
- programs with the right arguments for you; simply typing</para>
+ <command>cc</command> is a front end that manages calling all
+ these programs with the right arguments for you; simply
+ typing</para>
<screen>&prompt.user; <userinput>cc foobar.c</userinput></screen>
- <para>will cause <filename>foobar.c</filename> to be compiled by all the
- steps above. If you have more than one file to compile, just do
- something like</para>
+ <para>will cause <filename>foobar.c</filename> to be compiled by
+ all the steps above. If you have more than one file to compile,
+ just do something like</para>
<screen>&prompt.user; <userinput>cc foo.c bar.c</userinput></screen>
@@ -412,32 +424,28 @@
the syntax. It will not check for any logical mistakes you may
have made, like putting the program into an infinite loop, or
using a bubble sort when you meant to use a binary
- sort.
+ sort.<footnote><para>In case you did not know, a binary sort is
+ an efficient way of sorting things into order and a bubble
+ sort is not.</para></footnote></para>
- <footnote>
- <para>In case you did not know, a binary sort is an efficient
- way of sorting things into order and a bubble sort
- is not.</para>
- </footnote></para>
+ <para>There are lots and lots of options for
+ <command>cc</command>, which are all in the manual page. Here
+ are a few of the most important ones, with examples of how to
+ use them.</para>
- <para>There are lots and lots of options for <command>cc</command>, which
- are all in the manual page. Here are a few of the most important
- ones, with examples of how to use them.</para>
-
<variablelist>
<varlistentry>
- <term><option>-o <replaceable>filename</replaceable></option></term>
+ <term>
+ <option>-o <replaceable>filename</replaceable></option>
+ </term>
<listitem>
<para>The output name of the file. If you do not use this
- option, <command>cc</command> will produce an executable called
- <filename>a.out</filename>.
+ option, <command>cc</command> will produce an executable
+ called <filename>a.out</filename>.<footnote><para>The
+ reasons for this are buried in the mists of
+ history.</para></footnote></para>
- <footnote>
- <para>The reasons for this are buried in the mists of
- history.</para>
- </footnote></para>
-
<informalexample>
<screen>&prompt.user; <userinput>cc foobar.c</userinput> <lineannotation>executable is a.out</lineannotation>
&prompt.user; <userinput>cc -o foobar foobar.c</userinput> <lineannotation>executable is foobar</lineannotation></screen>
@@ -457,9 +465,10 @@
<screen>&prompt.user; <userinput>cc -c foobar.c</userinput></screen>
</informalexample>
- <para>This will produce an <firstterm>object file</firstterm> (not an
- executable) called <filename>foobar.o</filename>. This
- can be linked together with other object files into an
+ <para>This will produce an <firstterm>object
+ file</firstterm> (not an executable) called
+ <filename>foobar.o</filename>. This can be linked
+ together with other object files into an
executable.</para>
</listitem>
</varlistentry>
@@ -471,14 +480,15 @@
<para>Create a debug version of the executable. This makes
the compiler put information into the executable about
which line of which source file corresponds to which
- function call. A debugger can use this information to show
- the source code as you step through the program, which is
- <emphasis>very</emphasis> useful; the disadvantage is that
- all this extra information makes the program much bigger.
- Normally, you compile with <option>-g</option> while you
- are developing a program and then compile a <quote>release
- version</quote> without <option>-g</option> when you are
- satisfied it works properly.</para>
+ function call. A debugger can use this information to
+ show the source code as you step through the program,
+ which is <emphasis>very</emphasis> useful; the
+ disadvantage is that all this extra information makes the
+ program much bigger. Normally, you compile with
+ <option>-g</option> while you are developing a program and
+ then compile a <quote>release version</quote> without
+ <option>-g</option> when you are satisfied it works
+ properly.</para>
<informalexample>
<screen>&prompt.user; <userinput>cc -g foobar.c</userinput></screen>
@@ -493,8 +503,7 @@
executable called <filename>a.out</filename>.
Producing a debug version called
<filename>foobar</filename> is left as an exercise for
- the reader!</para>
- </footnote></para>
+ the reader!</para></footnote></para>
</listitem>
</varlistentry>
@@ -586,7 +595,8 @@
<term><option>-l<replaceable>library</replaceable></option></term>
<listitem>
- <para>Specify a function library to be used at link time.</para>
+ <para>Specify a function library to be used at link
+ time.</para>
<para>The most common example of this is when compiling a
program that uses some of the mathematical functions in C.
@@ -613,8 +623,8 @@
<filename>foobar</filename>.</para>
<para>If you are compiling C++ code, use
- <command>c++</command>. <command>c++</command> can also be
- invoked as <command>clang++</command> on &os;.</para>
+ <command>c++</command>. <command>c++</command> can also
+ be invoked as <command>clang++</command> on &os;.</para>
<informalexample>
<screen>&prompt.user; <userinput>c++ -o foobar foobar.cc</userinput></screen>
@@ -669,8 +679,7 @@ int main() {
f = pow(2.1, 6);
printf("2.1 ^ 6 = %f\n", f);
return 0;
-}
- </programlisting>
+}</programlisting>
</informalexample>
<para>and I compiled it as:</para>
@@ -717,8 +726,7 @@ int main() {
#include <stdio.h>
int main() {
-...
- </programlisting>
+...</programlisting>
</informalexample>
<para>After recompiling it as you did before, run
@@ -740,8 +748,8 @@ int main() {
<question>
<para>I compiled a file called
<filename>foobar.c</filename> and I cannot find an
- executable called <filename>foobar</filename>. Where has
- it gone?</para>
+ executable called <filename>foobar</filename>. Where
+ has it gone?</para>
</question>
<answer>
@@ -768,12 +776,11 @@ int main() {
</question>
<answer>
- <para>Unlike &ms-dos;, &unix; does not
- look in the current directory when it is trying to find
- out which executable you want it to run, unless you tell
- it to. Type <command>./foobar</command>, which
- means <quote>run the file called
- <filename>foobar</filename> in the current
+ <para>Unlike &ms-dos;, &unix; does not look in the current
+ directory when it is trying to find out which executable
+ you want it to run, unless you tell it to. Type
+ <command>./foobar</command>, which means <quote>run the
+ file called <filename>foobar</filename> in the current
directory.</quote></para>
</answer>
</qandaentry>
@@ -803,8 +810,8 @@ int main() {
<question>
<para>I compiled my program and it seemed to run all right
at first, then there was an error and it said something
- about <errorname>core dumped</errorname>. What does that
- mean?</para>
+ about <errorname>core dumped</errorname>. What does
+ that mean?</para>
</question>
<answer>
@@ -851,8 +858,7 @@ int main() {
pointer, eg</para>
<programlisting>char *foo = NULL;
-strcpy(foo, "bang!");
- </programlisting>
+strcpy(foo, "bang!");</programlisting>
</listitem>
<listitem>
@@ -860,12 +866,11 @@ strcpy(foo, "bang!");
eg</para>
<programlisting>char *foo;
-strcpy(foo, "bang!");
- </programlisting>
+strcpy(foo, "bang!");</programlisting>
<para>The pointer will have some random value that,
- with luck, will point into an area of memory that
- is not available to your program and the kernel will
+ with luck, will point into an area of memory that is
+ not available to your program and the kernel will
kill your program before it can do any damage. If
you are unlucky, it will point somewhere inside your
own program and corrupt one of your data structures,
@@ -877,8 +882,7 @@ strcpy(foo, "bang!");
eg</para>
<programlisting>int bar[20];
-bar[27] = 6;
- </programlisting>
+bar[27] = 6;</programlisting>
</listitem>
<listitem>
@@ -886,8 +890,7 @@ bar[27] = 6;
eg</para>
<programlisting>char *foo = "My string";
-strcpy(foo, "bang!");
- </programlisting>
+strcpy(foo, "bang!");</programlisting>
<para>&unix; compilers often put string literals like
<literal>"My string"</literal> into read-only areas
@@ -900,15 +903,13 @@ strcpy(foo, "bang!");
<function>free()</function>, eg</para>
<programlisting>char bar[80];
-free(bar);
- </programlisting>
+free(bar);</programlisting>
<para>or</para>
<programlisting>char *foo = malloc(27);
free(foo);
-free(foo);
- </programlisting>
+free(foo);</programlisting>
</listitem>
</itemizedlist>
@@ -966,14 +967,14 @@ free(foo);
<para>Alternatively, you can create a core dump from
inside your program, by calling the
- <function>abort()</function> function. See the manual page
- of &man.abort.3; to learn more.</para>
+ <function>abort()</function> function. See the manual
+ page of &man.abort.3; to learn more.</para>
- <para>If you want to create a core dump from outside your
- program, but do not want the process to terminate, you
- can use the <command>gcore</command> program. See the
- manual page of &man.gcore.1; for more information.</para>
-
+ <para>If you want to create a core dump from outside your
+ program, but do not want the process to terminate, you
+ can use the <command>gcore</command> program. See the
+ manual page of &man.gcore.1; for more
+ information.</para>
</answer>
</qandaentry>
</qandaset>
@@ -1001,8 +1002,8 @@ free(foo);
<screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> …</screen>
- <para>if we had changed <filename>file37.c</filename>, but not any
- of the others, since the last time we compiled. This may
+ <para>if we had changed <filename>file37.c</filename>, but not
+ any of the others, since the last time we compiled. This may
speed up the compilation quite a bit, but does not solve the
typing problem.</para>
@@ -1039,17 +1040,14 @@ free(foo);
or <filename>MAKEFILE</filename>. Most programmers use the
name <filename>Makefile</filename>, as this puts it near the
top of a directory listing, where it can easily be
- seen.
-
- <footnote>
- <para>They do not use the <filename>MAKEFILE</filename> form
- as block capitals are often used for documentation files
- like <filename>README</filename>.</para>
- </footnote></para>
+ seen.<footnote><para>They do not use the
+ <filename>MAKEFILE</filename> form as block capitals are
+ often used for documentation files like
+ <filename>README</filename>.</para></footnote></para>
</sect2>
<sect2>
- <title>Example of using <command>make</command></title>
+ <title>Example of Using <command>make</command></title>
<para>Here is a very simple make file:</para>
@@ -1073,12 +1071,12 @@ free(foo);
re-compiled.</para>
<para>The creation line starts with a <token>tab</token> (press
- the <keycap>tab</keycap> key) and then the command you would
- type to create <filename>foo</filename> if you were doing it
- at a command prompt. If <filename>foo</filename> is out of
- date, or does not exist, <command>make</command> then executes
- this command to create it. In other words, this is the rule
- which tells make how to re-compile
+ <keycap>tab</keycap>) and then the command you would type to
+ create <filename>foo</filename> if you were doing it at a
+ command prompt. If <filename>foo</filename> is out of date,
+ or does not exist, <command>make</command> then executes this
+ command to create it. In other words, this is the rule which
+ tells make how to re-compile
<filename>foo.c</filename>.</para>
<para>So, when you type <userinput>make</userinput>, it will
@@ -1091,8 +1089,8 @@ free(foo);
world</userinput> in the appropriate directory!</para>
<para>Another useful property of makefiles is that the targets
- do not have to be programs. For instance, we could have a make
- file that looks like this:</para>
+ do not have to be programs. For instance, we could have a
+ make file that looks like this:</para>
<programlisting>foo: foo.c
cc -o foo foo.c
@@ -1108,7 +1106,8 @@ install:
<para><command>make</command> will then only look at that target
and ignore any others. For example, if we type
<userinput>make foo</userinput> with the makefile above, make
- will ignore the <buildtarget>install</buildtarget> target.</para>
+ will ignore the <buildtarget>install</buildtarget>
+ target.</para>
<para>If we just type <userinput>make</userinput> on its own,
make will always look at the first target and then stop
@@ -1116,36 +1115,36 @@ install:
<userinput>make</userinput> here, it will just go to the
<buildtarget>foo</buildtarget> target, re-compile
<filename>foo</filename> if necessary, and then stop without
- going on to the <buildtarget>install</buildtarget> target.</para>
+ going on to the <buildtarget>install</buildtarget>
+ target.</para>
- <para>Notice that the <buildtarget>install</buildtarget> target does not
- actually depend on anything! This means that the command on
- the following line is always executed when we try to make that
- target by typing <userinput>make install</userinput>. In this
- case, it will copy <filename>foo</filename> into the user's
- home directory. This is often used by application makefiles,
- so that the application can be installed in the correct
- directory when it has been correctly compiled.</para>
+ <para>Notice that the <buildtarget>install</buildtarget> target
+ does not actually depend on anything! This means that the
+ command on the following line is always executed when we try
+ to make that target by typing <userinput>make
+ install</userinput>. In this case, it will copy
+ <filename>foo</filename> into the user's home directory. This
+ is often used by application makefiles, so that the
+ application can be installed in the correct directory when it
+ has been correctly compiled.</para>
<para>This is a slightly confusing subject to try to explain.
If you do not quite understand how <command>make</command>
works, the best thing to do is to write a simple program like
<quote>hello world</quote> and a make file like the one above
and experiment. Then progress to using more than one source
- file, or having the source file include a header file. The
- <command>touch</command> command is very useful here—it
- changes the date on a file without you having to edit
- it.</para>
+ file, or having the source file include a header file.
+ <command>touch</command> is very useful here—it changes
+ the date on a file without you having to edit it.</para>
</sect2>
<sect2>
<title>Make and include-files</title>
<para>C code often starts with a list of files to include, for
- example stdio.h. Some of these files are system-include
+ example stdio.h. Some of these files are system-include
files, some of them are from the project you are now working
- on:
- </para>
+ on:</para>
<programlisting>#include <stdio.h>
#include "foo.h"
@@ -1153,20 +1152,19 @@ install:
int main(....</programlisting>
<para>To make sure that this file is recompiled the moment
- <filename>foo.h</filename> is changed, you have to add it in
- your <filename>Makefile</filename>:</para>
+ <filename>foo.h</filename> is changed, you have to add it in
+ your <filename>Makefile</filename>:</para>
<programlisting>foo: foo.c foo.h</programlisting>
<para>The moment your project is getting bigger and you have
- more and more own include-files to maintain, it will be a
- pain to keep track of all include files and the files which
- are depending on it. If you change an include-file but
- forget to recompile all the files which are depending on
- it, the results will be devastating. <command>clang</command>
- has an option to analyze your files and to produce a list
- of include-files and their dependencies: <option>-MM</option>.
- </para>
+ more and more own include-files to maintain, it will be a pain
+ to keep track of all include files and the files which are
+ depending on it. If you change an include-file but forget to
+ recompile all the files which are depending on it, the results
+ will be devastating. <command>clang</command> has an option
+ to analyze your files and to produce a list of include-files
+ and their dependencies: <option>-MM</option>.</para>
<para>If you add this to your Makefile:</para>
@@ -1179,22 +1177,23 @@ int main(....</programlisting>
<programlisting>foo.o: foo.c foo.h</programlisting>
- <para>If you change <filename>foo.h</filename>, next time
- you run <command>make</command> all files depending on
+ <para>If you change <filename>foo.h</filename>, next time you
+ run <command>make</command> all files depending on
<filename>foo.h</filename> will be recompiled.</para>
<para>Do not forget to run <command>make depend</command> each
- time you add an include-file to one of your files.</para>
+ time you add an include-file to one of your files.</para>
</sect2>
<sect2>
<title>FreeBSD Makefiles</title>
- <para>Makefiles can be rather complicated to write. Fortunately,
- BSD-based systems like FreeBSD come with some very powerful
- ones as part of the system. One very good example of this is
- the FreeBSD ports system. Here is the essential part of a
- typical ports <filename>Makefile</filename>:</para>
+ <para>Makefiles can be rather complicated to write.
+ Fortunately, BSD-based systems like FreeBSD come with some
+ very powerful ones as part of the system. One very good
+ example of this is the FreeBSD ports system. Here is the
+ essential part of a typical ports
+ <filename>Makefile</filename>:</para>
<programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/
DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
@@ -1232,9 +1231,9 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
<step>
<para>Any special configuration needed for the source is
done. (Many &unix; program distributions try to work out
- which version of &unix; they are being compiled on and which
- optional &unix; features are present—this is where
- they are given the information in the FreeBSD ports
+ which version of &unix; they are being compiled on and
+ which optional &unix; features are present—this is
+ where they are given the information in the FreeBSD ports
scenario).</para>
</step>
@@ -1271,16 +1270,16 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
any errors that may occur) and anyone can get access to that
just by putting a single line in their own make file!</para>
- <para>If you want to have a look at these system makefiles,
- they are in <filename>/usr/share/mk</filename>, but it is
- probably best to wait until you have had a bit of practice with
+ <para>If you want to have a look at these system makefiles, they
+ are in <filename>/usr/share/mk</filename>, but it is probably
+ best to wait until you have had a bit of practice with
makefiles, as they are very complicated (and if you do look at
them, make sure you have a flask of strong coffee
handy!)</para>
</sect2>
<sect2>
- <title>More advanced uses of <command>make</command></title>
+ <title>More Advanced Uses of <command>make</command></title>
<para><command>Make</command> is a very powerful tool, and can
do much more than the simple example above shows.
@@ -1307,8 +1306,8 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
available as a port and package in its own right.</para>
<para>To view the info pages for <application>GNU
- make</application>, you will have to edit the
- <filename>dir</filename> file in the
+ make</application>, you will have to edit
+ <filename>dir</filename> in the
<filename>/usr/local/info</filename> directory to add an entry
for it. This involves adding a line like</para>
@@ -1344,10 +1343,10 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
program a line at a time, inspect the value of variables,
change them, tell the debugger to run up to a certain point
and then stop, and so on. You can even attach to a program
- that is already running, or load a core file to investigate why
- the program crashed. It is even possible to debug the kernel,
- though that is a little trickier than the user applications
- we will be discussing in this section.</para>
+ that is already running, or load a core file to investigate
+ why the program crashed. It is even possible to debug the
+ kernel, though that is a little trickier than the user
+ applications we will be discussing in this section.</para>
<para><command>gdb</command> has quite good on-line help, as
well as a set of info pages, so this section will concentrate
@@ -1364,19 +1363,18 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
</sect2>
<sect2>
- <title>Running a program in the debugger</title>
+ <title>Running a Program in the Debugger</title>
- <para>You will need to have compiled the program with the
- <option>-g</option> option to get the most out of using
- <command>gdb</command>. It will work without, but you will only
- see the name of the function you are in, instead of the source
- code. If you see a line like:</para>
+ <para>You will need to have compiled the program with
+ <option>-g</option> to get the most out of using
+ <command>gdb</command>. It will work without, but you will
+ only see the name of the function you are in, instead of the
+ source code. If you see a line like:</para>
<screen>… (no debugging symbols found) …</screen>
<para>when <command>gdb</command> starts up, you will know that
- the program was not compiled with the <option>-g</option>
- option.</para>
+ the program was not compiled with <option>-g</option>.</para>
<para>At the <command>gdb</command> prompt, type
<userinput>break main</userinput>. This will tell the
@@ -1392,10 +1390,10 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
<para>You can now step through the program, a line at a time, by
pressing <command>n</command>. If you get to a function call,
you can step into it by pressing <command>s</command>. Once
- you are in a function call, you can return from stepping into a
- function call by pressing <command>f</command>. You can also
- use <command>up</command> and <command>down</command> to take
- a quick look at the caller.</para>
+ you are in a function call, you can return from stepping into
+ a function call by pressing <command>f</command>. You can
+ also use <command>up</command> and <command>down</command> to
+ take a quick look at the caller.</para>
<para>Here is a simple example of how to spot a mistake in a
program with <command>gdb</command>. This is our program
@@ -1452,7 +1450,7 @@ bazz (anint=4231) at temp.c:17 <lineannotation>gdb d
<para>Hang on a minute! How did <symbol>anint</symbol> get to be
<literal>4231</literal>? Did we not we set it to be
- <literal>5</literal> in <function>main()</function>? Let's
+ <literal>5</literal> in <function>main()</function>? Let us
move up to <function>main()</function> and have a look.</para>
<screen>(gdb) <userinput>up</userinput> <lineannotation>Move up call stack</lineannotation>
@@ -1491,7 +1489,7 @@ main() {
</sect2>
<sect2>
- <title>Examining a core file</title>
+ <title>Examining a Core File</title>
<para>A core file is basically a file which contains the
complete state of the process when it crashed. In <quote>the
@@ -1499,9 +1497,9 @@ main() {
listings of core files and sweat over machine code manuals,
but now life is a bit easier. Incidentally, under FreeBSD and
other 4.4BSD systems, a core file is called
- <filename><replaceable>progname</replaceable>.core</filename> instead of just
- <filename>core</filename>, to make it clearer which program a
- core file belongs to.</para>
+ <filename><replaceable>progname</replaceable>.core</filename>
+ instead of just <filename>core</filename>, to make it clearer
+ which program a core file belongs to.</para>
<para>To examine a core file, start up <command>gdb</command> in
the usual way. Instead of typing <command>break</command> or
@@ -1509,9 +1507,9 @@ main() {
<screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput></screen>
- <para>If you are not in the same directory as the core file,
- you will have to do <userinput>dir
- /path/to/core/file</userinput> first.</para>
+ <para>If you are not in the same directory as the core file, you
+ will have to do <userinput>dir /path/to/core/file</userinput>
+ first.</para>
<para>You should see something like this:</para>
@@ -1534,11 +1532,11 @@ Cannot access memory at address 0x7020796d.
available to it in a function called
<function>bazz</function>.</para>
- <para>Sometimes it is useful to be able to see how a function was
- called, as the problem could have occurred a long way up the
- call stack in a complex program. The <command>bt</command>
- command causes <command>gdb</command> to print out a
- back-trace of the call stack:</para>
+ <para>Sometimes it is useful to be able to see how a function
+ was called, as the problem could have occurred a long way up
+ the call stack in a complex program. <command>bt</command>
+ causes <command>gdb</command> to print out a back-trace of the
+ call stack:</para>
<screen>(gdb) <userinput>bt</userinput>
#0 0x164a in bazz (anint=0x5) at temp.c:17
@@ -1552,14 +1550,14 @@ Cannot access memory at address 0x7020796d.
</sect2>
<sect2>
- <title>Attaching to a running program</title>
+ <title>Attaching to a Running Program</title>
<para>One of the neatest features about <command>gdb</command>
- is that it can attach to a program that is already running. Of
- course, that assumes you have sufficient permissions to do so.
- A common problem is when you are stepping through a program
- that forks, and you want to trace the child, but the debugger
- will only let you trace the parent.</para>
+ is that it can attach to a program that is already running.
+ Of course, that assumes you have sufficient permissions to do
+ so. A common problem is when you are stepping through a
+ program that forks, and you want to trace the child, but the
+ debugger will only let you trace the parent.</para>
<para>What you do is start up another <command>gdb</command>,
use <command>ps</command> to find the process ID for the
@@ -1659,14 +1657,13 @@ else if (pid == 0) { /* child */
the <package>editors/emacs</package>
port.</para>
- <para>Once it is installed, start it up and do <userinput>C-h
- t</userinput> to read an Emacs tutorial—that means
- hold down the <keycap>control</keycap> key, press
- <keycap>h</keycap>, let go of the <keycap>control</keycap>
- key, and then press <keycap>t</keycap>. (Alternatively, you
- can use the mouse to select <guimenuitem>Emacs
- Tutorial</guimenuitem> from the <guimenu>Help</guimenu>
- menu.)</para>
+ <para>Once it is installed, start it up and do <literal>C-h
+ t</literal> to read an Emacs tutorial—that means hold
+ down <keycap>control</keycap>, press <keycap>h</keycap>, let
+ go of <keycap>control</keycap>, and then press
+ <keycap>t</keycap>. (Alternatively, you can use the mouse to
+ select <guimenuitem>Emacs Tutorial</guimenuitem> from the
+ <guimenu>Help</guimenu> menu.)</para>
<para>Although Emacs does have menus, it is well worth learning
the key bindings, as it is much quicker when you are editing
@@ -1686,7 +1683,7 @@ else if (pid == 0) { /* child */
doing C-x C-f. When you are happy with that, move on to
another menu command.</para>
- <para>If you can not remember what a particular combination of
+ <para>If you cannot remember what a particular combination of
keys does, select <guimenuitem>Describe Key</guimenuitem> from
the <guimenu>Help</guimenu> menu and type it in—Emacs
will tell you what it does. You can also use the
@@ -1707,11 +1704,11 @@ else if (pid == 0) { /* child */
<keysym>return</keysym> again. Emacs will then do the
search-and-replace operation you have just requested.</para>
- <para>If you are wondering what on earth the
- <keysym>Meta</keysym> key is, it is a special key that many
- &unix; workstations have. Unfortunately, PC's do not have one,
- so it is usually the <keycap>alt</keycap> key (or if you are
- unlucky, the <keysym>escape</keysym> key).</para>
+ <para>If you are wondering what on earth <keysym>Meta</keysym>
+ is, it is a special key that many &unix; workstations have.
+ Unfortunately, PC's do not have one, so it is usually
+ <keycap>alt</keycap> (or if you are unlucky, the
+ <keysym>escape</keysym> key).</para>
<para>Oh, and to get out of Emacs, do <command>C-x C-c</command>
(that means hold down the <keysym>control</keysym> key, press
@@ -1739,20 +1736,20 @@ else if (pid == 0) { /* child */
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list