= RTEMS Add-On Packages =


The RTEMS Addon Packages is an infrastucture complete with examples of how to add libraries to RTEMS to make more complex applications.
= Getting the RTEMS Addon Package =

To get the RTEMS addon packages:
   $ git clone git://git.rtems.org/rtems-addon-packages.git \
     rtems-addon-packages
= Adding Libraries to RTEMS =

First we'll show how to build a library that is part of the RTEMS Addon Packages, then we'll look at the internals of complex port, finally, we'll discuss how to build your own port.
=  Setting up the Environment  =

First, set your RTEMS_MAKEFILE_PATH
   $ export RTEMS_MAKEFILE_PATH=/opt/rtems-4.11/i386-rtems4.11/pc386

Another (recommended choice) would be to add 

   export RTEMS_MAKEFILE_PATH=/opt/rtems-4.11/i386-rtems4.11/pc386

to your ~/.bashrc 

Second, to ensure i386-rtems4.11-gcc, will work, add your install point to your PATH.
   $ export PATH=$PATH:/opt/rtems-4.11
=  Using Makefile.avl  =

Navigate to the RTEMS Addon Packages
   $ cd ~/rtems-addon-packages

Navigate to the AVL library
   $ cd avl-1.4.0

Make the AVL library
   $ make -f ../RTEMS_Makefiles/Makefile.avl
=  Exploring Makefile.<<library>>  =

Makefile.<<library>> is a shell script to configure a package.

Look at rtems-addon-packages/RTEMS_Makefiles/Makefile.ncurses
   $ cat ~/rtems-addon-packages/RTEMS_Makefiles/Makefile.ncurses

The first four lines are comments that describe the package.
   #
   # Declare supported terminal types.
   # This value can be augmented/overridden by the site-configuration file
   #

The next line sets some environmental variables:
   TERMINALS=xterm,vt100,linux,ansi

Tell Makefile.ncurses to include the common RTEMS make rules...
   include ../RTEMS_Makefiles/Makefile.common

The next paragraph explains the dependencies:
   #
   # The following will work only if you have the latest ncurses version
   # of infocmp installed before trying to build for an RTEMS target.
   # The cf_cv_type_of_bool hack works around a bug when configuring
   # for a cross-target.
   #

all: is simply the makefile rule for all

Makefile.ncurses use some some cached variables.  
   cf_cv_type_of_bool=char

'''''Note:''' Cached variables help with cross-compiling by providing values that can't be determined by configure.''

Makefile.ncurses set the C++ compiler to the C compiler.
   CXX="$(CC)" 

Makefile.ncurses selected the TERM environmental variable to xterm
   TERM=xterm 

Makefile.ncurses invokes configure with the desired options.  Notice that each line ends with the " \" which "escapes out the newline" 
''Puts the cached variables on the same line as the configure invokation.''

Makefile.ncurses selects some complicated make options:
   make "TERM=xterm" "HOSTCC=gcc" "HOSTCCFLAGS=-I. -I../include" HOSTLDFLAGS=""

Finally, install the library:
   make install=  Porting Your Own Library to RTEMS  =

RTEMS has many special configurations required for it's use.  Where to look for headers and libraries, the start symbol, etc.  The simplest way to use these special configurations is to use an existing Makefile.<<library>>.
Note: make sure ALL prerequiset libraries are ported first!

Copy the Makefile.avl to Makefile.<<library>>
  $ cp ~/rtems-addon-packages/RTEMS_Makefiles/Makefile.avl \
       ~/rtems-addon-packages/RTEMS_Makefiles/Makefile.mylib

Put your sources in the rtems-addon-packages directory:
  $ cd ~/rtems-addon-packages/
  $ tar -xzf mylib.tar.xz
  $ cd ~/rtems-addon-packages/mylib

Now the long-haul of porting the library begins:
  $ make -f ../RTEMS_Makefiles/Makefile.mylib
=  Handling Errors: Disable Settings  =


Use configure --help to disable unneeded settings.  Disable those settings in rtems-addon-packages/RTEMS_Makefiles/Makefile.mylib.

  $ gedit ../RTEMS_Makefiles/Makefile.mylib

''For example: ../RTEMS_Makefiles/Makefile.mylib" 
   ./configure \
      --disable-dso'' \
=  Handling Errors: Caching Variables  =

Find the variable to cache to prevent the error.
  $ gedit rtems-addon-packages/mylib/configure

''Note: use the search feature of your word processor to find the error message, and look for variables to cache (for example: cf_cv_type_of_bool=char).  For gedit the search feature is: Ctrl+F'' 


Edit the rtems-addon-packages/RTEMS_Makefiles/Makefile.mylib.
  $ gedit ../RTEMS_Makefiles/Makefile.mylib

Using Makefile.ncurses has an example of adding cached variables to the configuration.

Continue adding and identifying cached variables ad-nauseum...
=  The RTEMS Addon Packages  =

RTEMS Addon Packages come with the following additions:

'''Name:''' avl-1.4.0

'''Site:''' http://savannah.gnu.org/projects/avl

'''Description:''' GNU libavl is a library in ANSI/ISO C for the manipulation of binary trees and balanced binary trees.

'''Name:''' gsl-1.9

'''Site:''' http://www.gnu.org/software/gsl/

'''Description:''' The GNU Scientific Library (GSL) is a numerical library for C and C++ programmers.

'''Name:''' libtecla-1.6.1

'''Site:''' http://www.astro.caltech.edu/~mcs/tecla/index.html

'''Description:''' The tecla library provides UNIX and LINUX programs with interactive command line editing facilities, similar to those of the UNIX tcsh shell.

'''Name:''' ncurses-5.9

'''Site:''' http://www.gnu.org/software/ncurses/

'''Description:''' The Ncurses (new curses) library is a free software emulation of curses in System V Release 4.0, and more.

'''Name:''' adline-6.2

'''Site:''' http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html

'''Description:''' The GNU Readline library provides a set of functions for use by applications that allow users to edit command lines as they are typed in.

The current maintainer of the RTEMS Addon Packages is: Joel Sherrill.