12.3. What's in the Archive

The bash archive contains a main directory (bash-3.0 for the current version) and a set of files and subdirectories. Among the first files you should examine are:

MANIFEST

A list of all the files and directories in the archive

COPYING

The GNU Copyleft for bash

NEWS

A list of bug fixes and new features since the last version

README

A short introduction and instructions for compiling bash

You should also be aware of two directories:

doc

Information related to bash in various formats

examples

Examples of startup files, scripts, and functions

The other files and directories in the archive are mostly things that are needed during the build. Unless you are going to go hacking into the internal workings of the shell, they shouldn't concern you.

12.3.1. Documentation

The doc directory contains a few articles that are worth reading. Indeed, it would be well worth printing out the manual entry for bash so you can use it in conjunction with this book. The README file gives a short summary of the files.

The document you'll most often use is the manual page entry (bash.1). The file is in troff format—that used by the manual pages. You can read it by processing it with the text-formatter nroff and piping the output to a pager utility: nroff -man bash.1 | more should do the trick. You can also print it off by piping it to the lineprinter (lp). This summarizes all of the facilities your version of bash has and is the most up-to-date reference you can get. This document is also available through the man facility once you've installed the package, but sometimes it's nice to have a hard copy so you can write notes all over it.

Of the other documents, FAQ is a Frequently Asked Questions document with answers, readline.3 is the manual entry for the readline facility, and article.ms is an article about the shell that appeared in Linux Journal, by the current bash maintainer, Chet Ramey.

12.3.2. Configuring and Building bash

To compile bash "straight out of the box" is easy;^[2] you just type configure and then make! The bash configure script attempts to work out if you have various utilities and C library functions, and whereabouts they reside on your system. It then stores the relevant information in the file config.h. It also creates a file called config.status that is a script you can run to recreate the current configuration information. While the configure is running, it prints out information on what it is searching for and where it finds it.

^[2] This configuration information pertains to bash version 3.0 and later. The configuration and installation for earlier versions is fairly easy, although it differs in certain details. For further information, refer to the INSTALL instructions that came with your version of bash.

The configure script also sets the location that bash will be installed; the default is the /usr/local area (/usr/local/bin for the executable, /usr/local/man for the manual entries etc.). If you don't have root privileges and want it in your own home directory, or you wish to install bash in some other location, you'll need to specify a path to configure. You can do this with the —exec-prefix option. For example:

$ configure --exec-prefix=/usr

specifies that the bash files will be placed under the /usr directory. Note that configure prefers option arguments be given with an equals sign (=).

After the configuration finishes and you type make, the bash executable is built. A script called bashbug is also generated, which allows you to report bugs in the format the bash maintainers want. We'll look at how you use it later in this chapter.

Once the build finishes, you can see if the bash executable works by typing ./bash. If it doesn't, turn to the Section 11.3 in Chapter 11.

To install bash, type make install. This will create all of the necessary directories (bin, info, man and its subdirectories) and copy the files to them.

If you've installed bash in your home directory, be sure to add your own bin path to your PATH and your own man path to MANPATH.

bash comes preconfigured with nearly all of its features enabled, but it is possible to customize your version by specifying what you want with the —enable-feature and —disable-feature command-line options to configure.

Table 12-1 is a list of the configurable features and a short description of what those features do.

Table 12-1. Configurable features

