Programming Guidelines

Generalities
The presentation of a program indicates the quality of programming. This section relates to the common recommendations for the Tulip project. Each new programmer has to follow the expressed rules.
In the header files, the programmer should write a headline containing : his name with personal email adress (for students), the date of the last modifications, a reminder of the licence GPL[1] and the references of the code (for example, an algorithm). Header files must include a construction that prevents multiple inclusions. The convention is an all uppercase construction of the file name, the h suffix and prefixed by Tulip, separated by an underscore.
[1] General Public License

#ifndef Tulip_MYTYPE_H
#define Tulip_MYTYPE_H

...

#endif // Tulip_MYTYPE_H

The organisation of files must be comprehensible. New module leads to a new set of files : a *.cpp and a *.h named with the name of the type. If the structure implicates that all methods are inline, the creation of a .cxx file is better than a .cpp file. The cxx should be included at the bottom of the header file. None implementation is in the header file. In the Tulip hiearchy, the cxx files are in a directory cxx in the header location.
The indentation is an important part for a easy reading in a file and a best understanding. Code must be properly indented to show the syntactic structure of the program. It is useless to space out excessively the code. A conventional indentation is just necessary. None useless TAB or spaces. The { caracter for the opening of a method or a function must be at the end of the line, not in following line. Each new fitted block of program implies a new shift for the indentation.
Each new module inserted in the Tulip library must be included in the namespace tlp. It is necessary in order to prevent eventually incompatibilities.

namespace tlp{

/* code inserted */

}

Tulip is dependent of the STL[2]. It provides a set of performing objects that you should use : vector, map, string, ... It exists two ways to use it. In the .h or .cxx files, you should preface them with the std namespace (e.g. std::string s;). You will refer them with the fullname : namespace and class name. For the .cpp files, you can use the short name if you insert the line at the top of your document using namespace std;.
[2] Standard Template Library
In a header file (.h or .cxx) :

class MyClasse{
  public:
    Myclasse();
    ~MyClasse(){}
    void draw();

  private:
    std::string mystring;
};

In a source file (.cpp) :

using namespace std;

MyClasse::MyClasse(){
    mystring = "Hello world";
}
void MyClasse::draw(){
    cout<<mystring<<endl;
}

Naming conventions
Programmer of Tulip has to follow some rules for choosing Type, Functions, or Variables names. Each names must be in English and choose to an easy understanding, descriptive and accurate. Each important word must be found in the name.

List of Rules
Types (struct, class, ...) : Names must be in mixed case starting with upper case. Each word should have first letter in upper case. Don't use underscore to separate words. (e.g. SortedVector, OrientedList, RedBird, ...)
Functions and Methods : Names must be in mixed case like for Types, but starting with lowercase. After the first one, each important word has first letter in upper case. Don't use underscore to separate words. (e.g drawString(), computeFormulas(), ...)
Variables : Names must be in lower case. (e.g. instances, nodes, tableofcontents, ...)
Constants : Names must be in upper case. (e.g. MAXSIZE, BLACKCOLOR, ... )
Macro and Enumeration constants : Names must be defined in upper case with an underscore between words. (e.g. LAYOUTPLUGIN(C, N, A, D, I, V, R), ...)
Namespaces : Names must be in lower case. (e.g. tlp)
The setter and getter must begin with the keyword set or get. All of the methods or functions should begin with a verb for understanding its goal. The prefix of a boolean variables or methods should be is, can, has, should : bool isValid(const edge e) const, function specified if the edge is valid.

Code Comments
All of the comments in the source and the header files must be written in the English language. Adding a lot of comments is a simple way to leave a clear code for the next programmer who will receive your work. A part of comments must be written with several rules to help the documentation of your work generating automatically with Doxygen. Choose a part of your comments to describe your work. See . It is important that a programmer can understand the using of your work and how to use your work.
Before a declaration of a class, you should write a little description to explain it. The role, the pre-requisites, the post-requisites, the return values and the parameters should be written before the declaration of the function or method. It is the minimum for an easy comprehension of your work. In the code, it is useless to comment each line because the comments are often a paraphrase of the code. It just is essential to write a comment for strong parts that you have thought.

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 , 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 -
Autoconf Manual -
Automake Manual -