compile.1

.TH compile 1
.SH NAME
compile - a compiler invocation tool
.SH SYNOPSIS
.B compile
\fItarget\fR
[\fItarget\fR ...]
[\fB\-\-help\fR]
[\fB\-\-version\fR]
.SH DESCRIPTION
The \fIcompile\fR command provides a simple compiler invocation tool. The
command accepts one or more file names or file name prefixes (i.e. the targets)
on its command-line, and determines which compiler to invoke. Compilers are
matched by the file extension of the first target, as defined in the
\fI~/.compile/targets\fR file.

Targets must be either a full relative or absolute path to the source file or
such a path but lacking the extension suffix. The compile program will search
the current directory and attempt to find a match against the extensions it has
registered in the \fI~/.compile/targets\fR file. For example, the invocation
\fBcompile thing\fR would resolve to the invocation \fBgcc -othing thing.c\fR
given that thing.c exists in the working directory and \fB.c\fR has an entry in
the targets file.

.SH THE TARGETS FILE
The \fI~/.compile/targets\fR file describes how to invoke compilers based on an
input target's file extension. It has the form:

\fB.\fR[\fIext\fR] [\fIcommand-line ...\fR]

The \fIcommand-line\fR may contain the special token \fI$project\fR. This refers
to the file name (minus extension) of the first input target. Consider:

\fB.c gcc -o$project -Wall -Wfatal-errors\fR

This will invoke \fIgcc\fR given a .c file.

The command line may also include one redirect sequence, which is useful for
redirecting the output of a compiler in case only standard output is used by a
compiler for its result. It follows conventional shell syntax. Consider the
following example:

\fB.md kramdown --template MY_TEMPLATE >$project.html\fR

The targets file and its containing directory are created upon running
\fIcompile\fR. It will contain a default rule for C files that can be used as a
template.

.SH AUTHOR
Written by Roger P. Gee <rpg11a@acu.edu>