debian/libdynamic-graph-doc.doc-base

-Document: dynamic-graph
-Title: Debian dynamic-graph Manual
-Author: Thomas Moulard <thomas.moulard@gmail.com>
-Abstract: Doxygen documentation of dynamic-graph.
-Section: Programming
-
-Format: HTML
-Index: /usr/share/doc/dynamic-graph/html/index.html
-Files: /usr/share/doc/dynamic-graph/html/*.html

debian/libdynamic-graph-doc.install

-usr/share/doc/dynamic-graph/*

debian/libdynamic-graph1.0.0.99.install

-usr/bin/*
-usr/lib/*.so.*
-usr/lib/plugin/*.so
-usr/share/man/*

debian/rules

-#!/usr/bin/make -f
-# -*- makefile -*-
-# Sample debian/rules that uses debhelper.
-# This file was originally written by Joey Hess and Craig Small.
-# As a special exception, when this file is copied by dh-make into a
-# dh-make output file, you may use that output file without restriction.
-# This special exception was added by Craig Small in version 0.37 of dh-make.
-
-# Uncomment this to turn on verbose mode.
-#export DH_VERBOSE=1
-
-override_dh_auto_configure:
-	dh_auto_configure -- -DGENERATE_DOC=ON
-
-%:
-	dh  $@

debian/source/format

-3.0 (quilt)

debian/watch

-# Watch control file for uscan
-# Rename this file to "watch" and then you can run the "uscan" command
-# to check for upstream updates and more.
-# See uscan(1) for format
-
-version=3
-
-http://githubredir.debian.net/github/jrl-umi3218/dynamic-graph (.*).tar.gz

doc/CMakeFiles/CMakeDirectoryInformation.cmake

-# CMAKE generated file: DO NOT EDIT!
-# Generated by "Unix Makefiles" Generator, CMake Version 2.8
-
-# Relative path conversion top directories.
-SET(CMAKE_RELATIVE_PATH_TOP_SOURCE "/home/blue/sot-devel/dg")
-SET(CMAKE_RELATIVE_PATH_TOP_BINARY "/home/blue/sot-devel/dg")
-
-# Force unix paths in dependencies.
-SET(CMAKE_FORCE_UNIX_PATHS 1)
-
-# The C and CXX include file search paths:
-SET(CMAKE_C_INCLUDE_PATH
-  "/usr/local/include"
-  )
-SET(CMAKE_CXX_INCLUDE_PATH ${CMAKE_C_INCLUDE_PATH})
-SET(CMAKE_Fortran_INCLUDE_PATH ${CMAKE_C_INCLUDE_PATH})
-
-# The C and CXX include file regular expressions for this directory.
-SET(CMAKE_C_INCLUDE_REGEX_SCAN "^.*$")
-SET(CMAKE_C_INCLUDE_REGEX_COMPLAIN "^$")
-SET(CMAKE_CXX_INCLUDE_REGEX_SCAN ${CMAKE_C_INCLUDE_REGEX_SCAN})
-SET(CMAKE_CXX_INCLUDE_REGEX_COMPLAIN ${CMAKE_C_INCLUDE_REGEX_COMPLAIN})

doc/CMakeFiles/documentation.dir/DependInfo.cmake

-# The set of languages for which implicit dependencies are needed:
-SET(CMAKE_DEPENDS_LANGUAGES
-  )
-# The set of files for implicit dependencies of each language:
-
-# Preprocessor definitions for this target.
-SET(CMAKE_TARGET_DEFINITIONS
-  "HAVE_LIBBOOST_THREAD"
-  "HAVE_PTHREAD"
-  )
-
-# Targets to which this target links.
-SET(CMAKE_TARGET_LINKED_INFO_FILES
-  )

doc/CMakeFiles/documentation.dir/build.make

-# CMAKE generated file: DO NOT EDIT!
-# Generated by "Unix Makefiles" Generator, CMake Version 2.8
-
-#=============================================================================
-# Special targets provided by cmake.
-
-# Disable implicit rules so canoncical targets will work.
-.SUFFIXES:
-
-# Remove some rules from gmake that .SUFFIXES does not remove.
-SUFFIXES =
-
-.SUFFIXES: .hpux_make_needs_suffix_list
-
-# Produce verbose output by default.
-VERBOSE = 1
-
-# Suppress display of executed commands.
-$(VERBOSE).SILENT:
-
-# A target that is always out of date.
-cmake_force:
-.PHONY : cmake_force
-
-#=============================================================================
-# Set environment variables for the build.
-
-# The shell in which to execute make rules.
-SHELL = /bin/sh
-
-# The CMake executable.
-CMAKE_COMMAND = /usr/bin/cmake
-
-# The command to remove a file.
-RM = /usr/bin/cmake -E remove -f
-
-# The program to use to edit the cache.
-CMAKE_EDIT_COMMAND = /usr/bin/ccmake
-
-# The top-level source directory on which CMake was run.
-CMAKE_SOURCE_DIR = /home/blue/sot-devel/dg
-
-# The top-level build directory on which CMake was run.
-CMAKE_BINARY_DIR = /home/blue/sot-devel/dg
-
-# Utility rule file for documentation.
-
-doc/CMakeFiles/documentation: doc/html/index.html
-
-doc/html/index.html:
-	$(CMAKE_COMMAND) -E cmake_progress_report /home/blue/sot-devel/dg/CMakeFiles $(CMAKE_PROGRESS_1)
-	@$(CMAKE_COMMAND) -E cmake_echo_color --switch=$(COLOR) --blue --bold "Generating html/index.html"
-	cd /home/blue/sot-devel/dg/doc && /usr/bin/doxygen "/home/blue/sot-devel/dg/doc/package.dox"
-
-documentation: doc/CMakeFiles/documentation
-documentation: doc/html/index.html
-documentation: doc/CMakeFiles/documentation.dir/build.make
-.PHONY : documentation
-
-# Rule to build all files generated by this target.
-doc/CMakeFiles/documentation.dir/build: documentation
-.PHONY : doc/CMakeFiles/documentation.dir/build
-
-doc/CMakeFiles/documentation.dir/clean:
-	cd /home/blue/sot-devel/dg/doc && $(CMAKE_COMMAND) -P CMakeFiles/documentation.dir/cmake_clean.cmake
-.PHONY : doc/CMakeFiles/documentation.dir/clean
-
-doc/CMakeFiles/documentation.dir/depend:
-	cd /home/blue/sot-devel/dg && $(CMAKE_COMMAND) -E cmake_depends "Unix Makefiles" /home/blue/sot-devel/dg /home/blue/sot-devel/dg/doc /home/blue/sot-devel/dg /home/blue/sot-devel/dg/doc /home/blue/sot-devel/dg/doc/CMakeFiles/documentation.dir/DependInfo.cmake --color=$(COLOR)
-.PHONY : doc/CMakeFiles/documentation.dir/depend
-

doc/CMakeFiles/documentation.dir/cmake_clean.cmake

-FILE(REMOVE_RECURSE
-  "CMakeFiles/documentation"
-  "html/index.html"
-)
-
-# Per-language clean rules from dependency scanning.
-FOREACH(lang)
-  INCLUDE(CMakeFiles/documentation.dir/cmake_clean_${lang}.cmake OPTIONAL)
-ENDFOREACH(lang)

doc/CMakeFiles/documentation.dir/progress.make

-CMAKE_PROGRESS_1 = 2
-

doc/CMakeFiles/progress.marks

-1

doc/CMakeLists.txt

-# Copyright 2010, Olivier Stasse, JRL, CNRS/AIST
-#
-# This file is part of dynamic-graph.
-# dynamic-graph is free software: you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public License
-# as published by the Free Software Foundation, either version 3 of
-# the License, or (at your option) any later version.
-#
-# dynamic-graph is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# General Lesser Public License for more details.  You should have
-# received a copy of the GNU Lesser General Public License along with
-# dynamic-graph. If not, see <http://www.gnu.org/licenses/>.
-
-
-SET(BUILD_DIR ${CMAKE_BINARY_DIR}/doc)
-SET(DOCDIR share/doc/${PROJECT_NAME})
-SET(HTMLDIR ${DOCDIR}/doxygen-html)
-
-# MANPAGE
-# -------
-#
-# Generate a pod man page from a template, then
-# generate the man page and compress it.
-# This macro also adds the installation rules.
-#
-MACRO(MANPAGE NAME)
-  FIND_PROGRAM(POD2MAN pod2man)
-  CONFIGURE_FILE(${NAME}.pod.in ${BUILD_DIR}/${NAME}.pod @ONLY)
-
-  ADD_CUSTOM_COMMAND(
-    OUTPUT ${NAME}.1
-    COMMAND ${POD2MAN} --section=1
-            --center="LOCAL USER COMMANDS"
-	    --release ${PROJECT_NAME} ${NAME}.pod
-	    > ${NAME}.1
-    DEPENDS ${BUILD_DIR}/${NAME}.pod)
-
-  ADD_CUSTOM_COMMAND(
-    OUTPUT ${NAME}.1.gz
-    COMMAND gzip -c ${NAME}.1 > ${NAME}.1.gz
-    DEPENDS ${BUILD_DIR}/${NAME}.1)
-  INSTALL(FILES ${BUILD_DIR}/${NAME}.1.gz DESTINATION share/man/man1)
-ENDMACRO(MANPAGE)
-
-
-# Generate Doxygen configuration file.
-CONFIGURE_FILE(package.dox.cmake ${BUILD_DIR}/package.dox)
-
-
-# Teach CMake how to generate the documentation.
-ADD_CUSTOM_TARGET(doc
-	COMMAND ${DOXYGEN_EXECUTABLE} package.dox
-	WORKING_DIRECTORY doc
-	DEPENDS ${BUILD_DIR}/dg-shell.1.gz ${BUILD_DIR}/dg-shell-plugin.1.gz
-)
-
-ADD_CUSTOM_COMMAND(
-	OUTPUT
-	${BUILD_DIR}/${PROJECT_NAME}.doxytag
-	${BUILD_DIR}/doxygen-html
-	COMMAND ${DOXYGEN_EXECUTABLE} package.dox
-	WORKING_DIRECTORY doc
-	COMMENT "Generating Doxygen documentation"
-)
-
-# Doxygen documentation installation rules.
-  # Install generated files.
-INSTALL(
-	CODE "EXECUTE_PROCESS(COMMAND make doc)"
-	FILES ${BUILD_DIR}/${PROJECT_NAME}.doxytag
-	DESTINATION share/doc/${PROJECT_NAME}/doxygen-html)
-INSTALL(DIRECTORY ${BUILD_DIR}/doxygen-html
-	DESTINATION share/doc/${PROJECT_NAME})
-INSTALL(DIRECTORY pictures DESTINATION ${HTMLDIR})
-
-
-# Man page generation.
-MANPAGE(dg-shell)
-MANPAGE(dg-shell-plugin)

doc/additionalDoc/debug-doc.h

+/**
+\page debug Debugging
+
+They are several ways to perform debugging in dynamic-graph depending on your
+needs or situation:
+- Programmatically inside the entity in C++, a logger will
+write inside a buffer in a
+different thread and output in a stream (either std::cout or a file). It is
+detailed in \subpage subp_debug_rt_logger.
+It provides 4 levels of messags :(DEBUG,INFO,
+WARNING, ERROR). It is described in details here: \subpage subp_logger
+
+- Programmatically in C++ to avoid overhead with macros and handling level as an
+int: \subpage subp_dbg_trace .
+- If you just need to collect informations from signals (like rosbag). You can
+use an entity called Tracer inside the graph:\subpage tracerdoc . <br> A real
+time version exists to write directly inside a memory buffer
+\subpage tracerrealtimedoc
+**/

