ede/doc/jambuild.txt

Jam build
=========

This is a short description of build library for EDE, based
on http://www.perforce.com/jam/jam.html[Jam] tool, an alternative to make.
But, this is *not* detail tutorial about jam, only detail description
of EDE build library. For jam tutorial you should consult jam documentation.

Introduction
------------
Why not make, you probably ask yourself, since the rest of the world
use it? Well, make is a nice tool for small projects, or relatively
large one with monolithic configuration file. This means, if you have
1000 files and you want to build them on the same way, make can be useful
(sorta of).

On other hand, if you want some of them to have specific requirements,
like linking with sound libraries (for example, ecalc does not have any
sound needs, but window manager does), this can't be accomplished without
unreadable and error prone make code mess.

Most projects often link every needed library with every binary inside tree,
and relay on compiler to figure out what will go into that binary or not.
Don't have to say how this slows things considerably (since compiler have
to scan each library, if is static). On other hand, in case of shared
libraries (today very often), that library 'will be tied to' that binary, even
if binary does not use any function from it. It is silly that ecalc requires,
for example, libogg for startup, even if it does not use any function from it!

In EDE 1.x we had pretty simple build system based on make (without automake stuff 
because is... ah, check comments online about it :-P) that served us very well. 

But it had a lot of limitation. You couldn't, as sample, specify '-DSHAPE' flag
for a window manager without passing it to every program in the tree. The same
applies for linked libraries too.

Jam is designed for these cases and when they occur, it is like homeland for him.
So, you want only 'foo.cpp' from 'baz' directory to get '-DXYZ' flag, no problem. Or you
want that every file in 'baz' directory (no matter is it binary or shared library)
be linked with 'libtaz'; no problem either.

So how it looks like
--------------------
Here are few samples with syntax explanation.

Let say you have 'foo.cpp', a cool application and you want to create executable from
it. This is the way:

-------------------------
  # this is an comment
  Main foo : foo.cpp ;
-------------------------

End :) Jam will see it as C\+\+ file and call a C\+\+ compiler in the background. Or, you
want to link it with libbaz.a library, it is like:

-------------------------
  # this is an comment
  Main foo : foo.cpp ;
  LinkLibraries foo : libbaz ;
-------------------------

As you can see, you give to it 'full' library name *without* extension. Jam will figure
out how to strip 'lib' part and pass correct parameters to the compiler. Jam is
very portable and runs almost everywhere (with various compilers), this 'unified' naming is needed
because different compilers see/get/creates libraries names on different ways.

This is sample how to create your own library and link own program with it:

-------------------------
  Library libmylib : file1.cpp file2.cpp file3.cpp ;
  Main foo : foo.cpp ;
  LinkLibraries foo : libmylib ;
-------------------------

Here it will be created 'libmylib.a' (with gcc compiler) and 'foo' will be linked with it. Order
or 'rules' ('Main', 'LinkLibraries' and 'Library' are called *rules*; you can see it as plain
C/C\+\+ function) is not important, so:

-------------------------
  Main foo : foo.cpp ;
  LinkLibraries foo : libmylib ;
  Library libmylib : file1.cpp file2.cpp file3.cpp ;
-------------------------

will do the same job. Jam builds internally dependency tree so order is not important to it.

[NOTE]
.Something to know
===================================
You could notice that at each line is ended with ';' character
and *space* before it. That is *needed* or jam will not
parse line correctly. So *every* line with expression
must have space before ending ';' character, like:

- 'something ;' (good)
- 'something;' (bad) !!!

Well, that is a jam syntax :-)

===================================