Commit 26eb058d authored by Thomas Moulard's avatar Thomas Moulard
Browse files

Add Asciidoc support.



	Asciidoc is a very simple markup language that supports source
	highlighting and can embed mathematical formula.
	It also generates much more beautiful documents than
	manually-written HTML pages.
	On Fedora, install it using: yum install -y asciidoc source-highlight

	* configure.ac: Do not generate autotools.html anymore.
	* doc/Makefile.am: Add Asciidoc compilation rule, fix filename lists.
	* doc/algorithm.html.in: Use images instead of pictures.
	* doc/autotools.html.in: Remove.
	* doc/autotools.txt: New.
	* doc/corba.html.in: Use images instead of pictures.
	* doc/develop.html.in: Use images instead of pictures.
	* doc/graph-dependency.html.in: Use images instead of pictures.
	* doc/images/archi.png: Rename from doc/pictures/archi.png.
	* doc/images/doxygen.png: Rename from doc/pictures/doxygen.png.
	* doc/images/film.png: Rename from doc/pictures/film.png.
	* doc/images/footer.jpg: Rename from doc/pictures/footer.jpg.
	* doc/images/ftv2blank.png: Rename from doc/pictures/ftv2blank.png.
	* doc/images/ftv2doc.png: Rename from doc/pictures/ftv2doc.png.
	* doc/images/ftv2folderclosed.png:
	Rename from doc/pictures/ftv2folderclosed.png.
	* doc/images/ftv2folderopen.png:
	Rename from doc/pictures/ftv2folderopen.png.
	* doc/images/ftv2lastnode.png:
	Rename from doc/pictures/ftv2lastnode.png.
	* doc/images/ftv2link.png: Rename from doc/pictures/ftv2link.png.
	* doc/images/ftv2mlastnode.png:
	Rename from doc/pictures/ftv2mlastnode.png.
	* doc/images/ftv2mnode.png: Rename from doc/pictures/ftv2mnode.png.
	* doc/images/ftv2node.png: Rename from doc/pictures/ftv2node.png.
	* doc/images/ftv2plastnode.png:
	Rename from doc/pictures/ftv2plastnode.png.
	* doc/images/ftv2pnode.png: Rename from doc/pictures/ftv2pnode.png.
	* doc/images/ftv2vertline.png:
	Rename from doc/pictures/ftv2vertline.png.
	* doc/images/graph_legend.png:
	Rename from doc/pictures/graph_legend.png.
	* doc/images/icons/README: New.
	* doc/images/icons/callouts/1.png: New.
	* doc/images/icons/callouts/10.png: New.
	* doc/images/icons/callouts/11.png: New.
	* doc/images/icons/callouts/12.png: New.
	* doc/images/icons/callouts/13.png: New.
	* doc/images/icons/callouts/14.png: New.
	* doc/images/icons/callouts/15.png: New.
	* doc/images/icons/callouts/2.png: New.
	* doc/images/icons/callouts/3.png: New.
	* doc/images/icons/callouts/4.png: New.
	* doc/images/icons/callouts/5.png: New.
	* doc/images/icons/callouts/6.png: New.
	* doc/images/icons/callouts/7.png: New.
	* doc/images/icons/callouts/8.png: New.
	* doc/images/icons/callouts/9.png: New.
	* doc/images/icons/caution.png: New.
	* doc/images/icons/example.png: New.
	* doc/images/icons/home.png: New.
	* doc/images/icons/important.png: New.
	* doc/images/icons/next.png: New.
	* doc/images/icons/note.png: New.
	* doc/images/icons/prev.png: New.
	* doc/images/icons/tip.png: New.
	* doc/images/icons/up.png: New.
	* doc/images/icons/warning.png: New.
	* doc/images/kineo.jpg: Rename from doc/pictures/kineo.jpg.
	* doc/images/kppInterfaceWalk.png:
	Rename from doc/pictures/kppInterfaceWalk.png.
	* doc/images/passing-under.jpg:
	Rename from doc/pictures/passing-under.jpg.
	* doc/images/tab_b.gif: Rename from doc/pictures/tab_b.gif.
	* doc/images/tab_l.gif: Rename from doc/pictures/tab_l.gif.
	* doc/images/tab_r.gif: Rename from doc/pictures/tab_r.gif.
	* doc/images/walk.png: Rename from doc/pictures/walk.png.
	* doc/images/whole-body.png: Rename from doc/pictures/whole-body.png.
	* doc/install.html.in: Use images instead of pictures.
	* doc/kpp-interface.html.in: Use images instead of pictures.
	* doc/main.html.in: Use images instead of pictures.
	* doc/missing.html.in: Use images instead of pictures.
	* doc/robotic-component.html.in: Use images instead of pictures.
	* doc/tree.html.in: Use images instead of pictures.
