The "rebuild" Utility

This is a functional replacement for the UNIX make utility, with new syntax and abilities.

This manual unfortunately assumes some familiarity with "make".

If you chose to use this program, drop me a line and I'll see what I can do on keeping you up to date.

A current copy of the program should be available at the Utilities web page. There are some extensive examples there also.

This program is clearly a work in progress. I'm willing to discuss directions with most folk that might be interested.


Table of Contents


Commands

Default Configuration File

By default, rebuild looks in the current directory for a file called "Rebuild" as it's configuration file.

Includes

Other files can be included with the "include" command.

# Example
include filename

Macros

Defines

The basic define command is:

# Example:
define NAME as TEXT

Where TEXT may be nil.

Usages

The main power of "rebuild" is in its usage of macros.

In addition to strict text substitution, there are a number of evaluation tools available.

The names in the executing environment are imported as defined macros, as are some standard symbols. Many of these symbols are used to annotate usage.

# Predefined macros.
DATE        -> Current date
DATESUFFIX  -> Date suitable for file names (1998-11-10T17:00:45)
REBUILD     -> Name the rebuild program is running as.
OPTIONS     -> Options it was called with.
DEFINES     -> Macro definitions from the command line.
REBUILDFILE -> Configuration file it is using.
TARGETS     -> Targets from the command line.
               (Note that this one is modifiable. [But I can't think of a good use])
...

Macro invocation is with curly braces ("{}"), and whatever is in the braces is interpretated as macro commands.

Macro commands are separated by the pipe ("|") symbol.

The types of macro commands are as follows:

# Examples:

# Definition of regular text macro.
define ME as John Halleck

# Define a macro as the files in the current directory.
define FILES as { dir(.) }

# define a macro as the .c and .h files (if any) in the home directory.
define CFILES as { dir({HOME}) | only(*.c *.h) }

# The previous define without .c files.
define HFILES as { CFILES | minus (*.c) }

# The previous file mapping .c filenames to .o filenames keeping only those that exist.
define OFILES as { HFILES | *.c => *.o | -e }

# Patterns can be specific with no wildcards.
define SOMEC as {CFILES | minus(foobar.c)}

Patterns

Rebuild allows patterns in both macros, and in targets.

Patterns are either of the form *text or text*.

Pattern rewrites are used in macros to change forms of file names.

# (Examples from macro mappings...)
*.c => *.h 
  # in a macro this maps a list of .c files to .h files.

/home/dir1/* => /home/dir2/*
  # Maps names in one directory to names in another.
  # This could be combined with other filters to give (for example)

define TODO as { dir(/home/dir1/) | *.c => /home/dir2/*.h | -e | /home/dir2/*.h => * }
  # list of names of the .c files in dir1 that have matching .h files in dir2

Targets

The form of the targets command is either:

targets : ancestors
or
targets <= ancestors

The first form is kept for compatibility with "makedepend".

Any code lines that follow must be prefixed with "=>"

Targets may appear multiple times, as long as generating code appears only for the last occurrence. Unlike make, patterns may be used in the targets...

# Example.
*.o <= *.c
=> {CC} {*}.c

The example above says that .o files have .c files as ancestors.

Within a code block there are several predefined macros in addition to the ones defined everywhere.

{*}
The matching part of the file name.
{target}
The target we are building.
{ext}
The final trailing extension on the target (if any)
{file}
The target name with {ext} removed.
{parents}
The direct ancestors of this file.
{newparents}
The {parents} that are newer than this target.

All the macro features may be freely used in the data lines.

Target and dependency lists can be generated by macros.

# Examples
{dir(.) | only(*.final) } <= *.original
{dir(.) | *.h => *.c | -e} <= *.h
finalstuff <= {dir(/includes) | only(*.originals)}

In addition to code lines, there can be build time macros, noted by a line starting with "=:". These can use the macros that are defined for the target.

# Examples.

define Built as
# The above line defines "Built" as having nil text.

*.o <= *.c
=> {CC} {*}.c
=: define Built as {Built} {target}

all <= {dir(.) | only(*.c) | *.c => *.o }
=> echo "Files we built: {Built}"

Document Tools

The "Tools" command just puts a block of comments in the output file that documents which version of a given program was used in processing.

This is useful (I guess) for those that worry about configuration management seriously.

# Example
tools {CC}

Command Line Options

No documentation yet. Fire up rebuild with nothing on the command line for a list.

Some important ones are:

-n
Don't build. (But do show what would be done.)
-c file
Use alternate configuration file.
-o file
Specify a place to place the output.
-d
Turn on debugging. (Lots of output.)
-f
Force every target to appear out of date.
-l
Expanded listing.
-m
Show results of macro assignments. (Debugging)
-r
Show reasons for building target.
-V
Version

Command Line Defines

Macro's may be predefined on the command line.

rebuild a=12345 "b=some value" c=`foo` all

Go to ...


This page is http://www.cc.utah.edu/~nahaj/utilities/rebuild.documentation.html
This page was last modified on February 1st, 2001