doc/additionalDoc/debug-logger.h

+/**
+\page subp_logger Loggers
+
+\section sec_init_rt_logger Initialization of the logger
+
+\subsection subsec_init_rt_logger_hcpp Header and preprocessor variable
+
+In order to activate the logger you need to add the following lines:
+\code
+#define ENABLE_RT_LOG
+#include <dynamic-graph/logger.h>
+#include <dynamic-graph/real-time-logger.h>
+\endcode
+
+\subsection subsec_logger_ Initialize the output stream
+
+It is possible to set the output stream of the messages inside a file:
+\code
+  dynamicgraph::RealTimeLogger::instance();
+  of.open("/tmp/dg-LOGS.txt",std::ofstream::out|std::ofstream::app);
+  dgADD_OSTREAM_TO_RTLOG (of);
+
+  dynamicgraph::RealTimeLogger::destroy();
+\endcode
+
+\section sec_use_rt_logger Using the rt_logger
+
+
+\code
+// Somewhere in your library
+dgRTLOG() << "your message. Prefer to use \n than std::endl."
+\endcode
+
+
+Here the output file is "/tmp/dg-LOGS.txt".
+
+
+Specifying the file with __FILE__ and the line inside the file by __LINE__ are
+necessary for the STREAM messages. Indeed they are indexed using the two values.
+The default values "" and 0 for the counting are not well understood.
+*/

