
                                     librt
                         rt library of General Functions

                <http://www.primenet.com/~jerome/software.html>

                               Douglas R. Jerome
                             <jerome@primenet.com>



==========
Disclaimer
==========

caveat:	This file was written by a nerd engineer type.  It may not be easy to
	read or understand.  You will, no doubt, find sentences that aren't
	sentences.



===========
Description
===========

The is a distribution of librt, the rt library.  I no longer remember exactly
what it is that "rt" stands for, maybe something like "run-time".

librt contains functions implementing general subsystems.  By "subsystem", I
mean a sort of abstract data type, or a poor man's object.  What this really
means is, for a hash table as an example, all the hash table functions are in
the same .c source file with the appropriate parts hidden away (static) from
the user of the hash table functions during link time.  All exportable
definitions and constants that the user of the hash table functions would want
are in a .h file.

Not everything in librt is so conceptually complete that it should legitimately
be called a "subsystem"; but they're in librt because they're reusable
functionality which are (hopefully) reinforced with debug aids, even if the
debug aids are just a bunch of assertions.

librt currently contains these subsystems:

	file in rt/src		functionality
	--------------		-------------
	rtBSDsock.c ........... BSD socket functions
	rtPOSIXflock.c ........ file lock (posix) functions
	rtPOSIXsys.c .......... general system calls
	rtbintree.c ........... binary tree subsystem
	rtfile.c .............. file/path name subsystem
	rthash.c .............. hash table subsystem
	rtio.c ................ general I/O functions
	rtlist.c .............. general list (queue/stack) subsystem
	rtmath.c .............. some math functions
	rtmem.c ............... dynamic memory allocation functions
	rtnotify.c ............ notification subsystem
	rtstr.c ............... strxxx wrappers
	rtstring.c ............ string handling functions
	rtsymbol.c ............ symbol structure managing function
	rtsymtab.c ............ symbol table subsystem
	xrtassert.c ........... hidden assertion helper functions

There are two drivers in the development of librt:

1.	There are so many thing I want to do, so many programs to write, so
	much functionality I want to implement-- I'm never going to have the
	time to do anywhere near all of it.  Anything I can do to reduce the
	amount of code to write will be a BIG help.  I've, therefore, become
	highly aware of the code I write and constantly look to abstract
	what ever I'm implementing into a common reusable subsystem.

2.	The fewer bugs I generate, the sooner I'll be done.  It is important
	that code be loaded with bug catching features.  Reusing code will
	help reduce bugs also.  The logical conclusion is to develop reusable
	code with bug catching features.

It is the goal of librt to implement bug catching features in commonly used
functionality and thereby provide a common, reusable base for constructing
solid applications.

