ede/docs/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 usefull
(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 (and that is 'wohaaa' with arcane make syntax)
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 explaination.

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 :-)

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


EDE build specific rules
------------------------
This is the main reason why you are reading this :-P. This is a list of rules
for easier building various pieces and short showcase how to use them.

Program rules
~~~~~~~~~~~~~
These rules are used to build binary file(s).


Program [target] : [sources] : [libraries] : [flags] ;
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Creates [target] binary from [sources]. If libraries are given (normal way of linking
like '-lfoo', they will be used. If [flags] are given, like '-DABC' they will be
passed to compiler. Like:

-------------------------
# Compile and link with fltk libraries
SOURCE = Main.cpp SciCalc.cpp ;
Program ecalc : $(SOURCE) : -L/usr/local/share -lfltk -lX11 -lm -lstdc++ ;

# Compile and link with fltk libraries; also pass -D_DEBUG
SOURCE = Main.cpp SciCalc.cpp ;
Program ecalc : $(SOURCE) : -L/usr/local/share -lfltk -lX11 -lm -lstdc++ : -D_DEBUG ;
-------------------------


EdeProgram [target] : [sources] : [optional-libraries] : [optional-flags] ;
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create [target] and link it with edelib and fltk libraries. If [optional-libraries] and
[optional-flags] are given, they will be used. Like:

-------------------------
SOURCE = abc.cpp ;
EdeProgram abc : abc.cpp ;
-------------------------

EfltkProgram [target] : [sources] : [optional-libraries] : [optional-flags] ;
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The same as EdeProgram, but will link with efltk libraries. This rule is used to compile 
some programs from 1.x version, and will be removed when those programs are ported
to the edelib and fltk code.

FltkProgram [target] : [sources] : [optional-libraries] : [optional-flags] ;
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create [target] linking it with fltk libraries only. Also will link with images libraries.


FltkProgramBare [target] : [sources] : [optional-libraries] : [optional-flags] ;
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Same as FltkProgram, but will *not* link with images libraries. Usefull for programs
which does not require images support.

Library rules
~~~~~~~~~~~~~
These rules are used to build either static or shared libraries.

StaticLibrary [library] : [sources] : [optional-flags] ;
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Creates static library from [sources] files. If [optional-flags] are given, they
will be passed to the compiler. Sample:

-------------------------
# Compile each file with -D_DEBUG flag and create
# mylib.a library
StaticLibrary mylib : file1.cpp file2.cpp file3.cpp : -D_DEBUG ;
-------------------------

SharedLibrary [library] : [sources] : [optional-linklibs] ;
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Creates a shared library from [sources] and link with [optional-linklibs]. Shared library
will, by default, have a '.so' extension, if extension in [library] was not given.

SharedLibraryVersioned [library] : [sources] : [optional-linklibs] : [optional-version] : [nolink] ;
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Creates a versioned shared library (like foo.so.1.2.0) and symbolic link (foo.so) to it.
If [optional-version] is given, it will be used to add version extension, if not,
this rule behaves the same as SharedLibrary (meaning symbolic link will *not* be created).

If option [nolink] was given, but [optional-version] does, symbolic link will not be created.
Here are few samples:

-------------------------
# Create foo.so.1.2.0 and symbolic link to it
SharedLibraryVersioned foo : file1.cpp file2.cpp : -L/some/path -lsomelib : 1.2.0 ;

# Create foo.so.1.2.0 without symbolic link
SharedLibraryVersioned foo : file1.cpp file2.cpp : -L/some/path -lsomelib : 1.2.0 : nolink ;

# Create foo.so.1.2.0 without linking with external libraries
SharedLibraryVersioned foo : file1.cpp file2.cpp : : 1.2.0 : nolink ;
-------------------------