Skip to content

GitLab

Commit 4af3d06d authored by florent's avatar florent
Browse files

Added some examples on front page, documentation on EXTRA_DIST in autotools page.

parent 68ebdf4b
Hide whitespace changes
Inline Side-by-side
ChangeLog
View file @ 4af3d06d
2008/06/04
16. Added some examples on front page.
15. Added documentation on EXTRA_DIST in autotools page
2008/06/03
14. Added "Robotic component" page with links to GenoM and OpenRTM components.
2008/05/28
......
doc/Makefile.am
View file @ 4af3d06d
......@@ -30,7 +30,10 @@ nobase_dist_hppDoc_DATA= \
pictures/graph_legend.png \
pictures/tab_b.gif \
pictures/tab_l.gif \
pictures/tab_r.gif
pictures/tab_r.gif \
pictures/film.png \
movies/whole-body.mpg \
movies/passing-under.mpg
# these files are installed in the root document directory.
#
......
doc/html/hppdoc_autotools.html
View file @ 4af3d06d
......@@ -5,111 +5,137 @@
</HEAD>
<BODY>
<h1><a class="anchor" name="hppDoc_autotools">About autoconf, automake and pkg-config</a></h1><h2><a class="anchor" name="hppDoc_autotools_intro">
Introduction</a></h2>
<h1><a class="anchor" name="hppDoc_autotools">
About autoconf, automake and pkg-config
</a></h1>
HPP (Humanoid Path Planner) is composed of several software modules managed by autotools. This page explains the basics of these tools for more information, the reader is refered to the official documentation pages of each tool.
<h2><a class="anchor" name="hppDoc_autoconf">
Autoconf</a></h2>
<h2><a class="anchor" name="hppDoc_autotools_intro">
Introduction
</a></h2>
Autoconf takes as input file <code>configure.ac</code> and builds <code>configure</code> script.
HPP (Humanoid Path Planner) is composed of several software modules managed by autotools. This page explains the basics of these tools for more information, the reader is refered to the official documentation pages of each tool.
<h3><a class="anchor" name="hppDoc_autoconf_commands">Main commands in <code>configure.ac</code></a></h3>
<h4><a class="anchor" name="hppDoc_autoconf_init">AC_INIT([packageName], [Version], [Contact])</a></h4>
<h2><a class="anchor" name="hppDoc_autoconf">
Autoconf
</a></h2>
File <code>configure.ac</code> should start by this command. The command specifies the name of the package, the version number and a contact for bug report.
Autoconf takes as input file <code>configure.ac</code> and builds <code>configure</code> script.
<h4><a class="anchor" name="hppDoc_autoconf_automake">AM_INIT_AUTOMAKE</a></h4>
<h3><a class="anchor" name="hppDoc_autoconf_commands">
Main commands in <code>configure.ac</code>
</a></h3>
This commands specifies that <a href="hppdoc_autotools.html#hppdoc_automake"><code>automake</code></a> will be used to generate <code>Makefile.in</code> files.
<h4><a class="anchor" name="hppDoc_autoconf_init">
AC_INIT([packageName], [Version], [Contact])
</a></h4>
<h4><a class="anchor" name="hppDoc_autoconf_pkgcheckmodule">PKG_CHECK_MODULES(PACKAGENAME, packageName)</a></h4>
File <code>configure.ac</code> should start by this command. The command specifies the name of the package, the version number and a contact for bug report.
This command specifies that the dependence to package <code>packageName</code> will be handled by <a href="hppdoc_autotools.html#hppDoc_pkg_config"><code>pkg-config</code></a> at configuration.
For example the following lines will trigger the following operations:
<div class="fragment"><pre class="fragment">
<h4><a class="anchor" name="hppDoc_autoconf_automake">
AM_INIT_AUTOMAKE</a>
</h4>
This commands specifies that <a href="hppdoc_autotools.html#hppdoc_automake"><code>automake</code></a> will be used to generate <code>Makefile.in</code> files.
<h4><a class="anchor" name="hppDoc_autoconf_pkgcheckmodule">
PKG_CHECK_MODULES(PACKAGENAME, packageName)
</a></h4>
This command specifies that the dependence to package <code>packageName</code> will be handled by <a href="hppdoc_autotools.html#hppDoc_pkg_config"><code>pkg-config</code></a> at configuration.
For example the following lines will trigger the following operations:
<div class="fragment"><pre class="fragment">
PKG_CHECK_MODULES(KWSPLUS, kwsPlus >= 1.1)
KWSPLUS_PREFIX=`$PKG_CONFIG kwsPlus --variable=prefix`
AC_SUBST(KWSPLUS_PREFIX)
AC_SUBST(KWSPLUS_CFLAGS)
AC_SUBST(KWSPLUS_LIBS)
</pre></div>
The current package depends on <code>kwsPlus</code>, version at least 1.1. The following variable will be defined and substituted by their value by <code>configure</code> script:
<ul>
<li><code>KWSPLUS_PREFIX</code> contains the prefix where <code>kwsPlus</code> has been installed,</li>
<li><code>KWSPLUS_CFLAGS</code> contains compilation flags necessary to compile source files including headers of <code>kwsPlus</code>,</li>
<li><code>KWSPLUS_LIBS</code> contains linking flags necessary to link with <code>kwsPlus</code>.</li>
</ul>
<h4><a class="anchor" name="hppDoc_autoconf_acoutput">AC_OUTPUT</a></h4>
This command specifies which files are generated in the build directory by <code>configure</code> script. For each output, the corresponding file ending with extension <code>.in</code> should exist in the source hierarchy. For instance,
<div class="fragment"><pre class="fragment">
</pre></div>
The current package depends on <code>kwsPlus</code>, version at least 1.1. The following variable will be defined and substituted by their value by <code>configure</code> script:
<ul>
<li><code>KWSPLUS_PREFIX</code> contains the prefix where <code>kwsPlus</code> has been installed,</li>
<li><code>KWSPLUS_CFLAGS</code> contains compilation flags necessary to compile source files including headers of <code>kwsPlus</code>,</li>
<li><code>KWSPLUS_LIBS</code> contains linking flags necessary to link with <code>kwsPlus</code>.</li>
</ul>
<h4><a class="anchor" name="hppDoc_autoconf_acoutput">
AC_OUTPUT
</a></h4>
This command specifies which files are generated in the build directory by <code>configure</code> script. For each output, the corresponding file ending with extension <code>.in</code> should exist in the source hierarchy. For instance,
<div class="fragment"><pre class="fragment">
AC_OUTPUT(Makefile
src/Makefile
include/Makefile
doc/package.dox
)
</pre></div>
specifies that configure will create 4 files in the build directory:
<ul>
<li><code>build/Makefile</code></li>
<li><code>build/src/Makefile</code></li>
<li><code>build/include/Makefile</code></li>
<li><code>build/doc/package.dox</code></li>
</ul>
The following files should therefore exist:
<ul>
<li><code>Makefile.in</code></li>
<li><code>src/Makefile.in</code></li>
<li><code>include/Makefile.in</code></li>
<li><code>doc/package.dox.in</code></li>
</ul>
Note that <code>@KWSPLUS_PREFIX@</code> in <code>doc/package.dox.in</code> will be transformed into the string corresponding to the directory where package <code>kwsPlus</code> has been installed in <code>build/doc/package.dox.in</code>
<h2><a class="anchor" name="hppDoc_automake">Automake</a></h2>
Automake builds <code>Makefile.in</code> files from <code>Makefile.am</code> files in the same directory.
<h3><a class="anchor" name="hppDoc_automake_commands">Variables defined in <code>Makefile.am</code></a></h3>
Some variables are automatically defined in file <code>Makefile.am</code>. Following are some of these variables.
<ul>
<li><code>$(srcdir)</code> corresponds to the directory in which the <code>Makefile.am</code> file is,</li>
<li><code>$(top_srcdir)</code> corresponds to the directory where <code>configure.ac</code> is,</li>
<li><code>$(builddir)</code> is the directory in the build hierarchy corresponding to <code>$(srcdir)</code> in the source hierarchy,</li>
<li><code>$(top_builddir)</code> corresponds to the build directory,</li>
<li><code>$(prefix)</code> corresponds to the installation directory.</li>
</ul>
For instance, let us assume that your package source is in directory <code>/local/devel/package</code>.
In file <code>/local/devel/package/src/Makefile.am</code>,
<ul>
<li><code>$(srcdir)</code> is <code>/local/devel/package/src</code></li>
<li><code>$(top_srcdir)</code> is <code>/local/devel/package</code>.</li>
</ul>
Let us assume that you build your package from a build directory.
<div class="fragment"><pre class="fragment">
</pre></div>
specifies that configure will create 4 files in the build directory:
<ul>
<li><code>build/Makefile</code></li>
<li><code>build/src/Makefile</code></li>
<li><code>build/include/Makefile</code></li>
<li><code>build/doc/package.dox</code></li>
</ul>
The following files should therefore exist:
<ul>
<li><code>Makefile.in</code></li>
<li><code>src/Makefile.in</code></li>
<li><code>include/Makefile.in</code></li>
<li><code>doc/package.dox.in</code></li>
</ul>
Note that <code>@KWSPLUS_PREFIX@</code> in <code>doc/package.dox.in</code> will be transformed into the string corresponding to the directory where package <code>kwsPlus</code> has been installed in <code>build/doc/package.dox.in</code>
<h2><a class="anchor" name="hppDoc_automake">
Automake</a>
</h2>
Automake builds <code>Makefile.in</code> files from <code>Makefile.am</code> files in the same directory.
<h3><a class="anchor" name="hppDoc_automake_commands">
Variables defined in <code>Makefile.am</code>
</a></h3>
Some variables are automatically defined in file <code>Makefile.am</code>. Following are some of these variables.
<ul>
<li><code>$(srcdir)</code> corresponds to the directory in which the <code>Makefile.am</code> file is,</li>
<li><code>$(top_srcdir)</code> corresponds to the directory where <code>configure.ac</code> is,</li>
<li><code>$(builddir)</code> is the directory in the build hierarchy corresponding to <code>$(srcdir)</code> in the source hierarchy,</li>
<li><code>$(top_builddir)</code> corresponds to the build directory,</li>
<li><code>$(prefix)</code> corresponds to the installation directory.</li>
</ul>
For instance, let us assume that your package source is in directory <code>/local/devel/package</code>.
In file <code>/local/devel/package/src/Makefile.am</code>,
<ul>
<li><code>$(srcdir)</code> is <code>/local/devel/package/src</code></li>
<li><code>$(top_srcdir)</code> is <code>/local/devel/package</code>.</li>
</ul>
Let us assume that you build your package from a build directory.
<div class="fragment"><pre class="fragment">
[~] mkdir /local/devel/package/build
[~] cd /local/devel/package/build
[build] ../configure --prefix=/local/install
</pre></div>
Then, in file <code>/local/devel/package/src/Makefile.am</code>,
<ul>
<li><code>$(builddir)</code> becomes <code>/local/devel/package/build/src</code></li>
<li><code>$(top_builddir)</code> becomes <code>/local/devel/package/build</code>.</li>
<li><code>$(prefix)</code> becomes <code>/local/install</code>.</li>
</ul>
<h3><a class="anchor" name="hppDoc_automake_commands">Main commands in <code>Makefile.am</code></a></h3>
The two main objects created at compilation are libraries and programs.
<h4><a class="anchor" name="hppDoc_automake_libraries">Libraries</a></h4>
The typical commands related to the compilation and installation of a library are the following
<div class="fragment"><pre class="fragment">
</pre></div>
Then, in file <code>/local/devel/package/src/Makefile.am</code>,
<ul>
<li><code>$(builddir)</code> becomes <code>/local/devel/package/build/src</code></li>
<li><code>$(top_builddir)</code> becomes <code>/local/devel/package/build</code>.</li>
<li><code>$(prefix)</code> becomes <code>/local/install</code>.</li>
</ul>
<h3><a class="anchor" name="hppDoc_automake_commands">
Main commands and variables in <code>Makefile.am</code>
</a></h3>
The two main objects created at compilation are libraries and programs.
<h4><a class="anchor" name="hppDoc_automake_libraries">
Libraries
</a></h4>
The typical commands related to the compilation and installation of a library are the following
<div class="fragment"><pre class="fragment">
lib_LTLIBRARIES = libpackage.la
libpackage_la_SOURCES = \
package1.cpp \
......@@ -119,69 +145,83 @@ libpackage_la_CPPFLAGS = -I$(top_srcdir)/include -I@DEPENDENCE_CFLAGS@
libpackage_la_LDFLAGS =\
@DEPENDENCE_LIBS@
</pre></div>
<code>lib_LTLIBRARIES</code> specifies the name of the library to be built and installed by this package. Extension <code>.la</code> means that <code>libtool</code> is used.
<br>
<code>libpackage_la_SOURCES</code> specifies the list of source files that constitute the library.
<br>
<code>libpackage_la_CPPFLAGS</code> specifies the compilation flags to be used. Note that
<ul>
<li><code>-I$(top_srcdir)/include</code> give access to the header of this package that are located in <code>include</code> directory, </li>
<li><code>-I@DEPENDENCE_CFLAGS@</code> specifies compilation flags to access the header files of some dependences. The string eventually produced at configuration in build directory will be produced by <a href="hppdoc_autotools.html#hppDoc_pkg_config"><code>pkg-config</code></a>.</li>
</ul>
<br>
<code>libpackage_la_LDFLAGS</code> defines the linking flags. Note that <a href="hppdoc_autotools.html#hppDoc_pkg_config"><code>pkg-config</code></a> will replace <code>@DEPENDENCE_LIBS@</code> at configuration by linking options <code>-L... -l...</code> to link with dependence libraries.
<h4><a class="anchor" name="hppDoc_automake_programs">Programs</a></h4>
The commands related to programs are almost the same as for libraries. The programs to be compiled are specified by commands
<ul>
<li><code>noinst_PROGRAMS</code> for program compiled but not installed,</li>
<li><code>bin_PROGRAMS</code> for program compiled and installed.</li>
</ul>
Compilation and linking flags work the same way as for libraries.
<h2><a class="anchor" name="hppDoc_pkg_config">Pkg-config</a></h2>
<code>pkg-config</code> is a program that recovers information about installed packages.
<div class="fragment"><pre class="fragment">
</pre></div>
<code>lib_LTLIBRARIES</code> specifies the name of the library to be built and installed by this package. Extension <code>.la</code> means that <code>libtool</code> is used.
<br>
<code>libpackage_la_SOURCES</code> specifies the list of source files that constitute the library.
<br>
<code>libpackage_la_CPPFLAGS</code> specifies the compilation flags to be used. Note that
<ul>
<li><code>-I$(top_srcdir)/include</code> give access to the header of this package that are located in <code>include</code> directory, </li>
<li><code>-I@DEPENDENCE_CFLAGS@</code> specifies compilation flags to access the header files of some dependences. The string eventually produced at configuration in build directory will be produced by <a href="hppdoc_autotools.html#hppDoc_pkg_config"><code>pkg-config</code></a>.</li>
</ul>
<br>
<code>libpackage_la_LDFLAGS</code> defines the linking flags. Note that <a href="hppdoc_autotools.html#hppDoc_pkg_config"><code>pkg-config</code></a> will replace <code>@DEPENDENCE_LIBS@</code> at configuration by linking options <code>-L... -l...</code> to link with dependence libraries.
<h4><a class="anchor" name="hppDoc_automake_programs">
Programs
</a></h4>
The commands related to programs are almost the same as for libraries. The programs to be compiled are specified by commands
<ul>
<li><code>noinst_PROGRAMS</code> for program compiled but not installed,</li>
<li><code>bin_PROGRAMS</code> for program compiled and installed.</li>
</ul>
Compilation and linking flags work the same way as for libraries.
<h4><a class="anchor" name="hppDoc_automake_EXTRA_DIST">
Variable EXTRA_DIST
</a></h4>
The makefile generated in the top build directory implements a target call <code>dist</code>. This target generates a tarball of the package. The tarball can be sent to a third party and inflated in order to install the package. Variable EXTRA_DIST specifies files that should be included in the tarball. If you forget to add all necessary files in this variable, the third party will not be able to install the package.
<p>
It is therefore a good idea to generate a tarball (<code>make dist</code>) and to install the package from this tarball, as a test.
<h2><a class="anchor" name="hppDoc_pkg_config">
Pkg-config
</a></h2>
<code>pkg-config</code> is a program that recovers information about installed packages.
<div class="fragment"><pre class="fragment">
pkg-config package options
</pre></div>
will try to find a file named <code>package.pc</code> and read the requested information defined by <code>options</code>.
<h3><a class="anchor" name="hppDoc_pkg_config_path">PKG_CONFIG_PATH environment variable</a></h2>
The directories where <code>pkg-config</code> looks for file <code>package.pc</code> is defined by environment variable <code>PKG_CONFIG_PATH</code>. <code>pkg-config</code> scan directories in the order they are specified in <code>PKG_CONFIG_PATH</code>.
<h3><a class="anchor" name="hppDoc_pkg_config_path">pkg-config syntax</a></h2>
<div class="fragment"><pre class="fragment">
</pre></div>
will try to find a file named <code>package.pc</code> and read the requested information defined by <code>options</code>.
<h3><a class="anchor" name="hppDoc_pkg_config_path">
PKG_CONFIG_PATH environment variable
</a></h2>
The directories where <code>pkg-config</code> looks for file <code>package.pc</code> is defined by environment variable <code>PKG_CONFIG_PATH</code>. <code>pkg-config</code> scan directories in the order they are specified in <code>PKG_CONFIG_PATH</code>.
<h3><a class="anchor" name="hppDoc_pkg_config_path">
pkg-config syntax
</a></h2>
<div class="fragment"><pre class="fragment">
pkg-config package --cflags
</pre></div>
returns the string after <code>Cflags:</code> in <code>package.pc</code>.
<div class="fragment"><pre class="fragment">
</pre></div>
returns the string after <code>Cflags:</code> in <code>package.pc</code>.
<div class="fragment"><pre class="fragment">
pkg-config package --libs
</pre></div>
returns the string after <code>Libs:</code> in <code>package.pc</code>.
<div class="fragment"><pre class="fragment">
</pre></div>
returns the string after <code>Libs:</code> in <code>package.pc</code>.
<div class="fragment"><pre class="fragment">
pkg-config package --variable=var
</pre></div>
returns the string after <code>var=</code> in <code>package.pc</code>.
<hr>
<center>
<img src="./pictures/footer.jpg" Height=100>
<br>Humanoid Path Planner documentation</br>
</center>
<hr>
</body>
</pre></div>
returns the string after <code>var=</code> in <code>package.pc</code>.
<hr>
<center>
<img src="./pictures/footer.jpg" Height=100>
<br>Humanoid Path Planner documentation</br>
</center>
<hr>
</body>
</html>
doc/html/main.html.in
View file @ 4af3d06d
......@@ -11,21 +11,62 @@
HPP (Humanoid Path Planner) is a collection of software packages
implementing path planning functionalities for a humanoid robot.
HPP is built upon KineoWorks (KWS) and KineoPathPlanner-SDK (KPP-SDK).
Global motion planning algorithms are built upon KineoWorks (KWS) and
KineoPathPlanner-SDK (KPP-SDK), commercial software products marketed
by <a href="http://www.kineocam.com">Kineo CAM</a>.
<p>
However, many basic software modules (dynamic model, walk pattern generator,...)
are independent of the above commercial products.
It can be extended to path planning for other types of robots like digital actors for instance.
<h2> Organization of the packages </h2>
The code relative to the HPP is distributed into several software packages. The packages are distributed into three
categories:
The code relative to HPP is distributed into several software packages handled by
<a href="http://www.gnu.org/software/autoconf">autotools</a>.
The packages are distributed into the following categories:
<ul>
<li> <a href="algorithm.html">Algorithms</a> implementing path planning functionalities </li>
<li> <a href="corba.html">Corba</a> communication facilities to control the algorithms </li>
<li> <a href="corba.html">Corba</a> communication facilities to control algorithms </li>
<li> <a href="kppInterface.html">Add-on</a> to KineoPathPlanner GUI interface. </li>
<li> <a href="roboticComponent.html">Robotic components</a> including HPP algorithms</li>
<li> <a href="roboticComponent.html">Robotic components</a> encapsulating HPP algorithms</li>
</ul>
<h2>A few examples</h2>
Here are a few examples of problems solved by HPP packages.
<h3>Whole-body motion generation</h3>
This problem consists in computing a dynamically stable motion a humanoid robot
in order to perform specified geometric tasks like moving the right hand at a given
position, looking in a given direction for instance.
<p>
<center>
<a href="movies/whole-body.mpg"><img src="pictures/film.png" width="40%"> </a>
</center>
<h3>Passing under obstacles</h3>
Passing under a low obstacle is a difficult task for a humanoid robot.
The robot should use all degrees-of-freedom while keeping quasi-static
balance.
<p>
<center>
<a href="movies/passing-under.mpg"><img src="pictures/film.png" width="40%"> </a>
</center>
<h3>Walk planning</h3>
To move on a flat ground cluttered with obstacles, the best strategy is to walk. In this example, we plan a motion for the bounding box of the robot with cart-like kinematics and then animate the path of the box using a walk pattern generator.
<p>
<center>
<img src="pictures/film.png" width="40%">
</center>
<hr>
<center>
<img src="./pictures/footer.jpg" Height=100>
......
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