.\" $Revision: 1.00 $
.TH XMAKE 1
.SH NAME
xmake \- portable make utility
.SH SYNOPSIS
.B xmake
[
.B \-v
]
[
.B \-f xmakefile
]
[
.B \-d[#]
]
[
.B \-n
]
[
.B \-D sym[=data]
]
label1 ... labelN

.PP
.BI \-v		
print version and exit.  If xmake doesn't know what version it is,
someone forgot to re-make and re-install it with itself.
.PP
.BI \-f		
specify different default file
.PP
.BI \-d[#]	
turn on debugging
.PP
.BI \-n		
dry run - do not execute commands lists
.PP
.BI \-D sym[=data]	
specify additional symbols to call cpp with, also sets the EXTDEFS variable
.PP

.SH DESCRIPTION
.PP
.IR XMake
is a make utility.  It is not compatible with other makes, but provides
extended functionality over most standard makes.  Whereas most other
makes have confusing rulesets and do not support many-to-many dependancy
specifications, XMake has relatively few (basically no) rulesets and allows
you to easily specify many:many dependancies.  This gives XMake the flexibility
to deal with complex project hierarchies very simply.  Despite the fact that
there are no built-in rulesets, an XMakefile is often no more complex then
a normal Makefile.  XMake incorporates the following major features:
.PP
The ability to specify one-to-many, and many-to-one dependancies
.PP
The ability to apply a single command list to many one-to-one dependancies
(typically lots of object files depending on lots of source files can be
dealt with in a single line).
.PP
The ability to embed shell commands (e.g. find, ls, whatever...) in variable
and other definitions.
.PP
The ability to generate wildcard template conversions on the fly.  For example,
you can list the source files and generate the object files and all associated
dependancies from the source file list.
.PP
Runs the C preprocessor, allowing you to use #if/#else/#endif and, if need be,
use preprocessor macros.  The main purpose is to support the #include directive
and allow operating system and compiler auto-detect.
.PP
Maintains special 'dependancy' variables %(left) and %(right) which may used
in command sequences.
.PP
Allows variables to be .set inside a command sequence, where the .set 
directive is executed when/if the command sequence is executed... useful
when dealing with side effect issues.
.PP
Understands delayed-expansion variable specifications.  A normal variable
specification is something like $(NAME) or %(NAME), whereas a delayed-expansion
variable specification is something like ${NAME}.  This allows you to
set up global variables whos contents are based on other variables which
have not yet been initialized.  The variable is fully resolved when used
in a dependancy or executed as part of a command list.
.PP
By default, XMake attempts to access the 
.B XMakefile
in the current directory.  This can be overriden with the 
.B \-f
option.

.SH DIRECTIVES AND VARIABLE SPECIFICATIONS
.PP
Directives must start in column 1.  XMake understands 
the following directives:
.PP
.B \.set
varname contents
.PP
Set the contents of the specified variable

.PP
.B \.beg / \.end
.PP
Applicable only within a command sequence, allows blank lines to be 
inserted without terminating a command sequence.
.PP
Variables may be referenced in any one of several ways:
.PP
$(varname)
.br
$(varname?wildmatch)
.br
$(varname?wildmatch:wildreplace)
.br
$(varname:wildmatch)
.br
$(varname:wildmatch:wildreplace)
.br
%(special)
.br
%(special:wildmatch)
.br
%(special:wildmatch:wildreplace)
.PP
The $() variable form references a .set variable, while the %() variable
form references a special dependancy variable.  Dependancy variables only
work within command sequences.  Currently 
.B %(left)
and
.B %(right)
are defined.  %(left) represents the left hand side of the dependancy, while
%(right) represents the right hand side.
.PP
The optional wildmatch and wildreplace elements allow you to dynamically
restrict transform the elements contained within the variable.  For example,
if a variable contains a mix of 
.B \.c
and 
.B \.h
files, you can extract just the .c files with
.B $(VARNAME:*.c) .
Transformations are accomplished with a third element.  Each '*' or '?'
in the match side is represented by 
.B %1
to
.B %N
on the replace side.  You can also use '*' and '?' on the replace side,
which sequentially represent %1 ... %N.  The most common transformation
is something like this:
.PP
.br
 \.set SRCS       include.c list.c main.c subs.c
.br
 \.set OBJS       $(SRCS:"*.c":"$(OD)/*.o")
.PP

.SH DEPENDANCIES
.PP
XMake allows you to specify dependancies in a manner simliar to make.  
However, XMake extends the facility to allow many one-to-one dependancies
to be specified on a single line, as well as other combinations.  The
format for a dependancy is:
.PP
.br
d1 d2 ... dn : s1 s2 ... sn [ : a1 a2 a3 ... aX ]
.br
d1 : s1 s2 ... sn [ : a1 a2 a3 ... aX ]
.br
d1 d2 .. dn : [ : s1 a2 a3 ... aX ]
.PP
In the first form, each
.B dN 
is dependant on the associated
.B sN
and ALL of the 
.B a1-aX
elemnts.
.PP
In the second form, a single
.B d1
depends on ALL of the
.B s1-sN
and
.B a1-aX
elements.
.PP
In the third form, each destination
.B dN
depends on ALL of the
.B a1-aX
elements, and there are no 's' elements listed at all.
.PP
Note that the a1..aX elements are optional.  You may also specify a 
dependancy with no right hand side elements at all.  This will cause
the execution list for the left hand side to be run if the left hand
side is ever depended upon from a higher level.
.PP
The right hand side is not required to represent a real file if its label 
is used on the left hand side of another dependancy.  However, if it
does represent a real file, then the 'return code' will be based on a
time-stamp comparison even if the sub-dependancies of the right hand
side themselves are out of date and cause commands to run.  The best
example of this is the PROTOS dependancy shown below:

.br
$(OBJS):: $(PROTOS)
.PP
$(OBJS):: defs.h
.PP
$(OBJS): $(SRCS)
.br
    cc $(CFLAGS) %(right) -o %(left) -c
.PP
$(PROTOS): $(OD)/$(XMKPROTO) $(SRCS)
.br
    $(OD)/$(XMKPROTO) -o %(left) %(right:"*.c")
.PP
In this example, the object modules are dependant on the
prototype file being up-to-date (as well as defs.h).  However,
the prototype file is updated by xmkproto if any of the
source files change.  xmkproto is smart enough to not touch
the prototype file if it determines that none of the
prototypes have changed.  Even though the PROTOS:SRCS
dependancy is run, the OBJS:PROTOS dependancy will not be
run if the prototypes file was not actually modified.

.SH "INCLUDE PATHS"
.PP
XMake automatically includes the following directories when it runs CPP
on your XMakefile:
.br
The . directory
.br
The .. directory
.br
Your $HOME/.xmk directory
.br
/usr/local/share/xmk
.br
/usr/share/xmk
.PP
This allows you to configure XMake in a global system, with local overrides.
Most XMakefiles will not need any of these directories.  The most useful
is the . and .. directories, which allow you to setup hierarchical
XMakefile.inc files which are recursively included.

.SH CONCEPTS
.PP
It is extremely easy to construct XMakefile's that use a single file or
directory list to compile an entire project.  Once you have learned how
to use the wildcard match-and-replace capabilities, you will wonder how
you could have lived without it before.  Amoung other things, these functions
allow you to mix multiple file extensions in a single variable, such as
SRCS, yet apply a different ruleset to each extension.

.SH FILES
.PP

.br
XMakefile		default xmake control file
.br
$HOME/.xmk		In include path for cpp
.br
/usr/local/share/xmk	In include path for cpp
.br
/usr/share/xmk		In include path for cpp