CrossPath building with ACR
===========================

** IMPORTANT **
Read carefully the entire document. At the end there's detailed information
to create well written crosspath Makefiles (only for acr>=0.4) (older ones
are buggy).
** IMPORTANT **

Crosspath building is a way to build sources in a clean way. And is also
useful for crosscompiling and make parallel builds.

This feature is an internal 'make' tool tip. But must be enabled in all
Makefiles and the ./configure must know that to allow it.

All Makefile.acr files must a line like this:

  VPATH=@VPATH@

This is the same that GNU autoconf does with:

  VPATH=@srcdir@

ACR internally will autodetect if you are using a crosspath and will set this path to the correct one when generating the Makefiles from the .acr files.



This is an example:

$ tar xzvf foo-0.1.tar.gz
$ mkdir build
$ cd build
$ ../foo/configure
$ make

By this way source directory will be kept clean, and all files, objects and
modifications generated by ACR will be done in build/ directory instead of
foo/ one.



Install target
==============
I was noticed that GNU and BSD Makefiles ignores VPATH when currentpath files
are found in the install stage.

This bug is fixed in acr v0.4, and requires some changes in the Makefile.acr.

Simple explanation of the problem:
----------------------------------
You've two directories called 'alice' and 'bob' :) The first one contains
the configure script and two source files:

$ ls alice
configure 	Makefile.acr 	a.c 	b.c

the configure script SUBST the a.c file.
On <0.4 will do:
  - mv a.c a.c.orig
  - sed {sedflags} a.c.orig > a.c

this is ok for non-crosspath builds, but crosspath builds forces the build to
keep intact the source tree. By this way acr 0.4 fixes this tip just sedding
them into the current path:
  - sed {sedflags} {vpath}/a.c a.c

By now, the a.c file in current dir will override the {vpath}/a.c. (handled
by VPATH rule in make).

The problem is that make only handles VPATH fine on builds. If you'r installing
you'r forced to specify the entire path to the file. BTW all non substed files
must be referenced by a ${VPATH} prefix and substed files without it.

A simple example is 'here', in the ACR's Makefile.acr:

---[ acr's makefile.acr ]---
...

VPATH=@VPATH@
INSTALL_SCRIPT?=@INSTALL_SCRIPT@
BINDIR=@BINDIR@

install:
	mkdir -p ${BINDIR}
	${INSTALL_SCRIPT} src/acr ${BINDIR}/acr
	${INSTALL_SCRIPT} src/acr-sh ${BINDIR}/acr-sh
	${INSTALL_SCRIPT} ${VPATH}/src/acr-cat ${BINDIR}/acr-cat
...
---[ acr's makefile.acr ]---

---[ acr's configure.acr ]---
...

(( directories ))
SUBDIRS . ;
SUBST_FILES src/acr src/acr-sh ;

...
---[ acr's configure.acr ]---
