G E E K    G A D G E T S

		   P R O J E C T    I N F O R M A T I O N

			     (Updated 16-June-97)

[Note: This is a preliminary draft which will change greatly as it is
converted to texinfo format (from which we can automatically generate
AmigaGuide files, GNU info files, dvi files, and PostScript files.]

=============
What Is This?
=============

Because of the hard work from a number of members of the Amiga community, we
now have a large body of development tools that have been ported to the
Amiga and are available in both source and binary form.  We will refer to
this software set as Geek Gadgets.

The name reflects the fact that not only is this environment intended to
meet the needs of Amiga Developers for tools, examples, documentation, and
other useful material, but that it is also supported by the developer
community itself and not any single entity, commercial or otherwise.  This
ensures that it will always be available and supportable by this community.

One of the goals of Geek Gadgets is to have a completely self hosting
environment.  I.E. that everything within it be compilable by the provided
compilers.  It should be possible for the recipient of these utilities to
make whatever changes or bug fixes they want in any piece of code, and then
rebuild and use that fixed version (and hopefully send those changes back
for integration into future releases).

Although Geek Gadgets started out as ports of tools covered by the GNU
General Public License, the GNU Library General Public License, or some code
covered by the "Berkeley License", it certainly isn't limited to those.  Any
package which is available in source is eligible to be part of Geek Gadgets.

There are several mailing lists available for people that are interested in
getting ongoing Geek Gadgets information or participating in discussions
about Geek Gadgets.  For information about what lists are available and how
to subscribe, send email to "majordomo@ninemoons.com" with just "help" as
the body of the message.

============
ORGANIZATION
============

Geek Gadgets can be divided into several distinct files trees, as follows:

GG-bin		Binary tree where executables, runtime libraries,
		user documentation, etc live in "ready-to-run"
		form.  Uses "GG:" as an alias (Amiga assign).
		The files in this area are built from source in
		GG-src or copied from files in GG-src.

GG-src		Source tree which contains all the sources for
		components of Geek Gadgets.  Given the GG-src tree,
		and a copy of the GG-bin tree, it should be possible
		to completely recreate the GG-bin and GG-dist
		trees.

GG-dist		Tree which contains material from GG-bin and
		GG-src, archived in a form suitable for BBS or ftp
		access.  Also contains baseline source archives
		for packages which have been modified and diff
		files for the Amiga sources relative to this
		baseline.

The GG-dist tree normally contains several files for each program.  As an
example, here are the names of the files for the GNU C compiler.  Each file
also has an associated product info file which has the same name but an
additional suffix of ".pi":

gcc-X.X.X-base.tgz	Baseline source before incorporation into Geek Gadgets.
			In some cases base files have been reorganized to
			match the same file tree structure as used for the
			Amiga source in Geek Gadgets, so that diff files can be
			mechanically generated.

gcc-X.X.X-bin.lha	The binary package for GNU C, C++, and Objective C.

gcc-X.X.X-src.tgz	The Amiga source from which the supplied binaries
			were compiled.

gcc-X.X.X-diffs.gz	The diffs from the baseline to the Amiga source.
			The baseline source, amiga source, and diff file
			form a complete source distribution.  In theory,
			only any two of these are needed, since the third
			can be regenerated from either of the other two.

Note that ".tgz" is short for ".tar.gz", which is a tar archive that has
been compressed with GNU gzip.  To use the supplied tools to extract files
from these archives you'll have to first install the following packages:

	gzip-X.X-bin.lha
	ixemul-X.X-bin.lha
	ixemul-X.X-env-bin.lha
	tar-X.X-bin.lha

To extract the contents of tgz archives, you would do something like:

	tar -xvpzf gcc-X.X.X-base.tgz

If this causes you any problems, you can use pipes to do the decompression
and tar extraction as two separate processes, without creating a temporary
file:

	zcat gcc-X.X.X-base.tgz | tar -xvpf -

Without using pipes, you can create a temporary file to extract from,
as follows:

	zcat gcc-X.X.X-base.tgz >gcc-X.X.X-base.tar
	tar -xvpf gcc-X.X.X.tar

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

Currently the only supported method of installing components of Geek Gadgets
is to create a directory which will be the root of Geek Gadgets binary tree,
assign GG: to this directory, cd to GG:, and use lha or tar (as appropriate)
to extract the contents of the packages you wish to install (everything is
archived relative to GG:).

For example, the following illustrates populating the Geek Gadgets binary
tree with the minimum set of packages that we would recommend for doing
serious C or C++ development.  Replace -X.X- with the appropriate version
numbers for the current release:

	makedir dh0:GG
	assign GG: dh0:GG
	cd GG:
	lha -mraxe x GG-misc-bin.lha
	lha -mraxe x binutils-X.X-bin.lha
	lha -mraxe x bison-X.X-bin.lha
	lha -mraxe x diffutils-X.X-bin.lha
	lha -mraxe x fd2inline-X.X-bin.lha
	lha -mraxe x fifolib-X.X-bin.lha
	lha -mraxe x fileutils-X.X-bin.lha
	lha -mraxe x findutils-X.X-bin.lha
	lha -mraxe x flex-X.X-bin.lha
	lha -mraxe x gcc-X.X-bin.lha
	lha -mraxe x grep-X.X-bin.lha
	lha -mraxe x gzip-X.X-bin.lha
	lha -mraxe x ixemul-X.X-bin.lha
	lha -mraxe x ixemul-X.X-env-bin.lha
	lha -mraxe x ixemul-X.X-inc-bin.lha
	lha -mraxe x libamiga-bin.lha
	lha -mraxe x libg++-X.X-bin.lha
	lha -mraxe x libm-X.X-bin.lha
	lha -mraxe x libnix-X.X-bin.lha
	lha -mraxe x make-X.X-bin.lha
	lha -mraxe x patch-X.X-bin.lha
	lha -mraxe x pdksh-X.X-bin.lha
	lha -mraxe x sed-X.X-bin.lha
	lha -mraxe x sh-utils-X.X-bin.lha
	lha -mraxe x tar-X.X-bin.lha
	lha -mraxe x termcap-X.X-bin.lha
	lha -mraxe x textutils-X.X-bin.lha

The following should be optional, unless you want to remake a "configure"
file, want EMACS, or currently need a curses library.

	lha -mraxe x autoconf-X.X-bin.lha
	lha -mraxe x emacs-X.X-bin.lha
	lha -mraxe x ncurses-X.X-bin.lha

You may want to examine the ixemul.library flavors in GG:Sys/Libs and select
one more appropriate for your specific machine.  For example, A4000 users
might want to remove the default ixemul.library (68000) and copy
ixemul040fpu.library to ixemul.library.

If you want to just do libnix development and not ixemul development, note
that you still need the include files from ixemul-X.X-inc-bin.lha.

You should also ensure that you have an environment variable called HOME,
which should point to a local directory that can be used to contain
"reconfiguration scripts" that many tools look for.  As an example, the
following is a useful definition for $HOME/.inputrc:

  # My ~/.inputrc file is in -*- text -*- for easy editing with Emacs.
  #
  # Notice the various bindings which are conditionalized depending
  # on which program is running, or what terminal is active.
  #

  # In all programs, all terminals, make sure this is bound.
  "\C-x\C-r": re-read-init-file

  # Amiga console specials
  "": delete-char

  "›A": previous-history
  "›B": next-history
  "›C": forward-char
  "›D": backward-char

There are some files that we cannot yet distribute with the ftp version of
Geek Gadgets for legal reasons, such as the AmigaOS include files (required
for AmigaOS specific programming), or the AmigaOS fd files (used by
fd2inline to generate the inline files).  These files are included on CD-ROM
versions because we have written permission to include them.  If you install
Geek Gadgets from something other than a Geek Gadgets CD, you will need to
copy the AT include files to the GG:os-include directory, creating a
directory hierarchy like the following:

	os-include/clib
	os-include/datatypes
	os-include/devices
	os-include/diskfont
	os-include/dos
	os-include/exec
	...

Sometimes these files contain errors or other problems that need to be fixed
before they can be used with Geek Gadgets.  These patches are contained in
the "non-GG-patches-src.tgz" file and have already been applied in the
CD-ROM releases.  For ftp releases of Geek Gadgets, you should get this file
and extract it in a temporary location with:

	gzip -d non-GG-patches-src.tgz
	tar -xvf non-GG-patches.tar

This will create a directory called non-GG-patches, which will have
individual patch files that can be applied with the "patch" program or by
hand editing (not recommended) the affected files.  See each patch file for
specific directions and an explanation of the patch.

Many Geek Gadgets tools require large amounts of stack space.  Some of them
have been compiled to automatically grow the stack as necessary, but the
work to build all of them with automatic stack expansion is not yet
complete.  Thus you need to take care to set an appropriate amount of stack.
One way to do this is to add a line like:

	stack 200000

to your S:Stack-Startup file.  There are various opinions about what the
minimum stack size should be.  You could get away with as little as 50K in
some circumstances, or need over 500K in others.  Random crashes,
irreproducible behavior, machine lockups, and other such problems are
typical symptoms of setting the stack too low.

The last step in the installation is to modify your S:User-Startup file to
assign GG: to the root of your Geek Gadgets installation tree and also to
execute GG:Sys/S/GG-Startup at boot time.  Once you reboot, Geek Gadgets
should be ready for use.

===
CVS
===

All of the source in Geek Gadgets is kept in a centralized repository and
managed by CVS (Concurrent Versions System).  This allows many developers to
work simultaneously on the source for a particular program without having to
"freeze" the source and thus impede progress by other developers that want
to work on the same sources.

Using remote CVS, a distributed team of cooperating developers can check out
a copy of the source from the repository machine located anywhere on the
internet, make local changes to that source, test those changes, then check
those changes back into the repository.  All other developers that have a
copy of that source checked out will have those changes inserted into their
copy automatically the next time they do a CVS "update", and in the rare
case where their changes conflict with the latest repository changes, they
will be notified of the conflict and thus be able to resolve it before
checking in their own changes.

CVS will also arrange to log changes to particular modules (groups of files
which may be one or more programs) in the repository and send notifications
via email to interested developers that want to know about changes to the
modules they are working on.  For example, if one of the developers working
on gcc makes a change, all of the other developers which have signed up to
receive notices of gcc changes will receive a notice via email that
typically consists of a copy of the ChangeLog entries for the files that are
affected by the change.

This system also allows "lurking developers", I.E. those that want access to
the latest source simply to build new binaries.  Even though they are not
making any changes themselves, they can maintain a complete and up-to-date
source base with a minimal amount of effort, by simply doing a CVS update
every few days.  These people are not parasites; they provide a very useful
function by working with the latest source base on a wide variety of
machines with a wide variety of configurations, and can quickly provide
feedback when ill advised changes to the source base cause trouble that the
developers did not catch during their own testing.

To find out more about CVS, obtain a current copy of the source or binary
distribution which contains the documentation in postscript form, and then
print and read the documents "CVS II: Parallelizing Software Development",
"Version Management with CVS", and "CVS Client/Server".

===============
ChangeLog Files
===============

All changes made to the source base in the repository must be accompanied by
appropriate entries to a ChangeLog file.  A ChangeLog files documents what
changes were made to particular files and who made them.  A sample (from the
gdb ChangeLog file) is:

    Wed Aug  9 18:59:05 1995  Fred Fish  <fnf@cygnus.com>

	* defs.h (strchr, strrchr, strstr, strtok, strerror): Enclose in
	#ifndefs to protect against previous definitions as macros.

    Wed Aug  9 14:51:36 1995  Kung Hsu  <kung@mexican.cygnus.com>

	* xcoffread.c (xcoff_symfile_offset): Revert an unwanted change
	that got in accidentally with Aug 1 change.

    Sat Aug  5 09:07:28 1995  steve chamberlain  <sac@slash.cygnus.com>
 
 	* remote-hms.c (hms_cmds): Get reg term right.
	* monitor.c (monitor_fetch_register):  If we see
	a non-hex digit, just stop reading.  
 	* remote.c (remote_wait): Change way $O is handled.

Most programs come with ChangeLog files, but those that don't will have one
created at the time they are imported into the repository.  ChangeLog
entries can be easily created by using the EMACS command "C-x 4 A".

============
Mirror Sites
============

We are actively looking for mirrors for this material.  If you have trouble
accessing the master Geek Gadgets site from your location because of network
delays, and regularly use a closer site for other ftp needs, you may want
to ask that site to mirror the Geek Gadgets tree.

The Geek Gadgets ftp tree can be found at the following locations:

  Master Site:

    ftp://ftp.ninemoons.com/pub/geekgadgets           (208.226.30.106)

  Full Mirrors:

    ftp://ftp.grolier.fr/pub/amiga/ade                (194.158.97.67)
    ftp://plukwa.pdi.net/geekgadgets                  (196.116.162.7)
    ftp://ftp.livewire.com.au/pub/ade                 (203.16.26.3)

  Partial Mirrors:

    ftp://bilbo.di.unipi.it/pub/ade                   (131.114.4.62)
    ftp://ftp.uni-erlangen.de/pub/source/geekgadgets  (131.188.3.2)
    ftp://ftp.uni-trier.de/pub/amiga/ade              (136.199.8.81)
    ftp://ftp.it.kth.se/people/jj/ADE                 (130.237.212.130)

================
ACKNOWLEDGEMENTS
================

A large portion of this material is covered by the GNU General Public
License (GPL) or the GNU Library General Public License (LGPL).  Copies of
these licenses can be found in the file "GG-misc-bin.lha" and also in the
package source and binary archives.

This product includes software developed by the University of California,
Berkeley and its contributors.