SETBASE

Introduction

When building software from source code for installation on your computer, it's not unusual to have to fix a few things to work around differences between your build environment and that of the developer. This is particularly the case for Open Source packages developed on GNU/Linux systems which you're trying to deploy on other flavours of Unix such as Solaris or IRIX.

After getting the software to build and installing it on your system, it's only human to forget what changes you've made, and then, when you later decide to install a newer version, having to start all over fixing the same problems. You could, of course, put the distribution into a source code change control system such as RCS or CVS and use it to keep track of your local modifications, but this can be a bit much when all you're trying to do is keep track of small changes to a few files.

For more than twenty years, I've been using setbase, about the simplest change control system imaginable, in cases such as these and have found it entirely adequate. Setbase was originally written as a Unix shell script by Kern Sibbald when we both worked at Autodesk, and was used by many programmers at Autodesk to keep track of changes while developing software. Over the years, I've developed a few accessory shell scripts to work with setbase, which I finally decided to integrate into setbase itself, while rewriting the basic shell script to check for some error conditions which might lead to confusion when working with software distributions whose content is largely unknown to the individual attempting to build them.

How It Works

The operation of setbase could hardly be simpler. When you receive a source distribution for a software package, before making any local changes, set all source files read-only. You can do this with the “chmod” command, or the setbase “-s” option.

With the files marked read-only, any attempt to modify them will be rejected. Before modifying one or more files, use the command:

setbase file…

which will copy the original unmodified read-only file(s) from the distribution into a directory of "base" files, by default a “Base” subdirectory, which will be automatically created if necessary. The file in the current directory is then marked write-enabled, permitting it to be edited. You can, at any time, determine which files you've modified simply by looking at the contents of the Base subdirectory, and see what changes you've made by performing a diff between the distribution file in the Base directory and the modified version in the current directory. The setbase “-d” option lists all changes made to files in the current directory.

Command Line Options

Usually setbase is run with no command line options—just one or more file names for which base copies should be saved and write enabled. The following command line options perform utility functions associated with setbase.

-b

List files in the base directory. While this identifies all files in the distribution which you've modified, it does not list new files you've added. Use the “-m” option to list both new and modified files.

-d file…

Diff the base copies of the file arguments against their copies in the current directory.

-d

Diff all base files against their copies in the current directory.

-m

List all modified (write-enabled) files in the current directory. Note that this shows both files with base copies and newly-added files. Since object files will be included in this listing, you'll usually want to delete them before using this command.

-mr

List all modified (write-enabled) files in the current directory and any subdirectories.

-s

Set all files in the current directory read-only. This prepares a directory for use with setbase.

-sr

Set all files in the current directory and any subdirectories read-only.

-u

Print how to call information.

Configuration Variables

The following variables are defined at the start of the setbase shell script; change them if you don't like the default values supplied.

BASEDIR

This is the name of the directory (beneath the current directory) in which base files will be saved. The default value is “Base”. This name must not duplicate the name of an existing file or subdirectory in which setbase is run.

FIND

Path to run the GNU find utility. The default is just “find”, which assumes it's on the user's search PATH. If you're running on a Unix system where the default find isn't the GNU version, you'll need to specify the explicit path to run GNU find here.

Installation and Configuration

To install and configure setbase, perform the following steps.

1. Download the setbase source archive and extract its contents into a new directory. The archive contains setbase, the main shell script, and setbase.1, the manual page for the program.
2. Edit setbase and set the configuration variables appropriately for your application. The configuration variables are discussed in detail above. The setbase script is written for a Bourne-compatible shell such as bash or ksh; if “/bin/sh” is not such a shell on your system, modify the shell specification in the first line of the script accordingly.
3. Install setbase in a binaries directory on your PATH and the setbase.1 manual page in a man1 directory on your MANPATH.

Download setbase.tar.gz (gzipped TAR archive)

Bugs, Features, and Gotchas

Setbase works only on files in the current directory. If given a file name with a path specification, an error message is issued and the file ignored.

Setbase is a Bourne shell script. It won't work on systems without a compatible shell.

The “-d”, “-m”, and “-s” options require the GNU version of find. The basic no-option setbase command does not require this program to be available.

If you find errors in this program or document, please report them to Bravo Uniform Golf Sierra @ Foxtrot Oscar Uniform Romeo Mike India Lima Alpha Bravo Decimal Charlie Hotel. If you don't have any idea what I just said, please consult this document.

Copying and Support Information

This software is in the public domain. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. This software is provided “as is” without express or implied warranty.

Fourmilab Home Page