4. Integration in Tulip project
Prev | Chapter 8. Programming Guidelines | Next

## 4. Integration in Tulip project

The build of Tulip uses a mechanism of the GNU operating system. GNU has several tools used for the management of the configuration files. It modifies the `makefile` to adapt them to the distribution you have and the tools you need : the most important tools are autoconf, automake and libtool. Tulip generates three libraries : `libtulip, libtulip-ogl, libtulip-qt`, a software : `tulip` and a script : `tulip-config`. In a thirdparty, Tulip compiles several external libraries needed by the software : ftgl, gle, gzstream, triangle.

### GNU Build system

#### Presentation

The goals of this system is to simplify the development of portable programs and the building of programs that are distributed as source code.

Autoconf is a tool of GNU producing shell scripts that automtically configure software packages to adapt to many kinds of UNIX systems. It is not the unique tool, it runs with others to solve all problems to making portable software. It generates configurations files : specially the `configure` script from a `configure.in` or `configure.ac` file. Running this script, you produce the customized Makefiles, and other files. It checks for the presence of each feature that the software need. Autoconf requires GNU M4 in order to generate the scripts.

To this end, GNU has developed a set of integrated utilities to finish the job of Autoconf. Automake is the next in run. It is a tool for generating `Makefile.in` from files called `Makefile.am`. Each `Makefile.am` is basically a series of `make` variable definitions, with the GNU Makefile standards. Automake requires Autoconf in order to be used properly.

The last is Libtool. It makes it possible to compile position independent code and build shared libraries in a portable manner. It does not require either Autoconf, or Automake and can be used independently. Automake however supports libtool and operates with it in a seamless manner.

#### A simple example

... to understand the basic mechanism.

To create a `configure` script with autoconf, you need so to write an autoconf input file `configure.ac` (or `configure.in`, use in previous versions of Autoconf). In this example, it is created a `configure.ac` file but Tulip contains `configure.in`. The both files are correct.

    `hello.c`
      #include <stdio.h>
      main(){
         printf("Hello world!\n");
      }

    `Makefile.am`
      bin_PROGRAMS = hello
      hello_SOURCES = hello.c

    `configure.ac`
      AC_INIT(hello, 1.0)
      AC_CONFIG_SRCDIR(hello.c)
      AM_INIT_AUTOMAKE()
      AC_PROG_CC
      AC_OUTPUT(Makefile)

| `bin_PROGRAMS` : specifies the name of programs that are building.
| `hello_SOURCES` : specifies the sources code that composed the program “hello”.
| `AC_INIT` : initializes the `configure` script. It must be passed as argument the name of the package and the version.
| `AC_CONFIG_SRCDIR` : specifies a file in the source directory. `configure` script checks for the existence of this file to make sur that directory that it is told contains the source code in fact does. Any source file could do.
| `AC_INIT_AUTOMAKE` : performs some further initializations that are related to the fact that we are using Automake. If you are writing your `Makefile.in` by hand, then you do not need to call this command.
| `AC_PROG_CC` : checks to see which C compiler you have
| `AC_OUTPUT` : tells the configure script to generate `Makefile` from `Makefile.in`

Create the files and Run :

    $ aclocal
    $ autoconf

The `aclocal` command installs a file called `aclocal.m4'. It contains the knowned Autoconf macros to be in use in `configure.ac`, like `AC_PROG_CC`. If you want to include your macros, you can create an `acinclude.m4` file. An other cache directory is created to store the traces of the runs of `m4`. It is called `autom4te.cache`.

The `autoconf` command create the `configure` script. Then, Run :

    $ automake -a

It displays :

    configure.ac: installing `./install-sh'
    configure.ac: installing `./missing'
    Makefile.am: installing `./INSTALL'
    Makefile.am: required file `./NEWS' not found
    Makefile.am: required file `./README' not found
    Makefile.am: required file `./AUTHORS' not found
    Makefile.am: required file `./ChangeLog' not found
    Makefile.am: installing `./COPYING'
    Makefile.am: installing `./depcomp'

