/** * @page libraries Writing Libraries * @ingroup guidedev * @author Bastian Blywis
The ScatterWeb firmware can be easily extended by libraries.
Some general rules:
A library basically consists of the following parts:
@verbatim LIBRARY_ROOT/makefile LIBRARY_ROOT/libLIBRARY_NAME.h LIBRARY_ROOT/doc/libLIBRARY_NAME.doc.html LIBRARY_ROOT/include/ScatterWeb.LIBRARY_NAME.h LIBRARY_ROOT/src/ScatterWeb.LIBRARY_NAME.c LIBRARY_ROOT/src/ScatterWeb.LIBRARY_NAME.internals.h @endverbatimYou can use the provided EMPTY library as template.
Please read the section \ref docs.
@section libraries_makefile Libray MakefileThe makefile is vital to the build process. Choose a descriptive name containing no whitespaces or special characters. The description should be no longer than a single line. List the names of any library this one depends on (without the lib-prefix).
Example:
@verbatim # # Configure this makefile here: # NAME := LIBRARY_NAME DESCRIPTION := This is a description of library LIBRARY_NAME DEPENDS := DEPENDING_ON_THIS_LIBRARY ############################################################################### SYSROOT := ../.. include $(SYSROOT)/System/makefile.library @endverbatim@section libraries_compiletime Compile Time Options
Store compile time options in this file.
The options of all libraries will be aggregated in the group \ref config_compile and are therefore listed at a central location.
Example:
@verbatim /** * @file libLIBRARY_NAME.h * @brief Default compile-time configuration of library LIBRARY_NAME * @ingroup config_compile, LIBRARY_NAME * @since 0.1 * @version $Revision$ * */ /** * @addtogroup config_compile * @{ */ #define SOME_OPTION 4 #ifndef IMPORTANT_STRING #define IMPORTANT_STRING FooBar #endif ///@} @endverbatim@section libraries_documentation Documentation
The content of this file gets the introduction of the library documentation.
Example:
@verbatim /** * @defgroup libLIBRARY_NAME LIBRARY_NAME * @ingroup driver \p Library LIBRARY_NAME is a vital part of this project and a state of the art implementation. Do not question its beauty! \p Since this library is beta and still in development you can contact the author directly if you are quite sure that you found a bug. For general questions please use the mailing list or consult the ScatterWeb website: http://scatterweb.mi.fu-berlin.de and the mailinglist scatterweb@lists.spline.inf.fu-berlin.de (subscription via the Website). */ @endverbatim@section libraries_public Public Interface
The public interface lets other people use your library.
An initialization function has to be included (see \ref libraries_init).
Example:
@verbatim /** * @file ScatterWeb.LIBRARY_NAME.h * @ingroup libLIBRARY_NAME * @brief LIBRARY_NAME library, Public interface * * @author Someone@section libraries_source Source Code* @date Aug 2007 * @since 1.1 * @version $Revision$ */ /** * @ingroup libLIBRARY_NAME * @{ */ #ifndef __LIBRARY_NAME_H__ #define __LIBRARY_NAME_H__ /****************************************************************************** * @name initialisation and usage * @{ */ /** * @brief Initialize LIBRARY_NAME * */ void libLIBRARY_NAME_Init(); #endif /*__LIBRARY_NAME_H__*/ /** @} */ @endverbatim
Your source code may consist of one or more file(-s) but you should name the main file including the initialization function in ScatterWeb.LIBRARY_NAME.c.
Example:
@verbatim /** * @file ScatterWeb.LIBRARY_NAME.c * @ingroup libLIBRARY_NAME * @brief LIBRARY_NAME library * * @author Someone@section libraries_private Private Definitions* @date Aug 2007 * @since 1.1 * @version $Revision$ * */ #include "ScatterWeb.LIBRARY_NAME.internals.h" #include "ScatterWeb.LIBRARY_NAME.h" /****************************************************************************** * @name Initialization and configuration * @{ */ void libLIBRARY_NAME_Init() { #warning library LIBRARY_NAME does nothing and is useless } /** @} */ @endverbatim
Keep private member definitions out of the headers file(-s) in the include directory. Place them in one or more seperate headers in the src path.
Use static whenever if applicable.
Example:
@verbatim /** * @file ScatterWeb.LIBRARY_NAME.internals.h * @ingroup libLIBRARY_NAME * @brief LIBRARY_NAME library * * @author Someone@section libraries_init Initialisation* @date Aug 2007 * @since 1.1 * @version $Revision$ * * Header file containing private declarations used by the LIBRARY_NAME library. */ #ifndef LIBRARY_NAME_INT_H_ #define LIBRARY_NAME_INT_H_ #include void superSecretFunction(); #endif /*LIBRARY_NAME_INT_H_*/ @endverbatim
Libraries have to provide an initialisation function. This function shall be named after the library (e.g. library "libSD" -> "libSD_Init()") and declared in the libraries configuration header-file (e.g. libSD.h).
These library initialisers are automatically invoked on system boot.
Example
@verbatim void libSD_Init() { // do initialisation } @endverbatim*/