==============================================================================
____ _____ _____ _ _
| _ \ | __ \ | __ \ (_) |
| |_) || |__) | | |__) |___ _ __ ___ ___ _| |_ ___ _ __ _ _
| _ < | _ / | _ // _ \ '_ \ / _ \/ __| | __/ _ \| '__| | | |
| |_) || | \ \ _ | | \ \ __/ |_) | (_) \__ \ | || (_) | | | |_| |
|____(_)_| \_(_) |_| \_\___| .__/ \___/|___/_|\__\___/|_| \__, |
| | __/ |
|_| |___/
==============================================================================
DEVELOPER'S GUIDE
==============================================================================
TABLE OF CONTENTS
-----------------
I. QUICK START
II. REPOSITORY STRUCTURE
III. FREQUENTLY NEEDED CVS TASKS
IV. SUPPORTED MAKE TARGETS
V. MODULES.XML HOWTO
VI. PMAKEFILE HOWTO
VII. LIST OF PRE-DEFINED COMPILER FLAGS
VIII. LIST OF PRE-DEFINED MAKE VARIABLES
IX. DOCUMENTATION HOWTO: DOXYGEN QUICKSTART
==============================================================================
I. QUICK START
--------------
You may access the CVS using :pserver: authentication or SSH, the latter
is possible for `rhino' members only.
1. Check out the control files for the B.R. repository.
If you are member of the `rhino' group, set the CVS_RSH environment
variable to `ssh', either with
| $ export CVS_RSH=ssh
or with
| $ setenv CVS_RSH ssh
depending on your command shell. Then enter
| $ cvs -d rhino:/home/rhino/repositorys/br checkout br
If you are not member of the `rhino' group, you need the password for the
`prak' account. Enter
| $ cvs -d :pserver:prak@rhino:/home/rhino/repositorys/br login
| $ cvs checkout br
2. Configure the build system:
| $ cd br
| $ ./bootstrap.sh
| $ ./configure
3. Select the modules you are going to work with:
| $ ./select-modules
If you are not sure which modules to enable, select `simple'.
4. Compile the software:
| $ make
5. If you just want to use the software and do not plan to develop, you
may optionally clean the source tree after building to save on disk space:
| $ make clean
==============================================================================
II. REPOSITORY STRUCTURE
------------------------
BR
\-+-- autom4te.cache this directory is created by the autoconf package
|-- bin B.R. executables
|-- build perl scripts for the build system
|-- doc documentation
\---- html HTML output generated by Doxygen
|-- etc configuration files
|-- include header files of B.R. libraries
|-- lib B.R. libraries
|-- skel skeleton files for new modules
+-- src source files for B.R. modules
Important files:
acinclude.m4 M4 macros for build system
bootstrap.sh shell script to initialize the build system
configure shell script to configure the build system
configure.ac M4 script for build system
modules.build a list of enabled B.R. modules. The order of the
modules matters.
modules.xml XML declaration for all available modules
Makefile.in template for global B.R. Makefile
select-modules perl script to (de-)select B.R. modules
build/modules perl script to process the modules.xml
build/pmake perl script to create Makefiles from PMakefiles
build/create-module shell script to create module source dir stub
build/checkin-module shell script to import module into CVS
src/config.h.in template for compiler flags header
src/Make.config.in template for Makefile variables
==============================================================================
III. FREQUENTLY NEEDED CVS TASKS
--------------------------------
All command sequences assume that your current working directory is the
top directory of your repository working copy, e.g. $HOME/br
1. Update from CVS
This command may be issued in any sub directory, too.
| $ cvs update -d
2. Manually check out the B.R. module "example"
| $ cvs checkout example
However, you should use the ./selectmodules.sh script to enable
additional modules.
3. Commit changes to repository (write-access required)
This command may be issued in any sub directory, too.
| $ cvs commit
4. Add newsource.c to module "example" (example has to be in CVS,
CVS write-access required)
| $ cd src/example
| $ cvs add newsource.c
| $ cvs commit
5. Create a new module "example" with the program test1 and the library test2
| $ ./build/create-module example P test1 L test2
6. Add newly created module "example" to the CVS (CVS write-access required)
| $ ./build/checkin-module example
==============================================================================
IV. SUPPORTED MAKE TARGETS
--------------------------
The following targets are provided automatically if you use the PMakefile
system. Otherwise, you should ensure that your Makefiles behave according
to this specification.
build (default target) a combination of compile and install
clean remove dependency lists and object files from
source tree
compile compile all programs and libraries, but do not
install
doc create documentation
dist create .tar.gz archive
distclean like clean, but additionally remove created
binaries from source tree
install install modules to the bin/, lib/
etc/, and include/ directories
relink relink libraries and executables even if up to
date. Use this if you want a program to use
the new version of a static library.
mostlyclean remove object files, but keep dependency lists
uninstall remove installed modules from bin/, lib/,
etc/, and include/ directories
==============================================================================
V. MODULES.XML HOWTO
--------------------
The file modules.xml contains some XML declarations about the available
B.R. modules. Its primary purpose is the mapping of inter-module
dependencies. The following tags are recognized:
Tag: br
Attributes: -
Valid children: module
Description:
is the root node of the modules.xml file.
Tag: module
Attributes: name -- Name of the module, i.e. the name of the src/ sub
directory that hosts the module.
Valid children: depend, define, subst
Description: Every node corresponds with a B.R. module
Tag: depend
Attributes: -
Valid children: -
Description: The node contains the name of another B.R. module
that is required in order to build the particular module.
You may specify as many tags as needed.
Tag: define
Attributes: -
Valid children: -
Description: The node contains the name of a C(++) compiler
macro that should be defined if the module is built. A
corresponding #define line is added to src/config.h by the
./configure script
Tag: subst
Attributes: name -- Name of the Makefile substitution tag @...@
Valid children: -
Description: The node allows to specify substitutions in the
Makefile.in and src/Make.config.in templates. Each @...@ tag
is replaced by the contents of this node.
WARNING: For this to work, you have to add the tag name
to the AC_SUBST list in configure.ac, and run ./bootstrap.sh
afterwards.
==============================================================================
VI. PMAKEFILE HOWTO
-------------------
The PMakefile is a stripped-down version of the GNU automake "language".
In principal, it is just a collection of assignments to special variables.
The most important variables are PROGRAMS and LIBRARIES, which contain
the names of the programs and libraries that are to be built.
Most other variables can be specified either globally to affect all
programs and libraries, or locally by prepending the name of a program
or library and an underscore (e.g. SOURCES vs. example_SOURCES, assuming
there is a program or a library named example) A local definition overrides
any global definition completely.
Available variables:
ADD add another source file declaration to own source list.
Example:
common_SOURCES = common1.c common2.c common3.c
prog1_SOURCES = prog1only.c
prog1_ADD = common
prog2_SOURCES = prog2only.c
prog2_ADD = common
BINDIR location to install programs to. Default is
$(PREFIX)/bin
CONFIG_H location of the config.h header. Global only.
CFLAGS C compiler flags
CPPFLAGS C/C++ preprocessor flags
CXXFLAGS C++ compiler flags
DEPENDS list of other programs/libraries that have to be built
first. Local only. Example:
libdummy_SOURCES = libfile.c
...
dummytest_SOURCES = dummy.c
dummytest_DEPENDS = libdummy
DOXYFILE Name of the Doxyfile configuration for doxygen. Defaults
to `Doxyfile'.
ETCDIR location to install configuration files to. Default is
$(PREFIX)/etc
EXTRADIST a list of non-source files that shall be added to a
distribution archive of the module.
EXTRAINST_BIN,
EXTRAINST_LIB,
EXTRAINST_INC,
EXTRAINST_ETC a list of files that are to be installed to $(BINDIR),
$(LIBDIR), $(INCDIR), and $(ETCDIR). Note that programs and
libraries do not need to be specified here.
HEADERS public header files for libraries
HEADERSUBDIR install public library headers to $(INCDIR)/$(HEADERSUBDIR)
instead of $(INCDIR)
INCDIR location to install library headers to. Default is
$(PREFIX)/include
LANGUAGE used compiler language. Currently supported: C and C++
LDFLAGS C/C++ linker flags
LIBDIR location to install libraries to. Default is
$(PREFIX)/lib
LIBMAJOR major version number for shared library
LIBMINOR minor version number for shared library
LIBRARIES list of libraries that are to be built
LIBREV revision version number for shared library
LIBTYPE select type of libraries to be built. Valid values:
"static", "shared" or "static shared" for both.
MAKE_CONFIG location of the Make.config file. Global only.
MANDIR location to install manual files to. Default is
$(PREFIX)/man
NOINST_LIBRARIES list of libraries that are to be built, but not
installed
NOINST_PROGRAMS list of programs that are to be built, but not
installed. Useful for small test programs.
PICFLAG Compiler flag needed for shared objects. Default is -fPIC
PREFIX location of the B.R. source tree. Global only.
PROGRAMS list of programs that are to be built
QOBJECTS list of header files that contain QOBJECT-enabled Qt
objects. These objects need extra code created by Qt moc,
resulting in an additional .moc.cc source file.
SONAME override shared library name. Not recommended.
UI add Qt user interface to program, as created with the
Qt Designer. Example:
example_UI = mygui.ui
(creates mygui.uic.cc, mygui.moc.cc, and mygui.hh from
mygui.ui)
==============================================================================
VII. LIST OF PRE-DEFINED COMPILER FLAGS
---------------------------------------
The following flags may be used to allow optional support for several
libraries using #ifdef ... #endif statements. These flags are defined
in src/config.h, which you should include if you want to use them.
NOTE: You may want to take a look at $(CONFIG_CPPFLAGS) in the following
section.
HAVE_LIBZ defined if zlib support is available
HAVE_CV defined if OpenCV is available
HAVE_QT defined if Qt is available
HAVE_SDL defined if SDL is available
==============================================================================
VIII. LIST OF PRE-DEFINED MAKE VARIABLES
----------------------------------------
The B.R. build system defines a bunch of make variables you may find useful
for your modules. If you write your own Makefiles, include src/Make.config
to gain access to these variables
$(CONFIG_CPPFLAGS) C(++) preprocessor flags to include src/config.h
$(WARN_CFLAGS) C compiler flags to enable ludicrous pedantic warnings
$(BR_BASEDIR) absolute path of the B.R. top-level directory
$(BR_BINDIR) absolute path of the B.R. binaries directory
$(BR_DOCDIR) absolute path of the B.R. documentation directory
$(BR_ETCDIR) absolute path of the B.R. configuration directory
$(BR_INCDIR) absolute path of the B.R. library headers directory
$(BR_LIBDIR) absolute path of the B.R. libraries directory
$(CXX) C++ compiler executable
$(CC) C compiler executable
$(OPTFLAGS) optimized compiler flags tailored to your current system
WARNING: If you switch machines, re-run ./configure!
$(QT_CPPFLAGS) C++ preprocessor flags needed for Qt or empty string
if Qt is not available (see HAVE_QT in previous section)
$(QT_LDFLAGS) C++ linker flags needed for Qt or empty string
$(QT_MOC) Qt moc executable or empty string
$(QT_UIC) Qt User Interface Compiler executable or empty string
$(SDL_CPPFLAGS) C(++) preprocessor flags needed for SDL or empty string
(see HAVE_SDL in previous section)
$(SDL_LDFLAGS) C(++) linker flags needed for SDL or empty string
$(CV_CPPFLAGS) C(++) preprocessor flags needed for OpenCV or empty string
$(CV_LDFLAGS) C(++) linker flags needed for OpenCV or empty string
$(LIBZ_LDFLAGS) C(++) linker flags for libz or empty string
$(TCX_CPPFLAGS) C(++) preprocessor flags needed for TCX
$(TCX_LDFLAGS) C(++) linker flags needed for TCX
$(BRCFG_CPPFLAGS)
$(BRCFG_LDFLAGS)
$(BRUTILS_CPPFLAGS)
$(BRUTILS_LDFLAGS) as expected
$(LINUXDIR) path to linux kernel sources, if you wish to build kernel
modules, or empty string if no sources available
$(LINUXVERSION) version number of linux kernel sources
==============================================================================
IX. DOCUMENTATION HOWTO: DOXYGEN QUICKSTART
---------------------------------------------
Doxygen documentation is inlined into the source code. Call
| $ make doc
in the B.R. top directory to actually create/update the documentation.
Open the doc/html/index.html file in your browser to view it.
A very brief tutorial on how to document your sources properly is
included with the documentation.
Further information about Doxygen can be found on its home page
http://www.stack.nl/~dimitri/doxygen/
==============================================================================
$Id: README,v 1.18 2006/08/22 14:27:59 roehling Exp $