         _________           ______ ______             ______         
         __  ____/______________  /____  /________________  /_________         
         _  /    _  __ \  __ \_  //_/_  __ \  __ \  __ \_  //_/_  ___/
         / /___  / /_/ / /_/ /  ,<  _  /_/ / /_/ / /_/ /  ,<  _(__  ) 
         \____/  \____/\____//_/|_| /_.___/\____/\____//_/|_| /____/  

What is Coolbooks?
==================

Cookbooks provides an infrastructure for projects who want to use
cook as build tool. In this respect it is much like automake. But
it does not generate any files. Also the project is not build
recursively, but from the main toplevel directory.

Cookbooks is designed to be modular, providing often used functionality
on a high level. However the developer may at any time dive deeper
into the build system and provide his own low-level procedures to
adapt to any need that might arise.

Cookbooks supports the developer in modularising his software by
providing utility functions to abstract away the position of the
modules in the source tree layout. Eg. a small library can be a
project on its own, but also be used in a larger project. With
cookbooks on can just drop the library source into the bigger
project's source tree and it is built as if it was the standalone
version of the library.

Cookbooks does nothing without being told! In that way you are
flexible in what you do.

How to use
==========

Just drop the Howto.cook file and the util subdirectory in your
project. Describe your project a config.cook file (one central
config.cook or one per module or any mixture of both methods is
possible). Type "cook" to build your project...

Examples
========

Building a C program:

----8<----8<----8<----8<----
/* Tell the build system where we are. This is unfortunately
 * necessary, because cook doesn't have macros. You may also
 * hardwire the path, but this takes away a lot of flexibility. */
here = [where-am-i [__FILE__]];

/* The source files are all relative to the previously
 * specified path in [here]. */
src =
	file1.c
	file2.c
	inasubdir/file3.c
	;

/* Now register the program with the build system. */
[c-program myprog [here] [src]];

/* Register the C source, which need to be compiled in the system.
 * Why? Maybe you have some assembler project, which doesn't use C.
 * But still the object files are there to link the program. Or
 * maybe you have some compiler, which creates object files. Then
 * the same applies. [c-program] does not make any assumptions about
 * the origin of the source files. In that it is easy to extend
 * the build system. */
[c-compile myprog [here] [src]];

/* Now the program gets compiled, but not installed. Maybe you
 * provide a special helper tool for building your project, but
 * which isn't needed on runtime later on. Therefor [c-program]
 * makes no assumptions on installing the program or where to
 * install it actually.
 *
 * Having an own function for installing abstracts away the need
 * to now the filename of the executable, which may be different
 * on different platforms. */

/* Install myprog into the standard [bindir] directory. */
[c-program-install myprog bin];

/* Or maybe it is a system utility, which is only of interest
 * to the system administrator?
[c-program-install myprog sbin];
 */

/* Or maybe it is a daemon?
[c-program-install myprog libexec];
 */
----8<----8<----8<----8<----

Building a static C library: (This basically the same as above.)

----8<----8<----8<----8<----
here = [where-am-i [__FILE__]];

/* Here we override some compiler flags. */
mylib_cflags = [cflags] -fPIC;
mylib_cppflags = [cppflags] -DPIC;
/* Goody: support for cook search_path. */
mylib_cincludeflags = [prepost -I /[here] [search_list]] [cincludeflags];

src =
	file1.c
	file2.c
	inasubdir/file3.c
	;

[c-static-library mylib [here] [src]];
[c-compile mylib [here] [src]];
[c-static-library-install mylib];
----8<----8<----8<----8<----

Feedback
========

Please send any feedback to the upstream author! Otherwise things
won't be fixed!

Bug reports, feature requests and improvement suggestions may be
either sent via mail or entered directly in the trac at the website.

 * email: cookbooks@kotka.de
 * trac:
     login: guest
     password same as login

Please do not discuss Cookbooks problems in non-related media, eg.
the cook-users mailing list. The people there maybe don't use
Cookbooks. Please do this only in case you really know that it is
allowed and appreciated. In any case don't forget to notify the
upstream author of the problems.

Author
======
Meikel Brandmeyer <mb@kotka.de>

-- 
  |\      _,,,---,,_
  /,`.-'`'    -.  ;-;;,_
 |,4-  ) )-,_..;\ (  `'-'
'---(_/--'  `-'\_)  fL				http://cookbooks.kotka.de

