Hacking in PadicoTM

This guide targets people tracking PadicoTM from the GIT repository and/or willing to code inside PadicoTM. It is not intended to be used by a regular end-user.

For any question regarding coding in PadicoTM: Alexandre.Denis@labri.fr

Tracking PadicoTM and PM2 from GIT

• PadicoTM has been merged into the PM2 repository. To checkout PM2, including PadicoTM:

  % git clone git@gitlab.inria.fr:pm2/pm2.git

• PadicoTM has some files auto-generated through autoconf & autoheader. To automatically generate them, in each directory where it is present:

  % ./autogen.sh

• If the default autoconf or autoheader are the wrong version, they may be overriden through the $AUTOCONF and $AUTOHEADER environment variables. Typically, on some old Debian systems where both autoconf 2 .13 and 2.50+ are installed (and the former is the default), use the following:

  % setenv AUTOCONF   autoconf2.50
  % setenv AUTOHEADER autoheader2.50 

Building PadicoTM

• PadicoTM and PM2 are split into several packages. Each package is configured through autoconf, built, and installed. A package needs to be fully installed before another package using it can be built. PadicoTM packages are:

  • Puk – the PadicoTM micro-kernel
  • PukABI – ABI manager
  • PadicoTM – the PadicoTM runtime system

  Other packages are available, not using the PM2 infrastructure:

  • myCORBA – multi-ORB manager
  • PadicoControl/GControl – GUI to steer PadicoTM processes
  • PadicoControl/NSConfig – NetSelector configurator
  • PadicoControl/PadicoRun – command-line steering tools
• For a full compilation, it is recommended to use the build script located in pm2/scripts/pm2-build-packages using a given or a custom configuration file, e.g.:

  % cd pm2/scripts
  % ./pm2-build-packages ./example-nmad+pioman+pthread.conf --prefix=$HOME/soft/x86_64

  Note: PM2 source directory is guessed from current directory when calling the script. Please call the script from pm2/scripts/ directory.
• Parallel build is supported, e.g.:

  % make -j 8 install

• If things go really wrong when reinstalling, delete all the install directory and try to build again.

Coding rules for PadicoTM

Good practices

• 'static': the load performance of dynamic objects depends on the number of exported symbols. PadicoTM being exclusively dynamic, it is strongly advised to reduce the number of global symbols. As a rule:
  • every symbol not required to be global must be declared static.
  • if not possible (symbol shared across multiple files of a module), it should be hidden through the '__PUK_SYM_INTERNAL' prefix or (better) the module should have a mapfile.
  • for every module <m> in PadicoTM, if file <m>.map.in exists, it is automatically taken as a mapfile for the module.
• const: for better type-correctness and optimization, everything that may be declared const must be declared const, especially pointers used as arguments to function with read-only access. Read carrefully your favorite C book to understand the difference between a const pointer and a pointer to const.
• use global variables sparingly. When a module needs global state, group them in a struct (to have only one global variable so as to make it clear that the particular variable is global) and make it static. Global non-static variables must be banished in dynamic objetcs.
• use assert(), use valgrind. Even basic things may fail in unexepcted ways.

Coding style

• Most of these rules are arbitrary. They aim at avoiding the patchwork effect of multiple codings styles and indentation juxtaposed in the same project or even the same file, which render code unreadable and impossible maintain.

• the indentation follows the C99 style.

  • indentation is 2 spaces
  • curly brackets are at the beginning of lines
  • add one spaces around affectation and comparison symbols; one space after colon and semicolon; no space before brackets.

  . Example:

  for(i = 0; i < n; i++)
  {
    a[i] = i;
  }

  • use C-style comments /* */, not C++-style comments //
• documentation is generated with doxygen.
  • use doxygen javadoc style, i.e. doxygen processes comments beginning with /** */, and commands begin with @
  • always include a @file in every file to make doxygen process it.
  • to track authorship, include a @author command in every file
• Don't cast the return value of calls to malloc, It has type void*, so it will be compatible with anything. K&R, p. 142 gives contrary advice, but it has since been retracted by Dennis Ritchie.

Naming things

• public symbols begin with "padico_<module>_" if module name is <module>. Private symbols begin with "<module>_".
• C symbols are lower case with underscores
• module names and include files use CamelCase. Note: this rule only applies in PadicoTM & Puk. NewMadeleine and Pioman do not use CamelCase at all.

Don't reinvent the wheel

PadicoTM already has a build system, an XML parser, a component model, loadable modules, basic types, container types, lots of communication methods. Don't reinvent anything that is already present.

• if you can use a feature of PadicoTM instead of adding a dependancy, use it.
• if the needed feature is almost present in PadicoTM, improve the feature in PadicoTM instead of adding a dependancy.
• if you don't know how to improve some feature in PadicoTM, then ask.