
Welcome to the FreeDOS C Library.
=================================

This file will be a short guide to the overall layout of the archive, 
the current status of the FreeDOS C Library and how you can rebuild it.

Status
------

The FreeDOS C Library (hereafter CLib or LibC) is currently in a very
fragile state. At the moment we are testing a new method of building
the library which should make it simpler for people in the future.

Currently LibC covers the majority of the functions that need to be 
implemented by the ANSI C standard. Very little work has been done on 
the math and time portions of the library, likewise compatibility for 
programs using Borland's DOS library and Microsoft's DOS library is 
still in progress.

The overall status report says:
+ The HEAP section does only work for near data memory models (tiny, small
and medium). That means that functions requiring the heap, e.g. the FIO
section or the opendir() function, will work for only them, too
+ The MEMORY section covers the <string.h> and portions of <stdlib.h>
requirements for ANSI C and POSIX.1 fully and define some additional
functions.
+ The DIR section covers the lowlevel ANSI C/POSIX.1 "Files and Directories"
functions, except readdir_r(), utime(), link(), chmod(), chown().
+ The IO section covers the handle based POSIX.1 compatible file functions
fully, except for "errno".
+ The FIO section covers the filepointer based ANSI C compatible file
functions except temporary files and float arethmetics.
+ The LOCALE section currently covers the ANSI C compatible <ctype.h>
functions as macros only.

Please see the file status.txt located in the doc subdirectory for
further details.

Rebuilding
----------

PREPARING

Before you can rebuild CLib by one of the three ways, you should make
sure that CLib is configured as you wish it.

First, give CLib the correct lowest-level information about the types
your compiler uses, e.g. sizeof(int) == ??? and sizeof(long) == ???.
To do this change into the BIN section, compile & run mkLimits.c.
See the beginning of the file for more information and make sure you
compile mkLimits.c with the environment your compiler normally uses,
e.g. the libraries and include files that were shipped with it.
Running mkLimits.Exe will produce a _LOCAL.INC file, copy it into
the CONF section overwriting the 0-byte file currently there.

Second, change into the INCLUDE section and edit _CONFIG.H. This
file contains _all_ the options an user can manipulate. The topmost
macros turn on or off debugging support, the latter manipulate several
static arrays, delays etc. Note, for boolean macros (true/false, present/
absent) the comment describes what happens if the line is not commented
out, e.g.:
//#define NDEBUG		/* turn off general debug support */
means that if this line remains unchanged the general debug support is
on (well, unless you defined this macro on another way).
"General debug support" mainly refers to the assert() macros, if NDEBUG
is present, those macros are not compiled into the object files.


WAY 1

STEP ONE

In order to rebuild LibC you will require (at least) the following:
a compiler, an assembler and an archiver (also known as a librarian). You 
will also require a 'make' utility in order to use the supplied makefiles.
In order to process each of the rules on the makefile you will also need
some kind of shell, command.com is (barely) adequate for this.

1. Compiler
	At this time the only compiler used to build the LibC has been 
	Borland's C compiler (tested with versions 4.02 and 5.2). Should 
	you wish to use another compiler, please modify the file 
	"compiler.mak" and forward and changes to the LibC maintainer.

2. Assembler
	You can use either Borland's Assembler (tasm) or the freely
	available ArrowASM (from your nearest FreeDOS site [1]).
	Microsoft's Assembler (masm) and A86 are reported to work, but 
	neither have been tested recently. Please select the assembler
	to use and modify the file "assemble.mak" accordingly.

3. Archiver / Librarian
	The only archiving utility used to create the library has been 
	Steffen's LIBBER [2]. Should you wish to use another archiving
	utility, please modify the file "archiver.mak" as appropriate.

4. 'make' utility
	The makefiles used for the FreeDOS LibC are very standard and
	should work with most make utilities. However only the only
	two which we have tested against are GNU Make (3.58) [3] and 
	DMake (4.10) [4]. GNU Make appears to have a bug which causes 
	memory corruption and eventually leads to the system halting.

	We recommend you use DMake until this has been fixed, or another
	'make' utility which understands the makefiles written. DMake is
	normally installed under the name 'dmake'. GNU Make is sometimes
	installed as 'gmake' and often as 'make'. Hereafter the term
	'make' refers to either DMake or GNU Make and whatever form is
	need to invoke them.

	Please update "make.mak" to match your needs.

5. Compiling definitions
	Due to the fact that currently a very basic set of Make functions
	are used you must set the memory model you want to built CLib for
	in the file "defines.mak", by default the small model is activated.
	NOTE: Currently only memory models with near data pointers (tiny,
	small and medium) are supported by all included functions!

Please read the documentation that accompanies each of these utilites
for further details on their installation.

STEP TWO