For efficiency sake, librt can be compiled without DEBUG (see INSTALLATION
below) and continue to be used for its reusable subsystems.  I use two versions
of librt, one standard (actually with optimization) and one debug.  I use the
debug version for application development, and then relinked the application to
the standard, nondebug version of librt for distribution.  (Well, maybe someday
I'll have applications.)



============
Requirements
============

- ANSI Complient Compiler
- ANSI C Library
- BSD Socket Subsystem

	The librt code is mostly developed with strict ANSI compliance enforced
	by the compiler, not by my knowledge of ANSI.  The compilation command
	lines containing the ANSI compliance switchs are in my makefiles (which
	are the makefiles that are in this distribution).

	librt uses the BSD socket subsystem and won't completely build without
	it.  Without your compilation and runtime system having a BSD socket
	subsystem you'll probably get a librt.a when you build it, but it won't
	have its own BSD socket subsystem.

	With any modern system the above requirements shouldn't be any problem.
	If you run into other things, email me about it and I'll do my best to
	fix it up.



===========
Directories
===========

This distribution should have these directories:

	directory	contents
	---------	--------
	doc		HTML documentation, some day
	include		client accessable header files live here
	lib		librt.a appears in here
	src		librt *.c source code lives here
	t		test programs live here



=============
Documentation
=============

BUGFORM ....... Use this to send bug reports.  Please do use it.

BUGS .......... List of known bugs.

CHECKSUMS ..... A list of checksums for rt/include/*, rt/src/*, and rt/t/*.

COPYRIGHT ..... The LGPL.

CREDITS ....... List of people that I know have contributed to librt.

ERRATA ........ List of known limitations.  List user visible changes from the
		previous version.  To do list.

FAQ ........... Frequently Asked Questions.

INSTALL ....... Installation instructions and some troubleshooting tips.

LICENSE ....... LGPL

to do:  Technical Reference in HTML.  Check the doc directory (if it exists);
	you might find a goody, but don't hold your breath.



============
INSTALLATION
============

NOTE	This all probably works only with gcc or egcs.  I've used both and
	that's all I have access to.

NOTE	I highly recommend building and installing the debug version of librt,
	NOT because this library is flakey.  (But it might be-- actually I bet
	it is in some areas.  See ERRATA and BUGS.)  One reason I made this
	library is to help catch bugs during application development.  When
	librt is built for debugging, it will help you catch bugs; I hope.
	That was one of the goals of this library.  This library is loaded with
	assertions and data checks that are only enabled when built for
	debugging.  After you are comfortable with your application (and librt),
	relink your application with the standard, nondebug version of librt.

Unpack the rt library tarball, rt-x.x.x.tar.gz.  If for some strange reason you
don't have the tarball, you can get it at:

	http://www.primenet.com/~jerome/software.html.

Build librt Locally
-------------------

1.	Edit rt/src/Makefile to your liking.  Sorry, I haven't yet learned
	better.  I expect as much hacking to take place on librt's makefiles as
	on its source code.  If you use librt then you should look into the
	makefiles and understand what it is that you can do with CDEBUGFLAGS
	and CC_PARAMS.

2.	cd into rt/src, type the following into your shell prompt:

		make "CC_PARAMS=-O3"

	or if you want to make the library with debugging instrumentation and
	symbols (highly suggested), you can instead type:

		make "CDEBUGFLAGS=-DDEBUG -DTRACE" "CC_PARAMS=-g"

	You now have librt.a and librt.o sitting in rt/lib.  There probably
	also is librt.a.names and librt.o.names which are the corresponding
	symbol tables.

3.	You can use librt from its current location.  Simply add rt/include
	to your compilation include path, add rt/lib to your link library path,
	and link with a -lrt flag.

Install librt
-------------

	You might have to be a priviledged user (root) to do this.  Remember,
	you can change the install location in the make file; see step 1.
	I personally install into ${HOME}/local even though I own the system
	(a linux pc at home).

1.	The default installation directory is /usr/local.  The library is
	installed into /usr/local/lib, and the header files are installed into
	/usr/local/include.  These directories probably need to already exist.
	If you want to change the default install location you can edit
	rt/src/Makefile.

2.	Install the header files:  cd into rt/src, type the following into
	your shell prompt:

		make installheaders

	This will put the header files into /usr/local/include (if you haven't
	changed the default installation directory in rt/src/Makefile).

3.	Install the standard version:  cd into rt/src, type the following into
	your shell prompt:

		make installstandard

	This will put librt.a into /usr/local/lib (if you haven't changed the
	default installation directory in rt/src/Makefile).  Actually, in the
	installation directory the library will be `librt.a.standard' and a
	symbolic link `librt.a' will point to it.  Make sure you do this librt
	installation ONLY after making a standard library, NOT after making the
	debug version.

4.	Install the debug version:  cd into rt/src, type the following into
	your shell prompt:

		make installdebug

	This will put librt.a into /usr/local/lib (if you haven't changed the
	default installation directory in rt/src/Makefile).  Actually, in the
	installation directory the library will be `librt.a.debug' and a
	symbolic link `librt.a' will point to it.  Make sure you do this librt
	installation ONLY after making a debug library, NOT after making the
	standard version.

Summary
-------

1.	For the debug version of librt (HIGHLY recommended):  cd into rt/src,
	type the following into your shell prompt:

		make "CDEBUGFLAGS=-DDEBUG -DTRACE" "CC_PARAMS=-g"
		make installheaders
		make installdebug

	You will have (where <dir> is the installation directory which is
	defaulted to /usr/local):

			<dir>/include/*.h
			<dir>/lib/librt.a.debug
			<dir>/lib/librt.a -> <dir>/lib/librt.a.debug

2.	For the standard, nondebug version of librt:  cd into rt/src, type the
	following into your shell prompt:

		make "CC_PARAMS=-O3"
		make installheaders
		make installstandard

	You will have (where <dir> is the installation directory which is
	defaulted to /usr/local):

			<dir>/include/*.h
			<dir>/lib/librt.a.standard
			<dir>/lib/librt.a -> <dir>/lib/librt.a.standard



===========================
How to Make a gdb Backtrace
===========================

Backtraces can help me fix bugs that make applications crash.  If you find a
bug that crashes an application, please send a backtrace with your bug report.

To make a usefull backtrace, you need a core file with debugging information
produced by the application when it crashes.

When it does crash, type the following from your shell:

	script
        gdb <application> core

Then, in the gdb prompt type "bt".  Blammo, you've got the backtrace in front
of you.  Quit from gdb by typing "quit", then in the shell prompt type "quit".
The file named typescript will contain the backtrace.



==========
Copyrights
==========

librt is copyrighted by Douglas R. Jerome and is licensed, read the LICENSE
file, through the GNU Library General Public License.  Read the COPYRIGHT file
for the complete license.
