[pclasses-devel] toc build tree HOWTO

[stephan b. <st...@s1...>]

Yo!

Here's an overview of how to try out the toc-based build tree...

First, update your pclasses2 tree to HEAD.

Some of the new files:

./configure - check this out from CVS, replacing the AT-generated copy. 
PLEASE do NOT commit an AT-generated configure script over this one! 
(But i know it's gonna happen by accident at some point.) The only time 
this file is edited is to change the PACKAGE_VERSION.

./configure.pclasses2 - this is the main configure script. It is called 
by the toc framework after toc does it's own bootstrapping. configure 
customizations go here.

./configure.toc is a stub file for working with AT. Ignore it - you'll 
never need to know it exists.

./toc.pclasses.help contains the help text for P-specific configure 
options.

./toc/... The entire build system lives here, which means it's always 
compatible with the version of the tree it is shipped with. (This is 
where AT sucks so badly.)

Makefile.toc (in every dir): the toc-based makefiles. They are called by 
Makefile stubs which get created by ./configure. Normally toc does not 
generate 'Makefile' (they are hand-implemented), but in this case we 
generate them to allow it to cooperate with AT. Put your Makefile code 
in Makefile.toc. toc will not modify your makefile at all. To generate 
a Makefile for a dir, run configure or copy one from any other dir 
(they are all 100% identical).


As usual, run ./configure --help for info.

Switching between toc and AT:

To use the AT support, simply use AT to rebuild the configure script and 
Makefiles. To use toc, replace the AT configure with the one from CVS 
and run configure. That's all there is to it.


ACHTUNG: the toc port of the build tree is not 100% complete:

- It builds the posix-compatible sources only, because i've only got a 
Suse Linux box. For the SharedLib support it currently uses libltdl or 
libdl, whichever the configure script finds (preferring ltdl).

- It builds all of the libs, but ./configure does not yet provide all of 
the necessary linker flags for linking against those libs. There are 
lots of fixes to be done here.

- Many of the config values are hard-coded at the moment. See 
configure.pclasses2 for notes.



Some things worth knowing about toc:

- toc = "the other ./configure"

- ./configure --help

- ./configure --help-tests

- If you export the env var 'prefix' then you don't need to pass it 
to ./configure. Useful when editing the configure script and re-running 
it a lot of times.

- Only works on systems hosting GNU versions of tools like Make, Tar, 
Bash, Awk, etc. Only common system tools are needed, but Solaris 
versions of Make or tar (and other apps) will not work.

- See ./toc/tests for the sources for the config tests run by 
configure.pclasses2.

- make dist. Works, but is probably still missing some files.

- toc's shell API is defined/documented in ./toc/sbin/toc_core.sh. Only 
the API which is actually used in configure.pclasses2 
and ./toc/tests/*.sh are of interest to clients.

- The makefile framework is quite modular. See ./toc/make for the 
various snippets (not all of which are used). See, e.g., 
toc/make/SHARED_LIBS.make for the snippet which does all DLL building. 
We can swap out these snippets for platforms which need custom 
handling.

- You do NOT have to run configure when you change your makefiles. You 
only need to run it when:
a) Initial config
b) You want to, because AT has trained you to.
c) You've added a subdir. You do NOT need to add the subdir to the 
config script, but you do need to generate toc.make (and friends) for 
that dir. configure generates a toc.make for any dir containing a 
Makefile{.toc} with the line "include toc.make".

- The make code explicitely takes advantage of features of GNU make, 
making it more powerful than portable Makefile.am code.

- "Project-global" makefile code should go into ./toc.pclasses2.make.at,
then re-run configure to regenerate ./toc.pclasses2.make. It then gets 
included into any Makefile.toc automatically.

- If you have lyx installed, try 'cd doc/manual; make LYX_EXPORT'.

- When using DIST_FILES in your Makefile.toc, NEVER use 
'DIST_FILES=...', but always use 'DIST_FILES+=...'. (Note the '+='.)

- The full toc docs (a bit outdated, but still mostly accurate) are 
available via toc.sourceforge.net.

- If you have a dir full of files and want to generate a mostly-usable 
Makefile.toc automatically, do this from the top srcdir:
	./toc/bin/create_makefile_stubs.sh ./my/subdir
	cd ./my/subdir
	mv Makefile.suggestion Makefile.toc
	emacs Makefile.toc ...
Normally the generated makefile contains 90%+ of what you need to build 
the dir, and for simple dirs it can do all the work itself.

- If we ever decide to drop AT then we can rename Makefile.toc ==> 
Makefile.

- Ask me if you have questions about what toc can/cannot do, or how to 
do a specific thing in toc. If something can't be currently done, it 
can be added. i've spent almost 2 years refining toc, so nobody knows 
it better than i ;).



Okay, that was more than i wanted to say, but i guess i just want to 
convince everyone that toc is pretty flexible. i've used it for ALL of 
my source trees since almost 2 years, so i know it easy to 
hack/extend/customize, and MUCH easier to maintain than autotools.

:)

See ya!

-- 
----- st...@s1...   http://s11n.net
"...pleasure is a grace and is not obedient to the commands
of the will." -- Alan W. Watts