tdevelop/languages/cpp/app_templates/kscons_kmdi/QUICKSTART

------------------------------------------
SUMMARY :

scons
scons install


The online documentation of bksys can be found at:
http://freehackers.org/~tnagy/bksys_manual.html

 ... and now for the quickstart:

CONFIGURING AND COMPILING THE PROJECT(S)
SCONS TIPS
TQMOC PROCESSING
SCONS MINIMUM DISTRIBUTION
MORE TIPS

------------------------------------------
CONFIGURING AND COMPILING THE PROJECT(S)

The program scons is usually launched as "scons"
When it is not intalled globally, one can run
"./scons" instead of "scons" (ie : to use the local scons
that comes with bksys - see below SCONS MINIMUM DISTRIBUTION
if you do not have scons already)

To compile the project, you will then only need to launch
scons on the top-level directory, the scripts find and
cache the environment detected *automatically* :
-> scons

To clean the project      ->  scons -c

To install the project    ->  scons install
To install as root user   ->  su -c 'scons install'
To uninstall the project  ->  scons -c install
To uninstall (as root)    ->  su -c 'scons -c install'
To consult the help       ->  scons -h

To (re)configure the project and give particular arguments, use :
        -> scons configure debug=1

The variables are saved automatically after the first run
in files named *.cache.py (look at kde.cache.py, ..)

------------------------------------------
SCONS TIPS

In a subdirectory, it is necessary to launch scons with the -u flag :
scons -u

This is annoying and you probably want to add this to your .bashrc
export SCONSFLAGS=-u
and forget about it :)

To make .deb or .rpm packages of your program, use :
checkinstall --fstrans=no --nodoc scons install
(if you have checkinstall on your system of course)

To make scons run (much) faster, consult ./addons/README in bksys

------------------------------------------
TQMOC PROCESSING

In qt programs, when a header 'foo.h' contains a class that has
Q_SIGNALS and Q_SLOTS, then 'foo.h' must contain the macro Q_OBJECT
in order to compile. foo_tqmoc.cpp is usually generated, and is 
used to produce foo_tqmoc.o which is linked with the 
program or the library.

In kde programs, 'foo.tqmoc' is generated instead of foo_tqmoc.cpp, 
and it must be included at the very end of foo.cpp 
(add #include "foo.moc" : this increases the speed of 
compilation a *lot* and makes less object files.

Both modes are provided though, see test6-tqmocfiesta/

------------------------------------------
MINIMUM SCONS DISTRIBUTION

A minimum scons distribution is included in the archive
for convenience to those who do not have scons packages 
for their operating system or their linux
distribution. For a full and more recent version of scons,
please consult http://www.scons.org

Including this scons distribution to your archive will add
about 63kb (compressed) , while including the necessary 
kdescripts (admin/ directory, configure, autom4 cache stuff, 
Makefile.in) can add easily 500kb (compressed).

To compile with the scons distribution :
* unpack it with :
  tar xjvf admin/scons-mini.tar.bz2
* compile the program with :
  ./scons (instead of just 'scons')
* install the program with :
  ./scons install (instead of just 'scons install')

More options :
* clean the object files with :
  ./scons -c
* uninstall the program with with :
  ./scons -c install
* create a package :
  ./scons dist

------------------------------------------
MORE TIPS

** static libraries **
With Makefile.am, one had to make static libraries all the time
because it did not allow having source code in other directories.
This is not the case anymore with scons, so you can specify
sources in other directories relative to the sconscript file, ie:
 test1_sources = ['mainfiles/main.cpp', 'otherfile/program.cpp']
 myenv.Program( target = "test1", source = test1_sources )
To encourage you to switch to the new scheme, the static library
helper has been omitted (look at the end of kde.py if you need one)

** libtool **
The LaFile build tool is a cheat that allows klibloader to load
.so files without complaints. If you need real libtool support
you can have a look to the libtool directory : it can work but
remember that libtool is broken on many systems (invalid flags
among others), so when you can work without libtool
(small projects especially), just do it.

** tqmoc processing **
As stated above, you should always add #include "foo.moc"
for your qt classes (Q_OBJECT) to save precious compilation time.

** using a cache **
It is a good idea to enable the cache feature in SConstruct,
especially if you are doing experiments (it saves your computer
from recompiling the same files over and over again ..).

** threading **
myenv.AppendUnique( CPPFLAGS = ['-DQT_THREAD_SUPPORT', '-D_REENTRANT'] )

** final notes ***
A medium-sized project containing several targets, libraries and data
files can be converted very quickly.
Also, remember that SConscript files are actually python scripts ..
you can use whatever python feature you want in them, ie: "for" loops,
this is how the kde helpers work (KDEprogram, KDEshlib ..).

If you are stuck, you can also have a look at more complicated 
bksys-based projects like kdissert or kshaderdesigner

The scons man page and the wiki can be very useful, do not forget to
consult them when you encounter an issue

------------------------------------------

I hope you will enjoy this alternative to the autotools
scripts for kde programming, at least as much as I do : 
http://freehackers.org/~tnagy/kdissert/index.html

Happy kde hacking,

Thomas Nagy, 2004, 2005 <tnagyemail-mail@yahoo^fr>