doc/additionalDoc/debug-trace-doc.h

+/**
+\page subp_dbg_trace Debugging with macros and level
+
+\section subp_dbg_trace_intro Introduction
+The idea of this class and collection of MACROS is to specify
+a level for a message, and record the message in a stream according to this
+level. In addition there are mechanisms allowing that no time is wasted in
+condition test. You can therefore let the debugging messages inside the code
+without impact on performances.
+
+\section subp_dbg_trace_set_on_macros Setting up dgDEBUG macros
+
+To allow message display the entity must be compiled with the macro
+\code
+#define VP_DEBUG 1
+\endcode
+Commenting or removing this macro disable all the messages specified
+by the following macros.
+
+The level up to which the messages are accepted for display is
+specified by:
+\code
+#define VP_DEBUG_MODE 50
+\endcode
+
+In the constructor of the entity, the file where all the messages
+are written is specified by:
+\code
+  dynamicgraph::dgDEBUGFLOW.openFile("/tmp/dynamic-graph-traces.txt");
+\endcode
+
+\section subp_dbg_trace_using_macros Using dgDEBUG macros
+
+To print that the beginning of a method is being executed use the following
+macros: \code dgDEBUGIN(5); \endcode 5 here specifies the minimum level that you
+be specified by VP_DEBUG_MODE for this message to be displayed.
+
+It will generate the following output:
+\code
+/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#46) :# In {
+\endcode
+The output displays the name of the source file, the name of the method,
+the line where is the macro, and the message itself.
+
+When going out of the method:
+\code
+    dgDEBUGOUT(5);
+\endcode
+
+This generates the following output:
+\code
+/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#54) :# Out }
+\endcode
+
+A message inside the code is written through:
+\code
+      dgDEBUG(5) << "Here is a test" << std::endl;
+\endcode
+
+This generates the following output:
+\code
+/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#52) :Here is a
+test \endcode
+
+\section subp_dbg_trace_wrk_exp Working example
+
+A full working example is given here:
+\include tests/debug-trace.cpp
+ */