Signed-off-by: default avatarThomas Moulard <thomas.moulard@gmail.com>
parent 66c489ed
2010-01-09 Thomas Moulard <thomas.moulard@gmail.com>
Add Asciidoc support.
Asciidoc is a very simple markup language that supports source
highlighting and can embed mathematical formula.
It also generates much more beautiful documents than
manually-written HTML pages.
On Fedora, install it using: yum install -y asciidoc source-highlight
* configure.ac: Do not generate autotools.html anymore.
* doc/Makefile.am: Add Asciidoc compilation rule, fix filename lists.
* doc/algorithm.html.in: Use images instead of pictures.
* doc/autotools.html.in: Remove.
* doc/autotools.txt: New.
* doc/corba.html.in: Use images instead of pictures.
* doc/develop.html.in: Use images instead of pictures.
* doc/graph-dependency.html.in: Use images instead of pictures.
* doc/images/archi.png: Rename from doc/pictures/archi.png.
* doc/images/doxygen.png: Rename from doc/pictures/doxygen.png.
* doc/images/film.png: Rename from doc/pictures/film.png.
* doc/images/footer.jpg: Rename from doc/pictures/footer.jpg.
* doc/images/ftv2blank.png: Rename from doc/pictures/ftv2blank.png.
* doc/images/ftv2doc.png: Rename from doc/pictures/ftv2doc.png.
* doc/images/ftv2folderclosed.png:
Rename from doc/pictures/ftv2folderclosed.png.
* doc/images/ftv2folderopen.png:
Rename from doc/pictures/ftv2folderopen.png.
* doc/images/ftv2lastnode.png:
Rename from doc/pictures/ftv2lastnode.png.
* doc/images/ftv2link.png: Rename from doc/pictures/ftv2link.png.
* doc/images/ftv2mlastnode.png:
Rename from doc/pictures/ftv2mlastnode.png.
* doc/images/ftv2mnode.png: Rename from doc/pictures/ftv2mnode.png.
* doc/images/ftv2node.png: Rename from doc/pictures/ftv2node.png.
* doc/images/ftv2plastnode.png:
Rename from doc/pictures/ftv2plastnode.png.
* doc/images/ftv2pnode.png: Rename from doc/pictures/ftv2pnode.png.
* doc/images/ftv2vertline.png:
Rename from doc/pictures/ftv2vertline.png.
* doc/images/graph_legend.png:
Rename from doc/pictures/graph_legend.png.
* doc/images/icons/README: New.
* doc/images/icons/callouts/1.png: New.
* doc/images/icons/callouts/10.png: New.
* doc/images/icons/callouts/11.png: New.
* doc/images/icons/callouts/12.png: New.
* doc/images/icons/callouts/13.png: New.
* doc/images/icons/callouts/14.png: New.
* doc/images/icons/callouts/15.png: New.
* doc/images/icons/callouts/2.png: New.
* doc/images/icons/callouts/3.png: New.
* doc/images/icons/callouts/4.png: New.
* doc/images/icons/callouts/5.png: New.
* doc/images/icons/callouts/6.png: New.
* doc/images/icons/callouts/7.png: New.
* doc/images/icons/callouts/8.png: New.
* doc/images/icons/callouts/9.png: New.
* doc/images/icons/caution.png: New.
* doc/images/icons/example.png: New.
* doc/images/icons/home.png: New.
* doc/images/icons/important.png: New.
* doc/images/icons/next.png: New.
* doc/images/icons/note.png: New.
* doc/images/icons/prev.png: New.
* doc/images/icons/tip.png: New.
* doc/images/icons/up.png: New.
* doc/images/icons/warning.png: New.
* doc/images/kineo.jpg: Rename from doc/pictures/kineo.jpg.
* doc/images/kppInterfaceWalk.png:
Rename from doc/pictures/kppInterfaceWalk.png.
* doc/images/passing-under.jpg:
Rename from doc/pictures/passing-under.jpg.
* doc/images/tab_b.gif: Rename from doc/pictures/tab_b.gif.
* doc/images/tab_l.gif: Rename from doc/pictures/tab_l.gif.
* doc/images/tab_r.gif: Rename from doc/pictures/tab_r.gif.
* doc/images/walk.png: Rename from doc/pictures/walk.png.
* doc/images/whole-body.png: Rename from doc/pictures/whole-body.png.
* doc/install.html.in: Use images instead of pictures.
* doc/kpp-interface.html.in: Use images instead of pictures.
* doc/main.html.in: Use images instead of pictures.
* doc/missing.html.in: Use images instead of pictures.
* doc/robotic-component.html.in: Use images instead of pictures.
* doc/tree.html.in: Use images instead of pictures.
2010-01-09 Thomas Moulard <thomas.moulard@gmail.com>
Use flash video player.
......
......@@ -124,7 +124,6 @@ AC_CONFIG_FILES([
doc/index.html
doc/tree.html
doc/develop.html
doc/autotools.html
doc/install.html
])
......
......@@ -9,13 +9,13 @@ graphDep.dot: $(top_builddir)/config.status
$(top_srcdir)/scripts/packageDep -o graphDep.dot $(PKG_LIST)
sed -i 's/size = "12,15"//' graphDep.dot
pictures/dependencies.png: graphDep.dot
mkdir -p pictures
dot -o pictures/dependencies.png -Tpng graphDep.dot
images/dependencies.png: graphDep.dot
mkdir -p images
dot -o images/dependencies.png -Tpng graphDep.dot
CLEANFILES += \
graphDep.dot \
pictures/dependencies.png
images/dependencies.png
# Generate pages for missing packages.
......@@ -28,6 +28,25 @@ CLEANFILES += \
BUILT_SOURCES = $(MISSING_FILES)
CLEANFILES += $(MISSING_FILES)
# Graph dependency.
# Replace the special tag ``@MAP@'' by the dot generated map.
graphDep.html: graphDep.dot
dot -o graphDep.html -Tcmapx graphDep.dot
graph-dependency.html: graph-dependency.html.in graphDep.html
MAP=`tr -d '\n' < graphDep.html`; \
sed "s|@MAP@|$$MAP|" "$<" > $@
EXTRA_DIST += $(DOC_EXTRA) \
graph-dependency.html.in \
cmaxp.html
# Asciidoc pages.
SUFFIXES += .html
.txt.html:
asciidoc -a icons -o $@ $<
# Distribute all files (HTML, images, videos...).
DOC_EXTRA = \
custom.css \
......@@ -36,28 +55,53 @@ DOC_EXTRA = \
figures/kppInterfaceWalk.png \
movies/passing-under.mp4 \
movies/whole-body.mp4 \
pictures/dependencies.png \
pictures/film.png \
pictures/footer.jpg \
pictures/ftv2blank.png \
pictures/ftv2doc.png \
pictures/ftv2folderclosed.png \
pictures/ftv2folderopen.png \
pictures/ftv2lastnode.png \
pictures/ftv2link.png \
pictures/ftv2mlastnode.png \
pictures/ftv2mnode.png \
pictures/ftv2node.png \
pictures/ftv2plastnode.png \
pictures/ftv2pnode.png \
pictures/ftv2vertline.png \
pictures/graph_legend.png \
pictures/passing-under.jpg \
pictures/tab_b.gif \
pictures/tab_l.gif \
pictures/tab_r.gif \
pictures/walk.png \
pictures/whole-body.png \
images/dependencies.png \
images/film.png \
images/footer.jpg \
images/ftv2blank.png \
images/ftv2doc.png \
images/ftv2folderclosed.png \
images/ftv2folderopen.png \
images/ftv2lastnode.png \
images/ftv2link.png \
images/ftv2mlastnode.png \
images/ftv2mnode.png \
images/ftv2node.png \
images/ftv2plastnode.png \
images/ftv2pnode.png \
images/ftv2vertline.png \
images/graph_legend.png \
images/icons/callouts/1.png \
images/icons/callouts/2.png \
images/icons/callouts/3.png \
images/icons/callouts/4.png \
images/icons/callouts/5.png \
images/icons/callouts/6.png \
images/icons/callouts/7.png \
images/icons/callouts/8.png \
images/icons/callouts/9.png \
images/icons/callouts/10.png \
images/icons/callouts/11.png \
images/icons/callouts/12.png \
images/icons/callouts/13.png \
images/icons/callouts/14.png \
images/icons/callouts/15.png \
images/icons/caution.png \
images/icons/example.png \
images/icons/home.png \
images/icons/important.png \
images/icons/next.png \
images/icons/note.png \
images/icons/prev.png \
images/icons/tip.png \
images/icons/up.png \
images/icons/warning.png \
images/passing-under.jpg \
images/tab_b.gif \
images/tab_l.gif \
images/tab_r.gif \
images/walk.png \
images/whole-body.png \
tabs.css
nobase_html_DATA = \
......@@ -75,17 +119,3 @@ nobase_html_DATA = \
nobase_html_DATA += $(MISSING_FILES) $(DOC_EXTRA)
EXTRA_DIST += $(DOC_EXTRA) \
graph-dependency.html.in
# Graph dependency.
# Replace the special tag ``@MAP@'' by the dot generated map.
graphDep.html: graphDep.dot
dot -o graphDep.html -Tcmapx graphDep.dot
graph-dependency.html: graph-dependency.html.in graphDep.html
MAP=`tr -d '\n' < graphDep.html`; \
sed "s|@MAP@|$$MAP|" "$<" > $@
CLEANFILES += \
cmaxp.html
......@@ -79,7 +79,7 @@
<h3>Motion planning for humanoid systems</h3>
<p>
Packages marked by <img src="pictures/kineo.jpg" alt="require Kineo
Packages marked by <img src="images/kineo.jpg" alt="require Kineo
SDK"> depend on <a href="http://www.kineocam.com/">KineoWorks SDK</a>.
</p>
......@@ -89,21 +89,21 @@
<tr>
<td>
<a href="@KWSPLUS_LINK@">kwsPlus</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>extension to KineoWorks (cart-like steering method) </td>
</tr>
<tr>
<td>
<a href="@HPPMODEL_LINK@">hppModel</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>implementation of hybrid geometric and dynamic robot.</td>
</tr>
<tr>
<td>
<a href="@HPPCORE_LINK@">hppCore</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>definition of basic classes. </td>
</tr>
......@@ -114,7 +114,7 @@
<tr>
<td>
<a href="@HPPHYBRIDROBOT_LINK@">hppHybridRobot</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>
Hybrid model of robot to combine various types of motions in
......@@ -124,49 +124,49 @@
<tr>
<td>
<a href="@HPPHRPPLANNER_LINK@">hppHRPPlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>Algorithms to plan motion going under an obstacle. </td>
</tr>
<tr>
<td>
<a href="@HPPCMPPLANNER_LINK@">hppCmpPlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>Contact motion planning. </td>
</tr>
<tr>
<td>
<a href="@HPPWALKFOOTPLANNER_LINK@">hppWalkFootPlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>Foot step planning along a bounding box trajectory. </td>
</tr>
<tr>
<td>
<a href="@HPPWALKPLANNER_LINK@">hppWalkPlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>Walk planning for a humanoid robot among obstacles. </td>
</tr>
<tr>
<td>
<a href="@HPPLOA_LINK@">hppLoa</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>Whole body motion planning with local obstacle avoidance. </td>
</tr>
<tr>
<td>
<a href="@HPPLOAPLANNER_LINK@">hppLoaPlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>Global motion planning based on local obstacle avoidance. </td>
</tr>
<tr>
<td>
<a href="@HPPTIMINGPLANNER_LINK@">hppTimingPlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>Dynamic time parameterization of quasi-static paths. </td>
</tr>
......@@ -183,14 +183,14 @@
<tr>
<td>
<a href="@SLAM3DPLANNER_LINK@">slam3DPlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>path planning in environments modelled by vision </td>
</tr>
<tr>
<td>
<a href="@HPPDYNAMICOBSTACLE_LINK@">hppDynamicObstacle</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
</td>
<td>Handle dynamic obstacles in the environment. </td>
......@@ -201,7 +201,7 @@
<tr>
<td>
<a href="@HPPVISUALIZEMOVEPLANNER_LINK@">hppVisualizeMovePlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
</td>
<td>Visualization of trajectories. </td>
......@@ -212,7 +212,7 @@
<tr>
<td>
<a href="@HPPTUTORIALPLANNER_LINK@">hppTutorialPlanner</a>
<img src="pictures/kineo.jpg" alt="require Kineo SDK" style="kineo">
<img src="images/kineo.jpg" alt="require Kineo SDK" style="kineo">
</td>
<td>a simple planner to learn how to make and use a planner. </td>
</tr>
......@@ -222,7 +222,7 @@
<br><br>
<hr>
<center>
<img src="pictures/footer.jpg" height="100" alt="footer"><br>
<img src="images/footer.jpg" height="100" alt="footer"><br>
Humanoid Path Planner documentation<br>
</center>
</body>
......
<HTML>
<HEAD>
<TITLE>Humanoid Path Planner Documentation</TITLE>
<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
</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>
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>
Autoconf takes as input file <code>configure.ac</code> and builds <code>configure</code> script.
<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>
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.
<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">
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">
[~] 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 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 \
package2.cpp
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.
<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">
pkg-config package --cflags
</pre></div>
returns the compilation flags required by this package, including flags of dependencies.
<div class="fragment"><pre class="fragment">
pkg-config package --libs
</pre></div>
returns the linking flags required by this package, including flags of dependencies.
<div class="fragment"><pre class="fragment">
pkg-config package --modversion
</pre></div>
returns the version number of the package.
<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>. For instance,
<div class="fragment"><pre class="fragment">
pkg-config package --variable=prefix
</pre></div>
returns the installation prefix of the package.
<hr>
<center>
<img src="./pictures/footer.jpg" Height=100>
<br>Humanoid Path Planner documentation</br>
</center>
<hr>
</body>
</html>
About GNU Autoconf, GNU Automake and pkg-config
===============================================
Introduction
------------
*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
tools).
pkg-config
----------
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).