Commit 7a969b59 authored by Joseph Mirabel's avatar Joseph Mirabel
Browse files

Clean dox file.

parent 5b4906ae
About GNU Autoconf, GNU Automake and pkg-config
*HPP* (Humanoid Path Planner) is composed of several software modules
managed by the Autotools and pkg-config.
This page explains the basics of these tools for more information, the
reader is refered to the official documentation pages of each tool.
IMPORTANT: Writing compilation chains requires basic knowledge on the
Linux system and shell script writing (syntax and basic
One main problem when writing package is handling properly
dependencies. Basically, there operating system know nothgin about
_packages_: as soon as the libaries, headers, documentation are
installed (i.e. copied) on the system, the link between all the files
is lost (as it is not possible anymore to know that they all come from
the same source).
`pkg-config` solves this problem by installing a small text file using
a simple syntax which defines values associated with a package.
Each package can install a `.pc` file which can then be used to
resolve dependencies.
For instance, here is the pkg-config file of hpp-walkfootplanner:
.hpp-walkfootplanner pkg-config file
Name: hpp-walkfootplanner
Description: HPP walk foot planner
Requires: hppCore >= 1.8, roboptim-trajectory >= 0.1, jrlMathTools >= 1.1
Libs: -L${libdir} -lhpp-walkfootplanner
Cflags: -I${includedir}
One can see that meta-information such as package name, version and
requirements (i.e. dependencies) are indicated.
pkg-config has keys and variables.
Keys are predefined fields such as ``Name'' or ``Libs''. Their list is
available in the pkg-config documentation.
Variables are free fields which can be added to factorize text (like
defining directories location) or to store additional information.
HPP packages are using a non-standard variable called `doxygendocdir`
which is used to find and link Doxygen documentation together.
PKG_CONFIG_PATH environment variable
The `PKG_CONFIG_PATH` environment variable lists directories that will
be scanned by pkg-config. The only exception is `/usr/lib` which is
scanned automatically.
pkg-config syntax
.pkg-config syntax
pkg-config [OPTIONS] package
* `OPTIONS` can be:
** `--modversion` to get the package version number.
** `--cflags` to get C/C++ preprocessor options.
** `--libs` to get linking options.
** `--variable=PREFIX` for other options.
* `package` is the package name (i.e. to get `hpp-walkfootplanner.pc`
information, use package name to be used is `hpp-walkfootplanner`).
WARNING: the package name required by `pkg-config` is *not* the
content of the field `Name:` which is included in the
pkg-config file.
GNU Autoconf
GNU Autoconf is used to generate a shell script called `configure`.
This shell script will allow the users to fine tune the package by
* installation directories (by default `/usr/local`)
* libraries and headers locations
* which compiler should be used
* should the package be compiled with debug or release flags
* etc.
As the `configure` file is difficult to write, GNU Autoconf
uses an intermediary language called m4 to generate the shell script.
This language supports macro which can be expanded into shell script.
This mechanism is quite similar to the C/C++ preprocessor symbols.
GNU Autoconf also offers ready-to-use m4 macro to check for compilers,
libraries, headers, binaries, etc.
The next sections describes the most important macros provided by
GNU Autoconf.
This macro initializes GNU Autoconf by providing meta-information
about your package such as its name, authors, etc.
It should be called at the beginning of your `` file.
AC_INIT (package, version, [bug-report], [tarname], [url])
* `package` is the human-readable name of the package
* `version` is the version number
* `bug-report` is an e-mail address for bug report. `` can
be used for HPP packages.
* `tarname` is the package UNIX name. This is the technical name of
the package, it should only contain lowercase letters, numbers and
hyphen (``-''). If part of HPP, name should be prefixed by ``hpp-''.
For instance, valid package names are: ``hpp-pkg'', ``hpp-pkg2'',
* `url` is the package website URL.
.GNU Autoconf configuration for ``hpp-walkfootplanner''.
AC_INIT ([HPP walk planner],
[3.14], [], [hpp-walkplanner], [])
WARNING: You *must* call this macro in your `` file.
This macro initialized GNU Automake. This tool which can be used to
generate `Makefile` files will be described in the next section.
GNU Automake supports many options, recommanded options are:
* a version number indicates that GNU Automake should be newer than
the specifid version. Usually 1.9.6 is enough.
* `nostdinc` disables standard includes.
* `dist-bzip2` makes GNU Automake generate `.tar.bz2` tarballs which
are usually smaller than the classic `.tar.gz` ones.
* `-Wall` is a *mandatory* flag in HPP as it is enabling all warnings
for GNU Automake. Most of them are extremly helpful to find bugs.
.Recommanded GNU Automake configuration
AM_INIT_AUTOMAKE([1.9.6 dist-bzip2 -Wall nostdinc])
This macro runs pkg-config and automatically create some GNU Autoconf
variables that contains package information.
.Checking for package `hpp-walkplanner`
PKG_CHECK_MODULES([HPP_WALKPLANNER], [hpp-walkplanner >= 0.7])
[`$PKG_CONFIG hpp-walkplanner --variable=prefix`])
If this piece of code is included in your `` file,
the `configure` will check for `hpp-walkplanner` and fail if this
package is not present.
All variables tagged as _subst_ituable will be substituted in
generated file. If you are using GNU Automake, it means that you can
directly use `$(HPP_WALKPLANNER_CFLAGS)` for instance anywhere in your
`` files.
`AC_CONFIG_FILES` lists the file that should be generated by the
`configure` file. In fact, to communicate users custom values inside
the package, specific strings are substituted in ``template'' files.
These template files have a ``.in'' suffix.
Strings which will be substituted are: `@XXX@` where ``XXX'' is some
value defined during the configuring process.
For instance `@PACKAGE@` is the package long name defined in `AC_INIT`.
When using GNU Automake, all Makefile have to be listed (i.e. if you
have `a/b/`, you should add `a/b/Makefile` to the list).
AC_CONFIG_FILES([file1 file2 ...])
The only argument is the list of the files that should be processed.
NOTE: Do not include the ``.in'' suffix when listing the files!
`AC_OUTPUT` should be the last line of the `` file, It is
needed for GNU Autoconf to work properly.
WARNING: You *must* call this macro at the end of your ``
GNU Automake
GNU Automake helps developpers to write robust and portable `Makefile`
files. It takes as input `` file which are just plain
normal `Makefile`. However, it recognizes some specific `Makefile`
variables and will automatically write rules to compile programs,
libraries, etc.
Variables defined in
Variables are set using the syntax `VAR=42` and read using the
`$(VAR)` syntax.
Plenty of variables are directly available:
* `$(srcdir)` corresponds to the directory of the `` file.
* `$(top_srcdir)` corresponds to the directory where `` is stored.
* `$(builddir)` is the directory in the build hierarchy corresponding
to `$(srcdir)` in the source hierarchy.
* `$(top_builddir)` corresponds to the top of the build directory.
* `$(prefix)` corresponds to the installation prefix.
Compiling using GNU Automake
Libraries are compiled using a helper tool called GNU Libtool to easy
portability issues. Most of the time, you can just ignore that it is
being used.
.Library compilation example
# Defining a new library to compile.
# Listing the associated sources.
libhpp_package_la_SOURCES = \
package1.cpp \
# Managing flags.
libpackage_la_CPPFLAGS = -I$(top_srcdir)/include -I$(DEP_CFLAGS)
libpackage_la_LDFLAGS = $(DEP_LIBS)
`lib_LTLIBRARIES` contains the list of the libraries that will be
built and installed in `libdir`. You *must* begin your library name
with `lib` and finish it by `.la`.
Then, by prefixing you library name with `_SOURCES`, one should define
the list of source files that will be compiled to build the library.
NOTE: Any characters which is not permitted in a variable name such as
hyphen (``-'') or dot (``.'') should be substituted by an
underscore (``_''). In the example ``'' is
transformed in ``libhpp_package_la''.
Programs are defined like libraries.
* `noinst_PROGRAMS` lists programs that will not be installed.
* `bin_PROGRAMS` lists programs that will be installed in `bindir`.
This variables lists all files that should be distributed
(i.e. included in the tarball of the project).
Used sources and headers are distributed automatically.
* link:[GNU Autoconf manual]
* link:[GNU Automake manual]
* link:[pkg-config website]
* link:[Autotools tutorial]
......@@ -57,77 +57,37 @@ how to use this project.
\page hpp_doc_algorithms Algorithms
<h1>Packages implementing algorithms</h1>
<h2>Technical tools</h2>
<table class="pkglist">
<td>technical tools for the HPP project (logging, benchmark, quality assurance tools),</td>
\section hpp_doc_algorithms_technical_tools Technical tools
- @HPPUTIL_LINK@: technical tools for the HPP project (logging, benchmark, quality assurance tools),
<h2>Motion planning for humanoid systems</h2>
\section hpp_doc_algorithms_motion_planning Motion planning for humanoid systems
\par Kinematic chain with geometry
<table class="pkglist">
<td>Modified version of Flexible collision library, for collision detection and distance computation,</td>
<td>implementation of kinematic chain with dynamic computations,</td>
<td>Interface between pinocchio and hpp-core,
- @HPPFCL_LINK@: Modified version of Flexible collision library, for collision detection and distance computation,
- @PINOCCHIO_LINK@: implementation of kinematic chain with dynamic computations,
- @HPPPINOCCHIO_LINK@: Interface between pinocchio and hpp-core,
\par Non linear constraints
<table class="pkglist">
<td>definition of some nonlinear constraints,</td>
- @HPPCONSTRAINTS_LINK@: definition of some nonlinear constraints,
\par Path planning
<table class="pkglist">
<td>definition of basic classes, path planning problems and solvers,</td>
- @HPPCORE_LINK@: definition of basic classes, path planning problems and solvers,
\par Path Planning for humanoid robots
<table class="pkglist">
<td>whole-body and walk planning using sliding path approximation.</td>
- @HPPWHOLEBODYSTEP_LINK@: whole-body and walk planning using sliding path approximation.
\par Manipulation Planning
<table class="pkglist">
<td>Manipulation planning.</td>
<td>Enhance hpp-pinocchio to support datas required by hpp-manipulation.</td>
- @HPPMANIPULATION_LINK@: Manipulation planning
- @HPPMANIPULATIONURDF_LINK@: Manipulation planning
\page hpp_doc_corba_interface Corba interfaces
<h1>Packages implementing CORBA interfaces</h1>
\par Packages implementing CORBA interfaces
The following packages implement Corba communication functionalities
\li @HPPCORBASERVER_LINK@ : Corba server embedding a hpp::core::ProblemSolver instance.
......@@ -140,7 +100,7 @@ The following packages implement Corba communication functionalities
\page hpp_doc_graphical_interface Graphical user interface
<h1>Packages implementing graphical user interface</h1>
\par Packages implementing graphical user interface
The following packages implement a corba connection with a graphical display
\li @GEPETTOVIEWER_LINK@ : Graphical window based on OpenSceneGraph.
......@@ -153,9 +113,7 @@ The following packages implement a corba connection with a graphical display
\page hpp_doc_dependency_graph Dependencies
<h1>Graph of dependencies between packages</h1>
Below is the graph of dependencies between packages.
Graph of dependencies between packages
\dotfile "Dependency graph"
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment