Better Repository old

From Wiki for iCub and Friends
Revision as of 19:06, 13 March 2010 by Lorenzo (talk | contribs)
Jump to navigation Jump to search

Author: Lorenzo Natale

For historical reasons the iCub repository and the build system have been designed in a way that make it quite difficult to provide the functionalities of a mature package.

In parallel cmake has evolved quite a lot since version 2.4 and offers much more robust and useful features than the ones we relayed upon when we started the project.

The philosophy

We still would like to keep at the minimum the amount of work required to maintain the repository. Users should be allowed to add new modules to the main build without much effort. However we also would like to give the possibility to use the software from other packages or libraries, in particular we would like this to be possible in two configurations:

  • out-of-source or in-source builds
  • from installation

We do a first distinction between modules that are "visible" only within the iCub repository and modules that are "exported", or in other words, can be used externally with respect to the big iCub build. Another distinction can be made between executables and libraries. Executables are easy to export: they do not provide header files or other resources. It is enough to put them in the system path. This can be done at install time, or by appending the binary directory where executables are built to the system path (something like ICUB_DIR/bin). Libraries are a bit more complicated because they define symbols, have header files and dependencies.

It is also important to stress that the iCub build is not just a normal package with a set of libraries and executables. We like to see the build more like a federation of modules, made of executables and libraries. This is how external packages view the iCub software.

Executables

Adding an executable to the build is simple, it does not take more than a few lines of cmake code:

 PROJECT(mymodule)
 ADD_EXECUTABLE(mymodule)

To cope with intallation this is enough:

 INSTALL()

Libraries

You should be aware that a library has a public and a private interface. The public interface is a set of header files that users of the library will be offered to include; the private interface is a set of header files that are included only by code inside the library. This distinction is important. Header files that are the public interface of the library should be clean; they should define only the minimum set of symbols required by the user, and avoid polluting the main scope with unnecessary symbols (ideally all symbols should be hidden in a separate namespace, but for now let's not be too picky about this). Private header files are only required when you compile the library and, in principle, could be destroyed afterwards (ok don't do that).

It is a good idea to maintain the distinction between public and private interface at the file system level (public header files in one directory, private header files in another one).

This is because at install time only public header files are copied to the target destination (maybe with the exception of inline files/templates which should also be visible).

Files structure

Everyone is free to organize files in any way they like, clearly there is not a single solution that works.

How you organize header files is the combined result of how you include them in your code and how you configure the compiler.

The only restriction in this case is that public files are shared between external code and the code of the library, so, whatever you do, make sure you include them in the same way. This is the point where you need to be careful and follow normal practices.

When external users include a public file of a library they expect to do it like:

 #include <library-name/header-file.h>

For many reasons this is preferable than just:

 #include <header-file.h>

In our case this becomes:

 #include <iCub/header-file.h>

Even better, in case you define a namespace:

 #include <iCub/namespace/header-file.h>

Usually you instruct your compiler to know where to start looking for header files, so you do not have to wonder how the compiler will be able to fine the iCub directory. However, this means that the local directory structure of the files in your library should match the one above.

In short, all public header files should be placed in a directory called iCub. Since you want to be clean, this is also inside a directory called include (to keep it separate from the src directory where you put source files).

If you define a namespace, make a new directory there (in include/iCub).

Now private header files can go in a separate directory of your choice, e.g. include/private and included as:

#include "include/private/local.h"

We really do not care because it will be your job, as a maintainer of the library, to make sure everything compiles.

Using a library