DWARF Build Tutorial
This tutorial will get you some binary code that will make you happy.
This is just a general graphical explanation of the whole process:
For this tutorial, you should
- know how to install DWARF on your system (see DwarfInstallTutorial),
- know the difference betweeen compiling and linking (see your favorite computer science undergrad class)
- be able to install a bunch of 3rd party software and remember where it got installed (package managers such as rpm or dselect might help)
Lesson 1: Build DWARF out of the box
In this lesson, you will learn how to obtain and compile the current DWARF source files.
Getting and Understanding the Code and Directory Structure
Let us first get all the DWARF source code and get familiar with its structure.
Start with a checkout of the public DWARF repository, as described here
. You will now have quite a few files and directories on your computer. For now, the following are important:
- a script setting up some missing files for the build process
- the directory containing the whole public DWARF source tree
- the directory containing application-specific data
- an empty directory perfectly suited for the DWARF build tree. This is set up for convenience only, you may build DWARF in whatever directory you like.
Set up GNU Autotools
The DWARF build process is based on GNU Autotools
, a set of helper programs allowing us to write portable software.
If you scan through the
directories, you will notice that most subdirectories contain a file called
. These files contain highlevel descriptions of how binaries are created out of source files. To transform them in working Makefiles, we first have to create files called
, essentially forms for Makefiles that have to be filled out depending on your local setup. In addition, we have to create some scripts that handle library generation depending on your operating system.
Go to the directory where you checked out DWARF (we will refer to this as
) and type
If automake, autoconf and libtool are installed properly on your system, you will get something like the following output:
*** Welcome to the DWARF build system.
*** (c) Technische Universitaet Muenchen 2001 - 2005
*** We will now create the necessary template Makefiles and
*** scripts that check your computer environment.
*** Please wait [6 + will appear]
*** + + + + + + Done.
*** Now go to the directory
*** and enter "../configure --help"
*** To see a list of available options and finally
*** enter "../configure <youroptions>" to set up the
*** build environment. All output gets stored in the
*** file <config.log>, check this first if something seems
*** not to work or compile.
*** Finally, enter "make" and "make install" to get
*** the applications going.
Usually, you can safely ignore all hints and warnings that may come up.
If you now scan through the
trees, you should have a
. In addition, the bootstrap script generated a script
. Do not try to understand this script, unless you are interested in winning obfuscated shell script awards.
What does the bootstrap script do? (For people interested in unnecessary details :-)
* A libtool library (suffix .la) is generated and can be used as static library.
* M4 Macros are collected in file aclocal.m4. These macros check, if specific libs, ... are installed.
* The configuration header is created (depending on the platform) to be added to source files
* create the Makefile.in's out of the Makefile.am's
* create the configure script out of configure.ac
* declare all IDL files as new, so that these get compiled
Get familiar with configure
script's purpose is twofold:
- Analyze the host system. Check for necessary header files, libraries and programs and adjust what gets built accordingly. In addition, incorporate options given by the user building the stuff.
- Create a build tree, consisting of specifically tailored Makefiles that allow an almost arbitrary separation of source, build and installation tree.
The script always
generates a build tree rooted in the current directory. As such, you may set up two distinct build trees based on the same source tree, having e.g. separate compile options. In contrast, the install tree may be given on the command line, using the command
Try it out:
You should see hundreds of lines of debug output.
starts with checking basic compiler features, goes on with checking libraries relevant to DWARF, such as OmniORB, Qt and AR Toolkit and finally generates a script
that is immediately executed. This script does the actual work and generates the buildtree with all Makefiles in it. Really verbose debugging information is put in the file
. This file usually may give you hints on what went wrong if
does not work as intended.
The configure script takes a lot of command line parameters. Call
to get a list of all parameters.
Compile the code
Now everything is set up, compilation is easy:
You now have the choice: watch fascinating compilation output for at least an hour or go get a beer. We recommend the latter.
If compile crashes for example while building CorbaInit?
.java or the Viewer just try it again up to 4 times. This problem will often disappear.
If all goes well, you now have quite a few libaries and binaries, all still residing in your buildtree. If you actually watch one of these with an editor of your choice, you will realize that they are shell scripts. These get generated by libtool
, hiding all ugly library details from the user and allowing you to let most programs run directly from the build tree. However, this is not supported from the DWARF team, so you still have to install everything.
Install the binaries
Similar to compilation,
does the job:
After some minutes, you should now have a working DWARF installation on your system. You may go on with the DwarfMiddlewareTutorial
and go on with the other Lessons from this tutorial if you want to add your own DWARF services to the build environment.
Lesson 2: Fine-tuning configure
to get a list of all parameters.
../configure --prefix=<your install DIR>
to indicate where to install the binaries
* Use the
parameter to indicate which application dependend services should be included in the build tree
* Use the
parameter to indicate where extra software is installed
Lesson 3: Adding your own service
* Create your own directory within the src/services directory and write your service code.
* Write the
file. Do not hesitate to consult other =Makefile.am=s from other services.
* Add service to the
file. Use the AC_CONFIG_FILES to indicate that Makefiles are generated and use the SRC_SERVICES_SD flag to add the service to be compiled in the build tree. Or the other flags starting with SRC_SERVICES_ to indicate compilation for specific applications
again to get the
to get your
When you made changes to a
file where a
already exists, you do NOT have to walk through the whole build process again. Just call
determines, if changes to its corresponding
have been made and reconfigures itself!
Lesson 4: Adding your own 3rd party software
When you are going to use third party software, you must include some checks in the DWARF system to validate, that no code is going to get compiled, when your software is not installed. This may happen often, because various people are going to use DWARF on their computers.
Each check is separated to a separate file. These check-files reside in the
directory. A good example to look in is
After writing your check, you must include it in the
file at that position, where you like your service to get added to the build tree.
- 30 Jun 2003
- 27 Jul 2004