/** * @page libraries Writing Libraries * @ingroup guidedev * @author Bastian Blywis

The ScatterWeb firmware can be easily extended by libraries.

Some general rules:

- Write a library if the included source code is an optional component and/or a complete module on its own, e.g. a driver (see \ref driver).
- Do not expose "private" members (functions or variables). Use the keyword `static` if possible
to adjust the scope.
- Document your code as usual, but put your focus especially on the "public" members.
- Only a thoughtful developed interface keeps your code useful for other people.

A library basically consists of the following parts:

1. \ref libraries_makefile with name, description and dependencies
2. \ref libraries_compiletime
3. \ref libraries_documentation
4. A \ref libraries_public
5. \ref libraries_source file(-s)
6. \ref libraries_private
7. \ref libraries_init

A typical source tree therefore looks like this:

    @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
    @endverbatim

You can use the provided EMPTY library as template.

Please read the section \ref docs.

@section libraries_makefile Libray Makefile

The 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
     * @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

@section libraries_source Source Code

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
     * @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

@section libraries_private Private Definitions

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
     * @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

@section libraries_init Initialisation

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

*/