<?xml version='1.0'?>
<!-- -*- DocBook -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [
 <!ENTITY % sgml.features "IGNORE">
 <!ENTITY % xml.features  "INCLUDE">
 <!ENTITY % dbcent PUBLIC
      "-//OASIS//ENTITIES DocBook Character Entities V4.2//EN"
      "/usr/share/sgml/docbook/dtd/xml/4.2/dbcentx.mod"> %dbcent;
 <!ENTITY % commondata     SYSTEM "../common.ent"      > %commondata;
 <!ENTITY % popcon         SYSTEM "../popcon.ent"      > %popcon;
 <!ENTITY % pkgsize        SYSTEM "../pkgsize.ent"     > %pkgsize;
 <!ENTITY % urlsdata       SYSTEM "../urls.ent"        > %urlsdata;
]>
<chapter id="programming">
    <title>Programming</title>
    <para>I provide some pointers for people to learn programming on the Debian system enough to trace the packaged source code.  Here are notable packages and corresponding documentation packages for programing. </para>
    <table id="listofpackagestohelpprograming">
      
      <title> List of packages to help programing. </title><tgroup x-pkgname=" 1 " x-popcon=" 2 " x-pkgsize=" 3 " cols="4">
        <colspec colname="xxx1"/>
        <colspec colname="xxx2"/>
        <colspec colname="xxx3"/>
        <colspec colname="xxx4"/>
        <thead><row>
            <entry>
              <para>
                <emphasis role="strong">package</emphasis>
              </para>
            </entry>
            <entry>
              <para>
                <emphasis role="strong">popcon</emphasis>
              </para>
            </entry>
            <entry>
              <para>
                <emphasis role="strong">size</emphasis>
              </para>
            </entry>
            <entry>
              <para>
                <emphasis role="strong">documentation</emphasis>
              </para>
            </entry>
          </row></thead><tbody><row>
            <entry>
              <para>
                <code>autoconf</code>
              </para>
            </entry>
            <entry><para>&pop-autoconf;</para></entry>
            <entry><para>&size-autoconf;</para></entry>
            <entry>
              <para> "<code>info autoconf</code>" provided by <code>autoconf-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>automake</code>
              </para>
            </entry>
            <entry><para>&pop-automake;</para></entry>
            <entry><para>&size-automake;</para></entry>
            <entry>
              <para> "<code>info automake</code>" provided by <code>automake1.10-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>bash</code>
              </para>
            </entry>
            <entry><para>&pop-bash;</para></entry>
            <entry><para>&size-bash;</para></entry>
            <entry>
              <para> "<code>info bash</code>" provided by <code>bash-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>bison</code>
              </para>
            </entry>
            <entry><para>&pop-bison;</para></entry>
            <entry><para>&size-bison;</para></entry>
            <entry>
              <para> "<code>info bison</code>" provided by <code>bison-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>cpp</code>
              </para>
            </entry>
            <entry><para>&pop-cpp;</para></entry>
            <entry><para>&size-cpp;</para></entry>
            <entry>
              <para> "<code>info cpp</code>" provided by <code>cpp-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>ddd</code>
              </para>
            </entry>
            <entry><para>&pop-ddd;</para></entry>
            <entry><para>&size-ddd;</para></entry>
            <entry>
              <para> "<code>info ddd</code>" provided by <code>ddd-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>exuberant-ctags</code>
              </para>
            </entry>
            <entry><para>&pop-exuberantctags;</para></entry>
            <entry><para>&size-exuberantctags;</para></entry>
            <entry>
              <para><code>exuberant-ctags</code>(1) </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>flex</code>
              </para>
            </entry>
            <entry><para>&pop-flex;</para></entry>
            <entry><para>&size-flex;</para></entry>
            <entry>
              <para> "<code>info flex</code>" provided by <code>flex-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>gawk</code>
              </para>
            </entry>
            <entry><para>&pop-gawk;</para></entry>
            <entry><para>&size-gawk;</para></entry>
            <entry>
              <para> "<code>info gawk</code>" provided by <code>gawk-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>gcc</code>
              </para>
            </entry>
            <entry><para>&pop-gcc;</para></entry>
            <entry><para>&size-gcc;</para></entry>
            <entry>
              <para> "<code>info gcc</code>" provided by <code>gcc-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>gdb</code>
              </para>
            </entry>
            <entry><para>&pop-gdb;</para></entry>
            <entry><para>&size-gdb;</para></entry>
            <entry>
              <para> "<code>info gdb</code>" provided by <code>gdb-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>gettext</code>
              </para>
            </entry>
            <entry><para>&pop-gettext;</para></entry>
            <entry><para>&size-gettext;</para></entry>
            <entry>
              <para> "<code>info gettext</code>" provided by <code>gettext-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>gfortran</code>
              </para>
            </entry>
            <entry><para>&pop-gfortran;</para></entry>
            <entry><para>&size-gfortran;</para></entry>
            <entry>
              <para> "<code>info gfortran</code>" provided by <code>gfortran-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>glade</code>
              </para>
            </entry>
            <entry><para>&pop-glade;</para></entry>
            <entry><para>&size-glade;</para></entry>
            <entry>
              <para> Help provided via menu </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>glade-gnome</code>
              </para>
            </entry>
            <entry><para>&pop-gladegnome;</para></entry>
            <entry><para>&size-gladegnome;</para></entry>
            <entry>
              <para> Help provided via menu </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>libc6</code>
              </para>
            </entry>
            <entry><para>&pop-libcg;</para></entry>
            <entry><para>&size-libcg;</para></entry>
            <entry>
              <para> "<code>info libc</code>" provided by <code>glibc-doc</code> and <code>glibc-doc-reference</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>make</code>
              </para>
            </entry>
            <entry><para>&pop-make;</para></entry>
            <entry><para>&size-make;</para></entry>
            <entry>
              <para> "<code>info make</code>" provided by <code>make-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>mawk</code>
              </para>
            </entry>
            <entry><para>&pop-mawk;</para></entry>
            <entry><para>&size-mawk;</para></entry>
            <entry>
              <para> "<code>man mawk</code>" </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>perl</code>
              </para>
            </entry>
            <entry><para>&pop-perl;</para></entry>
            <entry><para>&size-perl;</para></entry>
            <entry>
              <para> "<code>man 1 perl</code>" and html pages provided by <code>perl-doc</code> and <code>perl-doc-html</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>python</code>
              </para>
            </entry>
            <entry><para>&pop-python;</para></entry>
            <entry><para>&size-python;</para></entry>
            <entry>
              <para> "<code>man python</code>" and html pages provided by <code>python-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>tcl8.4</code>
              </para>
            </entry>
            <entry><para>&pop-tclie;</para></entry>
            <entry><para>&size-tclie;</para></entry>
            <entry>
              <para> "<code>man tcl</code>" and detail manual pages provided by <code>tcl8.4-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>tk8.4</code>
              </para>
            </entry>
            <entry><para>&pop-tkie;</para></entry>
            <entry><para>&size-tkie;</para></entry>
            <entry>
              <para> "<code>man tk</code>" and detail manual pages provided by <code>tk8.4-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>ruby</code>
              </para>
            </entry>
            <entry><para>&pop-ruby;</para></entry>
            <entry><para>&size-ruby;</para></entry>
            <entry>
              <para> "<code>man ruby</code>" and interactive reference provided by <code>ri</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>vim</code>
              </para>
            </entry>
            <entry><para>&pop-vim;</para></entry>
            <entry><para>&size-vim;</para></entry>
            <entry>
              <para> Help(F1) menu provided by <code>vim-doc</code> </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>susv2</code>
              </para>
            </entry>
            <entry><para>&pop-susvc;</para></entry>
            <entry><para>&size-susvc;</para></entry>
            <entry>
              <para> Fetch "<ulink url="&thesingleunixspecificationsvc;">The Single Unix Specifications v2</ulink>" </para>
            </entry>
          </row><row>
            <entry>
              <para>
                <code>susv3</code>
              </para>
            </entry>
            <entry><para>&pop-susvd;</para></entry>
            <entry><para>&size-susvd;</para></entry>
            <entry>
              <para> Fetch "<ulink url="&thesingleunixspecificationsvd;">The Single Unix Specifications v3</ulink>" </para>
            </entry>
          </row></tbody>
      </tgroup>
    </table>
    <para>Online references are available by typing <code>man name</code> after installing  <code>manpages</code> and <code>manpages-dev</code> packages. Online references for the GNU tools are available by typing <code>info program_name</code> after installing the pertinent documentation packages.  You may need to include the <code>contrib</code> and <code>non-free</code> archives in addition to the <code>main</code> archive since some GFDL documentations are not considered to be DSFG compliant. </para>
    <tip><para><ulink url="&codeexamplesofcrgjjbottlesofbeer;">Code examples of creating "Song 99 Bottles of Beer"</ulink> should give you good idea of practically all the programming languages. </para></tip>
    <caution><para> You should install software programs directly compiled from source into <code>/usr/local</code> or <code>/opt</code> to avoid collision with system programs. </para></caution>
    <warning><para> Do not use "<code>test</code>" as the name of an executable test file.  "<code>test</code>" is a shell built-in. </para></warning>
    <para/>
    <section id="theshellscript">
      <title>The shell script</title>
      <para>The <ulink url="&shellscript;">shell script</ulink> is a text file with the execution bit set and contains the commands in the following format. </para>
      <screen>#!/bin/sh