Feature	Description
alias	Support for aliases.
arith-for-command	Support for the alternate form of the `for' command that behaves like the C language for statement.
array-variables	Support for one dimensional arrays.
bang-history	C-shell-like history expansion and editing.
brace-expansion	Brace expansion.
command-timing	Support for the time command.
cond-command	Support for the [[ conditional command.
cond-regexp	Support for matching POSIX regular expressions using the =~ binary operator in the [[ conditional command.
directory-stack	Support for the pushd, popd, and dirs directory manipulation commands .
disabled-builtins	Whether a built-in can be run with the builtin command, even if it has been disabled with enable -n.
dparen-arithmetic	Support for ((...)) .
help-builtin	Support for the help built-in.
history	History via the fc and history commands .
job-control	Job control via fg, bg, and jobs if supported by the operating system.
multibyte	Support for multibyte characters if the operating system provides the necessary support.
net-redirections	Special handling of filenames of the form /dev/tcp/HOST/PORT and /dev/udp/HOST/PORT when used in redirections.
process-substitution	Whether process substitution occurs, if supported by the operating system.
prompt-string-decoding	Whether backslash escaped characters in PS1, PS2, PS3, and PS4 are allowed .
progcomp	Programmable completion facilities. If readline is not enabled, this option has no effect .
readline	readline editing and history capabilities.
restricted	Support for the restricted shell, the -r option to the shell, and rbash.
select	The select construct.
usg-echo-default xpg-echo-default	Make echo expand backslash-escaped characters by default, without requiring the -e option. This sets the default value of the xpg_echo shell option to on, which makes the bash echo behave more like the version specified in the Single Unix Specification, Version 2.

The options disabled-builtins and xpg-echo-default are disabled by default. The others are enabled.

Many other shell features can be turned on or off by modifying the file config-.top.h. For further details on this file and configuring bash in general, see INSTALL.

Finally, to clean up the source directory and remove all of the object files and executables, type make clean. Make sure you run make install first, otherwise you'll have to rerun the installation from scratch.

12.3.3. Testing bash

There are a series of tests that can be run on your newly built version of bash to see if it is running correctly. The tests are scripts that are derived from problems reported in earlier versions of the shell. Running these tests on the latest version of bash shouldn't cause any errors.

To run the tests just type make tests in the main bash directory. The name of each test is displayed, along with some warning messages, and then it is run. Successful tests produce no output (unless otherwise noted in the warning messages).

If any of the tests fail, you'll see a list of things that represent differences between what is expected and what happened. If this occurs you should file a bug report with the bash maintainer. See the Section 12.4.2 later in this chapter for information on how to do this.

12.3.4. Potential Problems

Although bash has been installed on a large number of different machines and operating systems, there are occasionally problems. Usually the problems aren't serious and a bit of investigation can result in a quick solution.

If bash didn't compile, the first thing to do is check that configure guessed your machine and operating system correctly. Then check the file NOTES, which contains some information on specific UNIX systems. Also look in INSTALL for additional information on how to give configure specific compilation instructions.

12.3.5. Installing bash as a Login Shell

Having installed bash and made sure it is working correctly, the next thing to do is to make it your login shell. This can be accomplished in two ways.

Individual users can use the chsh (change shell) command after they log in to their accounts. chsh asks for their password and displays a list of shells to choose from. Once a shell is chosen, chsh changes the appropriate entry in /etc/passwd. For security reasons, chsh will only allow you to change to a shell if it exists in the file /etc/shells (if /etc/shells doesn't exist, chsh asks for the pathname of the shell).

Another way to change the login shell is to edit the password file directly. On most systems, /etc/passwd will have lines of the form:

cam:pK1Z9BCJbzCrBNrkjRUdUiTtFOh/:501:100:Cameron Newham:/home/cam:/bin/bash

cc:kfDKDjfkeDJKJySFgJFWErrElpe/:502:100:Cheshire Cat:/home/cc:/bin/bash

As root you can just edit the last field of the lines in the password file to the pathname of whatever shell you choose.

If you don't have root access and chsh doesn't work, you can still make bash your login shell. The trick is to replace your current shell with bash by using exec from within one of the startup files for your current shell.

If your current shell is similar to sh (e.g., ksh), you have to add the line:

[ -f /pathname/bash ] && exec /pathname/bash --login

to your .profile, where pathname is the path to your bash executable.

You will also have to create an empty file called .bash_profile. The existence of this file prevents bash from reading your .profile and re-executing the exec—thus entering an infinite loop. Any initialization code that you need for bash can just be placed in .bash_profile.

If your current shell is similar to csh (e.g., tcsh) things are slightly easier. You just have to add the line:

if ( -f /pathname/bash ) exec /pathname/bash --login

to your .login, where pathname is the path to your bash executable.

12.3.6. Examples

The bash archive also includes an examples directory. This directory contains some subdirectories for scripts, functions, and examples of startup files.

The startup files in the startup-files directory provide many examples of what you can put in your own startup files. In particular, bash_aliases gives many useful aliases. Bear in mind that if you copy these files wholesale, you'll have to edit them for your system because many of the paths will be different. Refer to Chapter 3 for further information on changing these files to suit your needs.

The functions directory contains about 50 files with function definitions that you might find useful. Among them are:

basename

The basename utility, missing from some systems

dirfuncs

Directory manipulation facilities

dirname

The dirname utility, missing from some systems

whatis

An implementation of the Tenth Edition Bourne shell whatis builtin

whence

An almost exact clone of the Korn shell whence builtin

Especially helpful, if you come from a Korn shell background, is kshenv. This contains function definitions for some common Korn facilities such as whence, print, and the two-parameter cd builtins.

The scripts directory contains over 20 examples of bash scripts. The two largest scripts are examples of the complex things you can do with shell scripts. The first is a (rather amusing) adventure game interpreter and the second is a C shell interpreter. The other scripts include examples of precedence rules, a scrolling text display, a "spinning wheel" progress display, and how to prompt the user for a particular type of answer.

Not only are the script and function examples useful for including in your environment, they also provide many alternative examples that you can learn from when reading this book. We encourage you to experiment with them.