This creates copies of `install-sh`, `missing`, `COPYING`, `depcomp`. These files are required to be present by the GNU coding standards. But `NEWS`, `README`, `AUTHORS`, `ChangeLog` are not generated. You have to create them. If you have not them and you attempt to do `make distcheck`, then it will deliberately fail. To create it :

    $ touch NEWS README AUTHORS ChangeLog

Then, you have to run `automake -a` a second time. This one has created a `Makefile.in` file from `Makefile.am`. In this file, we have specify what are building and the used sources. For a library, you should define the `lib_LIBRARIES` variable.

Now the package is exactly in the state that the end-user will find it when person unpacks it from a source code distribution. To test you program, you can write :

    $ ./configure
    $ make
    $ ./hello

    and ...

    $ make install
    $ make uninstall
    $ make dist
    ...

### File adds

To integrate a new module, set of types, in the Tulip project, you must to know which library is concerned : General library, OpenGL library, QT library, ... For each case, the procedure is the same. `tulip/library/tulip-ogl/` is the directory to integrate a library attached to the Opengl library. All of the `.cpp` files are pasted in the `src` subdirectory, the `.h` files in `include/tulip` and `cxx` files in `include/tulip/cxx`. Some modifications of your code should be necessary. The inclusion of files of Tulip project (included your work) is made with < and > because the compiler knows the path. For Tulip, the header files is in a special directory : `tulip`.

`#include <tulip/TheFile.h>` is an exemple of the inclusion.

So, you have to modify two files in the directory of your library to indicate the new files. `include/Makefile.am` is the first. You have to complete a variable containing all `.h` and `.cxx` files with your header files named `nobase_include_HEADERS`. This name is a choice for the processing of the GNU build system. The second one is `src/Makefile.am` and so, you complete the variable containing all `.cpp` files with your source files : `libtulip_ogl_la_SOURCES`, `libtulip_la_SOURCES` or `libtulip_qt_la_SOURCES` depending of the librairie you complete. You have modified the both `Makefile.am` but the Makefile not. To update it, you have to recreate the `configure` file at the root directory and run it again. To do it, run `./gen-conf` and `./configure`. To avoid this procedure at each modification of the `Makefile.am`, you can specify an option when you use `configure` script : `--enable-maintainer-mode`. See Section 1, “Options”, for more details about the options. Now, the next compilation includes your work.

### Compilation directives : Makefile.am

If you want to change the directive of compilation for a program or a library, then you have to complete or modify the variables attached to the program or library. This section gives the essential variables (with their forms) for a customized compilation.

`Makefile.am` can use the same syntax as with ordinary makefiles. General variable can be defined, available for all your building objects.

`INCLUDES = -I/dir1 -I/dir2 -I$(top_srcdir)/src...`

  Insert the -I flags that you want to pass to your compiler when it builds executables.

`LDFLAGS = -L/dir1 -L/dir2 ...`

  Lists all the library files that will be compiled with make and installed with `make install` under `prefix/lib`.

`LDADD = MyClasse.o ... $(top_builddir)/dir1/libmylib.la ... -lmylib ...`

  List a set of object files, uninstalled libraries and installed libraries that you want to link in with all of your executables. Please refer to uninstalled libraries with absolute pathnames. Because uninstalled libraries are built files, you should start your path with `$(top_builddir)`.

  There is a set of variables like `top_builddir` which are defined by `configure` when it processes a `Makefile` and they can be used in all others variables presented here.

  `srcdir`

    The relative path to the directory that contains the source code for that `Makefile`.

  `abs_srcdir`

    Absolute path of `srcdir`.

  `top_srcdir`

    The relative path to the top-level of the current build tree. In the top-level directory, this is the same as `srcdir`.

  `abs_top_srcdir`

    Absolute path of `top_srcdir`.

  `builddir`

    Rigorously equal to “./”. Added for the symmetry only.

  `abs_builddir`

    Absolute path of `builddir`.

  `top_builddir`

    The relative path to the top-level of the current build tree. In the top-level directory, this is the same as `builddir`.

  `abs_top_builddir`

    Absolute path of `top_builddir`.

The following targets are used for a special directory or for special buildings:

