Unverified Commit af581abb authored by Joseph Mirabel's avatar Joseph Mirabel Committed by GitHub
Browse files

Merge pull request #33 from jmirabel/devel

Generation of the documentation.
parents eebbcdea 7a969b59
cmake_minimum_required(VERSION 2.8)
SET(INSTALL_DOCUMENTATION OFF)
include(cmake/base.cmake)
# These variables have to be defined before running setup_project
......@@ -64,78 +63,53 @@ FOREACH(PKG ${SETUP_DOC_PKG})
ELSE(DEFINED ${PREFIX}_DOCDIR)
SET(DOC_PREFIX ${${PREFIX}_PREFIX}/share/doc/${PKG}/doxygen-html)
ENDIF(DEFINED ${PREFIX}_DOXYGENDOCDIR)
STRING(REPLACE ${CMAKE_INSTALL_PREFIX}/share/doc .. DOC_PREFIX "${DOC_PREFIX}")
STRING(REPLACE ${CMAKE_INSTALL_PREFIX}/share/doc ../.. DOC_PREFIX "${DOC_PREFIX}")
IF (EXISTS ${DOC_PREFIX}/main.html)
SET(${DOC_VAR}_LINK ${DOC_PREFIX}/main.html)
SET(${DOC_VAR}_URL ${DOC_PREFIX}/main.html)
ELSE (EXISTS ${DOC_PREFIX}/main.html)
SET(${DOC_VAR}_LINK ${DOC_PREFIX}/index.html)
SET(${DOC_VAR}_URL ${DOC_PREFIX}/index.html)
ENDIF (EXISTS ${DOC_PREFIX}/main.html)
SET(${DOC_VAR}_LINK "<a href='${${DOC_VAR}_URL}'>${PKG}</a>")
ELSE(${PREFIX}_FOUND)
SET(${DOC_VAR}_LINK ${PKG}-missing.html)
SET(PACKAGE_NAME ${PKG})
SET(DOC_PKG_NAME "hpp_doc_missing_${DOC_VAR}")
SET(${DOC_VAR}_LINK "\\ref ${DOC_PKG_NAME}")
SET(${DOC_VAR}_URL ${${DOC_VAR}_LINK})
SET(STEPS)
IF(DEFINED ${PKG}_giturl)
SET(STEPS "${STEPS} <li>
to get the source code through <code>git</code>:
<code>git clone ${${PKG}_giturl}</code>,
then configure, compile and install the package.</code></li>")
SET(STEPS "${STEPS}\\li get the source code through \\c git:
\\code git clone --recursive ${${PKG}_giturl} \\endcode
Then configure, compile and install the package.\n")
ENDIF(DEFINED ${PKG}_giturl)
IF(DEFINED ${PKG}_robotpkg_package)
SET(STEPS "${STEPS} <li>
install it through <code>robotpkg</code>:
<code>cd robotpkg/${${PKG}_robotpkg_package};
make update</code></li>")
SET(STEPS "${STEPS}\\li install it through \\c robotpkg :
\\code
cd robotpkg/${${PKG}_robotpkg_package}
make update
\\endcode")
ENDIF(DEFINED ${PKG}_robotpkg_package)
CONFIGURE_FILE(doc/missing.html.in ${CMAKE_BINARY_DIR}/doc/${PKG}-missing.html @ONLY)
INSTALL(FILES ${CMAKE_BINARY_DIR}/doc/${PKG}-missing.html
DESTINATION ${CMAKE_INSTALL_DOCDIR})
CONFIGURE_FILE(doc/missing.dox.in ${CMAKE_BINARY_DIR}/doc/${PKG}-missing.dox @ONLY)
ENDIF(${PREFIX}_FOUND)
ENDFOREACH(PKG ${SETUP_DOC_PKG})
SET(EXTRA_HTML_FILES
doc/corba.html
doc/algorithm.html
doc/gui.html
doc/main.html
doc/index.html
doc/tree.html)
CONFIG_FILES(${EXTRA_HTML_FILES})
FOREACH(HTML_FILE ${EXTRA_HTML_FILES})
INSTALL(FILES ${CMAKE_BINARY_DIR}/${HTML_FILE} DESTINATION ${CMAKE_INSTALL_DOCDIR})
ENDFOREACH(HTML_FILE ${EXTRA_HTML_FILES})
CONFIG_FILES(doc/main.dox doc/doxygenLayout.xml)
ADD_CUSTOM_COMMAND(OUTPUT ${CMAKE_BINARY_DIR}/graphDep.dot
COMMAND ${CMAKE_SOURCE_DIR}/scripts/packageDep --quiet --output ${CMAKE_BINARY_DIR}/graphDep.dot ${SETUP_DOC_PKG}
COMMAND sed -i 's/size = \"12,15\"//' ${CMAKE_BINARY_DIR}/graphDep.dot)
ADD_CUSTOM_COMMAND(OUTPUT ${CMAKE_BINARY_DIR}/dependencies.png
COMMAND dot -o ${CMAKE_BINARY_DIR}/dependencies.png -Tpng ${CMAKE_BINARY_DIR}/graphDep.dot
DEPENDS graphDep.dot)
ADD_CUSTOM_COMMAND(OUTPUT ${CMAKE_BINARY_DIR}/graphDep.html
COMMAND dot -o ${CMAKE_BINARY_DIR}/graphDep.html -Tcmapx ${CMAKE_BINARY_DIR}/graphDep.dot
DEPENDS graphDep.dot)
ADD_CUSTOM_COMMAND(OUTPUT graph-dependency.html
COMMAND cat ${CMAKE_SOURCE_DIR}/doc/graph-dependency.html.head
${CMAKE_BINARY_DIR}/graphDep.html
${CMAKE_SOURCE_DIR}/doc/graph-dependency.html.foot
> ${CMAKE_BINARY_DIR}/graph-dependency.html
DEPENDS ${CMAKE_BINARY_DIR}/graphDep.html ${CMAKE_BINARY_DIR}/dependencies.png)
COMMAND ${CMAKE_SOURCE_DIR}/scripts/packageDep --quiet --output ${CMAKE_BINARY_DIR}/graphDep.dot ${SETUP_DOC_PKG})
ADD_CUSTOM_TARGET(generate-html ALL
DEPENDS graph-dependency.html)
DEPENDS graphDep.dot)
INSTALL(FILES
doc/custom.css
doc/doxygen.css
doc/tabs.css
${CMAKE_BINARY_DIR}/graph-dependency.html
doc/index.html
doc/jquery-3.3.1.min.js
${CMAKE_BINARY_DIR}/doc/main.dox
DESTINATION ${CMAKE_INSTALL_DOCDIR})
INSTALL(FILES
${CMAKE_BINARY_DIR}/dependencies.png
DESTINATION ${CMAKE_INSTALL_DOCDIR}/images)
INSTALL(DIRECTORY
doc/images
doc/figures
DESTINATION ${CMAKE_INSTALL_DOCDIR})
INSTALL(
FILES ${CMAKE_CURRENT_BINARY_DIR}/doc/doxygen-xml/index.xml
DESTINATION ${CMAKE_INSTALL_DOCDIR}/doxygen-html)
setup_project_finalize()
PROJECT_NAME = Humanoid Path Planner
INPUT = @PROJECT_SOURCE_DIR@/doc \
@PROJECT_BINARY_DIR@/doc
DOTFILE_DIRS = @PROJECT_BINARY_DIR@
HTML_EXTRA_STYLESHEET = @PROJECT_SOURCE_DIR@/doc/doxygen_extra.css
FILE_PATTERNS = *.dox
GENERATE_TREEVIEW = YES
LAYOUT_FILE = @PROJECT_BINARY_DIR@/doc/doxygenLayout.xml
GENERATE_XML = YES
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="custom.css" rel="stylesheet" type="text/css">
<title>Humanoid Path Planner documentation</title>
</head>
<body>
<h1>Packages implementing algorithms</h1>
<h3>Technical tools</h3>
<table class="pkglist">
<tr>
<td>
<a href="@HPPUTIL_LINK@">hpp-util</a>
</td>
<td>technical tools for the HPP project (logging, benchmark, quality assurance tools),</td>
</tr>
</table>
<h3>Motion planning for humanoid systems</h3>
<table class="pkglist">
<li><b>Kinematic chain with geometry</b></li>
<table class="pkglist">
<tr>
<td>
<a href="@HPPFCL_LINK@">Modified version of Flexible collision library</a>
</td>
<td>Collision detection and distance computation,</td>
</tr>
<tr>
<td>
<a href="@PINOCCHIO_LINK@">pinocchio</a>
</td>
<td>implementation of kinematic chain with dynamic computations,</td>
</tr>
<tr>
<td>
<a href="@HPPPINOCCHIO_LINK@">hpp-pinocchio</a>
</td>
<td>Interface between pinocchio and hpp-core,
</td>
</tr>
</table>
<li><b>Non linear constraints</b></li>
<table class="pkglist">
<tr>
<td>
<a href="@HPPCONSTRAINTS_LINK@">hpp-constraints</a>
</td>
<td>definition of some nonlinear constraints,</td>
</tr>
</table>
<li><b>Path planning</b></li>
<table class="pkglist">
<tr>
<td>
<a href="@HPPCORE_LINK@">hpp-core</a>
</td>
<td>definition of basic classes, path planning problems and solvers,</td>
</tr>
</table>
<li><b>Path Planning for humanoid robots</b></li>
<table class="pkglist">
<tr>
<td>
<a href="@HPPWHOLEBODYSTEP_LINK@">hpp-wholebody-step</a>
</td>
<td>whole-body and walk planning using sliding path approximation.</td>
</tr>
</table>
<li><b>Manipulation Planning</b></li>
<table class="pkglist">
<tr>
<td>
<a href="@HPPMANIPULATION_LINK@">hpp-manipulation</a>
</td>
<td>Manipulation planning.</td>
</tr>
<tr>
<td>
<a href="@HPPMANIPULATIONURDF_LINK@">hpp-manipulation-urdf</a>
</td>
<td>Enhance hpp-pinocchio to support datas required by hpp-manipulation.</td>
</tr>
</table>
</ul>
<br><br>
<hr>
<center>
<img src="images/footer.jpg" height="100" alt="footer"><br>
Humanoid Path Planner documentation<br>
</center>
</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).
`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
[source,shell]
---------------------------------------------------------------------
prefix=/my/prefix
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include
datarootdir=${prefix}/share
docdir=${prefix}/share/doc/hpp-walkfootplanner
doxygendocdir=${prefix}/share/doc/hpp-walkfootplanner/doxygen-html
Name: hpp-walkfootplanner
Description: HPP walk foot planner
URL:
Version: 1.2.1.215.0493
Requires: hppCore >= 1.8, roboptim-trajectory >= 0.1, jrlMathTools >= 1.1
Conflicts:
Libs: -L${libdir} -lhpp-walkfootplanner
Libs.private:
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
[source,shell]
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
customizing:
* 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.
`AC_INIT`
~~~~~~~~~
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 `configure.ac` file.
[source,autoconf]
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. `hpp@laas.fr` 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'',
``hpp-my-long-pkg''.
* `url` is the package website URL.
.GNU Autoconf configuration for ``hpp-walkfootplanner''.
[source,autoconf]
AC_INIT ([HPP walk planner],
[3.14], [hpp@laas.fr], [hpp-walkplanner], [http://www.laas.fr])
WARNING: You *must* call this macro in your `configure.ac` file.
`AM_INIT_AUTOMAKE`
~~~~~~~~~~~~~~~~~~
This macro initialized GNU Automake. This tool which can be used to
generate `Makefile` files will be described in the next section.
[source,autoconf]
AM_INIT_AUTOMAKE([automake-options])
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
[source,autoconf]
AM_INIT_AUTOMAKE([1.9.6 dist-bzip2 -Wall nostdinc])
`PKG_CHECK_MODULES`
~~~~~~~~~~~~~~~~~~~
This macro runs pkg-config and automatically create some GNU Autoconf
variables that contains package information.
.Checking for package `hpp-walkplanner`
[source,autoconf]
PKG_CHECK_MODULES([HPP_WALKPLANNER], [hpp-walkplanner >= 0.7])
AC_SUBST([HPP_WALKPLANNER_PREFIX],
[`$PKG_CONFIG hpp-walkplanner --variable=prefix`])
AC_SUBST([HPP_WALKPLANNER_CFLAGS])
AC_SUBST([HPP_WALKPLANNER_LIBS])
If this piece of code is included in your `configure.ac` 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
`Makefile.am` files.
`AC_CONFIG_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/Makefile.am`, you should add `a/b/Makefile` to the list).
[source,autoconf]
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`
~~~~~~~~~~~
`AC_OUTPUT` should be the last line of the `configure.ac` file, It is
needed for GNU Autoconf to work properly.
WARNING: You *must* call this macro at the end of your `configure.ac`
file.
GNU Automake
------------
GNU Automake helps developpers to write robust and portable `Makefile`
files. It takes as input `Makefile.am` 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 Makefile.am
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 `Makefile.am` file.
* `$(top_srcdir)` corresponds to the directory where `configure.ac` 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
^^^^^^^^^
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
[source,makefile]
---------------------------------------------------------------------
# Defining a new library to compile.
lib_LTLIBRARIES = libhpp-package.la
# Listing the associated sources.
libhpp_package_la_SOURCES = \
package1.cpp \
package2.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 ``libhpp-package.la'' is
transformed in ``libhpp_package_la''.
Programs
^^^^^^^^^
Programs are defined like libraries.
* `noinst_PROGRAMS` lists programs that will not be installed.
* `bin_PROGRAMS` lists programs that will be installed in `bindir`.
Variable EXTRA_DIST
~~~~~~~~~~~~~~~~~~~
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.
Resources
---------
* link:http://www.gnu.org/software/autoconf/manual[GNU Autoconf manual]
* link:http://www.gnu.org/software/automake/manual[GNU Automake manual]
* link:http://pkg-config.freedesktop.org[pkg-config website]
* link:http://www.lrde.epita.fr/~adl/autotools.html[Autotools tutorial]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="custom.css" rel="stylesheet" type="text/css">
<title>Humanoid Path Planner documentation</title>
</head>
<body>
<h1>Packages implementing CORBA interfaces</h1>
<p>
The following packages implement Corba communication functionalities
<ul>
<li><a href="@HPPCORBASERVER_LINK@">hpp-corbaserver</a> Corba server embedding a hpp::core::ProblemSolver instance.</li>
<li><a href="@HPPWHOLEBODYSTEPCORBA_LINK@">hpp-wholebody-step-corba</a> Corba server for <a href="@HPPWHOLEBODYSTEPPLANNER_LINK@">hpp-wholebody-step</a>.</li>
<li><a href="@HPPMANIPULATIONCORBA_LINK@">hpp-manipulation-corba</a> Corba server for <a href="@HPPMANIPULATION_LINK@">hpp-manipulation</a>.</li>
</ul>
</p>
<br><br>
<hr>
<center>
<img src="images/footer.jpg" height="100" alt="footer"><br>
Humanoid Path Planner documentation<br>
</center>
</body>
</html>
table.pkglist
{
padding: 1em;
}
body, table, div, p, dl {
font-family: Lucida Grande, Verdana, Geneva, Arial, sans-serif;
font-size: 12px;
}
/* @group Heading Levels */
h1 {
text-align: center;
font-size: 150%;
font-variant: small-caps;
}
h2 {
font-size: 120%;
}
h3 {
font-size: 100%;
}
h4 {
color: #3C9A35;
}
h2, h3, hr {
font-variant: small-caps;
color:#0066CC;
}
/* @end */
caption {
font-weight: