mirror of https://github.com/tLDP/LDP
319 lines
21 KiB
XML
319 lines
21 KiB
XML
<chapter id="chap_02"><title>Writing and debugging scripts</title>
|
|
|
|
<abstract>
|
|
<para>After going through this chapter, you will be able to:</para>
|
|
<para><itemizedlist>
|
|
<listitem><para>Write a simple script</para></listitem>
|
|
<listitem><para>Define the shell type that should execute the script</para></listitem>
|
|
<listitem><para>Put comments in a script</para></listitem>
|
|
<listitem><para>Change permissions on a script</para></listitem>
|
|
<listitem><para>Execute and debug a script</para></listitem>
|
|
</itemizedlist></para>
|
|
</abstract>
|
|
|
|
<sect1 id="sect_02_01"><title>Creating and running a script</title>
|
|
<sect2 id="sect_02_01_01"><title>Writing and naming</title>
|
|
<para>A shell script is a sequence of commands for which you have a repeated use. This sequence is typically executed by entering the name of the script on the command line. Alternatively, you can use scripts to automate tasks using the cron facility. Another use for scripts is in the UNIX boot and shutdown procedure, where operation of daemons and services are defined in init scripts.</para>
|
|
<para>To create<indexterm><primary>scripts</primary><secondary>creation</secondary></indexterm> a shell script, open a new empty file in your editor. Any text editor will do: <command>vim</command>, <command>emacs</command>, <command>gedit</command>, <command>dtpad</command> et cetera are all valid. You might want to chose a more advanced editor like <command>vim</command> or <command>emacs</command>, however, because these can be configured to recognize shell and Bash syntax and can be a great help in preventing those errors that beginners frequently make, such as forgetting brackets and semi-colons.</para>
|
|
<tip><title>Syntax highlighting in vim</title>
|
|
<para>In order to activate syntax highlighting in <command>vim</command>, use the command</para>
|
|
<cmdsynopsis><command>:syntax enable</command></cmdsynopsis>
|
|
<para>or</para>
|
|
<cmdsynopsis><command>:sy enable</command></cmdsynopsis>
|
|
<para>or</para>
|
|
<cmdsynopsis><command>:syn enable</command></cmdsynopsis>
|
|
<para>You can add this setting to your <filename>.vimrc</filename> file to make it permanent.</para>
|
|
</tip>
|
|
<para>Put UNIX commands in the new empty file, like you would enter them on the command line. As discussed in the previous chapter (see <xref linkend="sect_01_03" />), commands can be shell functions, shell built-ins, UNIX commands and other scripts.</para>
|
|
<para>Give your script a sensible name<indexterm><primary>scripts</primary><secondary>naming</secondary></indexterm> that gives a hint about what the script does. Make sure that your script name does not conflict with existing commands. In order to ensure that no confusion can rise, script names often end in <filename>.sh</filename>; even so, there might be other scripts on your system with the same name as the one you chose. Check using <command>which</command>, <command>whereis</command> and other commands for finding information about programs and files:</para>
|
|
<cmdsynopsis><command>which <option>-a</option> <filename>script_name</filename></command></cmdsynopsis>
|
|
<cmdsynopsis><command>whereis <filename>script_name</filename></command></cmdsynopsis>
|
|
<cmdsynopsis><command>locate <filename>script_name</filename></command></cmdsynopsis>
|
|
</sect2>
|
|
<sect2 id="sect_02_01_02"><title>script1.sh</title>
|
|
<para>In this example<indexterm><primary>scripts</primary><secondary>example</secondary></indexterm> we use the <command>echo</command> Bash built-in to inform the user about what is going to happen, before the task that will create the output is executed. It is strongly advised to inform users about what a script is doing, in order to prevent them from becoming nervous <emphasis>because the script is not doing anything</emphasis>. We will return to the subject of notifying users in <xref linkend="chap_08" />.</para>
|
|
|
|
<figure><title>script1.sh</title>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/script1.sh.eps" format="EPS"></imagedata></imageobject><imageobject>
|
|
<imagedata fileref="images/script1.sh.png" format="PNG"></imagedata>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>Example script using statements like "echo hello", "echo hello $USER" and "VARIABLE=value".</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</figure>
|
|
|
|
|
|
<para>Write this script for yourself as well. It might be a good idea to create a directory <filename>~/scripts</filename> to hold your scripts. Add the directory to the contents of the <varname>PATH</varname> variable<indexterm><primary>variables</primary><secondary>PATH</secondary></indexterm>:</para>
|
|
<cmdsynopsis><command>export <varname>PATH</varname>="<varname>$PATH</varname>:<filename>~/scripts</filename>"</command></cmdsynopsis>
|
|
<para>If you are just getting started with Bash, use a text editor that uses different colours for different shell constructs. Syntax highlighting is supported by <command>vim</command>, <command>gvim</command>, <command>(x)emacs</command>, <command>kwrite</command> and many other editors; check the documentation of your favorite editor.</para>
|
|
<note><title>Different prompts</title><para>The prompts throughout this course vary depending on the author's mood. This resembles much more real life situations than the standard educational <emphasis>$</emphasis> prompt. The only convention we stick to, is that the <emphasis>root</emphasis> prompt ends in a hash mark (#).</para></note>
|
|
</sect2>
|
|
<sect2 id="sect_02_01_03"><title>Executing the script</title>
|
|
<para>The script should have execute<indexterm><primary>scripts</primary><secondary>execution</secondary></indexterm> permissions for the correct owners in order to be runnable. When setting permissions<indexterm><primary>scripts</primary><secondary>permissions</secondary></indexterm>, check that you really obtained the permissions that you want. When this is done, the script can run like any other command:</para>
|
|
<screen>
|
|
<prompt>willy:~/scripts></prompt> <command>chmod <option>u+x</option> <filename>script1.sh</filename></command>
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>ls <option>-l</option> <filename>script1.sh</filename></command>
|
|
-rwxrw-r-- 1 willy willy 456 Dec 24 17:11 script1.sh
|
|
|
|
<prompt>willy:~></prompt> <command>script1.sh</command>
|
|
The script starts now.
|
|
Hi, willy!
|
|
|
|
I will now fetch you a list of connected users:
|
|
|
|
3:38pm up 18 days, 5:37, 4 users, load average: 0.12, 0.22, 0.15
|
|
USER TTY FROM LOGIN@ IDLE JCPU PCPU WHAT
|
|
root tty2 - Sat 2pm 4:25m 0.24s 0.05s -bash
|
|
willy :0 - Sat 2pm ? 0.00s ? -
|
|
willy pts/3 - Sat 2pm 3:33m 36.39s 36.39s BitchX willy ir
|
|
willy pts/2 - Sat 2pm 3:33m 0.13s 0.06s /usr/bin/screen
|
|
|
|
I'm setting two variables now.
|
|
This is a string: black
|
|
And this is a number: 9
|
|
|
|
I'm giving you back your prompt now.
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>echo <varname>$COLOUR</varname></command>
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>echo <varname>$VALUE</varname></command>
|
|
|
|
<prompt>willy:~/scripts></prompt>
|
|
</screen>
|
|
|
|
<para>This is the most common way to execute a script. It is preferred to execute the script like this in a subshell. The variables, functions and aliases created in this subshell are only known to the particular bash session of that subshell. When that shell exits and the parent regains control, everything is cleaned up and all changes to the state of the shell made by the script, are forgotten.</para>
|
|
<para>If you did not put the <filename>scripts</filename> directory in your <varname>PATH</varname>, and <filename>.</filename> (the current directory) is not in the <varname>PATH</varname> either, you can activate the script like this:</para>
|
|
|
|
<cmdsynopsis><command>./script_name.sh</command></cmdsynopsis>
|
|
|
|
<para>A script can also explicitly be executed by a given shell, but generally we only do this if we want to obtain special behavior, such as checking if the script works with another shell or printing traces for debugging:</para>
|
|
|
|
<cmdsynopsis><command>rbash <filename>script_name.sh</filename></command></cmdsynopsis>
|
|
<cmdsynopsis><command>sh <filename>script_name.sh</filename></command></cmdsynopsis>
|
|
<cmdsynopsis><command>bash <option>-x</option> <filename>script_name.sh</filename></command></cmdsynopsis>
|
|
|
|
<para>The specified shell will start as a subshell of your current shell and execute the script. This is done when you want the script to start up with specific options or under specific conditions which are not specified in the script.</para>
|
|
<para>If you don't want to start a new shell but execute the script in the current shell, you <emphasis>source<indexterm><primary>built-ins</primary><secondary>source</secondary></indexterm></emphasis> it:</para>
|
|
|
|
<cmdsynopsis><command>source <filename>script_name.sh</filename></command></cmdsynopsis>
|
|
|
|
<tip><title>source = .</title><para>The Bash <command>source</command> built-in is a synonym for the Bourne shell <command>.</command> (dot) command.</para></tip>
|
|
|
|
<para>The script does not need execute permission in this case. Commands are executed in the current shell context, so any changes made to your environment will be visible when the script finishes execution:</para>
|
|
|
|
<screen>
|
|
<prompt>willy:~/scripts></prompt> <command>source <filename>script1.sh</filename></command>
|
|
--output ommitted--
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>echo <varname>$VALUE</varname></command>
|
|
9
|
|
|
|
<prompt>willy:~/scripts></prompt>
|
|
</screen>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
<sect1 id="sect_02_02"><title>Script basics</title>
|
|
<sect2 id="sect_02_02_01"><title>Which shell will run the script?</title>
|
|
<para>When running a script in a subshell<indexterm><primary>scripts</primary><secondary>executing shell</secondary></indexterm>, you should define which shell should run the script. The shell type in which you wrote the script might not be the default on your system, so commands you entered might result in errors when executed by the wrong shell.</para>
|
|
<para>The first line of the script determines the shell to start. The first two characters of the first line should be <emphasis>#!</emphasis>, then follows the path to the shell that should interpret the commands that follow. Blank lines are also considered to be lines, so don't start your script with an empty line.</para>
|
|
<para>For the purpose of this course, all scripts will start with the line</para>
|
|
<cmdsynopsis><command>#!/bin/bash</command></cmdsynopsis>
|
|
<para>As noted before, this implies that the Bash executable can be found in <filename>/bin</filename>.</para>
|
|
</sect2>
|
|
<sect2 id="sect_02_02_02"><title>Adding comments</title>
|
|
<para>You should be aware of the fact that you might not be the only person reading your code. A lot of users and system administrators run scripts that were written by other people. If they want to see how you did it, comments<indexterm><primary>scripts</primary><secondary>comments</secondary></indexterm> are useful to enlighten the reader.</para>
|
|
<para>Comments<indexterm><primary>comments</primary><secondary>usage</secondary></indexterm> also make your own life easier. Say that you had to read a lot of man pages in order to achieve a particular result with some command that you used in your script. You won't remember how it worked if you need to change your script after a few weeks or months, unless you have commented what you did, how you did it and/or why you did it.</para>
|
|
<para>Take the <filename>script1.sh</filename> example and copy it to <filename>commented-script1.sh</filename>, which we edit so that the comments reflect what the script does. Everything the shell encounters after a hash mark on a line is ignored and only visible upon opening the shell script file:</para>
|
|
<screen>
|
|
#!/bin/bash
|
|
# This script clears the terminal, displays a greeting and gives information
|
|
# about currently connected users. The two example variables are set and displayed.
|
|
|
|
clear # clear terminal window
|
|
|
|
echo "The script starts now."
|
|
|
|
echo "Hi, $USER!" # dollar sign is used to get content of variable
|
|
echo
|
|
|
|
echo "I will now fetch you a list of connected users:"
|
|
echo
|
|
w # show who is logged on and
|
|
echo # what they are doing
|
|
|
|
echo "I'm setting two variables now."
|
|
COLOUR="black" # set a local shell variable
|
|
VALUE="9" # set a local shell variable
|
|
echo "This is a string: $COLOUR" # display content of variable
|
|
echo "And this is a number: $VALUE" # display content of variable
|
|
echo
|
|
|
|
echo "I'm giving you back your prompt now."
|
|
echo
|
|
</screen>
|
|
<para>In a decent script, the first lines are usually comment about what to expect. Then each big chunk of commands will be commented as needed for clarity's sake. Linux init scripts, as an example, in your system's <filename>init.d</filename> directory, are usually well commented since they have to be readable and editable by everyone running Linux.</para>
|
|
</sect2>
|
|
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="sect_02_03"><title>Debugging Bash scripts</title>
|
|
<sect2 id="sect_02_03_01"><title>Debugging on the entire script</title>
|
|
<para>When things<indexterm><primary>scripts</primary><secondary>debugging</secondary></indexterm> don't go according to plan, you need to determine what exactly causes the script to fail. Bash provides extensive debugging<indexterm><primary>debugging</primary></indexterm> features. The most common is to start up the subshell with the <option>-x</option> option, which will run the entire script in debug mode. Traces of each command plus its arguments are printed to standard output after the commands have been expanded but before they are executed.</para>
|
|
<para>This is the <filename>commented-script1.sh</filename> script ran in debug mode<indexterm><primary>debugging</primary><secondary>on entire script</secondary></indexterm>. Note again that the added comments are not visible in the output of the script.</para>
|
|
<screen>
|
|
<prompt>willy:~/scripts></prompt> <command>bash <option>-x</option> <filename>script1.sh</filename></command>
|
|
+ clear
|
|
|
|
+ echo 'The script starts now.'
|
|
The script starts now.
|
|
+ echo 'Hi, willy!'
|
|
Hi, willy!
|
|
+ echo
|
|
|
|
+ echo 'I will now fetch you a list of connected users:'
|
|
I will now fetch you a list of connected users:
|
|
+ echo
|
|
|
|
+ w
|
|
4:50pm up 18 days, 6:49, 4 users, load average: 0.58, 0.62, 0.40
|
|
USER TTY FROM LOGIN@ IDLE JCPU PCPU WHAT
|
|
root tty2 - Sat 2pm 5:36m 0.24s 0.05s -bash
|
|
willy :0 - Sat 2pm ? 0.00s ? -
|
|
willy pts/3 - Sat 2pm 43:13 36.82s 36.82s BitchX willy ir
|
|
willy pts/2 - Sat 2pm 43:13 0.13s 0.06s /usr/bin/screen
|
|
+ echo
|
|
|
|
+ echo 'I'\''m setting two variables now.'
|
|
I'm setting two variables now.
|
|
+ COLOUR=black
|
|
+ VALUE=9
|
|
+ echo 'This is a string: '
|
|
This is a string:
|
|
+ echo 'And this is a number: '
|
|
And this is a number:
|
|
+ echo
|
|
|
|
+ echo 'I'\''m giving you back your prompt now.'
|
|
I'm giving you back your prompt now.
|
|
+ echo
|
|
</screen>
|
|
<para>There is now a full-fledged debugger for Bash, available at <ulink url="http://bashdb.sourceforge.net">SourceForge</ulink>. These debugging features are available in most modern versions of Bash, starting from 3.x.</para>
|
|
|
|
</sect2>
|
|
<sect2 id="sect_02_03_02"><title>Debugging on part(s) of the script</title>
|
|
<para>Using the <command>set</command> Bash built-in you can run in normal mode those portions<indexterm><primary>debugging</primary><secondary>partial</secondary></indexterm> of the script of which you are sure they are without fault, and display debugging information only for troublesome zones. Say we are not sure what the <command>w</command> command will do in the example <filename>commented-script1.sh</filename>, then we could enclose it in the script like this:</para>
|
|
|
|
<screen>
|
|
set -x # activate debugging from here
|
|
w
|
|
set +x # stop debugging from here
|
|
</screen>
|
|
<para>Output then looks like this:</para>
|
|
<screen>
|
|
<prompt>willy: ~/scripts></prompt> <command>script1.sh</command>
|
|
The script starts now.
|
|
Hi, willy!
|
|
|
|
I will now fetch you a list of connected users:
|
|
|
|
+ w
|
|
5:00pm up 18 days, 7:00, 4 users, load average: 0.79, 0.39, 0.33
|
|
USER TTY FROM LOGIN@ IDLE JCPU PCPU WHAT
|
|
root tty2 - Sat 2pm 5:47m 0.24s 0.05s -bash
|
|
willy :0 - Sat 2pm ? 0.00s ? -
|
|
willy pts/3 - Sat 2pm 54:02 36.88s 36.88s BitchX willyke
|
|
willy pts/2 - Sat 2pm 54:02 0.13s 0.06s /usr/bin/screen
|
|
+ set +x
|
|
|
|
I'm setting two variables now.
|
|
This is a string:
|
|
And this is a number:
|
|
|
|
I'm giving you back your prompt now.
|
|
|
|
<prompt>willy: ~/scripts></prompt>
|
|
</screen>
|
|
<para>You can switch debugging mode on and off as many times as you want within the same script.</para>
|
|
<para>The table below gives an overview of other useful Bash options<indexterm><primary>debugging</primary><secondary>options</secondary></indexterm>:</para>
|
|
<table id="table_02_01" frame="all">
|
|
<title>Overview of set debugging options</title>
|
|
<tgroup cols="3" align="left" colsep="1" rowsep="1">
|
|
<thead>
|
|
<row><entry>Short notation</entry><entry>Long notation</entry><entry>Result</entry></row>
|
|
</thead>
|
|
<tbody>
|
|
<row><entry>set -f</entry><entry>set -o noglob</entry><entry>Disable file name generation using metacharacters (globbing).</entry></row>
|
|
<row><entry>set -v</entry><entry>set -o verbose</entry><entry>Prints shell input lines as they are read.</entry></row>
|
|
<row><entry>set -x</entry><entry>set -o xtrace</entry><entry>Print command traces before executing command.</entry></row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>The dash is used to activate a shell option and a plus to deactivate it. Don't let this confuse you!</para>
|
|
<para>In the example below, we demonstrate these options on the command line:</para>
|
|
<screen>
|
|
<prompt>willy:~/scripts></prompt> <command>set <option>-v</option></command>
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>ls</command>
|
|
ls
|
|
commented-scripts.sh script1.sh
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>set <option>+v</option></command>
|
|
set +v
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>ls <parameter>*</parameter></command>
|
|
commented-scripts.sh script1.sh
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>set <option>-f</option></command>
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>ls <filename>*</filename></command>
|
|
ls: *: No such file or directory
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>touch <filename>*</filename></command>
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>ls</command>
|
|
* commented-scripts.sh script1.sh
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>rm <filename>*</filename></command>
|
|
|
|
<prompt>willy:~/scripts></prompt> <command>ls</command>
|
|
commented-scripts.sh script1.sh
|
|
</screen>
|
|
<para>Alternatively, these modes can be specified in the script itself, by adding the desired options to the first line shell declaration. Options can be combined, as is usually the case with UNIX commands:</para>
|
|
<cmdsynopsis><command>#!/bin/bash <option>-xv</option></command></cmdsynopsis>
|
|
<para>Once you found the buggy<indexterm><primary>debugging</primary><secondary>echo statements</secondary></indexterm> part of your script, you can add <command>echo</command> statements before each command of which you are unsure, so that you will see exactly where and why things don't work. In the example <filename>commented-script1.sh</filename> script, it could be done like this, still assuming that the displaying of users gives us problems:</para>
|
|
<screen>
|
|
echo "debug message: now attempting to start w command"; w
|
|
</screen>
|
|
<para>In more advanced scripts, the <command>echo</command> can be inserted to display the content of variables at different stages in the script, so that flaws can be detected:</para>
|
|
<screen>
|
|
echo "Variable VARNAME is now set to $VARNAME."
|
|
</screen>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
<sect1 id="sect_02_05"><title>Summary</title>
|
|
<para>A shell script is a reusable series of commands put in an executable text file. Any text editor can be used to write scripts.</para>
|
|
<para>Scripts start with <emphasis>#!</emphasis> followed by the path to the shell executing the commands from the script. Comments are added to a script for your own future reference, and also to make it understandable for other users. It is better to have too many explanations than not enough.</para>
|
|
<para>Debugging a script can be done using shell options. Shell options can be used for partial debugging or for analyzing the entire script. Inserting <command>echo</command> commands at strategic locations is also a common troubleshooting technique.</para>
|
|
|
|
</sect1>
|
|
<sect1 id="sect_02_06"><title>Exercises</title>
|
|
<para>This exercise will help you to create your first script.</para>
|
|
<orderedlist>
|
|
<listitem><para>Write a script using your favorite editor. The script should display the path to your homedirectory and the terminal type that you are using. Additionally it shows all the services started up in runlevel 3 on your system. (hint: use <varname>HOME</varname>, <varname>TERM</varname> and <command>ls <filename>/etc/rc3.d/S*</filename></command>)</para></listitem>
|
|
<listitem><para>Add comments in your script.</para></listitem>
|
|
<listitem><para>Add information for the users of your script.</para></listitem>
|
|
<listitem><para>Change permissions on your script so that you can run it.</para></listitem>
|
|
<listitem><para>Run the script in normal mode and in debug mode. It should run without errors.</para></listitem>
|
|
<listitem><para>Make errors in your script: see what happens if you misspell commands, if you leave out the first line or put something unintelligible there, or if you misspell shell variable names or write them in lower case characters after they have been declared in capitals. Check what the debug comments say about this.</para></listitem>
|
|
</orderedlist>
|
|
|
|
</sect1>
|
|
</chapter>
|