doc/additionalDoc/dgshell_doc.h

-/**
-
-\page dgshell_doc dg-shell executable
-The dynamic-graph shell program "dg-shell" allows access to the dynamic-graph library's
-Interpreter class, which can execute commands and scripts from the command line.
-It can be found in the installation prefix's bin/ directory.
-
-There is also a linux shell script available, dg-shell-plugin, that creates a
-and loads a default script whose goal is to load useful plugins at startup
-(shell-functions and shell-procedure).
-
-For an example of shell commands and scripts, see \ref scriptingabout.
-
-**/

doc/additionalDoc/doc-command.h

+/** \page subpage_command Commands
+
+\section subpage_command_intro Quick introduction
+
+Commands are allowing to expand the entities.
+It has no real interest in C++, and is mostly targeted to scripting languages
+used to manipulate the control graph.
+dynamic-graph-python provides a mecanism which is automatically binding command
+to python. The main interest for a programmer is that there is no additional
+lines to add. It is realized through CMake rules provided by the submodule
+jrl-cmakemodules.
+
+\section subpage_command_using Extending entities
+
+\subsection subpage_command_setters_and_getters Setters and getters
+
+To modify a quantity with a special method of your class, it is recommanded to
+use Setter.
+
+For instance to specify the size of the state in one entity and calls the
+method setStateSize it is possible to write:
+
+\code
+    docstring = "\n"
+                "    Set size of state vector\n"
+                "\n";
+    addCommand("resize", new command::Setter<Device, unsigned int>(
+                             *this, &Device::setStateSize, docstring));
+\endcode
+
+Getting the information of the member of the class can be realized with
+the following snippet:
+
+\code
+    addCommand("getTimeStep",
+               command::makeDirectGetter(
+                   *this, &this->timestep_,
+                   command::docDirectGetter("Time step", "double")));
+\endcode
+
+\subsubsection subsubpage_command_void_multiple_args Implementing a command
+
+Templates are provided to create commands returning no value, but with up to
+4 arguments.
+
+In order to call the following method:
+\code
+  void four_args(const int &, const int &, const int &, const int &) {
+    test_four_args_ = true;
+  }
+\endcode
+
+It is sufficient to add in the constructor:
+\code
+    addCommand("4_args",
+               makeCommandVoid4(
+                   *this, &CustomEntity::four_args,
+                   docCommandVoid4("four args", "int", "int", "int", "int")));
+\endcode
+
+The arguments are limited to the types provided by the class Value.
+
+\subsection subpage_command_void_multiple_args Commands returning a value
+
+The templates with the prefix makeCommandReturnType are allowing to return
+a type.
+
+For instance to add a command returning a type with two arguments:
+\code
+  std::string two_args_ret(const int &, const int &)
+  { test_two_args_ = true; return std::string("return");}
+\endcode
+
+In the constructor, the following snippet shows to create the command:
+\code
+    addCommand("2_args_r",
+               makeCommandReturnType2(
+                 *this, &CustomEntity::two_args_ret,
+                 docCommandVoid2("two args", "int","int")));
+\endcode
+
+\section section_calling_a_generic_command Calling a generic command
+
+Of course calling in C++ a command amounts to call directly the method.
+However in the context of writing a wrapper for another language,
+one may wants to find a command and build the call.
+
+All the commands of an entity are store in a map. The strings storing the
+commands name are the map keys.
+
+Therefore calling the previous command can be done with the following snippet:
+\code
+
+std::map<const std::string, Command *> aCommandMap =
+ this->getNewStyleCommandMap();
+
+std::string cmd_name = "4_args";
+
+std::map<const std::string, Command *>::iterator it_map;
+
+it_map = aCommandMap.find(cmd_name);
+if (it_map == aCommandMap.end())
+
+int first_arg = 1;
+Value aValue(first_arg);
+std::vector<Value> values;
+
+for (unsigned int i = 0; i < 4; i++)
+  values.push_back(aValue);
+
+it_map->second->setParameterValues(values);
+it_map->second->execute();
+it_map->second->owner();
+it_map->second->getDocstring();
+
+\endcode
+
+when returning a value the line with the call to execute is :
+\code
+Value aValue =it_map->second->execute();
+\endcode
+
+*/

