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:

Prerequisites

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:

bootstrap

a script setting up some missing files for the build process

src

the directory containing the whole public DWARF source tree

applications

the directory containing application-specific data

build

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 src and applications directories, you will notice that most subdirectories contain a file called Makefile.am. 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 Makefile.in, 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 <srcdir>) and type

./bootstrap

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 src and applicationa trees, you should have a Makefile.in for every Makefile.am. In addition, the bootstrap script generated a script <srcdir>/configure. 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

The configure script's purpose is twofold:

1. 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.
2. 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 --prefix=<instdir>

Try it out:

cd <srcdir>/build
<srcdir>/configure --prefix=$HOME/dwarfinstall

You should see hundreds of lines of debug output. configure 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 config.status 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 <builddir>/config.log. This file usually may give you hints on what went wrong if configure does not work as intended.

The configure script takes a lot of command line parameters. Call configure --help to get a list of all parameters.

Compile the code

Now everything is set up, compilation is easy:

cd <buildir>
make all

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, make does the job:

cd <buildir>
make install

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

* Call ../configure --help to get a list of all parameters. * Use ../configure --prefix=<your install DIR> to indicate where to install the binaries
* Use the --enable-<DWARF-application> parameter to indicate which application dependend services should be included in the build tree
* Use the --with-<DWARF-relevant-3rd-party-software> 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 Makefile.am file. Do not hesitate to consult other =Makefile.am=s from other services.
* Add service to the configure.ac 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
* Execute ./bootstrap again to get the Makefile.in created. * Run configure to get your Makefile.

NOTE: When you made changes to a Makefile.am file where a Makefile already exists, you do NOT have to walk through the whole build process again. Just call make. The Makefile determines, if changes to its corresponding Makefile.am 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 <srcdir>/dwarf/config directory. A good example to look in is dwarf_have_isense.m4.

After writing your check, you must include it in the <srcdir>/dwarf/configure.ac file at that position, where you like your service to get added to the build tree.

-- MartinWagner - 30 Jun 2003
-- MarcusToennis - 27 Jul 2004