... command lines ...
</screen>
      <para>The first line specifies the shell interpreter which read and execute this file contents.  </para>
      <para>Reading shell scripts is the <emphasis role="strong">best</emphasis> way to understand how a Unix-like system works.  Here, I give some pointers and reminders for shell programming. See "Shell Mistakes" (<ulink url="&httpwwwgreenendokcaabaeshellhtml;">http://www.greenend.org.uk/rjk/2001/04/shell.html</ulink>) to learn from mistakes. </para>
      <para>Unlike shell interactive mode (see: <xref linkend="thesimpleshellcommand"/> and <xref linkend="unixliketextprocessing"/>), parameters, conditionals, and loops are used frequently. </para>
      <para/>
      <section id="posixshellcompatibility">
        <title>POSIX shell compatibility</title>
        <para>Many system scripts may be interpreted by any one of <ulink url="&posix;">POSIX</ulink> shells (see <xref linkend="listofshellprograms"/>).  For this shell <code>bash</code> may be used, but for the sake of speed, <code>dash</code> is recommended.  You can switch actual shell program to be used by changing symlink for <code>/bin/sh</code>. </para>
        <para>Avoid writing a shell script with "bashisms" or "zshisms" to make it portable among all POSIX shells: </para>
        <table id="listofbashizms">
          
          <title> List of bashizms. </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">Good: POSIX</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">Avoid: bashism</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para>
                    <code>if [ "$foo" = "$bar" ] ; then ...</code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code>if [ "$foo" == "$bar" ] ; then ...</code>
                  </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>diff -u file.c.orig file.c</code>
                  </para>
                </entry>
                <entry>
                  <para><code>diff -u file.c{.orig,</code>} </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>mkdir /foobar /foobaz</code>
                  </para>
                </entry>
                <entry>
                  <para><code>mkdir /foo{bar,baz</code>} </para>
                </entry>
              </row><row>
                <entry>
                  <para> octal format: <code>"\377"</code> </para>
                </entry>
                <entry>
                  <para> hexadecimal format: <code>"\xff"</code> </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <para>The "<code>echo</code>" command must be used with care since its implementation differs among shell built-in commands and external command. </para>
        <itemizedlist>
          <listitem>
            <para>Avoid using any command options except "<code>-n</code>".  (Notably avoid "<code>-e</code>" and "<code>-E</code>") </para>
          </listitem>
          <listitem><para>Avoid using escape sequences in the string since their handling varies. </para></listitem>
        </itemizedlist>
        <note><para> Although "<code>-n</code> option is not really POSIX syntax, it is generally accepted. </para></note>
        <tip><para> Use the "<code>printf</code>" command instead of the "<code>echo</code>" command if you need to embed escape sequences in the output string. </para></tip>
        <para/>
      </section>
      <section id="shellparameters">
        <title>Shell parameters</title>
        <para>Special shell parameters are frequently used in the shell script: </para>
        <table id="listofshellparameters">
          
          <title> List of shell parameters. </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">shell parameter</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">value</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para>
                    <code>$0</code>
                  </para>
                </entry>
                <entry>
                  <para> name of the shell or shell script </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>$1</code>
                  </para>
                </entry>
                <entry>
                  <para> first(1) shell argument </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>$9</code>
                  </para>
                </entry>
                <entry>
                  <para> ninth(9) shell argument </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>$#</code>
                  </para>
                </entry>
                <entry>
                  <para> number of positional parameters </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>"$*"</code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code>"$1 $2 $3 $4 ... "</code>
                  </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>"$@"</code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code>"$1" "$2" "$3" "$4" ...</code>
                  </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>$?</code>
                  </para>
                </entry>
                <entry>
                  <para> exit status of the most recent command </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>$$</code>
                  </para>
                </entry>
                <entry>
                  <para> PID of this shell script </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>$!</code>
                  </para>
                </entry>
                <entry>
                  <para> PID of most recently started background job </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <para>Basic <emphasis role="strong">parameter expansions</emphasis> to remember: </para>
        <table id="listofshellparameterexpansions">
          
          <title> List of shell parameter expansions. </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">parameter expression form</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">If <code>var</code> is set</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">If <code>var</code> is not set</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para>
                    <code> ${var:-string} </code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code> $var </code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code>string</code>
                  </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code> ${var:+string} </code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code>string</code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code>null</code>
                  </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code> ${var:=string} </code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code> $var </code>
                  </para>
                </entry>
                <entry>
                  <para><code>string</code> (and run var=string) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code> ${var:?string} </code>
                  </para>
                </entry>
                <entry>
                  <para>
                    <code> $var </code>
                  </para>
                </entry>
                <entry>
                  <para> (echo string to stderr and exit with error) </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <para>Here, the colon ':' in all of these operators is actually optional. </para>
        <itemizedlist>
          <listitem><para>With ':' = operator test for "exist" and "not null". </para></listitem>
          <listitem><para>Without ':' = operator test for "exist" only. </para></listitem>
        </itemizedlist>
        <table id="listofkeyshellpatersubstitutions">
          
          <title> List of key shell parameter substitutions. </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">parameter substitution form</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">Result</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para>
                    <code> ${var%suffix} </code>
                  </para>
                </entry>
                <entry>
                  <para>  Remove smallest suffix pattern </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code> ${var%%suffix} </code>
                  </para>
                </entry>
                <entry>
                  <para> Remove largest suffix pattern </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code> ${var#prefix} </code>
                  </para>
                </entry>
                <entry>
                  <para> Remove smallest prefix pattern </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code> ${var##prefix} </code>
                  </para>
                </entry>
                <entry>
                  <para> Remove largest prefix pattern </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <para/>
      </section>
      <section id="shellconditionals">
        <title>Shell conditionals</title>
        <para>Each command returns an <emphasis role="strong">exit status</emphasis> which can be used for conditional expressions: </para>
        <itemizedlist>
          <listitem><para>Success: 0 (True) </para></listitem>
          <listitem><para>Error: 1--255 (False) </para></listitem>
        </itemizedlist>
        <para>Note that the use here of a 0 value to mean "true" differs from the usual convention in some other areas of computing.  Also, `[' is the equivalent of the <code>test</code> command, which evaluates its arguments up to `]' as a conditional expression. </para>
        <para>Basic <emphasis role="strong">conditional idioms</emphasis> to remember are: </para>
        <itemizedlist>
          <listitem>
            <para>
              <code>&lt;command&gt; &amp;&amp; &lt;if_success_run_this_command_too&gt; || true</code>
            </para>
          </listitem>
          <listitem>
            <para>
              <code>&lt;command&gt; || &lt;if_not_success_run_this_command_too&gt; || true</code>
            </para>
          </listitem>
          <listitem>
            <screen>if [ &lt;conditional_expression&gt; ]; then
&lt;if_success_run_this_command&gt;
else
&lt;if_not_success_run_this_command&gt;
fi
</screen>
          </listitem>
        </itemizedlist>
        <para>Here trailing "<code>|| true</code>" was needed to ensure this shell script will not exit at this line accidentally when shell is invoked with <code>-e</code> flag. </para>
        <table id="listoffilecompartionalexpression">
          
          <title> List of file comparison operators in the conditional expression. </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">equation</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">value</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para> -e &lt;file&gt; </para>
                </entry>
                <entry>
                  <para> True if &lt;file&gt; exists. </para>
                </entry>
              </row><row>
                <entry>
                  <para> -d &lt;file&gt; </para>
                </entry>
                <entry>
                  <para> True if &lt;file&gt; exists and is a directory. </para>
                </entry>
              </row><row>
                <entry>
                  <para> -f &lt;file&gt; </para>
                </entry>
                <entry>
                  <para> True if &lt;file&gt; exists and is a regular file. </para>
                </entry>
              </row><row>
                <entry>
                  <para> -w &lt;file&gt; </para>
                </entry>
                <entry>
                  <para> True if &lt;file&gt; exists and is writable. </para>
                </entry>
              </row><row>
                <entry>
                  <para> -x &lt;file&gt; </para>
                </entry>
                <entry>
                  <para> True if &lt;file&gt; exists and is executable. </para>
                </entry>
              </row><row>
                <entry>
                  <para> &lt;file1&gt; -nt &lt;file2&gt; </para>
                </entry>
                <entry>
                  <para> True if &lt;file1&gt; is newer than &lt;file2&gt;. (modification). </para>
                </entry>
              </row><row>
                <entry>
                  <para> &lt;file1&gt; -ot &lt;file2&gt; </para>
                </entry>
                <entry>
                  <para> True if &lt;file1&gt; is older than &lt;file2&gt;. (modification). </para>
                </entry>
              </row><row>
                <entry>
                  <para> &lt;file1&gt; -ef &lt;file2&gt; </para>
                </entry>
                <entry>
                  <para> True if they are the same device and inode number. </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <table id="listofstringcomptionalexpression">
          
          <title> List of string comparison operators in the conditional expression. </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">equation</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">value</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para> -z &lt;str&gt; </para>
                </entry>
                <entry>
                  <para> True if the length of &lt;str&gt; is zero. </para>
                </entry>
              </row><row>
                <entry>
                  <para> -n &lt;str&gt; </para>
                </entry>
                <entry>
                  <para> True if the length of &lt;str&gt; is non-zero. </para>
                </entry>
              </row><row>
                <entry>
                  <para> &lt;str1&gt; = &lt;str2&gt;</para>
                </entry>
                <entry>
                  <para> True if &lt;str1&gt; and &lt;str2&gt; are equal. </para>
                </entry>
              </row><row>
                <entry>
                  <para> &lt;str1&gt; != &lt;str2&gt;</para>
                </entry>
                <entry>
                  <para> True if &lt;str1&gt; and &lt;str2&gt; are not equal. </para>
                </entry>
              </row><row>
                <entry>
                  <para> &lt;str1&gt; &lt; &lt;str2&gt;</para>
                </entry>
                <entry>
                  <para> True if &lt;str1&gt; sorts before &lt;str2&gt;. (locale dependent) </para>
                </entry>
              </row><row>
                <entry>
                  <para> &lt;str1&gt; &gt; &lt;str2&gt;</para>
                </entry>
                <entry>
                  <para> True if &lt;str1&gt; sorts after &lt;str2&gt;. (locale dependent) </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <para><emphasis role="strong">Arithmetic</emphasis> integer comparison operators in the conditional expression are <code>-eq</code>, <code>-ne</code>, <code>-lt</code>, <code>-le</code>, <code>-gt</code>, and <code>-ge</code>. </para>
        <para/>
      </section>
      <section id="shellloops">
        <title>Shell loops</title>
        <para>There are several loop idioms to use in POSIX shell: </para>
        <itemizedlist>
          <listitem>
            <para>"<code>for name in word ; do list ; done</code>": loops over list of words. </para>
          </listitem>
          <listitem>
            <para>"<code>while list; do list; done</code>": repeats while true. </para>
          </listitem>
          <listitem>
            <para>"<code>until list; do list; done</code>": repeats while not true. </para>
          </listitem>
          <listitem>
            <para>"<code>break</code>": enables to exit from the loop. </para>
          </listitem>
          <listitem>
            <para>"<code>continue</code>" enables to resume the next iteration of the loop. </para>
          </listitem>
        </itemizedlist>
        <tip><para> See <xref linkend="repeatingacommanloopingoverfiles"/> too. </para></tip>
        <note><para> The C-language like numeric iteration can be realized by using the <code>seq</code>(1) command as the "<code>word</code>" generator. </para></note>
        <para/>
      </section>
      <section id="theshellcommandlocessingsequence">
        <title>The shell command-line processing sequence</title>
        <para>The shell processes a script as following sequence: </para>
        <itemizedlist>
          <listitem>
            <para>split into <emphasis role="strong">tokens</emphasis> by the metacharacters: <code>SPACE TAB NEWLINE ; ( ) &lt; &gt; | &amp;</code> </para>
          </listitem>
          <listitem>
            <para>check <emphasis role="strong">keyword</emphasis> if not within "..."  or '...'  (loop) </para>
          </listitem>
          <listitem>
            <para>expand <emphasis role="strong">alias</emphasis> if not within "..."  or '...'  (loop) </para>
          </listitem>
          <listitem>
            <para>expand <emphasis role="strong">tilde</emphasis>, <code>~</code>&lt;user&gt; -&gt; &lt;user&gt;'s home directory, if not within "..."  or '...' </para>
          </listitem>
          <listitem>
            <para>expand <emphasis role="strong">parameter</emphasis>, <code>$</code><emphasis>PARAMETER</emphasis>, if not within '...' </para>
          </listitem>
          <listitem>
            <para>expand <emphasis role="strong">command substitution</emphasis>, <code>$(</code><emphasis>command</emphasis><code>)</code>, if not within '...' </para>
          </listitem>
          <listitem>
            <para>split into <emphasis role="strong">words</emphasis> with $IFS if not within "..."  or '...' </para>
          </listitem>
          <listitem>
            <para>expand <code>* ? [ ]</code> in <emphasis role="strong">pathname</emphasis> if not within "..."  or '...' </para>
          </listitem>
          <listitem>
            <para>look up <emphasis role="strong">command</emphasis> </para>
          </listitem>
          <listitem><para>function </para></listitem>
          <listitem><para>built-in </para></listitem>
          <listitem><para>file in $PATH </para></listitem>
          <listitem><para>loop </para></listitem>
        </itemizedlist>
        <para>Single quotes within double quotes have no effect. </para>
        <para>Executing <code>set -x</code> in the shell or invoking the shell with <code>-x</code> option make the shell to print all of commands executed.  This is quite handy for debugging. </para>
        <para/>
      </section>
      <section id="utilityprogramsforshellscript">
        <title>Utility programs for shell script</title>
        <para>In order to make your shell program as portable as possible across Debian system, it is good idea to limit utility programs used within Essential programs listed by "<code>aptitude search ~E</code>" as much as possible. </para>
        <para>The <code>coreutils</code>, <code>bsdutils</code>, and <code>debianutils</code> packages contain many useful small utilities. </para>
        <para/>
      </section>
      <section id="shellscriptdialog">
        <title>Shell script dialog</title>
        <para>The user interface of a simple shell program can be improved from dull interaction by the "<code>echo</code>" and "<code>read</code>" commands to more interactive one by using one of the so-called dialog program etc.   </para>
        <table id="listofuserinterfaceprograms">
          
          <title> List of user interface programs. </title><tgroup x-pkgname=" 1 " x-popcon=" 2 " x-pkgsize=" 3 " cols="4">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <colspec colname="xxx3"/>
            <colspec colname="xxx4"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">package</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">popcon</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">size</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">function</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para>
                    <code>xbase-clients</code>
                  </para>
                </entry>
                <entry><para>&pop-xbaseclients;</para></entry>
                <entry><para>&size-xbaseclients;</para></entry>
                <entry>
                  <para> The <code>xmessage</code>(1) displays a message or query in a window (X)(etch) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>x11-utils</code>
                  </para>
                </entry>
                <entry><para>&pop-xbbutils;</para></entry>
                <entry><para>&size-xbbutils;</para></entry>
                <entry>
                  <para> The <code>xmessage</code>(1) , , (lenny) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>whiptail</code>
                  </para>
                </entry>
                <entry><para>&pop-whiptail;</para></entry>
                <entry><para>&size-whiptail;</para></entry>
                <entry>
                  <para> displays user-friendly dialog boxes from shell scripts. (newt) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>dialog</code>
                  </para>
                </entry>
                <entry><para>&pop-dialog;</para></entry>
                <entry><para>&size-dialog;</para></entry>
                <entry>
                  <para> displays user-friendly dialog boxes from shell scripts. (ncurses) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>zenity</code>
                  </para>
                </entry>
                <entry><para>&pop-zenity;</para></entry>
                <entry><para>&size-zenity;</para></entry>
                <entry>
                  <para> display graphical dialog boxes from shell scripts. (gtk2.0) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>xdialog</code>
                  </para>
                </entry>
                <entry><para>&pop-xdialog;</para></entry>
                <entry><para>&size-xdialog;</para></entry>
                <entry>
                  <para> X11 replacement for the text utility <code>dialog</code>. (gtk1.2) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>gtkdialog</code>
                  </para>
                </entry>
                <entry><para>&pop-gtkdialog;</para></entry>
                <entry><para>&size-gtkdialog;</para></entry>
                <entry>
                  <para> GUI-creation command-line utility based on GTK+ library. (gtk2.0+glade2) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>ssft</code>
                  </para>
                </entry>
                <entry><para>&pop-ssft;</para></entry>
                <entry><para>&size-ssft;</para></entry>
                <entry>
                  <para> Shell Scripts Frontend Tool. (wrapper for zenity, kdialog, and dialog with gettext) </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>gettext</code>
                  </para>
                </entry>
                <entry><para>&pop-gettext;</para></entry>
                <entry><para>&size-gettext;</para></entry>
                <entry>
                  <para> The <code>gettext.sh</code> for translate message </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <para/>
      </section>
      <section id="shellscriptexamplewithzenity">
        <title>Shell script example with zenity</title>
        <para>Here is a simple script which creates ISO image with RS02 data supplemented by <code>dvdisaster</code>(1): </para>
        <screen>#!/bin/sh -e
# gmkrs02 : Copyright (C) 2007 Osamu Aoki &lt;osamu@debian.org&gt;, Public Domain
#set -x
error_exit()
{
  echo "$1" &gt;&amp;2
  exit 1
}
# Initialize variables
DATA_ISO="$HOME/Desktop/iso-$$.img"
LABEL=$(date +%Y%m%d-%H%M%S-%Z)
if [ $# != 0 ] &amp;&amp; [ -d "$1" ]; then
  DATA_SRC="$1"
else
  # Select directory for creating ISO image from folder on desktop
  DATA_SRC=$(zenity --file-selection --directory  \
    --title="Select the directory tree root to create ISO image") \
    || error_exit "Exit on directory selection"
fi
# Check size of archive
xterm -T "Check size $DATA_SRC" -e du -s $DATA_SRC/*
SIZE=$(($(du -s $DATA_SRC | awk '{print $1}')/1024))
if [ $SIZE -le 520 ] ; then
  zenity --info --title="Dvdisaster RS02" --width 640  --height 400 \
    --text="The data size is good for CD backup:\\n $SIZE MB"
elif [ $SIZE -le 3500 ]; then
  zenity --info --title="Dvdisaster RS02" --width 640  --height 400 \
    --text="The data size is good for DVD backup :\\n $SIZE MB"
else
  zenity --info --title="Dvdisaster RS02" --width 640  --height 400 \
    --text="The data size is too big to backup : $SIZE MB"
  error_exit "The data size is too big to backup :\\n $SIZE MB"
fi
# only xterm is sure to have working -e option
# Create raw ISO image
rm -f "$DATA_ISO" || true
xterm -T "genisoimage $DATA_ISO" \
  -e genisoimage -r -J -V "$LABEL" -o "$DATA_ISO" "$DATA_SRC"
# Create RS02 supplemental redundancy
xterm -T "dvdisaster $DATA_ISO" -e  dvdisaster -i "$DATA_ISO" -mRS02 -c
zenity --info --title="Dvdisaster RS02" --width 640  --height 400 \
  --text="ISO/RS02 data ($SIZE MB) \\n created at: $DATA_ISO"
# EOF
</screen>
        <para>You may wish to create launcher on the desktop with command set something like "<code>/usr/local/bin/gmkrs02 %d</code>". </para>
        <para/>
      </section>
    </section>
    <section id="make">
      <title>Make</title>
      <para><ulink url="&make;">Make</ulink> is a utility to maintain groups of programs. Upon execution of <code>make</code>(1), <code>make</code> read the rule file, <code>Makefile</code>, and updates a target if it depends on prerequisite files that have been modified since the target was last modified, or if the target does not exist.  The execution of these updates may occur concurrently. </para>
      <para>The rule file syntax is : </para>
      <screen>target: [ prerequisites ... ]
 [TAB]  command1
 [TAB]  -command2 # ignore errors
 [TAB]  @command3 # suppress echoing
</screen>
      <para>Here "<code> [TAB] </code>" is a TAB code.  Each line is interpreted by the shell after <code>make</code> variable substitution.  Use <code>\</code> at the end of a line to continue the script.  Use "<code>$$</code>" to enter "<code>$</code>" for environment values for a shell script. </para>
      <para>Implicit rules for the target and prerequisites can be written, for example, as: </para>
      <screen>%.o: %.c header.h
</screen>
      <para>Here, the target contains the character "<code>%</code>" (exactly one of them). The "<code>%</code>" can match any nonempty substring in the actual target filenames. The prerequisites likewise use "<code>%</code>" to show how their names relate to the actual target name. </para>
      <table id="listofmakeautomaticvariables">
        
        <title> List of make automatic variables. </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
          <colspec colname="xxx1"/>
          <colspec colname="xxx2"/>
          <thead><row>
              <entry>
                <para>
                  <emphasis role="strong">automatic variable</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">value</emphasis>
                </para>
              </entry>
            </row></thead><tbody><row>
              <entry>
                <para>
                  <code>$@</code>
                </para>
              </entry>
              <entry>
                <para> target </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>$&lt;</code>
                </para>
              </entry>
              <entry>
                <para> first prerequisite </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>$?</code>
                </para>
              </entry>
              <entry>
                <para> all newer prerequisites </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>$^</code>
                </para>
              </entry>
              <entry>
                <para> all prerequisites </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>$*</code>
                </para>
              </entry>
              <entry>
                <para><code>%</code> matched stem in the target pattern </para>
              </entry>
            </row></tbody>
        </tgroup>
      </table>
      <table id="listofmakevariableexpansions">
        
        <title> List of make variable expansions. </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
          <colspec colname="xxx1"/>
          <colspec colname="xxx2"/>
          <thead><row>
              <entry>
                <para>
                  <emphasis role="strong">variable expansion</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">effects</emphasis>
                </para>
              </entry>
            </row></thead><tbody><row>
              <entry>
                <para>
                  <code>foo1 := bar</code>
                </para>
              </entry>
              <entry>
                <para> One-time expansion </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>foo2  = bar</code>
                </para>
              </entry>
              <entry>
                <para> Recursive expansion </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>foo3 += bar</code>
                </para>
              </entry>
              <entry>
                <para> Append </para>
              </entry>
            </row></tbody>
        </tgroup>
      </table>
      <para>Run <code>make -p -f/dev/null</code> to see automatic internal rules. </para>
      <para/>
    </section>
    <section id="c">
      <title>C</title>
      <para>You can set up proper environment to compile programs written in the <ulink url="&cprogramminglanguage;">C programming language</ulink> by: </para>
      <screen># aptitude install glibc-doc manpages-dev libc6-dev gcc build-essential
</screen>
      <para>The <code>libc6-dev</code> package, i.e., GNU C Library, provides <ulink url="&cstandardlibrary;">C standard library</ulink> which is collection of header files and library routines used by the C programming language. </para>
      <para>References for C: </para>
      <itemizedlist>
        <listitem>
          <para><code>info libc</code> (C library function reference) </para>
        </listitem>
        <listitem>
          <para><code>gcc</code>(1) and <code>info gcc</code></para>
        </listitem>
        <listitem>
          <para><code>each_C_library_function_name</code>(3) </para>
        </listitem>
        <listitem>
          <para>Kernighan &amp; Ritchie, "The C Programming Language", 2nd edition (Prentice Hall). </para>
        </listitem>
      </itemizedlist>
      <para/>
      <section id="simplecprogramgcc">
        <title>Simple C program (gcc)</title>
        <para>A simple example to compile <code>example.c</code> with a library <code>libm</code> into an executable <code>run_example</code>: </para>
        <para/>
        <screen>$ cat &gt; example.c &lt;&lt; EOF
#include &lt;stdio.h&gt;
#include &lt;math.h&gt;
#include &lt;string.h&gt;

int main(int argc, char **argv, char **envp){
        double x;
        char y[11];
        x=sqrt(argc+7.5);
        strncpy(y, argv[0], 10); /* prevent buffer overflow */
        y[10] = '\0'; /* fill to make sure string ends with '\0' */
        printf("%5i, %5.3f, %10s, %10s\n", argc, x, y, argv[1]);
        return 0;
}
EOF
$ gcc -Wall -g -o run_example example.c -lm
$ ./run_example
        1, 2.915, ./run_exam,     (null)
$ ./run_example 1234567890qwerty
        2, 3.082, ./run_exam, 1234567890qwerty
</screen>
        <para>Here, <code>-lm</code> is needed to link library <code>libm</code> for <code>sqrt()</code>.  The actual library is in <code>/lib/</code> with filename <code>libm.so.6</code>, which is a symlink to <code>libm-2.1.3.so</code>. </para>
        <para>Look at the last parameter in the output text.  There are more than 10 characters even though <code>%10s</code> is specified. </para>
        <para>The use of pointer memory operation functions without boundary checks, such as <code>sprintf</code> and <code>strcpy</code>, is deprecated to prevent buffer overflow exploits that leverage the above overrun effects.  Instead, use <code>snprintf</code> and <code>strncpy</code>. </para>
        <para/>
      </section>
      <section id="debuggingwithgdb">
        <title>Debugging with gdb</title>
        <para>In order to be a good Debian user, you must be able to produce meaningful bug report using <ulink url="&debugger;">debugger</ulink>.  The fist step is to install <code>gdb</code>: </para>
        <para/>
        <screen># aptitude install gdb gdb-doc build-essential devscripts
</screen>
        <para>Good tutorial of <code>gdb</code> is provided by "<code>info gdb</code>" or found  <ulink url="&elsewhereontheweb;">elsewhere on the web</ulink>. </para>
        <para/>
        <section id="basicgdbexecution">
          <title>Basic gdb execution</title>
          <para>Here is a simple example of using <code>gdb</code>(1) on a <code>program</code> compiled with the <code>-g</code> option to produce debugging information. </para>
          <para/>
          <screen>$ gdb program
(gdb) b 1                # set break point at line 1
(gdb) run args           # run program with args
(gdb) next               # next line
...
(gdb) step               # step forward
...
(gdb) p parm             # print parm
...
(gdb) p parm=12          # set value to 12
...
(gdb) quit
</screen>
          <tip><para> Many <code>gdb</code> commands can be abbreviated.  Tab expansion works as in the shell. </para></tip>
          <para/>
        </section>
        <section id="debuggingthedebianpackage">
          <title>Debugging the Debian package</title>
          <para>Since all installed binaries should be stripped on the Debian system by default, most debugging symbols are removed in the normal package.  In order to debug Debian packages with make <code>gdb</code>, corresponding <code>*-dbg</code> packages need to be installed (e.g. libc6-dbg in the case of libc6). </para>
          <para>If the package to be debugged does not provide <code>*-dbg</code> package, you need to install rebuild packages as follows: </para>
          <screen>$ mkdir /path/new ; cd /path/new
$ sudo aptitude update
$ sudo aptitude dist-upgrade
$ sudo aptitude install fakeroot devscripts build-essential
$ sudo apt-get build-dep source_package_name
$ apt-get source package_name
$ cd package_name*
</screen>
          <itemizedlist>
            <listitem><para>fix bugs if needed. </para></listitem>
          </itemizedlist>
          <para/>
          <screen>$ dch -i
</screen>
          <itemizedlist>
            <listitem>
              <para>bump package version to one which does not collide with official Debian versions, e.g. one appended with "<code>+debug1</code>" when recompiling existing package version, or one appended with "<code>~pre1</code>" when compiling unreleased package version. </para>
            </listitem>
          </itemizedlist>
          <para/>
          <screen>$ export DEB_BUILD_OPTIONS=nostrip,noopt
$ debuild
$ cd ..
$ sudo debi package_name*.changes 
</screen>
          <para>You need to check the build scripts of the package and ensure to use <code>CFLAGS=-g -Wall</code> for compiling binaries. </para>
          <para/>
        </section>
        <section id="obtainingbacktrace">
          <title>Obtaining backtrace</title>
          <para>When you encounter program crash, reporting bug report with cut-and-pasted backtrace information is a good idea. </para>
          <para>The backtrace can be obtained by the following steps: </para>
          <itemizedlist>
            <listitem>
              <para>run the program under <code>gdb</code>, </para>
            </listitem>
            <listitem><para>reproduce crash to be dropped back to the gdb prompt, and </para></listitem>
            <listitem>
              <para>type "<code>bt</code>" at the gdb prompt. </para>
            </listitem>
          </itemizedlist>
          <para>In case of program freeze, you can crash the program by pressing <code>Ctrl-C</code> in the terminal running gdb to obtain gdb prompt. </para>
          <tip><para> Often, you will see a backtrace where one or more of the top lines is in malloc() or g_malloc(). When this happens, chances are your backtrace isn't very useful. The easiest way to find some useful information is to set the environment variable MALLOC_CHECK_ to a value of 2. You can do this while running gdb by doing this:</para></tip>
          <screen> $ MALLOC_CHECK_=2 gdb hello
</screen>
          <para/>
        </section>
        <section id="advancedgdbcommands">
          <title>Advanced gdb commands</title>
          <table id="listofadvancedgdbcommands">
            
            <title> List of advanced gdb commands </title><tgroup x-pkgname=" " x-popcon="" x-pkgsize="" cols="2">
              <colspec colname="xxx1"/>
              <colspec colname="xxx2"/>
              <thead><row>
                  <entry>
                    <para>
                      <emphasis role="strong">objective</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="strong">commands</emphasis>
                    </para>
                  </entry>
                </row></thead><tbody><row>
                  <entry>
                    <para> To get a backtrace for all threads for multi-threaded program. </para>
                  </entry>
                  <entry>
                    <para>
                      <code>(gdb) thread apply all bt</code>
                    </para>
                  </entry>
                </row><row>
                  <entry>
                    <para> To get parameters came on the stack of function calls. </para>
                  </entry>
                  <entry>
                    <para>
                      <code>(gdb) bt full</code>
                    </para>
                  </entry>
                </row><row>
                  <entry>
                    <para> To get a backtrace and parameters as the combination of the preceding options. </para>
                  </entry>
                  <entry>
                    <para>
                      <code>(gdb) thread apply all bt full</code>
                    </para>
                  </entry>
                </row><row>
                  <entry>
                    <para> To get them for top 10 calls to cut off irrelevant output. </para>
                  </entry>
                  <entry>
                    <para>
                      <code>(gdb) thread apply all bt full 10</code>
                    </para>
                  </entry>
                </row><row>
                  <entry>
                    <para> To write log of gdb output to a file (the default is gdb.txt). </para>
                  </entry>
                  <entry>
                    <para>
                      <code>(gdb) set logging on</code>
                    </para>
                  </entry>
                </row></tbody>
            </tgroup>
          </table>
          <para/>
        </section>
        <section id="debuggingxerrors">
          <title>Debugging X Errors</title>
          <para>If the Gnome program has received an X error; i.e. you see a message of the form: </para>
          <para/>
          <screen>The program 'preview1' received an X Window System error.
</screen>
          <para>then you can try running the program with "<code>--sync</code>", and break on the "<code>gdk_x_error</code>" function in order to obtain a backtrace. </para>
          <para/>
        </section>
      </section>
      <section id="checkdependencyonlibraries">
        <title>Check dependency on libraries</title>
        <para>Use <code>ldd</code>(1) to find out a program's dependency on libraries: </para>
        <para/>
        <screen>$ ldd /bin/ls
        librt.so.1 =&gt; /lib/librt.so.1 (0x4001e000)
        libc.so.6 =&gt; /lib/libc.so.6 (0x40030000)
        libpthread.so.0 =&gt; /lib/libpthread.so.0 (0x40153000)
        /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x40000000)
</screen>
        <para>For <code>ls</code>(1) to work in a <code>chroot</code>ed environment, the above libraries must be available in your <code>chroot</code>ed environment. </para>
        <para>See also <xref linkend="traceprogramactivities"/>. </para>
        <para/>
      </section>
      <section id="debuggingwithmemakdetectiontools">
        <title>Debugging with memory leak detection tools</title>
        <para>There are several memory leak detection tools available in Debian. </para>
        <table id="listofmemoryleakdetectiontools">
          
          <title> List of memory leak detection tools </title><tgroup x-pkgname=" 1 " x-popcon=" 2 " x-pkgsize=" 3 " cols="4">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <colspec colname="xxx3"/>
            <colspec colname="xxx4"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">package</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">popcon</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">size</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">description</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para>
                    <code>libc6-dev</code>
                  </para>
                </entry>
                <entry><para>&pop-libcgdev;</para></entry>
                <entry><para>&size-libcgdev;</para></entry>
                <entry>
                  <para><code>mtrace</code>(1): malloc debugging functionality in glibc </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>valgrind</code>
                  </para>
                </entry>
                <entry><para>&pop-valgrind;</para></entry>
                <entry><para>&size-valgrind;</para></entry>
                <entry>
                  <para> memory debugger and profiler </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>kmtrace</code>
                  </para>
                </entry>
                <entry><para>&pop-kmtrace;</para></entry>
                <entry><para>&size-kmtrace;</para></entry>
                <entry>
                  <para> KDE memory leak tracer using glibc's "<code>mtrace</code>(1)" </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>alleyoop</code>
                  </para>
                </entry>
                <entry><para>&pop-alleyoop;</para></entry>
                <entry><para>&size-alleyoop;</para></entry>
                <entry>
                  <para> Gnome front-end to the Valgrind memory checker </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>electric-fence</code>
                  </para>
                </entry>
                <entry><para>&pop-electricfence;</para></entry>
                <entry><para>&size-electricfence;</para></entry>
                <entry>
                  <para> malloc(3) debugger </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>ccmalloc</code>
                  </para>
                </entry>
                <entry><para>&pop-ccmalloc;</para></entry>
                <entry><para>&size-ccmalloc;</para></entry>
                <entry>
                  <para> memory profiler/debugger </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>leaktracer</code>
                  </para>
                </entry>
                <entry><para>&pop-leaktracer;</para></entry>
                <entry><para>&size-leaktracer;</para></entry>
                <entry>
                  <para> memory-leak tracer for C++ programs </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>libdmalloc5</code>
                  </para>
                </entry>
                <entry><para>&pop-libdmallocf;</para></entry>
                <entry><para>&size-libdmallocf;</para></entry>
                <entry>
                  <para> debug memory allocation library </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>mpatrolc2</code>
                  </para>
                </entry>
                <entry><para>&pop-mpatrolcc;</para></entry>
                <entry><para>&size-mpatrolcc;</para></entry>
                <entry>
                  <para> library for debugging memory allocations </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <para/>
      </section>
      <section id="disassemblebinary">
        <title>Disassemble binary</title>
        <para>You can disassemble binary code with <code>objdump</code>(1). For example: </para>
        <screen>$  objdump -m i386 -b binary -D /usr/lib/grub/x86_64-pc/stage1
</screen>
        <note><para><code>gdb</code>(1) may be used to disassemble code interactively. </para></note>
        <para/>
      </section>
      <section id="flexabetterlex">
        <title>Flex -- a better Lex</title>
        <para><ulink url="&flex;">Flex</ulink> is a a <ulink url="&lex;">Lex</ulink>-compatible fast <ulink url="&lexicalanalyzer;">lexical analyzer</ulink> generator. </para>
        <para>Tutorial for <code>flex</code>(1) can be found in "<code>info flex</code>". </para>
        <para>You need to provide your own <code>main()</code> and <code>yywrap()</code>, or your <code>program.l</code> should look like this to compile without a library (<code>yywrap</code> is a macro; <code>%option main</code> turns on <code>%option noyywrap</code> implicitly): </para>
        <para/>
        <screen>%option main
%%
.|\n    ECHO ;
%%
</screen>
        <para>Alternatively, you may compile with the <code>-lfl</code> linker option at the end of your <code>cc</code> command line (like AT&amp;T-Lex with <code>-ll</code>).  No <code>%option</code> is needed in this case. </para>
        <para/>
      </section>
      <section id="bisonabetteryacc">
        <title>Bison -- a better Yacc</title>
        <para>Several packages provide a <ulink url="&yacc;">Yacc</ulink>-compatible lookahead <ulink url="&lrparser;">LR parser</ulink> or <ulink url="&lalrparser;">LALR parser</ulink> generator in Debian: </para>
        <table id="listofyacccompatparsergenerators">
          
          <title> List of Yacc-compatible LALR parser generators </title><tgroup x-pkgname=" 1 " x-popcon=" 2 " x-pkgsize=" 3 " cols="4">
            <colspec colname="xxx1"/>
            <colspec colname="xxx2"/>
            <colspec colname="xxx3"/>
            <colspec colname="xxx4"/>
            <thead><row>
                <entry>
                  <para>
                    <emphasis role="strong">package</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong"> popcon</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">size</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="strong">description</emphasis>
                  </para>
                </entry>
              </row></thead><tbody><row>
                <entry>
                  <para>
                    <code>bison</code>
                  </para>
                </entry>
                <entry><para>&pop-bison;</para></entry>
                <entry><para>&size-bison;</para></entry>
                <entry>
                  <para>
                    <ulink url="&gnulalrparsergenerator;">GNU LALR parser generator</ulink>
                  </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>byacc</code>
                  </para>
                </entry>
                <entry><para>&pop-byacc;</para></entry>
                <entry><para>&size-byacc;</para></entry>
                <entry>
                  <para> The Berkeley LALR parser generator </para>
                </entry>
              </row><row>
                <entry>
                  <para>
                    <code>btyacc</code>
                  </para>
                </entry>
                <entry><para>&pop-btyacc;</para></entry>
                <entry><para>&size-btyacc;</para></entry>
                <entry>
                  <para> Backtracking parser generator based on <code>byacc</code> </para>
                </entry>
              </row></tbody>
          </tgroup>
        </table>
        <para>Tutorial for <code>bison</code>(1) can be found in "<code>info bison</code>". </para>
        <para>You need to provide your own <code>main()</code> and <code>yyerror()</code>.  <code>main()</code> calls <code>yyparse()</code> which calls <code>yylex()</code>, usually created with Flex. </para>
        <para/>
        <screen>%%

%%
</screen>
        <para/>
      </section>
    </section>
    <section id="autoconf">
      <title>Autoconf</title>
      <para><ulink url="&autoconf;">Autoconf</ulink> is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of Unix-like systems using the entire GNU build system. </para>
      <para><code>autoconf</code>(1) produces the configuration script <code>configure</code>. <code>configure</code> automatically creates a customized <code>Makefile</code> using the <code>Makefile.in</code> template. </para>
      <para/>
      <section id="compileandinstallaprogram">
        <title>Compile and install a program</title>
        <warning><para> Do not overwrite system files with your compiled programs when installing them. </para></warning>
        <para>Debian does not touch files in <code>/usr/local/</code> or <code>/opt</code>.  So if you compile a program from source, install it into <code>/usr/local/</code> so it will not interfere with Debian. </para>
        <para/>
        <screen>$ cd src
$ ./configure --prefix=/usr/local
$ make
$ make install # this puts the files in the system
</screen>
        <para/>
      </section>
      <section id="uninstallprogram">
        <title>Uninstall program</title>
        <para>If you still have the source and if it uses <code>autoconf</code>/<code>automake</code> and if you can remember how you configured it: </para>
        <para/>
        <screen>$ ./configure ''all-of-the-options-you-gave-it''
# make uninstall
</screen>
        <para>Alternatively, if you are absolutely sure that the install process puts files only under <code>/usr/local/</code> and there is nothing important there, you can erase all its contents by: </para>
        <para/>
        <screen># find /usr/local -type f -print0 | xargs -0 rm -f
</screen>
        <para>If you are not sure where files are installed, you should consider using <code>checkinstall</code>, which provides a clean path for the uninstall. </para>
        <para/>
      </section>
    </section>
    <section id="perlshortscriptmadness">
      <title>Perl short script madness</title>
      <para>Although any <ulink url="&awk;">AWK</ulink> scripts can be automatically rewritten in <ulink url="&perl;">Perl</ulink> using <code>a2p</code>(1), one-liner AWK scripts are best converted to one-liner perl scripts manually.  For example </para>
      <screen>awk '($2=="1957") { print $3 }' |
</screen>
      <para>is equivalent to any one of the following lines: </para>
      <screen>perl -ne '@f=split; if ($f[1] eq "1957") { print "$f[2]\n"}' |
</screen>
      <para/>
      <screen>perl -ne 'if ((@f=split)[1] eq "1957") { print "$f[2]\n"}' |
</screen>
      <para/>
      <screen>perl -ne '@f=split; print $f[2] if ( $f[1]==1957 )' |
</screen>
      <para/>
      <screen>perl -lane 'print $F[2] if $F[1] eq "1957"' |
</screen>
      <para/>
      <screen>perl -lane 'print$F[2]if$F[1]eq+1957' |
</screen>
      <para>The last one is a riddle.  It took advantage of the Perl features that  </para>
      <itemizedlist>
        <listitem><para>the whitespace is optional and  </para></listitem>
        <listitem><para>the automatic conversion from number to the string.  </para></listitem>
      </itemizedlist>
      <para>See <code>perlrun</code>(1) for the command-line options.  For more crazy Perl scripts, <ulink url="&perlgolf;">Perl Golf</ulink> may be interesting. </para>
      <para/>
    </section>
    <section id="web">
      <title>Web</title>
      <para>Basic interactive dynamic web pages can be made as follows: </para>
      <itemizedlist>
        <listitem>
          <para>Queries are presented to the browser user using <ulink url="&html;">HTML</ulink> forms. </para>
        </listitem>
        <listitem>
          <para>Filling and clicking on the form entries will send an <ulink url="&url;">URL</ulink> with encoded parameters from the browser to the web server.  For example: </para>
          <itemizedlist>
            <listitem>
              <para>
                <code>http://www.foo.dom/cgi-bin/program.pl?VAR1=VAL1&amp;VAR2=VAL2&amp;VAR3=VAL3</code>
              </para>
            </listitem>
            <listitem>
              <para>
                <code>http://www.foo.dom/cgi-bin/program.py?VAR1=VAL1&amp;VAR2=VAL2&amp;VAR3=VAL3</code>
              </para>
            </listitem>
            <listitem>
              <para>
                <code>http://www.foo.dom/program.php?VAR1=VAL1&amp;VAR2=VAL2&amp;VAR3=VAL3</code>
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para><code>%nn</code> in URL is replaced with a character with hexadecimal <code>nn</code> value. </para>
        </listitem>
        <listitem>
          <para>The environment variable is set as: <code>QUERY_STRING="VAR1=VAL1 VAR2=VAL2 VAR3=VAL3"</code> </para>
        </listitem>
        <listitem>
          <para><ulink url="&cgi;">CGI</ulink> program (any one of <code>program.*</code>) on the web server executes itself with the environment variable "<code>QUERY_STRING</code>". </para>
        </listitem>
        <listitem>
          <para><code>stdout</code> of CGI program will be sent to the web browser and is presented as an interactive dynamic web page. </para>
        </listitem>
      </itemizedlist>
      <para>For security reasons it is better not to hand craft new hacks for parsing CGI parameters.  There are established modules for them in Perl and Python.  <ulink url="&php;">PHP</ulink> comes with these functionalities.  When client data storage is needed, cookies are used.  When client side data processing is needed, javascript is frequently used. </para>
      <para>For more, see <ulink url="&thecommongatewayinterface;">The Common Gateway Interface</ulink>, <ulink url="&theapachesoftwarefoundation;">The Apache Software Foundation</ulink>, and <ulink url="&javascript;">JavaScript</ulink>. </para>
      <para>Searching "CGI tutorial" on Google by typing encoded URL <ulink url="&httpwwwgooglecomutfiqcgitutorial;">http://www.google.com/search?hl=en&amp;ie=UTF-8&amp;q=CGI+tutorial</ulink> directly to the browser address is a good way to see the CGI script in action on the Google server. </para>
      <para/>
    </section>
    <section id="staticcodeanalysistools">
      <title>Static code analysis tools</title>
      <para>There are <ulink url="&lint;">lint</ulink> like tools for <ulink url="&staticcodeanalysis;">static code analysis</ulink>: </para>
      <table id="listoftoolsforstaticcodeanalysis">
        
        <title> List of tools for static code analysis </title><tgroup x-pkgname=" 1 " x-popcon=" 2 " x-pkgsize=" 3 " cols="4">
          <colspec colname="xxx1"/>
          <colspec colname="xxx2"/>
          <colspec colname="xxx3"/>
          <colspec colname="xxx4"/>
          <thead><row>
              <entry>
                <para>
                  <emphasis role="strong">package</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">popcon</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">size</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">description</emphasis>
                </para>
              </entry>
            </row></thead><tbody><row>
              <entry>
                <para>
                  <code>splint</code>
                </para>
              </entry>
              <entry><para>&pop-splint;</para></entry>
              <entry><para>&size-splint;</para></entry>
              <entry>
                <para> A tool for statically checking C programs for bugs </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>rats</code>
                </para>
              </entry>
              <entry><para>&pop-rats;</para></entry>
              <entry><para>&size-rats;</para></entry>
              <entry>
                <para> Rough Auditing Tool for Security (C, C++, PHP, Perl, and Python code) </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>flawfinder</code>
                </para>
              </entry>
              <entry><para>&pop-flawfinder;</para></entry>
              <entry><para>&size-flawfinder;</para></entry>
              <entry>
                <para> A tool to examine C/C++ source code and looks for security weaknesses </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>perl</code>
                </para>
              </entry>
              <entry><para>&pop-perl;</para></entry>
              <entry><para>&size-perl;</para></entry>
              <entry>
                <para> The <code>perl</code> package has internal code static checker: <code>B::Lint</code>(3perl)</para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>pylint</code>
                </para>
              </entry>
              <entry><para>&pop-pylint;</para></entry>
              <entry><para>&size-pylint;</para></entry>
              <entry>
                <para> A python code static checker </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>jlint</code>
                </para>
              </entry>
              <entry><para>&pop-jlint;</para></entry>
              <entry><para>&size-jlint;</para></entry>
              <entry>
                <para> A Java program checker </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>weblint-perl</code>
                </para>
              </entry>
              <entry><para>&pop-weblintperl;</para></entry>
              <entry><para>&size-weblintperl;</para></entry>
              <entry>
                <para> A syntax and minimal style checker for HTML </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>linklint</code>
                </para>
              </entry>
              <entry><para>&pop-linklint;</para></entry>
              <entry><para>&size-linklint;</para></entry>
              <entry>
                <para> A fast link checker and web site maintenance tool </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>libxml2-utils</code>
                </para>
              </entry>
              <entry><para>&pop-libxmlcutils;</para></entry>
              <entry><para>&size-libxmlcutils;</para></entry>
              <entry>
                <para> The <code>libxml2-utils</code> package provides <code>xmllint</code>(1) command to validate XML files </para>
              </entry>
            </row></tbody>
        </tgroup>
      </table>
      <para/>
    </section>
    <section id="thesourcecodetranslation">
      <title>The source code translation</title>
      <para>There are programs to convert source codes: </para>
      <table id="listofsourcecodetranslationtools">
        
        <title> List of source code translation tools. </title><tgroup x-pkgname=" 1 " x-popcon=" 2 " x-pkgsize=" 3 " cols="4">
          <colspec colname="xxx1"/>
          <colspec colname="xxx2"/>
          <colspec colname="xxx3"/>
          <colspec colname="xxx4"/>
          <thead><row>
              <entry>
                <para>
                  <emphasis role="strong">package</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">popcon</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">size</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">keyword</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="strong">function</emphasis>
                </para>
              </entry>
            </row></thead><tbody><row>
              <entry>
                <para>
                  <code>perl</code>
                </para>
              </entry>
              <entry><para>&pop-perl;</para></entry>
              <entry><para>&size-perl;</para></entry>
              <entry>
                <para> AWK-&gt;PERL </para>
              </entry>
              <entry>
                <para> The <code>a2p</code> converter from AWK to PERL. </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>f2c</code>
                </para>
              </entry>
              <entry><para>&pop-fcc;</para></entry>
              <entry><para>&size-fcc;</para></entry>
              <entry>
                <para> FORTRAN-&gt;C </para>
              </entry>
              <entry>
                <para> The converter from A FORTRAN 77 to C/C++. </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>protoize</code>
                </para>
              </entry>
              <entry><para>&pop-protoize;</para></entry>
              <entry><para>&size-protoize;</para></entry>
              <entry>
                <para> ANSI C </para>
              </entry>
              <entry>
                <para> Create/remove ANSI prototypes from C code. </para>
              </entry>
            </row><row>
              <entry>
                <para>
                  <code>intel2gas</code>
                </para>
              </entry>
              <entry><para>&pop-intelcgas;</para></entry>
              <entry><para>&size-intelcgas;</para></entry>
              <entry>
                <para> intel-&gt;gas </para>
              </entry>
              <entry>
                <para> The converter from NASM (intel format) to the GNU Assembler (GAS). </para>
              </entry>
            </row></tbody>
        </tgroup>
      </table>
      <para/>
    </section>
    <section id="makingdebianpackage">
      <title>Making Debian package</title>
      <para>If you want to make a Debian package, read: </para>
      <itemizedlist>
        <listitem><para><xref linkend="debianpackagemanagement"/> to understand the basic package system, </para></listitem>
        <listitem><para><xref linkend="portapackagetothestablesystem"/> to understand basic porting process, </para></listitem>
        <listitem><para><xref linkend="thechroot"/> to understand basic chroot techniques, </para></listitem>
        <listitem>
          <para>manpages of <code>pbuilder</code>(1) and <code>pdebuild</code>(1) commands, </para>
        </listitem>
        <listitem><para><xref linkend="debuggingthedebianpackage"/> for recompiling for debugging, </para></listitem>
        <listitem>
          <para><ulink url="&debiannewmaintainersguide;">Debian New Maintainers' Guide</ulink> as tutorial (<code>maint-guide</code> package), </para>
        </listitem>
        <listitem>
          <para><ulink url="&debiandevelopersreference;">Debian Developer's Reference</ulink> (<code>developers-reference</code> package), and </para>
        </listitem>
        <listitem>
          <para><ulink url="&debianpolicymanual;">Debian Policy Manual</ulink> (<code>debian-policy</code> package). </para>
        </listitem>
      </itemizedlist>
      <para>There are packages such as <code>dh-make</code>, <code>dh-make-perl</code>, etc., which help packaging. </para>
    </section>
  </chapter>