How to compile LavaRnd
======================

    for LavaRnd version 0.1.3

QUICK START:
-----------

    To compile LavaRnd in the default way, try:

	cd your_src_tree/LavaRnd-0.1.3
	make clobber
	make all

    NOTE: Your Linux system should be running at least a 2.4.9-31 kernel.
          The command:

	  	uname -r

	  will print your kernel version if you do not know it.

=-=-=

TOP LEVEL AND LOWER LEVEL MAKEFILE RELATIONSHIPS:
------------------------------------------------

Each Makefile has two sections where make variables are set:

	#!/bin/make
	...

	common Makefile vars are set here

	...
	#########################################
	#=-=-= end of common Makefile vars =-=-=#
	#########################################
	...

	special Makefile vars are set here

	...
	#####################################
	#=-=-= start of Makefile rules =-=-=#
	#####################################

The top level Makefile will pass down a common Makefile variable
to a sub-directory.  So if you change the value of CC_OPT in the
top level Makefile or on the command line:

	make all CC_OPT=-O2

then the lower level Makefiles will temporarily use 'CC_OPT=-O2' for
that make run.

=-=-=

MAKE VARIABLES YOU MIGHT WANT TO CHANGE:
---------------------------------------

Normally you do not need to change the common Makefile variables.
Most likely you will not need to change the special Makefile vars.

The common Makefile vars are found in 5 sub-sections:

	1) setup section
	2) How to compile C programs section
	3) where to install section
	4) user and host information section
	5) distribution section

The 'setup' section:

	# setup
	#
	SHELL= /bin/sh
	AWK= awk
	BASENAME= basename
	...

defines the name of any build tools.  Normally the tool is just
the basename (such as 'awk' for the awk command): allowing it
to be found along the $PATH.  When a Makefile rules needs to
use awk, it uses ${AWK}.  Thus if you need to force the use of
a special awk, you can:

	make all AWK="/usr/local/bin/nwak"

The 'How to compile C programs' section:

	# How to compile C programs
	#
	...
	#LAVA_DEBUG=
	LAVA_DEBUG= -DLAVA_DEBUG
	...

controls some of the aspects of C compilation.

The make variable LAVA_DEBUG is added to the C compiler command line.
Defining the LAVA_DEBUG:

	LAVA_DEBUG= -DLAVA_DEBUG

enables certain runtime LavaRnd debugging that is controlled by
the $LAVA_DEBUG environment variable.  See the usage string in the
lib/lava_debug.c source for details.  Compiling with -DLAVA_DEBUG
adds a little to the object size.  However if the environment variable
$LAVA_DEBUG is not set, the run time is not impacted very much.

The DMALLOC_CC and DMALLOC_LIB, if set to -DDMALLOC and -ldmalloc
respectively will allow one to use dmalloc's malloc debugger.

The CC_WARN sets the level of compiler warnings and errors.  By default
any warning is treated as an error and halts compilation.  One might
need to:

	make all CC_WARN=-Wall

to temp disable this 'treat warnings as errors'.

The CC_OPT var controls the optimizer level and the CC_DBG sets
the verbosity of debugger symbols.  If you want to use some
debugger such gdb, you might want to rebuild without optimization
(even though -g3 tries to help it is not always successful against
the -O3 extreme optimization):

	make clobber
	make all CC_OPT=

The 'where to install' section controls where things are installed plus
a few other build aspects.  These values are typically only used during
installation or building distributions.

The Makefile comments in this section go into more detail:

	# where to install
	#
	# DESTBIN       Locally installed program bin directory
	# DESTSBIN      Locally installed program etc directory and daemons
	# DESTLIB       Locally installed local libraries
	...

The 'user and host information' defines the conditions under which
things like the lavapool daemon execute:

	# user and host information
	#
	# LAVARND_VIDEODEV	special device file for the LavaRnd webcam
	# LAVARND_USER          username under which daemons run
	# LAVARND_GROUP         group under which daemons run
	# LAVAPOOL_CHROOT       lavapool chroots under this directory at startup
	...

By default, the user and group used is 'lava'.  While they can be any user
and group, we recommend that you setup a new user and group -- avoiding
any conflicts with existing users and groups.  Don't pick a privileged
user/group that is privileged ... LavaRnd does not need it.

The LAVARND_VIDEODEV should be set to the webcam special device file.
This is usually something such as /dev/video0.

The 'distribution' section controls how the dist rule builds source
tarballs for distribution.  One should not need to change any of
these values.

=-=-=

FOR MORE INFO:
-------------

To learn how to install LavaRnd, read:

	doc/README-install

You can also make individual sub-directories by cd-ing to them
and doing a 'make all'.  See the file:

	doc/README-src

for information on each sub-directory.

For more info on LavaRnd see:

	http://www.LavaRnd.org/index.html

To contact us / send us EMail related to LavaRnd see:

	http://www.LavaRnd.org/about-us/contact-us.html