debian-reference/rawxml/12_programming.rawxml

<!-- vim: set sw=2 et sts=2 ft=xml: -->
  <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 programming.</para>
    <para>Online references are available by typing "<literal>man name</literal>" after installing <literal>manpages</literal> and <literal>manpages-dev</literal> packages. Online references for the GNU tools are available by typing "<literal>info program_name</literal>" after installing the pertinent documentation packages.  You may need to include the <literal>contrib</literal> and <literal>non-free</literal> archives in addition to the <literal>main</literal> archive since some GFDL documentations are not considered to be DFSG compliant.</para>
    <para>Please consider to use version control system tools.  See <xref linkend="_git"/>. </para>
    <warning> <para>Do not use "<literal>test</literal>" as the name of an executable test file.  "<literal>test</literal>" is a shell builtin.</para> </warning>
    <caution> <para>You should install software programs directly compiled from source into "<literal>/usr/local</literal>" or "<literal>/opt</literal>" to avoid collision with system programs.</para> </caution>
    <tip> <para><ulink url="https://www.99-bottles-of-beer.net/">Code examples of creating "Song 99 Bottles of Beer"</ulink> should give you good ideas of practically all the programming languages.</para> </tip>
    <section id="_the_shell_script">
      <title>The shell script</title>
      <para>The <ulink url="https://en.wikipedia.org/wiki/Shell_script">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="https://www.greenend.org.uk/rjk/2001/04/shell.html">https://www.greenend.org.uk/rjk/2001/04/shell.html</ulink>) to learn from mistakes.</para>
      <para>Unlike shell interactive mode (see <xref linkend="_the_simple_shell_command"/> and <xref linkend="_unix_like_text_processing"/>), shell scripts frequently use parameters, conditionals, and loops.</para>
      <section id="_posix_shell_compatibility">
        <title>POSIX shell compatibility</title>
        <para>Many system scripts may be interpreted by any one of <ulink url="https://en.wikipedia.org/wiki/POSIX">POSIX</ulink> shells (see <xref linkend="list-of-shell-programs"/>).</para>
        <itemizedlist>
          <listitem> <para>The default non-interactive POSIX shell "<literal>/usr/bin/sh</literal>" is a symlink pointing to <literal>/usr/bin/dash</literal> and used by many system programs. </para> </listitem>
          <listitem> <para>The default interactive POSIX shell is <literal>/usr/bin/bash</literal>. </para> </listitem>
        </itemizedlist>
        <para>Avoid writing a shell script with <emphasis role="strong">bashisms</emphasis> or <emphasis role="strong">zshisms</emphasis> to make it portable among all POSIX shells.  You can check it using <literal>checkbashisms</literal>(1).</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of typical bashisms</title>
          <tgroup cols="2">
            <colspec colwidth="195pt" align="left"/>
            <colspec colwidth="200pt" align="left"/>
            <thead>
              <row>
                <entry> Good: POSIX </entry>
                <entry> Avoid: bashism </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>if [ "$foo" = "$bar" ] ; then …</literal> </entry>
                <entry> <literal>if [ "$foo" == "$bar" ] ; then …</literal> </entry>
              </row>
              <row>
                <entry> <literal>diff -u file.c.orig file.c</literal> </entry>
                <entry> <literal>diff -u file.c{.orig,}</literal> </entry>
              </row>
              <row>
                <entry> <literal>mkdir /foobar /foobaz</literal> </entry>
                <entry> <literal>mkdir /foo{bar,baz}</literal> </entry>
              </row>
              <row>
                <entry> <literal>funcname() { … }</literal> </entry>
                <entry> <literal>function funcname() { … }</literal> </entry>
              </row>
              <row>
                <entry> octal format: "<literal>\377</literal>" </entry>
                <entry> hexadecimal format: "<literal>\xff</literal>" </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>The "<literal>echo</literal>" command must be used with following cares since its implementation differs among shell builtin and external commands.</para>
        <itemizedlist>
          <listitem> <para> Avoid using any command options except "<literal>-n</literal>".  </para> </listitem>
          <listitem> <para> Avoid using escape sequences in the string since their handling varies.  </para> </listitem>
        </itemizedlist>
        <note> <para>Although "<literal>-n</literal>" option is <emphasis role="strong">not</emphasis> really POSIX syntax, it is generally accepted.</para> </note>
        <tip> <para>Use the "<literal>printf</literal>" command instead of the "<literal>echo</literal>" command if you need to embed escape sequences in the output string.</para> </tip>
      </section>
      <section id="_shell_parameters">
        <title>Shell parameters</title>
        <para>Special shell parameters are frequently used in the shell script.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of shell parameters</title>
          <tgroup cols="2">
            <colspec colwidth="86pt" align="left"/>
            <colspec colwidth="238pt" align="left"/>
            <thead>
              <row>
                <entry> shell parameter </entry>
                <entry> value </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>$0</literal> </entry>
                <entry> name of the shell or shell script </entry>
              </row>
              <row>
                <entry> <literal>$1</literal> </entry>
                <entry> first (1st) shell argument </entry>
              </row>
              <row>
                <entry> <literal>$9</literal> </entry>
                <entry> ninth (9th) shell argument </entry>
              </row>
              <row>
                <entry> <literal>$#</literal> </entry>
                <entry> number of positional parameters </entry>
              </row>
              <row>
                <entry> <literal>"$*"</literal> </entry>
                <entry> <literal>"$1 $2 $3 $4 … "</literal> </entry>
              </row>
              <row>
                <entry> <literal>"$@"</literal> </entry>
                <entry> <literal>"$1" "$2" "$3" "$4" …</literal> </entry>
              </row>
              <row>
                <entry> <literal>$?</literal> </entry>
                <entry> exit status of the most recent command </entry>
              </row>
              <row>
                <entry> <literal>$$</literal> </entry>
                <entry> PID of this shell script </entry>
              </row>
              <row>
                <entry> <literal>$!</literal> </entry>
                <entry> PID of most recently started background job </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>Basic <emphasis role="strong">parameter expansions</emphasis> to remember are as follows.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of shell parameter expansions</title>
          <tgroup cols="3">
            <colspec colwidth="141pt" align="left"/>
            <colspec colwidth="119pt" align="left"/>
            <colspec colwidth="282pt" align="left"/>
            <thead>
              <row>
                <entry> parameter expression form </entry>
                <entry> value if <literal>var</literal> is set </entry>
                <entry> value if <literal>var</literal> is not set </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>${var:-string}</literal> </entry>
                <entry> "<literal>$var</literal>" </entry>
                <entry> "<literal>string</literal>" </entry>
              </row>
              <row>
                <entry> <literal>${var:+string}</literal> </entry>
                <entry> "<literal>string</literal>" </entry>
                <entry> "<literal>null</literal>" </entry>
              </row>
              <row>
                <entry> <literal>${var:=string}</literal> </entry>
                <entry> "<literal>$var</literal>" </entry>
                <entry> "<literal>string</literal>" (and run "<literal>var=string</literal>") </entry>
              </row>
              <row>
                <entry> <literal>${var:?string}</literal> </entry>
                <entry> "<literal>$var</literal>" </entry>
                <entry> echo "<literal>string</literal>" to <emphasis role="strong">stderr</emphasis> (and exit with error) </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>Here, the colon "<literal>:</literal>" in all of these operators is actually optional.</para>
        <itemizedlist>
          <listitem> <para><emphasis role="strong">with</emphasis> "<literal>:</literal>" = operator test for <emphasis role="strong">exist</emphasis> and <emphasis role="strong">not null</emphasis> </para> </listitem>
          <listitem> <para><emphasis role="strong">without</emphasis> "<literal>:</literal>" = operator test for <emphasis role="strong">exist</emphasis> only </para> </listitem>
        </itemizedlist>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of key shell parameter substitutions</title>
          <tgroup cols="2">
            <colspec colwidth="152pt" align="left"/>
            <colspec colwidth="168pt" align="left"/>
            <thead>
              <row>
                <entry> parameter substitution form </entry>
                <entry> result </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>${var%suffix}</literal> </entry>
                <entry> remove smallest suffix pattern </entry>
              </row>
              <row>
                <entry> <literal>${var%%suffix}</literal> </entry>
                <entry> remove largest suffix pattern </entry>
              </row>
              <row>
                <entry> <literal>${var#prefix}</literal> </entry>
                <entry> remove smallest prefix pattern </entry>
              </row>
              <row>
                <entry> <literal>${var##prefix}</literal> </entry>
                <entry> remove largest prefix pattern </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </section>
      <section id="_shell_conditionals">
        <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: non 0 ("False") </para> </listitem>
        </itemizedlist>
        <note> <para>"0" in the shell conditional context means "True", while "0" in the C conditional context means "False".</para> </note>
        <note> <para>"<literal>[</literal>" is the equivalent of the <literal>test</literal> command, which evaluates its arguments up to "<literal>]</literal>" as a conditional expression.</para> </note>
        <para>Basic <emphasis role="strong">conditional idioms</emphasis> to remember are the following.</para>
        <itemizedlist>
          <listitem> <para> "<literal><emphasis>command</emphasis> &amp;&amp; <emphasis>if_success_run_this_command_too</emphasis> || true</literal>" </para> </listitem>
          <listitem> <para> "<literal><emphasis>command</emphasis> || <emphasis>if_not_success_run_this_command_too</emphasis> || true</literal>" </para> </listitem>
          <listitem> <para> A multi-line script snippet as the following </para> </listitem>
        </itemizedlist>
        <screen>if [ <emphasis>conditional_expression</emphasis> ]; then
 <emphasis>if_success_run_this_command</emphasis>
else
 <emphasis>if_not_success_run_this_command</emphasis>
fi</screen>
        <para>Here trailing "<literal>|| true</literal>" was needed to ensure this shell script does not exit at this line accidentally when shell is invoked with "<literal>-e</literal>" flag.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of file comparison operators in the conditional expression</title>
          <tgroup cols="2">
            <colspec colwidth="130pt" align="left"/>
            <colspec colwidth="298pt" align="left"/>
            <thead>
              <row>
                <entry> equation </entry>
                <entry> condition to return logical true </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>-e <emphasis>file</emphasis></literal> </entry>
                <entry> <emphasis>file</emphasis> exists </entry>
              </row>
              <row>
                <entry> <literal>-d <emphasis>file</emphasis></literal> </entry>
                <entry> <emphasis>file</emphasis> exists and is a directory </entry>
              </row>
              <row>
                <entry> <literal>-f <emphasis>file</emphasis></literal> </entry>
                <entry> <emphasis>file</emphasis> exists and is a regular file </entry>
              </row>
              <row>
                <entry> <literal>-w <emphasis>file</emphasis></literal> </entry>
                <entry> <emphasis>file</emphasis> exists and is writable </entry>
              </row>
              <row>
                <entry> <literal>-x <emphasis>file</emphasis></literal> </entry>
                <entry> <emphasis>file</emphasis> exists and is executable </entry>
              </row>
              <row>
                <entry> <literal><emphasis>file1</emphasis> -nt <emphasis>file2</emphasis></literal> </entry>
                <entry> <emphasis>file1</emphasis> is newer than <emphasis>file2</emphasis> (modification) </entry>
              </row>
              <row>
                <entry> <literal><emphasis>file1</emphasis> -ot <emphasis>file2</emphasis></literal> </entry>
                <entry> <emphasis>file1</emphasis> is older than <emphasis>file2</emphasis> (modification) </entry>
              </row>
              <row>
                <entry> <literal><emphasis>file1</emphasis> -ef <emphasis>file2</emphasis></literal> </entry>
                <entry> <emphasis>file1</emphasis> and <emphasis>file2</emphasis> are on the same device and the same inode number </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of string comparison operators in the conditional expression</title>
          <tgroup cols="2">
            <colspec colwidth="114pt" align="left"/>
            <colspec colwidth="298pt" align="left"/>
            <thead>
              <row>
                <entry> equation </entry>
                <entry> condition to return logical true </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>-z <emphasis>str</emphasis></literal> </entry>
                <entry> the length of <emphasis>str</emphasis> is zero </entry>
              </row>
              <row>
                <entry> <literal>-n <emphasis>str</emphasis></literal> </entry>
                <entry> the length of <emphasis>str</emphasis> is non-zero </entry>
              </row>
              <row>
                <entry> <literal><emphasis>str1</emphasis> = <emphasis>str2</emphasis></literal> </entry>
                <entry> <emphasis>str1</emphasis> and <emphasis>str2</emphasis> are equal </entry>
              </row>
              <row>
                <entry> <literal><emphasis>str1</emphasis> != <emphasis>str2</emphasis></literal> </entry>
                <entry> <emphasis>str1</emphasis> and <emphasis>str2</emphasis> are not equal </entry>
              </row>
              <row>
                <entry> <literal><emphasis>str1</emphasis> &lt; <emphasis>str2</emphasis></literal> </entry>
                <entry> <emphasis>str1</emphasis> sorts before <emphasis>str2</emphasis> (locale dependent) </entry>
              </row>
              <row>
                <entry> <literal><emphasis>str1</emphasis> &gt; <emphasis>str2</emphasis></literal> </entry>
                <entry> <emphasis>str1</emphasis> sorts after <emphasis>str2</emphasis> (locale dependent) </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para><emphasis role="strong">Arithmetic</emphasis> integer comparison operators in the conditional expression are "<literal>-eq</literal>", "<literal>-ne</literal>", "<literal>-lt</literal>", "<literal>-le</literal>", "<literal>-gt</literal>", and "<literal>-ge</literal>".</para>
      </section>
      <section id="_shell_loops">
        <title>Shell loops</title>
        <para>There are several loop idioms to use in POSIX shell.</para>
        <itemizedlist>
          <listitem> <para> "<literal>for x in foo1 foo2 … ; do command ; done</literal>" loops by assigning items from the list "<literal>foo1 foo2 …</literal>" to variable "<literal>x</literal>" and executing "<literal>command</literal>".  </para> </listitem>
          <listitem> <para> "<literal>while condition ; do command ; done</literal>" repeats "<literal>command</literal>" while "<literal>condition</literal>" is true.  </para> </listitem>
          <listitem> <para> "<literal>until condition ; do command ; done</literal>" repeats "<literal>command</literal>" while "<literal>condition</literal>" is not true.  </para> </listitem>
          <listitem> <para> "<literal>break</literal>" enables to exit from the loop.  </para> </listitem>
          <listitem> <para> "<literal>continue</literal>" enables to resume the next iteration of the loop.  </para> </listitem>
        </itemizedlist>
        <tip> <para>The <ulink url="https://en.wikipedia.org/wiki/C_(programming_language)">C</ulink>-language like numeric iteration can be realized by using <literal>seq</literal>(1) as the "<literal>foo1 foo2 …</literal>" generator.</para> </tip>
        <tip> <para>See <xref linkend="_repeating_a_command_looping_over_files"/>.</para> </tip>
      </section>
      <section id="_shell_environment_variables">
        <title>Shell environment variables</title>
        <para>Some popular environment variables for the normal shell command prompt may not be available under the execution environment of your script.</para>
        <itemizedlist>
          <listitem> <para> For "<literal>$USER</literal>", use "<literal>$(id -un)</literal>"  </para> </listitem>
          <listitem> <para> For "<literal>$UID</literal>", use "<literal>$(id -u)</literal>"  </para> </listitem>
          <listitem> <para> For "<literal>$HOME</literal>", use "<literal>$(getent passwd "$(id -u)"|cut -d ":" -f 6)</literal>" (this works also on <xref linkend="_the_modern_centralized_system_management"/>) </para> </listitem>
        </itemizedlist>
      </section>
      <section id="_the_shell_command_line_processing_sequence">
        <title>The shell command-line processing sequence</title>
        <para>The shell processes a script roughly as the following sequence.</para>
        <itemizedlist>
          <listitem> <para> The shell reads a line.  </para> </listitem>
          <listitem> <para> The shell groups a part of the line as <emphasis role="strong">one token</emphasis> if it is within <literal>"…"</literal> or <literal>'…'</literal>.  </para> </listitem>
          <listitem> <para> The shell splits other part of a line into <emphasis role="strong">tokens</emphasis> by the following.  </para>
            <itemizedlist>
              <listitem> <para> Whitespaces: <literal><emphasis>space</emphasis> <emphasis>tab</emphasis> <emphasis>newline</emphasis></literal> </para> </listitem>
              <listitem> <para> Metacharacters: <literal>&lt; &gt; | ; &amp; ( )</literal> </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> The shell checks the <emphasis role="strong">reserved word</emphasis> for each token to adjust its behavior if not within <literal>"…"</literal>  or <literal>'…'</literal>.  </para>
            <itemizedlist>
              <listitem> <para><emphasis role="strong">reserved word</emphasis>: <literal>if then elif else fi for in while unless do done case esac</literal></para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem> <para> The shell expands <emphasis role="strong">alias</emphasis> if not within <literal>"…"</literal>  or <literal>'…'</literal>.  </para> </listitem>
          <listitem>
            <para> The shell expands <emphasis role="strong">tilde</emphasis> if not within <literal>"…"</literal>  or <literal>'…'</literal>.  </para>
            <itemizedlist>
              <listitem> <para> "<literal>~</literal>" → current user's home directory </para> </listitem>
              <listitem> <para> "<literal>~<emphasis>user</emphasis></literal>" → <literal><emphasis>user</emphasis></literal>'s home directory </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> The shell expands <emphasis role="strong">parameter</emphasis> to its value if not within <literal>'…'</literal>.  </para>
            <itemizedlist>
              <listitem> <para><emphasis role="strong">parameter</emphasis>: "<literal>$PARAMETER</literal>" or "<literal>${PARAMETER}</literal>" </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> The shell expands <emphasis role="strong">command substitution</emphasis> if not within <literal>'…'</literal>.  </para>
            <itemizedlist>
              <listitem> <para> "<literal>$( command )</literal>" → the output of "<literal>command</literal>" </para> </listitem>
              <listitem> <para> "<literal>` command `</literal>" → the output of "<literal>command</literal>" </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> The shell expands <emphasis role="strong">pathname glob</emphasis> to matching file names if not within <literal>"…"</literal>  or <literal>'…'</literal>.  </para>
            <itemizedlist>
              <listitem> <para><literal>*</literal> → any characters </para> </listitem>
              <listitem> <para><literal>?</literal> → one character </para> </listitem>
              <listitem> <para><literal>[…]</literal> → any one of the characters in "<literal>…</literal>" </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> The shell looks up <emphasis role="strong">command</emphasis> from the following and execute it.  </para>
            <itemizedlist>
              <listitem> <para><emphasis role="strong">function</emphasis> definition </para> </listitem>
              <listitem> <para><emphasis role="strong">builtin</emphasis> command </para> </listitem>
              <listitem> <para><emphasis role="strong">executable file</emphasis> in "<literal>$PATH</literal>" </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem> <para> The shell goes to the next line and repeats this process again from the top of this sequence.  </para> </listitem>
        </itemizedlist>
        <para>Single quotes within double quotes have no effect.</para>
        <para>Executing "<literal>set -x</literal>" in the shell or invoking the shell with "<literal>-x</literal>" option make the shell to print all of commands executed.  This is quite handy for debugging.</para>
      </section>
      <section id="_utility_programs_for_shell_script">
        <title>Utility programs for shell script</title>
        <para>In order to make your shell program as portable as possible across Debian systems, it is a good idea to limit utility programs to ones provided by <emphasis role="strong">essential</emphasis> packages.</para>
        <itemizedlist>
          <listitem> <para> "<literal>aptitude search ~E</literal>" lists <emphasis role="strong">essential</emphasis> packages.  </para> </listitem>
          <listitem> <para> "<literal>dpkg -L <emphasis>package_name</emphasis> |grep '/man/man.*/'</literal>" lists manpages for commands offered by <literal><emphasis>package_name</emphasis></literal> package.  </para> </listitem>
        </itemizedlist>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of packages containing small utility programs for shell scripts</title>
          <tgroup cols="4">
            <colspec colwidth="81pt" align="left"/>
            <colspec colwidth="76pt" align="left"/>
            <colspec colwidth="70pt" align="left"/>
            <colspec colwidth="255pt" align="left"/>
            <thead>
              <row>
                <entry> package </entry>
                <entry> popcon </entry>
                <entry> size </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>dash</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> small and fast POSIX-compliant shell for <literal>sh</literal> </entry>
              </row>
              <row>
                <entry> <literal>coreutils</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> GNU core utilities </entry>
              </row>
              <row>
                <entry> <literal>grep</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> GNU <literal>grep</literal>, <literal>egrep</literal> and <literal>fgrep</literal> </entry>
              </row>
              <row>
                <entry> <literal>sed</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> GNU <literal>sed</literal> </entry>
              </row>
              <row>
                <entry> <literal>mawk</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> small and fast <literal>awk</literal> </entry>
              </row>
              <row>
                <entry> <literal>debianutils</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> miscellaneous utilities specific to Debian </entry>
              </row>
              <row>
                <entry> <literal>bsdutils</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> basic utilities from 4.4BSD-Lite </entry>
              </row>
              <row>
                <entry> <literal>bsdextrautils</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> extra utilities from 4.4BSD-Lite </entry>
              </row>
              <row>
                <entry> <literal>moreutils</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> additional Unix utilities </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <tip> <para>Although <literal>moreutils</literal> may not exist outside of Debian, it offers interesting small programs.  Most notable one is <literal>sponge</literal>(8) which is quite useful when you wish to overwrite original file.</para> </tip>
        <para>See <xref linkend="_unix_like_text_processing"/> for examples.</para>
      </section>
    </section>
    <section id="_scripting_in_interpreted_languages">
      <title>Scripting in interpreted languages</title>
    <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
      <title>List of interpreter related packages</title>
      <tgroup cols="4">
        <colspec colwidth="97pt" align="left"/>
        <colspec colwidth="76pt" align="left"/>
        <colspec colwidth="70pt" align="left"/>
        <colspec colwidth="396pt" align="left"/>
        <thead>
          <row>
            <entry> package </entry>
            <entry> popcon </entry>
            <entry> size </entry>
            <entry> documentation </entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry> <literal>dash</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/Unix_shell">sh</ulink>: small and fast POSIX-compliant shell for <literal>sh</literal> </entry>
          </row>
          <row>
            <entry> <literal>bash</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/Unix_shell">sh</ulink>: "<literal>info bash</literal>" provided by <literal>bash-doc</literal> </entry>
          </row>
          <row>
            <entry> <literal>mawk</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/AWK">AWK</ulink>: small and fast <literal>awk</literal> </entry>
          </row>
          <row>
            <entry> <literal>gawk</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/AWK">AWK</ulink>: "<literal>info gawk</literal>" provided by <literal>gawk-doc</literal> </entry>
          </row>
          <row>
            <entry> <literal>perl</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/Perl">Perl</ulink>: <literal>perl</literal>(1) and html pages provided by <literal>perl-doc</literal> and <literal>perl-doc-html</literal> </entry>
          </row>
          <row>
            <entry> <literal>libterm-readline-gnu-perl</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> Perl extension for the GNU ReadLine/History Library: <literal>perlsh</literal>(1) </entry>
          </row>
          <row>
            <entry> <literal>libreply-perl</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> REPL for Perl: <literal>reply</literal>(1) </entry>
          </row>
          <row>
            <entry> <literal>libdevel-repl-perl</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> REPL for Perl: <literal>re.pl</literal>(1) </entry>
          </row>
          <row>
            <entry> <literal>python3</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/Python_(programming_language)">Python</ulink>: <literal>python3</literal>(1) and html pages provided by <literal>python3-doc</literal></entry> </row>
          <row>
            <entry> <literal>tcl</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/Tcl">Tcl</ulink>: <literal>tcl</literal>(3) and detail manual pages provided by <literal>tcl-doc</literal></entry> </row>
          <row>
            <entry> <literal>tk</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/Tk_(software)">Tk</ulink>: <literal>tk</literal>(3) and detail manual pages provided by <literal>tk-doc</literal></entry>
          </row>
          <row>
            <entry> <literal>ruby</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> <ulink url="https://en.wikipedia.org/wiki/Ruby_(programming_language)">Ruby</ulink>: <literal>ruby</literal>(1), <literal>erb</literal>(1), <literal>irb</literal>(1), <literal>rdoc</literal>(1), <literal>ri</literal>(1) </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
        <para>When you wish to automate a task on Debian, you should script it with an interpreted language first.  The guide line for the choice of the interpreted language is:</para>
        <itemizedlist>
          <listitem> <para> Use <literal>dash</literal>, if the task is a simple one which combines CLI programs with a shell program. </para> </listitem>
          <listitem> <para> Use <literal>python3</literal>, if the task isn't a simple one and you are writing it from scratch. </para> </listitem>
          <listitem> <para> Use <literal>perl</literal>, <literal>tcl</literal>, <literal>ruby</literal>, ... if there is an existing code using one of these languages on Debian which needs to be touched up to do the task. </para> </listitem>
        </itemizedlist>
        <para>If the resulting code is too slow, you can rewrite only the critical portion for the execution speed in a compiled language and call it from the interpreted language.</para>
      <section id="_debugging_interpreter_codes">
        <title>Debugging interpreted language codes</title>
        <para>Most interpreters offer basic syntax check and code tracing functionalities.</para>
        <itemizedlist>
          <listitem> <para> “<emphasis role="strong">dash -n</emphasis> <emphasis>script.sh</emphasis>” - Syntax check of a Shell script </para> </listitem>
          <listitem> <para> “<emphasis role="strong">dash -x</emphasis> <emphasis>script.sh</emphasis>” - Trace a Shell script </para> </listitem>
          <listitem> <para> “<emphasis role="strong">python -m py_compile</emphasis> <emphasis>script.py</emphasis>” - Syntax check of a Python script </para> </listitem>
          <listitem> <para> “<emphasis role="strong">python -mtrace --trace</emphasis> <emphasis>script.py</emphasis>” - Trace a Python script </para> </listitem>
          <listitem> <para> “<emphasis role="strong">perl -I ../libpath -c</emphasis> <emphasis>script.pl</emphasis>” - Syntax check of a Perl script </para> </listitem>
          <listitem> <para> “<emphasis role="strong">perl -d:Trace</emphasis> <emphasis>script.pl</emphasis>” - Trace a Perl script </para> </listitem>
        </itemizedlist>
        <para>For testing code for <literal>dash</literal>, try <xref linkend="_readline_wrapper"/> which accommodates <literal>bash</literal>-like interactive environment.</para>
        <para>For testing code for <literal>perl</literal>, try REPL environment for Perl which accommodates <ulink url="https://en.wikipedia.org/wiki/Python_(programming_language)">Python</ulink>-like <ulink url="https://en.wikipedia.org/wiki/Read–eval–print_loop">REPL (=READ + EVAL + PRINT + LOOP)</ulink> environment for <ulink url="https://en.wikipedia.org/wiki/Perl">Perl</ulink>. </para>
      </section>
      <section id="_gui_program_with_the_shell_script">
        <title>GUI program with the shell script</title>
        <para>The shell script can be improved to create an attractive GUI program.  The trick is to use one of so-called dialog programs instead of dull interaction using <literal>echo</literal> and <literal>read</literal> commands.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of dialog programs</title>
          <tgroup cols="4">
            <colspec colwidth="65pt" align="left"/>
            <colspec colwidth="76pt" align="left"/>
            <colspec colwidth="70pt" align="left"/>
            <colspec colwidth="456pt" align="left"/>
            <thead>
              <row>
                <entry> package </entry>
                <entry> popcon </entry>
                <entry> size </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>x11-utils</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry><literal>xmessage</literal>(1): display a message or query in a window (X) </entry>
              </row>
              <row>
                <entry> <literal>whiptail</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> displays user-friendly dialog boxes from shell scripts (newt) </entry>
              </row>
              <row>
                <entry> <literal>dialog</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> displays user-friendly dialog boxes from shell scripts (ncurses) </entry>
              </row>
              <row>
                <entry> <literal>zenity</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> display graphical dialog boxes from shell scripts (GTK) </entry>
              </row>
              <row>
                <entry> <literal>ssft</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> Shell Scripts Frontend Tool (wrapper for zenity, kdialog, and dialog with gettext) </entry>
              </row>
              <row>
                <entry> <literal>gettext</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> "<literal>/usr/bin/gettext.sh</literal>": translate message </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>Here is an example of GUI program to demonstrate how easy it is just with a shell script.</para>
        <para>This script uses <literal>zenity</literal> to select a file (default <literal>/etc/motd</literal>) and display it.</para>
        <para>GUI launcher for this script can be created following <xref linkend="_starting_a_program_from_gui"/>.</para>
        <screen>#!/bin/sh -e
# Copyright (C) 2021 Osamu Aoki &lt;osamu@debian.org&gt;, Public Domain
# vim:set sw=2 sts=2 et:
DATA_FILE=$(zenity --file-selection --filename="/etc/motd" --title="Select a file to check") || \
  ( echo "E: File selection error" &gt;&amp;2 ; exit 1 )
# Check size of archive
if ( file -ib "$DATA_FILE" | grep -qe '^text/' ) ; then
  zenity --info --title="Check file: $DATA_FILE" --width 640  --height 400 \
    --text="$(head -n 20 "$DATA_FILE")"
else
  zenity --info --title="Check file: $DATA_FILE" --width 640  --height 400 \
    --text="The data is MIME=$(file -ib "$DATA_FILE")"
fi</screen>
        <para>This kind of approach to GUI program with the shell script is useful only for simple choice cases.  If you are to write any program with complexities, please consider writing it on more capable platform.</para>
      </section>
      <section id="_custom_actions_for_gui_filer">
        <title>Custom actions for GUI filer</title>
        <para>GUI filer programs can be extended to perform some popular actions on selected files using additional extension packages.  They can also made to perform very specific custom actions by adding your specific scripts.</para>
        <itemizedlist>
          <listitem> <para>For GNOME, see <ulink url="https://help.ubuntu.com/community/NautilusScriptsHowto">NautilusScriptsHowto</ulink>. </para> </listitem>
          <listitem> <para>For KDE, see <ulink url="https://develop.kde.org/docs/dolphin/service-menus/">Creating Dolphin Service Menus</ulink>. </para> </listitem>
          <listitem> <para>For Xfce, see <ulink url="https://docs.xfce.org/xfce/thunar/custom-actions">Thunar - Custom Actions</ulink> and <ulink url="https://help.ubuntu.com/community/ThunarCustomActions"></ulink>. </para> </listitem>
          <listitem> <para>For LXDE, see <ulink url="https://manual.lubuntu.me/stable/2/2.4/2.4.4/pcmanfm-qt.html#custom-actions">Custom Actions</ulink>. </para> </listitem>
        </itemizedlist>
      </section>
      <section id="_perl_short_script_madness">
        <title>Perl short script madness</title>
        <para>In order to process data, <literal>sh</literal> needs to spawn sub-process running <literal>cut</literal>, <literal>grep</literal>, <literal>sed</literal>, etc., and is slow.  On the other hand, <literal>perl</literal> has internal capabilities to process data, and is fast.  So many system maintenance scripts on Debian use <literal>perl</literal>.</para>
        <para>Let's think following one-liner AWK script snippet and its equivalents in Perl.</para>
        <screen>awk '($2=="1957") { print $3 }' |</screen>
        <para>This 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>
        <screen>perl -ne 'if ((@f=split)[1] eq "1957") { print "$f[2]\n"}' |</screen>
        <screen>perl -ne '@f=split; print $f[2] if ( $f[1]==1957 )' |</screen>
        <screen>perl -lane 'print $F[2] if $F[1] eq "1957"' |</screen>
        <screen>perl -lane 'print$F[2]if$F[1]eq+1957' |</screen>
        <para>The last one is a riddle.  It took advantage of following Perl features.</para>
        <itemizedlist>
          <listitem> <para> The whitespace is optional.  </para> </listitem>
          <listitem> <para> The automatic conversion exists from number to the string.  </para> </listitem>
          <listitem> <para> Perl execution tricks via command line options: <literal>perlrun</literal>(1) </para> </listitem>
          <listitem> <para> Perl special variables: <literal>perlvar</literal>(1) </para> </listitem>
        </itemizedlist>
        <para>This flexibility is the strength of Perl.  At the same time, this allows us to create cryptic and tangled codes.  So be careful.</para>
      </section>
    </section>
    <section id="_coding_in_compiled_languages">
      <title>Coding in compiled languages</title>
      <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
        <title>List of compiler related packages</title>
        <tgroup cols="4">
          <colspec colwidth="97pt" align="left"/>
          <colspec colwidth="76pt" align="left"/>
          <colspec colwidth="70pt" align="left"/>
          <colspec colwidth="396pt" align="left"/>
          <thead>
            <row>
              <entry> package </entry>
              <entry> popcon </entry>
              <entry> size </entry>
              <entry> description </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry> <literal>gcc</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> GNU C compiler</entry>
            </row>
            <row>
              <entry> <literal>libc6-dev</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> GNU C Library: Development Libraries and Header Files</entry>
            </row>
            <row>
              <entry> <literal>g++</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> GNU C++ compiler </entry>
            </row>
            <row>
              <entry> <literal>libstdc++-10-dev</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> GNU Standard C++ Library v3 (development files) </entry>
            </row>
            <row>
              <entry> <literal>cpp</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> GNU C preprocessor </entry>
            </row>
            <row>
              <entry> <literal>gettext</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> GNU Internationalization utilities </entry>
            </row>
            <row>
              <entry> <literal>glade</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> GTK User Interface Builder </entry>
            </row>
            <row>
              <entry> <literal>valac</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> C# like language for the GObject system </entry>
            </row>
            <row>
              <entry> <literal>flex</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> <ulink url="https://en.wikipedia.org/wiki/Lex_(software)">LEX</ulink>-compatible <ulink url="https://en.wikipedia.org/wiki/Flex_(lexical_analyser_generator)">fast lexical analyzer generator</ulink> </entry>
            </row>
            <row>
              <entry> <literal>bison</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> <ulink url="https://en.wikipedia.org/wiki/Yacc">YACC</ulink>-compatible <ulink url="https://en.wikipedia.org/wiki/GNU_Bison">parser generator</ulink> </entry>
            </row>
            <row>
              <entry> <literal>susv2</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> fetch "<ulink url="https://unix.org/version2/">The Single UNIX Specifications v2</ulink>" </entry>
            </row>
            <row>
              <entry> <literal>susv3</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> fetch "<ulink url="https://unix.org/version3/">The Single UNIX Specifications v3</ulink>" </entry>
            </row>
            <row>
              <entry> <literal>susv4</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> fetch "<ulink url="https://unix.org/version4/">The Single UNIX Specifications v4</ulink>" </entry>
            </row>
            <row>
              <entry> <literal>golang</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Go programming language compiler </entry>
            </row>
            <row>
              <entry> <literal>rustc</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Rust systems programming language </entry>
            </row>
            <row>
              <entry> <literal>haskell-platform</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Standard <ulink url="https://en.wikipedia.org/wiki/Haskell_(programming_language)">Haskell</ulink> libraries and tools </entry>
            </row>
            <row>
              <entry> <literal>gfortran</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> GNU Fortran 95 compiler </entry>
            </row>
            <row>
              <entry> <literal>fpc</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Free Pascal </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>Here, <xref linkend="_flex_a_better_lex"/> and <xref linkend="_bison_a_better_yacc"/> are included to indicate how compiler-like program can be written in C language by compiling higher level description into C language.</para>
      <section id="_c">
        <title>C</title>
        <para>You can set up proper environment to compile programs written in the <ulink url="https://en.wikipedia.org/wiki/C_(programming_language)">C programming language</ulink> by the following.</para>
        <screen># apt-get install glibc-doc manpages-dev libc6-dev gcc build-essential</screen>
        <para>The <literal>libc6-dev</literal> package, i.e., GNU C Library, provides <ulink url="https://en.wikipedia.org/wiki/C_standard_library">C standard library</ulink> which is collection of header files and library routines used by the C programming language.</para>
        <para>See references for C as the following.</para>
        <itemizedlist>
          <listitem> <para> "<literal>info libc</literal>" (C library function reference) </para> </listitem>
          <listitem> <para> <literal>gcc</literal>(1) and "<literal>info gcc</literal>" </para> </listitem>
          <listitem> <para> <literal>each_C_library_function_name</literal>(3) </para> </listitem>
          <listitem> <para> Kernighan &amp; Ritchie, "The C Programming Language", 2nd edition (Prentice Hall) </para> </listitem>
        </itemizedlist>
      </section>
      <section id="_simple_c_program_gcc">
        <title>Simple C program (gcc)</title>
        <para>A simple example "<literal>example.c</literal>" can compiled with a library "<literal>libm</literal>" into an executable "<literal>run_example</literal>" by the following.</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, "<literal>-lm</literal>" is needed to link library "<literal>/usr/lib/libm.so</literal>" from the <literal>libc6</literal> package for <literal>sqrt</literal>(3).  The actual library is in "<literal>/lib/</literal>" with filename "<literal>libm.so.6</literal>", which is a symlink to "<literal>libm-2.7.so</literal>".</para>
        <para>Look at the last parameter in the output text.  There are more than 10 characters even though "<literal>%10s</literal>" is specified.</para>
        <para>The use of pointer memory operation functions without boundary checks, such as <literal>sprintf</literal>(3) and <literal>strcpy</literal>(3), is deprecated to prevent buffer overflow exploits that leverage the above overrun effects.  Instead, use <literal>snprintf</literal>(3) and <literal>strncpy</literal>(3).</para>
      </section>
      <section id="_flex_a_better_lex">
        <title>Flex — a better Lex</title>
        <para><ulink url="https://en.wikipedia.org/wiki/Flex_(lexical_analyser_generator)">Flex</ulink> is a <ulink url="https://en.wikipedia.org/wiki/Lex_(software)">Lex</ulink>-compatible fast <ulink url="https://en.wikipedia.org/wiki/Lexical_analysis">lexical analyzer</ulink> generator.</para>
        <para>Tutorial for <literal>flex</literal>(1) can be found in "<literal>info flex</literal>".</para>
        <para>Many simple examples can be found under <literal>/usr/share/doc/flex/examples/</literal>".  <footnote> <para> Some <ulink url="https://bugs.debian.org/1055082">tweaks</ulink> may be required to get them work under the current system. </para></footnote> </para>
      </section>
      <section id="_bison_a_better_yacc">
        <title>Bison — a better Yacc</title>
        <para>Several packages provide a <ulink url="https://en.wikipedia.org/wiki/Yacc">Yacc</ulink>-compatible lookahead <ulink url="https://en.wikipedia.org/wiki/LR_parser">LR parser</ulink> or <ulink url="https://en.wikipedia.org/wiki/LALR_parser">LALR parser</ulink> generator in Debian.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of Yacc-compatible LALR parser generators</title>
          <tgroup cols="4">
            <colspec colwidth="48pt" align="left"/>
            <colspec colwidth="76pt" align="left"/>
            <colspec colwidth="70pt" align="left"/>
            <colspec colwidth="358pt" align="left"/>
            <thead>
              <row>
                <entry> package </entry>
                <entry> popcon </entry>
                <entry> size </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>bison</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> <ulink url="https://en.wikipedia.org/wiki/GNU_bison">GNU LALR parser generator</ulink> </entry>
              </row>
              <row>
                <entry> <literal>byacc</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> Berkeley LALR parser generator </entry>
              </row>
              <row>
                <entry> <literal>btyacc</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> backtracking parser generator based on <literal>byacc</literal> </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>Tutorial for <literal>bison</literal>(1) can be found in "<literal>info bison</literal>".</para>
        <para>You need to provide your own "<literal>main()</literal>" and "<literal>yyerror()</literal>".  "<literal>main()</literal>" calls "<literal>yyparse()</literal>" which calls "<literal>yylex()</literal>", usually created with Flex.</para>
        <para>Here is an example to create a simple terminal calculator program.</para>
        <para>Let's create <literal>example.y</literal>:</para>
        <screen>
/* calculator source for bison */
%{
#include &lt;stdio.h&gt;
extern int yylex(void);
extern int yyerror(char *);
%}

/* declare tokens */
%token NUMBER
%token OP_ADD OP_SUB OP_MUL OP_RGT OP_LFT OP_EQU

%%
calc:
 | calc exp OP_EQU    { printf("Y: RESULT = %d\n", $2); }
 ;

exp: factor
 | exp OP_ADD factor  { $$ = $1 + $3; }
 | exp OP_SUB factor  { $$ = $1 - $3; }
 ;

factor: term
 | factor OP_MUL term { $$ = $1 * $3; }
 ;

term: NUMBER
 | OP_LFT exp OP_RGT  { $$ = $2; }
  ;
%%

int main(int argc, char **argv)
{
  yyparse();
}

int yyerror(char *s)
{
  fprintf(stderr, "error: '%s'\n", s);
}

</screen>
        <para>Let's create, <literal>example.l</literal>:</para>
        <screen>
/* calculator source for flex */
%{
#include "example.tab.h"
%}

%%
[0-9]+ { printf("L: NUMBER = %s\n", yytext); yylval = atoi(yytext); return NUMBER; }
"+"    { printf("L: OP_ADD\n"); return OP_ADD; }
"-"    { printf("L: OP_SUB\n"); return OP_SUB; }
"*"    { printf("L: OP_MUL\n"); return OP_MUL; }
"("    { printf("L: OP_LFT\n"); return OP_LFT; }
")"    { printf("L: OP_RGT\n"); return OP_RGT; }
"="    { printf("L: OP_EQU\n"); return OP_EQU; }
"exit" { printf("L: exit\n");   return YYEOF; } /* YYEOF = 0 */
.      { /* ignore all other */ }
%%
</screen>
<para>Then execute as follows from the shell prompt to try this:</para>
        <screen>
$ bison -d example.y
$ flex example.l
$ gcc -lfl example.tab.c lex.yy.c -o example
$ ./example
$ ./example
1 + 2 * ( 3 + 1 ) =
L: NUMBER = 1
L: OP_ADD
L: NUMBER = 2
L: OP_MUL
L: OP_LFT
L: NUMBER = 3
L: OP_ADD
L: NUMBER = 1
L: OP_RGT
L: OP_EQU
Y: RESULT = 9

exit
L: exit
</screen>
      </section>
    </section>
    <section id="_static_code_analysis_tools">
      <title>Static code analysis tools</title>
      <para><ulink url="https://en.wikipedia.org/wiki/Lint_programming_tool">Lint</ulink> like tools can help automatic <ulink url="https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis">static code analysis</ulink>.</para>
      <para><ulink url="https://en.wikipedia.org/wiki/Indent_(Unix)">Indent</ulink> like tools can help human code reviews by reformatting source codes consistently.</para>
      <para><ulink url="https://en.wikipedia.org/wiki/Ctags">Ctags</ulink> like tools can help human code reviews by generating an index (or tag) file of names found in source codes.</para>
      <tip> <para>Configuring your favorite editor (<literal>emacs</literal> or <literal>vim</literal>) to use asynchronous lint engine plugins helps your code writing.  These plugins are getting very powerful by taking advantage of <ulink url="https://en.wikipedia.org/wiki/Language_Server_Protocol">Language Server Protocol</ulink>.  Since they are moving fast, using their upstream code instead of Debian package may be a good option.</para> </tip>
      <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
        <title>List of tools for static code analysis</title>
        <tgroup cols="4">
          <colspec colwidth="86pt" align="left"/>
          <colspec colwidth="76pt" align="left"/>
          <colspec colwidth="70pt" align="left"/>
          <colspec colwidth="380pt" align="left"/>
          <thead>
            <row>
              <entry> package </entry>
              <entry> popcon </entry>
              <entry> size </entry>
              <entry> description </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry> <literal>vim-ale</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Asynchronous Lint Engine for Vim 8 and NeoVim </entry>
            </row>
            <row>
              <entry> <literal>vim-syntastic</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Syntax checking hacks for vim </entry>
            </row>
            <row>
              <entry> <literal>elpa-flycheck</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> modern on-the-fly syntax checking for Emacs </entry>
            </row>
            <row>
              <entry> <literal>elpa-relint</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Emacs Lisp regexp mistake finder </entry>
            </row>
            <row>
              <entry> <literal>cppcheck-gui</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> tool for static C/C++ code analysis (GUI) </entry>
            </row>
            <row>
              <entry> <literal>shellcheck</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> lint tool for shell scripts </entry>
            </row>
            <row>
              <entry> <literal>pyflakes3</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> passive checker of Python 3 programs </entry>
            </row>
            <row>
              <entry> <literal>pylint</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Python code static checker </entry>
            </row>
            <row>
              <entry> <literal>perl</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> interpreter with internal static code checker: <literal>B::Lint</literal>(3perl) </entry>
            </row>
            <row>
              <entry> <literal>rubocop</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Ruby static code analyzer </entry>
            </row>
            <row>
              <entry> <literal>clang-tidy</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> clang-based C++ linter tool </entry>
            </row>
            <row>
              <entry> <literal>splint</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> tool for statically checking C programs for bugs </entry>
            </row>
            <row>
              <entry> <literal>flawfinder</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> tool to examine C/C++ source code and looks for security weaknesses </entry>
            </row>
            <row>
              <entry> <literal>black</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> uncompromising Python code formatter </entry>
            </row>
            <row>
              <entry> <literal>perltidy</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Perl script indenter and reformatter </entry>
            </row>
            <row>
              <entry> <literal>indent</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> C language source code formatting program </entry>
            </row>
            <row>
              <entry> <literal>astyle</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Source code indenter for C, C++, Objective-C, C#, and Java </entry>
            </row>
            <row>
              <entry> <literal>bcpp</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> C(++) beautifier </entry>
            </row>
            <row>
              <entry> <literal>xmlindent</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> XML stream reformatter </entry>
            </row>
            <row>
              <entry> <literal>global</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> Source code search and browse tools </entry>
            </row>
            <row>
              <entry> <literal>exuberant-ctags</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> build tag file indexes of source code definitions </entry>
            </row>
            <row>
              <entry> <literal>universal-ctags</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> build tag file indexes of source code definitions </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
    <section id="_debug">
      <title>Debug</title>
      <para>Debug is important part of programming activities.  Knowing how to debug programs makes you a good Debian user who can produce meaningful bug reports.</para>
    <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
      <title>List of debug packages</title>
      <tgroup cols="4">
        <colspec colwidth="97pt" align="left"/>
        <colspec colwidth="76pt" align="left"/>
        <colspec colwidth="70pt" align="left"/>
        <colspec colwidth="396pt" align="left"/>
        <thead>
          <row>
            <entry> package </entry>
            <entry> popcon </entry>
            <entry> size </entry>
            <entry> documentation </entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry> <literal>gdb</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> "<literal>info gdb</literal>" provided by <literal>gdb-doc</literal> </entry>
          </row>
          <row>
            <entry> <literal>ddd</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> "<literal>info ddd</literal>" provided by <literal>ddd-doc</literal> </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
      <section id="_basic_gdb_execution">
        <title>Basic gdb execution</title>
        <para>Primary <ulink url="https://en.wikipedia.org/wiki/Debugger">debugger</ulink> on Debian is <literal>gdb</literal>(1) which enables you to inspect a program while it executes.</para>
        <para>Let's install <literal>gdb</literal> and related programs by the following.</para>
        <screen># apt-get install gdb gdb-doc build-essential devscripts</screen>
        <para>Good tutorial of <literal>gdb</literal> can be found:</para>
        <itemizedlist>
          <listitem> <para> “<literal>info gdb</literal>” </para> </listitem>
          <listitem> <para> “Debugging with GDB” in <literal>/usr/share/doc/gdb-doc/html/gdb/index.html</literal>  </para> </listitem>
          <listitem> <para> “<ulink url="https://developers.redhat.com/blog/2021/04/30/the-gdb-developers-gnu-debugger-tutorial-part-1-getting-started-with-the-debugger">tutorial on the web</ulink>” </para> </listitem>
        </itemizedlist>
        <para>Here is a simple example of using <literal>gdb</literal>(1) on a "<literal>program</literal>" compiled with the "<literal>-g</literal>" option to produce debugging information.</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 <literal>gdb</literal>(1) commands can be abbreviated.  Tab expansion works as in the shell.</para> </tip>
      </section>
      <section id="_debugging_the_debian_package">
        <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 <literal>gdb</literal>(1), <literal>*-dbgsym</literal> packages need to be installed (e.g. <literal>coreutils-dbgsym</literal> in the case of <literal>coreutils</literal>).  The source packages generate <literal>*-dbgsym</literal> packages automatically along with normal binary packages and those debug packages are placed separately in <ulink url="http://deb.debian.org/debian-debug/">debian-debug</ulink> archive. Please refer to <ulink url="https://wiki.debian.org/DebugPackage">articles on Debian Wiki</ulink> for more information.</para>
        <para>If a package to be debugged does not provide its <literal>*-dbgsym</literal> package, you need to install it after rebuilding it by the following.</para>
        <screen>$ mkdir /path/new ; cd /path/new
$ sudo apt-get update
$ sudo apt-get dist-upgrade
$ sudo apt-get install fakeroot devscripts build-essential
$ apt-get source package_name
$ cd package_name*
$ sudo apt-get build-dep ./</screen>
        <para>Fix bugs if needed.</para>
        <para>Bump package version to one which does not collide with official Debian versions, e.g. one appended with "<literal>+debug1</literal>" when recompiling existing package version, or one appended with "<literal>~pre1</literal>" when compiling unreleased package version by the following.</para>
        <screen>$ dch -i</screen>
        <para>Compile and install packages with debug symbols by the following.</para>
        <screen>$ export DEB_BUILD_OPTIONS="nostrip noopt"
$ debuild
$ cd ..
$ sudo debi package_name*.changes</screen>
        <para>You need to check build scripts of the package and ensure to use "<literal>CFLAGS=-g -Wall</literal>" for compiling binaries.</para>
      </section>
      <section id="_obtaining_backtrace">
        <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 <literal>gdb</literal>(1) using one of the following approaches:</para>
        <itemizedlist>
          <listitem>
            <para>Crash-in-GDB approach:</para>
            <itemizedlist>
              <listitem> <para>Run the program from GDB.</para> </listitem>
              <listitem> <para>Crash the program.</para> </listitem>
              <listitem> <para>Type "<literal>bt</literal>" at the GDB prompt.</para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para>Crash-first approach:</para>
            <itemizedlist>
              <listitem> <para>Update the “<emphasis role="strong">/etc/security/limits.conf</emphasis>” file to include the following: </para> <screen>* soft core unlimited</screen> </listitem>
              <listitem> <para>Type "<literal>ulimit -c unlimited</literal>" to the shell prompt.</para> </listitem>
              <listitem> <para>Run the program from this shell prompt.</para> </listitem>
              <listitem> <para>Crash the program to produce a <ulink url="https://en.wikipedia.org/wiki/Core_dump">core dump</ulink> file.</para> </listitem>
              <listitem> <para>Load the <ulink url="https://en.wikipedia.org/wiki/Core_dump">core dump</ulink> file to GDB as "<literal>gdb gdb ./program_binary core</literal>" .</para> </listitem>
              <listitem> <para>Type "<literal>bt</literal>" at the GDB prompt.</para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <para>For infinite loop or frozen keyboard situation, you can force to crash the program by pressing <literal>Ctrl-\</literal> or <literal>Ctrl-C</literal> or executing “<literal>kill -ABRT <emphasis>PID</emphasis></literal>”.  (See <xref linkend="_killing_a_process"/>)</para>
        <tip> <para>Often, you see a backtrace where one or more of the top lines are in "<literal>malloc()</literal>" or "<literal>g_malloc()</literal>". 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 "<literal>$MALLOC_CHECK_</literal>" to a value of 2 (<literal>malloc</literal>(3)). You can do this while running <literal>gdb</literal> by doing the following.</para>
          <screen> $ MALLOC_CHECK_=2 gdb hello</screen>
        </tip>
      </section>
      <section id="_advanced_gdb_commands">
        <title>Advanced gdb commands</title>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of advanced gdb commands</title>
          <tgroup cols="2">
            <colspec colwidth="195pt" align="left"/>
            <colspec colwidth="428pt" align="left"/>
            <thead>
              <row>
                <entry> command </entry>
                <entry> description for command objectives </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>(gdb) thread apply all bt</literal> </entry>
                <entry> get a backtrace for all threads for multi-threaded program </entry>
              </row>
              <row>
                <entry> <literal>(gdb) bt full</literal> </entry>
                <entry> get parameters came on the stack of function calls </entry>
              </row>
              <row>
                <entry> <literal>(gdb) thread apply all bt full</literal> </entry>
                <entry> get a backtrace and parameters as the combination of the preceding options </entry>
              </row>
              <row>
                <entry> <literal>(gdb) thread apply all bt full 10</literal> </entry>
                <entry> get a backtrace and parameters for top 10 calls to cut off irrelevant output </entry>
              </row>
              <row>
                <entry> <literal>(gdb) set logging on</literal> </entry>
                <entry> write log of <literal>gdb</literal> output to a file (the default is "<literal>gdb.txt</literal>") </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </section>
      <section id="_check_dependency_on_libraries">
        <title>Check dependency on libraries</title>
        <para>Use <literal>ldd</literal>(1) to find out a program's dependency on libraries by the followings.</para>
        <screen>$ ldd /usr/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 <literal>ls</literal>(1) to work in a `chroot`ed environment, the above libraries must be available in your `chroot`ed environment.</para>
        <para>See <xref linkend="_tracing_program_activities"/>.</para>
      </section>
      <section id="_dynamic_call_tracing_tools">
        <title>Dynamic call tracing tools</title>
        <para>There are several dynamic call tracing tools available in Debian.  See <xref linkend="_monitoring_controlling_and_starting_program_activities"/>. </para>
      </section>
      <section id="_debugging_x_errors">
        <title>Debugging X Errors</title>
        <para>If a GNOME program <literal>preview1</literal> has received an X error, you should see a message as follows.</para>
        <screen>The program 'preview1' received an X Window System error.</screen>
        <para>If this is the case, you can try running the program with "<literal>--sync</literal>", and break on the "<literal>gdk_x_error</literal>" function in order to obtain a backtrace.</para>
      </section>
      <section id="_memory_leak_detection_tools">
        <title>Memory leak detection tools</title>
        <para>There are several memory leak detection tools available in Debian.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of memory leak detection tools</title>
          <tgroup cols="4">
            <colspec colwidth="92pt" align="left"/>
            <colspec colwidth="76pt" align="left"/>
            <colspec colwidth="70pt" align="left"/>
            <colspec colwidth="287pt" align="left"/>
            <thead>
              <row>
                <entry> package </entry>
                <entry> popcon </entry>
                <entry> size </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>libc6-dev</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry><literal>mtrace</literal>(1): malloc debugging functionality in glibc </entry>
              </row>
              <row>
                <entry> <literal>valgrind</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> memory debugger and profiler </entry>
              </row>
              <row>
                <entry> <literal>electric-fence</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry><literal>malloc</literal>(3) debugger </entry>
              </row>
              <row>
                <entry> <literal>libdmalloc5</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> debug memory allocation library </entry>
              </row>
              <row>
                <entry> <literal>duma</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> library to detect buffer overruns and under-runs in C and C++ programs </entry>
              </row>
              <row>
                <entry> <literal>leaktracer</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> memory-leak tracer for C++ programs </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </section>
      <section id="_disassemble_binary">
        <title>Disassemble binary</title>
        <para>You can disassemble binary code with <literal>objdump</literal>(1) by the following.</para>
        <screen>$  objdump -m i386 -b binary -D /usr/lib/grub/x86_64-pc/stage1</screen>
        <note> <para><literal>gdb</literal>(1) may be used to disassemble code interactively.</para> </note>
      </section>
    </section>
    <section id="_build_tools">
      <title>Build tools</title>
    <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
      <title>List of build tool packages</title>
      <tgroup cols="4">
        <colspec colwidth="97pt" align="left"/>
        <colspec colwidth="76pt" align="left"/>
        <colspec colwidth="70pt" align="left"/>
        <colspec colwidth="396pt" align="left"/>
        <thead>
          <row>
            <entry> package </entry>
            <entry> popcon </entry>
            <entry> size </entry>
            <entry> documentation </entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry> <literal>make</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> "<literal>info make</literal>" provided by <literal>make-doc</literal> </entry>
          </row>
          <row> <entry> <literal>autoconf</literal>
            </entry> <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> "<literal>info autoconf</literal>" provided by <literal>autoconf-doc</literal> </entry>
          </row>
          <row>
            <entry> <literal>automake</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> "<literal>info automake</literal>" provided by <literal>automake1.10-doc</literal> </entry>
          </row>
          <row>
            <entry> <literal>libtool</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry> "<literal>info libtool</literal>" provided by <literal>libtool-doc</literal> </entry>
          </row>
          <row>
            <entry> <literal>cmake</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry><literal>cmake</literal>(1) cross-platform, open-source make system </entry>
          </row>
          <row>
            <entry> <literal>ninja-build</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry><literal>ninja</literal>(1) small build system closest in spirit to Make </entry>
          </row>
          <row>
            <entry> <literal>meson</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry><literal>meson</literal>(1) high productivity build system on top of <literal>ninja</literal> </entry>
          </row>
          <row>
            <entry> <literal>xutils-dev</literal> </entry>
            <entry> @-@popcon1@-@ </entry>
            <entry> @-@psize1@-@ </entry>
            <entry><literal>imake</literal>(1), <literal>xmkmf</literal>(1), etc.  </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
      <section id="_make">
        <title>Make</title>
        <para><ulink url="https://en.wikipedia.org/wiki/Make_(software)">Make</ulink> is a utility to maintain groups of programs. Upon execution of <literal>make</literal>(1), <literal>make</literal> read the rule file, "<literal>Makefile</literal>", 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 the following.</para>
        <screen>target: [ prerequisites ... ]
 [TAB]  command1
 [TAB]  -command2 # ignore errors
 [TAB]  @command3 # suppress echoing</screen>
        <para>Here "<literal>[TAB]</literal>" is a TAB code.  Each line is interpreted by the shell after make variable substitution.  Use "<literal>\</literal>" at the end of a line to continue the script.  Use "<literal>$$</literal>" to enter "<literal>$</literal>" for environment values for a shell script.</para>
        <para>Implicit rules for the target and prerequisites can be written, for example, by the following.</para>
        <screen>%.o: %.c header.h</screen>
        <para>Here, the target contains the character "<literal>%</literal>" (exactly one of them). The "<literal>%</literal>" can match any nonempty substring in the actual target filenames. The prerequisites likewise use "<literal>%</literal>" to show how their names relate to the actual target name.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of make automatic variables</title>
          <tgroup cols="2">
            <colspec colwidth="103pt" align="left"/>
            <colspec colwidth="222pt" align="left"/>
            <thead>
              <row>
                <entry> automatic variable </entry>
                <entry> value </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>$@</literal> </entry>
                <entry> target </entry>
              </row>
              <row>
                <entry> <literal>$&lt;</literal> </entry>
                <entry> first prerequisite </entry>
              </row>
              <row>
                <entry> <literal>$?</literal> </entry>
                <entry> all newer prerequisites </entry>
              </row>
              <row>
                <entry> <literal>$^</literal> </entry>
                <entry> all prerequisites </entry>
              </row>
              <row>
                <entry> <literal>$*</literal> </entry>
                <entry> "<literal>%</literal>" matched stem in the target pattern </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of make variable expansions</title>
          <tgroup cols="2">
            <colspec colwidth="103pt" align="left"/>
            <colspec colwidth="108pt" align="left"/>
            <thead>
              <row>
                <entry> variable expansion </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>foo1 := bar</literal> </entry>
                <entry> one-time expansion </entry>
              </row>
              <row>
                <entry> <literal>foo2  = bar</literal> </entry>
                <entry> recursive expansion </entry>
              </row>
              <row>
                <entry> <literal>foo3 += bar</literal> </entry>
                <entry> append </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>Run "<literal>make -p -f/dev/null</literal>" to see automatic internal rules.</para>
      </section>
      <section id="_autotools">
        <title>Autotools</title>
        <para><ulink url="https://en.wikipedia.org/wiki/GNU_Autotools">Autotools</ulink> is a suite of programming tools designed to assist in making source code packages portable to many <ulink url="https://en.wikipedia.org/wiki/Unix-like">Unix-like</ulink> systems.</para>
        <itemizedlist>
        <listitem>
          <para><ulink url="https://en.wikipedia.org/wiki/Autoconf">Autoconf</ulink> is a tool to produce a shell script "<literal>configure</literal>" from "<literal>configure.ac</literal>".</para>
          <itemizedlist>
            <listitem><para>"<literal>configure</literal>" is used later to produce "<literal>Makefile</literal>" from "<literal>Makefile.in</literal>" template.</para></listitem>
          </itemizedlist>
        </listitem>
        <listitem><para><ulink url="https://en.wikipedia.org/wiki/Automake">Automake</ulink> is a tool to produce "<literal>Makefile.in</literal>" from "<literal>Makefile.am</literal>".</para></listitem>
        <listitem><para><ulink url="https://en.wikipedia.org/wiki/GNU_Libtool">Libtool</ulink> is a shell script to address the software portability problem when compiling shared libraries from source code.</para></listitem>
        </itemizedlist>
        <section id="_compile_and_install_a_program">
          <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 "<literal>/usr/local/</literal>" or "<literal>/opt</literal>".  So if you compile a program from source, install it into "<literal>/usr/local/</literal>" so it does not interfere with Debian.</para>
          <screen>$ cd src
$ ./configure --prefix=/usr/local
$ make # this compiles program
$ sudo make install # this installs the files in the system</screen>
        </section>
        <section id="_uninstall_program">
          <title>Uninstall program</title>
          <para>If you have the original source and if it uses <literal>autoconf</literal>(1)/<literal>automake</literal>(1) and if you can remember how you configured it, execute as follows to uninstall the program.</para>
          <screen>$ ./configure <emphasis>all-of-the-options-you-gave-it</emphasis>
$ sudo make uninstall</screen>
          <para>Alternatively, if you are absolutely sure that the install process puts files only under "<literal>/usr/local/</literal>" and there is nothing important there, you can erase all its contents by the following.</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 <literal>checkinstall</literal>(8) from the <literal>checkinstall</literal> package, which provides a clean path for the uninstall.  It now supports to create a Debian package with "<literal>-D</literal>" option.</para>
        </section>
      </section>
      <section id="_meson">
        <title>Meson</title>
        <para>The software build system has been evolving:</para>
        <itemizedlist>
          <listitem> <para> <ulink url="https://en.wikipedia.org/wiki/GNU_Autotools">Autotools</ulink> on the top of <ulink url="https://en.wikipedia.org/wiki/Make_(software)">Make</ulink> has been the de facto standard for the portable build infrastructure since 1990s.  This is extremely slow.</para> </listitem>
          <listitem> <para> <ulink url="https://en.wikipedia.org/wiki/Cmake">CMake</ulink> initially released in 2000 improved speed significantly but was originally built on the top of inherently slow <ulink url="https://en.wikipedia.org/wiki/Make_(software)">Make</ulink>.  (Now <ulink url="https://en.wikipedia.org/wiki/Ninja_(build_system)">Ninja</ulink> can be its backend.)</para> </listitem>
          <listitem> <para> <ulink url="https://en.wikipedia.org/wiki/Ninja_(build_system)">Ninja</ulink> initially released in 2012 is meant to replace Make for the further improved build speed and is designed to have its input files generated by a higher-level build system.</para> </listitem>
          <listitem> <para> <ulink url="https://en.wikipedia.org/wiki/Meson_(software)">Meson</ulink> initially released in 2013 is the new popular and fast higher-level build system which uses <ulink url="https://en.wikipedia.org/wiki/Ninja_(build_system)">Ninja</ulink> as its backend.</para> </listitem>
        </itemizedlist>
        <para>See documents found at "<ulink url="https://mesonbuild.com/">The Meson Build system</ulink>" and "<ulink url="https://ninja-build.org/manual.html">The Ninja build system</ulink>".</para>
      </section>
    </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="https://en.wikipedia.org/wiki/HTML">HTML</ulink> forms.  </para> </listitem>
        <listitem>
          <para> Filling and clicking on the form entries sends one of the following <ulink url="https://en.wikipedia.org/wiki/Uniform_Resource_Locator">URL</ulink> string with encoded parameters from the browser to the web server.  </para>
          <itemizedlist>
            <listitem> <para> "<literal>https://www.foo.dom/cgi-bin/program.pl?VAR1=VAL1&amp;VAR2=VAL2&amp;VAR3=VAL3</literal>" </para> </listitem>
            <listitem> <para> "<literal>https://www.foo.dom/cgi-bin/program.py?VAR1=VAL1&amp;VAR2=VAL2&amp;VAR3=VAL3</literal>" </para> </listitem>
            <listitem> <para> "<literal>https://www.foo.dom/program.php?VAR1=VAL1&amp;VAR2=VAL2&amp;VAR3=VAL3</literal>" </para> </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para> "<literal>%nn</literal>" in URL is replaced with a character with hexadecimal <literal>nn</literal> value.  </para>
        </listitem>
        <listitem> <para> The environment variable is set as: "<literal>QUERY_STRING="VAR1=VAL1 VAR2=VAL2 VAR3=VAL3"</literal>".  </para> </listitem>
        <listitem> <para><ulink url="https://en.wikipedia.org/wiki/Common_Gateway_Interface">CGI</ulink> program (any one of "<literal>program.*</literal>") on the web server executes itself with the environment variable "<literal>$QUERY_STRING</literal>".  </para> </listitem>
        <listitem> <para><literal>stdout</literal> of CGI program is 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="https://en.wikipedia.org/wiki/PHP">PHP</ulink> comes with these functionalities.  When client data storage is needed, <ulink url="https://en.wikipedia.org/wiki/HTTP_cookie">HTTP cookies</ulink> are used.  When client side data processing is needed, <ulink url="https://en.wikipedia.org/wiki/JavaScript">Javascript</ulink> is frequently used.</para>
      <para>For more, see the <ulink url="https://en.wikipedia.org/wiki/Common_Gateway_Interface">Common Gateway Interface</ulink>, <ulink url="https://en.wikipedia.org/wiki/Apache_Software_Foundation">The Apache Software Foundation</ulink>, and <ulink url="https://en.wikipedia.org/wiki/JavaScript">JavaScript</ulink>.</para>
      <para>Searching "CGI tutorial" on Google by typing encoded URL <ulink url="https://www.google.com/search?hl=en&amp;ie=UTF-8&amp;q=CGI+tutorial">https://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>
    </section>
    <section id="_the_source_code_translation">
      <title>The source code translation</title>
      <para>There are programs to convert source codes.</para>
      <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
        <title>List of source code translation tools</title>
        <tgroup cols="5">
          <colspec colwidth="65pt" align="left"/>
          <colspec colwidth="76pt" align="left"/>
          <colspec colwidth="70pt" align="left"/>
          <colspec colwidth="59pt" align="left"/>
          <colspec colwidth="363pt" align="left"/>
          <thead>
            <row>
              <entry> package </entry>
              <entry> popcon </entry>
              <entry> size </entry>
              <entry> keyword </entry>
              <entry> description </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry> <literal>perl</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> AWK→PERL </entry>
              <entry> convert source codes from AWK to PERL: <literal>a2p</literal>(1) </entry>
            </row>
            <row>
              <entry> <literal>f2c</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> FORTRAN→C </entry>
              <entry> convert source codes from FORTRAN 77 to C/C++: <literal>f2c</literal>(1) </entry>
            </row>
            <row>
              <entry> <literal>intel2gas</literal> </entry>
              <entry> @-@popcon1@-@ </entry>
              <entry> @-@psize1@-@ </entry>
              <entry> intel→gas </entry>
              <entry> converter from NASM (Intel format) to the GNU Assembler (GAS) </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
    <section id="_making_debian_package">
      <title>Making Debian package</title>
      <para>If you want to make a Debian package, read followings.</para>
      <itemizedlist>
        <listitem> <para><xref linkend="_debian_package_management"/> to understand the basic package system </para> </listitem>
        <listitem> <para><xref linkend="_porting_a_package_to_the_stable_system"/> to understand basic porting process </para> </listitem>
        <listitem> <para><xref linkend="_chroot_system"/> to understand basic chroot techniques </para> </listitem>
        <listitem> <para><literal>debuild</literal>(1), and <literal>sbuild</literal>(1) </para> </listitem>
        <listitem> <para><xref linkend="_debugging_the_debian_package"/> for recompiling for debugging </para> </listitem>
        <listitem> <para><ulink url="https://www.debian.org/doc/manuals/debmake-doc/">Guide for Debian Maintainers</ulink> (the <literal>debmake-doc</literal> package) </para> </listitem>
        <listitem> <para><ulink url="https://www.debian.org/doc/manuals/developers-reference/">Debian Developer's Reference</ulink> (the <literal>developers-reference</literal> package) </para> </listitem>
        <listitem> <para><ulink url="https://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink> (the <literal>debian-policy</literal> package) </para> </listitem>
      </itemizedlist>
      <para>There are packages such as <literal>debmake</literal>, <literal>dh-make</literal>, <literal>dh-make-perl</literal>, etc., which help packaging.</para>
    </section>
  </chapter>