xref: /csrg-svn/lib/libc/db/PORT/README (revision 66199)

#	@(#)README	8.3 (Berkeley) 02/21/94

This is the area for building the libdb library.  There are a number
of porting directories, for various architecture/OS combinations.  Pick
the one that's closest to yours and try "make".  For the rest of this
file, I'll use "MACH" as a fake architecture/OS name.

To PORT to a new system, create the following subdirectories and
symbolic links.

	mkdir MACH		(for example: mkdir sunos.4.0)
	cd MACH
	cp ../Makefile .
	chmod 664 Makefile
	ln -s ../clib .
	mkdir include
	ln -s include sys
	cd include
	ln -s ../../include/*.h .
	rm compat.h
	cp ../../include/compat.h .
	chmod 664 compat.h
	cd ..

The basic idea is that you now have a local area that you can modify.
In particular, you have local copies of the Makefile and the include
file compat.h.  Read through the Makefile and compat.h and make whatever
changes are appropriate to your system.  If there's an architecture
that's close to yours, you probably should diff the Makefile and
compat.h in that tree against the standard ones and see what changes
were necessary, as they're probably necessary for you as well.  Then,
enter "make" and see what happens!

There are several subroutines that are found in POSIX 1003.2, ANSI
C, or 4.4BSD that you may not have.  Once you get libdb.a to compile,
go through the list of undefined routines and add entries to the MISC
line in the Makefile as necessary.

If you have to add some functions that are missing (and which aren't
in the PORT/clib directory), please don't add them in the PORT/clib
directory.  Add them in a MACH/local directory, and add lines of the
form:

	function.o: local/function.o
		${CL} -Ilocal local/function.o

to your local Makefile.

Hopefully, over time, we'll develop a set of system directories that
are known to work.  If you send me the changes that were necessary to
make your system work, this will happen much more quickly.

In some of the system directories, you'll see a file named OTHER_PATCHES.
This is a set of patches which you'll have to make from the top-level db
directory to get libdb.a to run on this system:

	cd ..
	patch < PORT/MACH/OTHER_PATCHES

If patch prompts you for the name of the file to modify (some versions
of patch don't figure it out on their own) use the file name which patch
displays.

Some knobs you may have to turn:

In include/compat.h:
	Before attempting to build libdb, you should look through the
	compat.h file, and adjust it as necessary for your system.
	It's possible to use the #ifndef construct to figure out if a
	#ifdef has been set, but C provides no similar method to figure
	out if a typedef has been done.  Your compile errors should
	give you a good indication of which ones you need.

You may see warning messages about illegal pointer combinations.  Systems
prototype malloc, calloc and realloc in different places, and the missing
prototypes will produce such warnings.  You may also see lots of warning
messages about #define's being redefined.  These can mostly be ignored.
In general, I ignore all warning messages until something doesn't work.
Some systems produce thousands of lines of completely useless warnings.

The other parts of the PORT directory are as follows:

	The directory PORT/clib is a set of functions that the 4.4BSD
	C library had and which your system may not have.  They are
	added to the MISC line of the Makefile if they aren't defined
	when you try and load libdb.a.

	The directory PORT/include is header files that the 4.4BSD
	system had which your system may not have.  There is also
	one really important extra one, named compat.h, which is a
	set of compatibility work-arounds that you'll almost certainly
	have to copy and modify for a new system.

	The symbolic link PORT/sys points to the PORT/include directory
	so that includes of the form <sys/include.h> work.

Some of the more common portability problems:

	If you don't have:

		memmove(3):	add memmove.o
		mkstemp(3):	add mktemp.o
		strerror(3):	add strerror.o

			... to the MISC line in the Makefile.

	If realloc(3) of a NULL pointer on your system isn't the same
	as a malloc(3) call, add realloc.o to the MISC line in the
	Makefile.

	If you don't have snprintf/vsnprintf(3), add snprintf.o to the
	MISC line in the Makefile.  This workaround depends on your
	system having vsprintf(3) -- if you don't, there's no workaround
	other than changing the source code to not use the snprintf calls.
	If you have to make that change, check to see if your vsprintf
	returns a length or a char *; if it's the latter, make sure you
	set VSPRINTF_CHARSTAR in the MACH/include/compat.h file.

Installing the DB library:

	The Makefile builds a C library named libdb.a.  This file needs
	to be installed in a place where the loader will automatically
	look for it (or, if you're building it for a single project,
	wherever that project's Makefile loads it from).

	In addition, the header file PORT/include/db.h must be copied to
	a directory (often /usr/include/) where programs that use the
	db package can include it in their source.  (If you intend to use
	the ndbm interface to libdb, you'll need to copy the header file
	PORT/include/ndbm.h as well.)