Appendix E. Building bash from Source
In this appendix we’ll show you how to get the latest version of bash and install it on your system from source, and we’ll discuss potential problems you might encounter along the way. We’ll also look briefly at the examples that come with bash and how you can report bugs to the bash maintainer. The material in this appendix also appears in Learning the bash Shell, 3rd Edition, by Cameron Newham (O’Reilly).
Obtaining bash
You can find the very latest details on the current distribution and where to obtain it from the bash home page.
Unpacking the Archive
Having obtained the archive file, you need to unpack it and install it on your system. Unpacking can be done anywhere—we’ll assume you’re unpacking it in your home directory. Installing it on the system requires you to have root privileges. If you aren’t a system administrator with root access, you can still compile and use bash; you just can’t install it as a system-wide utility. The first thing to do is uncompress the archive file: gunzip bash-4.4.tar.gz. Then you need to untar the archive: tar -xf bash- 4.4.tar. The -xf means “extract the archived material from the specified file.” This will create a directory called bash-4.4 in your home directory. If you do not have the gunzip utility, you can obtain it in the same way you obtained bash or simply use gzip -d instead.
The archive contains all of the source code needed to compile bash and a large amount of documentation and examples. We’ll look at these things and how you go about making a bash executable in the rest of this appendix.
What’s in the Archive
The bash archive contains a main directory (bash-4.4 for the current version) and a set of files and subdirectories. Among the first files you should examine are:
- CHANGES
-
A comprehensive list of bug fixes and new features since the last version
- COPYING
-
The GNU copyleft for bash
- MANIFEST
-
A list of all the files and directories in the archive
- NEWS
-
A list of 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; if you’re interested in seeing the full list, however, check out Appendix B.
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 manpage entry bash.0. 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.
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 and was written by the current bash maintainer, Chet Ramey.
Configuring and Building bash
Compiling bash “straight out of the box” is easy—you just type ./configure and then make! The configure script attempts to work out whether you have various utilities and C library functions, and their locations on your system. It then stores the relevant information in the file config.h. It also creates a file called config.status, which is a script you can run to recreate the current configuration information. While configure is running, it prints out information on what it is searching for and where it finds it.
The configure script also sets the location where 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 provide configure with the path you want to use. 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 to use it later in this appendix.
Once the build finishes, you can see if the bash executable works by typing ./bash.
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. See the INSTALL file for more details on the configurable features and what they do.
Many other shell features can be turned on or off by modifying the file config-top.h. For further details on this file and on 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’ve run make install first; otherwise, you’ll have to rerun the installation from scratch.
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 “Reporting Bugs” for information on how to do this.
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.
Installing bash as a Login Shell
See Recipe 1.11.
Examples
See Appendix B for examples included with bash.
Who Do I Turn To?
No matter how good something is or how much documentation comes with it, you’ll eventually come across something that you don’t understand or that doesn’t work. In such cases it can’t be stressed enough to carefully read the documentation (in more casual computer parlance: RTFM). In many cases, this will answer your question or point out what you’re doing wrong.
Sometimes you’ll find this only adds to your confusion or confirms that there is something wrong with the software. The next thing to do is to talk to a local bash guru to sort out the problem. If that fails, or there is no guru handy, you’ll have to turn to other means (currently only via the internet).
Asking Questions
If you have any questions about bash, there are currently many ways to go about getting them answered. You can email questions to [email protected] or [email protected], or you can post your question to the USENET newsgroup gnu.bash.bug (perhaps via https://groups.google.com/forum/#!forum/gnu.bash.bug). There are also more generic help sites, such as StackOverflow, Linux Stack Exchange, and so forth.
When asking a question, try to give a meaningful summary of your question in the subject line—see “How to Ask Questions the Smart Way” by Eric Raymond.
Reporting Bugs
Bug reports should be sent to [email protected], and include the version of bash and the operating system it is running on, the compiler used to compile bash, a description of the problem, a description of how the problem was produced, and, if possible, a fix for the problem. The best way to do this is with the bashbug script, installed with bash.
Before you run bashbug, make sure that you’ve set your $EDITOR environment variable to your favorite editor and have exported it (bashbug defaults to Emacs, which might not be installed on your system). When you execute bashbug it will enter the editor with a partially blank report form. Some of the information (bash version, operating system version, etc.) will have been filled in automatically. We’ll take a brief look at the form, but most of it is self-explanatory.
The From field should be filled out with your email address. For example:
- From: [email protected]
Next comes the Subject field; make an effort to fill it out, as this makes it easier for the maintainers when they need to look up your submission. Just replace the line surrounded by square brackets with a meaningful summary of the problem.
The next few lines are a description of the system and should not be touched. Then comes the Description field. You should provide a detailed description of the problem and how it differs from what is expected. Try to be as specific and concise as possible when describing the problem.
The Repeat-By field is where you describe how you generated the problem; if necessary, list the exact keystrokes you used. Sometimes you won’t be able to reproduce the problem yourself, but you should still fill out this field with the events leading up to the problem. Attempt to reduce the problem to the smallest possible form. For example, if it was a large shell script, try to isolate the section that produced the problem and include only that in your report.
Lastly, the Fix field is where you can provide the necessary patch to fix the problem if you’ve investigated it and found out what was going wrong. If you have no idea what caused the problem, just leave the field blank.
Tip
If the maintainer can easily reproduce and then identify the problem, it will be fixed faster—so make sure your Repeat-By (and ideally Fix) sections are as good as you can make them. Reading the article mentioned in “Asking Questions” is also encouraged.
Once you’ve finished filling in the form, save it and exit your editor. The form will automatically be sent to the maintainers.