Once you have these four things, it is vital that you modify the following
makefiles as appropriate for your setup.

	Compiler definitions    -       compiler.mak
	Assembler definitions   -       assemble.mak
	Archivier definitions   -       archiver.mak
	Common definitions      -       common.mak
	Compiling definitions   -       defines.mak

You should take particular care to ensure that each of the programs mentioned
in these makefile is either a) on your path or b) has its path fully 
specified. One definition that is often overlooked is the command 'SHELL'
(defined in common.mak), please remember to modify it.

STEP THREE

A number of targets are defined in the makefiles:

	make library
		to cause the library to be rebuilt, and:

	make depend
		to cause the dependancies to be updated (requires Perl)

	make clean
		to cause the objects files to be deleted.

You should rebuild the library by invoking:

	make clean
	make depend     (if appropriate)
	make library


WAY 2

Probably, you do not have any make utility or the make process does not
work for you. This way describes how you can manually rebuilt CLib.

PREPARATION STEP

Change into the LIB section and delete the files "c0?.obj" and "c?.lib",
if they are exist, where you must replace ? by the first letter of
the memory you want to compile CLib for, e.g. s for small, t for tiny a.s.o.

Change into the OBJ section and delete all files.

STEP ONE

Aquire all the information necessary to invoke the command line tools
for your C compiler and assembler.

For your C compiler you must know how to:
+ compile .C files into .OBJ files,
+ specify three search paths for include files,&
+ specify the memory model.

For your assembler you must know how to:
+ assemble .ASM files into .OBJ files,
+ pass a macro (define) to the assembler,&
+ specify case-sensitive symbols.

STEP TWO

Change into all subdirectories of CLib's root directory where .C files
are located, except BIN.

Compile all the .C files into .OBJ files you can find, specify as
the two include search paths: "..\INCLUDE", "..\CONF" and ".";
specify the memory model. For example with Borland C you could write:
	BCC -I..\include;..\conf;. -ms -c *.c
(Note: -ms specifies _small_ memory model.)
(Also note: In the DOS section you will find subdirectories, too;
 compile all the .C files within them, too!)

Then delete the file "t.obj", if it exists.

Then assemble all .ASM files you can find into .OBJ files turning on
case-sensitve symbols and passing the memory model as a macro (define),
use "__SMALL__" (without quotes) for small model, "__TINY__" for tiny
model a.s.o.

Rename the file "c0.obj" into "c0?.obj", where "?" stands for the
first letter of the memory model, e.g. s for small, t for tiny a.s.o.
Move "c0?.obj" into the LIB subdirectory of CLib's root directory.

Now archive all .OBJ files together, e.g. by invoking:
	LIB ..\OBJ\name /C + .\*.OBJ
where you must repace "name" by the name of the section you are currently in.

STEP THREE

After creating all the .LIB files change into the LIB section and
invoke: LIB ..\LIB\c?.LIB /C + .\*.LIB
where you must replace ? by the first letter of the memory model.

Now you have the startup file "c0?.obj" and the C standard library
"c?.lib" within the LIB section of the CLib directory structure!

WAY 3

If you want to use any IDE, you can follow these hints:
1) Create a new project. You will need a different project for
	each memory model you wnt to compile CLib for.
2) Create the main node as a library. The name of the library
	should be "c?.lib" where you must replace ? by the first letter
	of the memory model you want to compile CLib for.
3) Specify project-wide options:
	+ the memory model,
	+ case-sensitve external symbols,
	+ include search paths: <CLIB>\CONF <CLIB>\INCLUDE .
3) Insert all .C files you can find in any section of CLib, except
	the BIN section and all the "t.c" files, as direct dependencies
	of the main node.
4) Insert all .ASM files you can find in any section of CLib, except
	the BIN section and "CORE\c0.asm", as direct dependencies of the
	main node.
5) Create a secondary main node as an object file called "c0?.obj"
	where you must replace ? by the first letter of the memory model.
6) Insert "CORE\c0.asm" as the only direct dependency.
Now hit the "Built" project button and hope all the best :)

If your IDE does not support multiple main targets, you must create
two projects.

Using FreeDOS LibC
------------------

Now that you have recompiled the library you can use it to write DOS 
programs that are compiler independant. You must use the include 
files in the "include" directory and link against the library files
which are located in the "lib" directory.

Problems
--------

In rare circumstances you might have problems either rebuilding the
library or making use of it. If you have read all the associated 
documentation and still find yourself stuck please don't hesitate to 
ask on the FreeDOS development list for further assistance.

URLs
----

[1]     FreeDOS master site and mirrors.
	http://www.freedos.org/
	ftp://???

[2]     Steffen's LIBBER
	ftp://ftp.inf.fh-fhein-seig.de/pub/freedos/local/lib-sk31.zip

[3]     GNUish tools
	Located at your nearest SimTel mirror.

[4]     DMake (source and binaries)
	source: ftp://???
	binary: ftp://???