`bin_PROGRAMS = prog1 prog2 ...`

  Lists the executable files that will be compiled with `make` and installed with `make install` under `prefix/bin`, where `prefix` is usually `/usr/local` but you can specify to an other value.

`lib_LIBRARIES = lib1.la lib2.la ...`

  Lists all the library files that will be compiled with make and installed with `make install` under `prefix/lib`.

`SUBDIRS = dir1 dir2 ...`

  Lists all the subdirectories that we want to build before building this directory. `make` will recursively invoke itself in each subdirectory before doing anything on the current directory. If you mention the current directory “.” in `SUBDIRS` then the current directory will be built first, and the subdirectories will be build afterwards.

`EXTRA_DIST = file1 file2 ...`

  Lists any files that you want to include into your source code distribution.

`include_HEADERS = fich1.h fich2.h ...`

  Lists all the public header files in this directory that you want to install to `prefix/include`. If you change the keyword `include` by `noinst`, then you can specify headers that will not be installed.

For each progam, a set of variables should be declared :

`prog_SOURCES = fich1.c fich2.c ...`

  Lists all the files that compose the source code of the program. Header files can be specified here.

`prog_LDADD = $(top_builddir)/dir1/lib1.a -lext1 -lext2 ...`

  Lists the libraries that need to be linked with your source code. Installed libraries should be mentioned using '-l' flags. Uninstalled libraries must be mentioned using absolute pathnames. Please use `$(top_buiddir)` to build a path to a directory.

`prog_LDFLAGS = -L/dir1 -L/dir2 -L/dir3 ...`

  Adds the '-L' flags that are needed to find the installed libraries that you want to link in `prog_LDADD`.

`prog_DEPENDENCIES = dep1 dep2 dep3 ...`

  Lists any targets that you want to build before building this program.

In the same way, you can specify variable for a specialy library or shared library by prefixing the variable by the name of the library.

Occasionally it is useful to know which Makefile variables that Automake uses for compilations. For instance you might need to do your own compilation in some special cases. Some variables are inherited from Autoconf; these are CC, CFLAGS, CPPFLAGS, DEFS, LDFLAGS, LIBS, CXX, CXXFLAGS, ... There are some additional variables which Automake defines itself:

`AM_CPPFLAGS`

  The contents of this variable are passed to every compilation which invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance, `-I` and `-D` options should be listed here. Automake already provides some `-I` options automatically. `AM_CPPFLAGS` is ignored in preference to a per-executable (or per-library) `_CPPFLAGS` variable if it is defined.

`INCLUDES`

  This does the same job as `AM_CPPFLAGS`. It is an older name for the same functionality. This variable is deprecated; we suggest using `AM_CPPFLAGS` instead.

`AM_CFLAGS`

  This is the variable which the Makefile.am author can use to pass in additional C compiler flags. It is more fully documented elsewhere. In some situations, this is not used, in preference to the per-executable (or per-library) `_CFLAGS`.

`COMPILE`

  This is the command used to actually compile a C source file. The filename is appended to form the complete command line.

`AM_LDFLAGS`

  This is the variable which the Makefile.am author can use to pass in additional linker flags. In some situations, this is not used, in preference to the per-executable (or per-library) `_LDFLAGS`.

`LINK`

  This is the command used to actually link a C program. It already includes -o $@ and the usual variable references (for instance, `CFLAGS`); it takes as “arguments” the names of the object files and libraries to link in.

### Variable prefix

`nobase_`

  e.g. `nobase_include_HEADERS`, mentionned that all the headers files will not be installed in the same place. It is possible to make subdirectories. `nobase_` should be specified first when used in conjunction with either `dist_` or `nodist_`.

`noinst_`

  denotes data which do not need to be installed.

`dist_ /nodist_`

  denotes files or data that will be included to the distribution (or not with `nodist_`).

### References

Developing software with GNU : the GNU build system - http://www.amath.washington.edu/~lf/tutorials/autoconf/toolsmanual.html#SEC30

Autoconf Manual - http://www.gnu.org/software/autoconf/manual/

Automake Manual - http://www.gnu.org/software/automake/manual/

Prev | Up | Next
3. Code Comments | Home | Chapter 9. Documentation Guidelines