doc/additionalDoc/doc-debug-real-time-logger.h

+/**
+\page subp_debug_rt_logger Real-time Logger
+
+ \section real_time_logger_quick_intro Quick introduction
+ Each entity has a protected logger_ object.
+ The simplest way to have information while running your graph is to initialize
+ it in the constructor, and then display information in the methods.
+
+ You can then change the level of information you want to display using
+ either the entity method setLoggerVerbosityLevel()
+ or the corresponding python bindings.
+
+ \section real_time_logger_modifying_entities Putting information in your
+entity.
+
+ It is possible to define the periodicity of the logger:
+ \code
+ logger_.setTimeSample(0.001);
+ \endcode
+
+ To define the periodicity at which one wants to print information:
+ \code
+ logger_.setStreamPrintPeriod(0.005);
+ \endcode
+
+ Several level of verbosity are possible:
+ \code
+ logger_.setVerbosity(VERBOSITY_ALL);
+ \endcode
+ The full list of options are:
+<ul>
+<li>VERBOSITY_ALL: Accept all messages</li>
+<li>VERBOSITY_INFO_WARNING_ERROR: Accept messages at minimum level : INFO,
+WARNING, ERROR</li> <li>VERBOSITY_WARNING_ERROR: Accept messages at minimum
+level : WARNING, ERROR</li> <li>VERBOSITY_ERROR: Accept messages at minimum
+level : ERROR</li>
+</ul>
+
+It is specified by the enum LoggerVerbosity
+
+ It is possible to display information according to various level of debug:
+ \code
+ sendMsg("This is a message of level MSG_TYPE_DEBUG", MSG_TYPE_DEBUG);
+ \endcode
+ or
+ \code
+ DYNAMIC_GRAPH_ENTITY_DEBUG   (*this) << "This is a message of level
+MSG_TYPE_DEBUG\n"; DYNAMIC_GRAPH_ENTITY_INFO    (*this) << "This is a message of
+level MSG_TYPE_INFO\n"; DYNAMIC_GRAPH_ENTITY_WARNING (*this) << "This is a
+message of level MSG_TYPE_WARNING\n"; DYNAMIC_GRAPH_ENTITY_ERROR   (*this) <<
+"This is a message of level MSG_TYPE_ERROR\n"; DYNAMIC_GRAPH_ENTITY_DEBUG_STREAM
+(*this) << "This is a message of level MSG_TYPE_DEBUG_STREAM\n";
+ DYNAMIC_GRAPH_ENTITY_INFO_STREAM    (*this) << "This is a message of level
+MSG_TYPE_INFO_STREAM\n"; DYNAMIC_GRAPH_ENTITY_WARNING_STREAM (*this) << "This is
+a message of level MSG_TYPE_WARNING_STREAM\n"; DYNAMIC_GRAPH_ENTITY_ERROR_STREAM
+(*this) << "This is a message of level MSG_TYPE_ERROR_STREAM\n"; \endcode
+
+
+   \note Thread safety. This class expects to have:
+   - only one reader: the one who take the log entries and write them somewhere.
+   - one writer at a time. Writing to the logs is **never** a blocking
+     operation. If the resource is busy, the log entry is discarded.
+*/