Building Linux software from source

Locate software and retrieve source code

This might involve checking out a copy from a repository with subversion (svn) or git.
eg git clone or retrieving a compressed archive (.tar.gz, .tgz, .zip) from a web site.

Decide where the source code will be located once it has been retrieved and extracted.
eg $HOME/src

Within that directory either check out a copy of the source code

	cd $HOME/src
	git clone https://github.com/example_pkg/example_pkg.git

or extract the source code from the downloaded archive

	cd $HOME/src
	wget https://mirror.aarnet.edu.au/pub/gnu/bison/bison-3.0.4.tar.gz
	tar -z -x -f bison-3.0.4.tar.gz

(Replace -z with -j for .tar.bz2 and --xz for .tar.xz compressed archives)

Applying patches

Since its release the package may have accumulated a number of fixes and small features available as patch files.

Retrieve any desirable or applicable patches.

	cd $HOME/patches/example_pkg
	wget http://www.example.org/example_pkg/example_pkg-fixes-1.patch

Apply the patch(es) to the source tree.

	cd $HOME/src/example_pkg
	patch -p1 < $HOME/patches/example_pkg/example_pkg-fixes-1.patch

Set up a working directory

While not all packages support building outside the source tree this is best practice. In this case you create a working directory separate from the source directory under which you will build the application. Your source tree is then left untouched.

	mkdir -p ${HOME}/work/bison-3.0.4

Where this is not supported your working directory will be the source directory.

Configure the build

If the autoconf tool set was used to prepare the package there will be a shell script configure in the source directory. This script will accept command line parameters that specify where the final components will be installed, enable or disable various optional features.

You will invoke this script from the work directory

	cd ${HOME}/work/bison-3.0.4

	# List what features and options are available
	#
	sh ${HOME}/src/bison-3.0.4/configure --help

At this point you will have to decide where the resulting executables, libraries and configuration files will be installed.

	mkdir -p ${HOME}/gnu/bison-3.0.4

For simple installs everything can be place under one directory specified by the --prefix parameter.

For finer control the locations of the executables, libraries, configuration files and volatile files can be individually specified. See the output of --help

Building

The configure script will symlink the files in the source tree into the work directories and output Makefiles under the work directories. Once this process has successfully completed, the build can begin by invoking make

	make

There will usually be a number of warning messages from the compiler but hopefully the build will complete successfully.

Testing

Many packages include a test suite that may be invoked after building.

	make tests

Installation

To install the executables, libraries, configuration files and documentation into the location specified earlier during the configure phase—

	make install

Clean up

To remove the intermediate and temporary files required to construct the software—

	make clean

Start again from scratch

To return the to the source tree to its original (patched) state before the configure phase—

	make distclean

Updating your PATH

If your software has been installed under $HOME/gnu/bison-3.0.4 then the executables will be found under $HOME/gnu/bison-3.0.4/bin
To invoke the executable you can specify the full path

	$HOME/gnu/bison-3.0.4/bin/bison -y gram.y

More conveniently you can add $HOME/gnu/bison-3.0.4/bin to your PATH

	setenv PATH  ${PATH}:$HOME/gnu/bison-3.0.4/bin

If you have many such packages it may be more convenient to install every package under the same directory— here perhaps $HOME/gnu — then all the executables from each package will found under $HOME/gnu/bin
Then only one addition need be made to the PATH variable.

Alternatively you can still install each package (and different versions of) under its own directory but symbolically link each executable from the install bin/ directory into a common bin directory—
typically $HOME/bin which is usually included in your PATH

	cd $HOME/bin
	ln -s ../gnu/bison-3.0.4/bin/bison .
	rehash

To make the addition to your PATH permanent ‐ edit your .cshrc file to include your bin directories in your PATH

	# Edit .cshrc
	nano ~/.cshrc

	# Add to the end of the file - skip if already done.
	if ( ! $?_HOME_BIN ) then
	     setenv   $_HOME_BIN	${HOME}/bin
	     setenv   PATH	${PATH}:${_HOME_BIN}
	endif