head     1.1;
branch   ;
access   ;
symbols  ;
locks    lee:1.1;
comment  @# @;


1.1
date     94.08.02.00.00.00;  author lee;  state Exp;
branches ;
next     ;


desc
@notes for porters.
@



1.1
log
@Initial revision
@
text
@# $Id$

Notes for porting lq-text.

This is the free version.  It is not public domain, but you can use it
freely for non-commercial purposes.
If you want to sell it, or something derived from it, you should get in
touch with the author (me!), who will almost always give permission.

You can contact me as follows:
  lee@@sq.com,
  Liam Quin, SoftQuad Inc. 720 Spadina Ave., Toronto, ONT., Canada
  (+1) 416 963-8337

The ftp site for lq-text is
    ftp.cs.toronto.edu
in /pub; there may also be files on ftp.sq.com, but at the time of writing
(Augist 1994) our Internet connection is only 56Kbaud, so I'd suggest taking
the newest of the files, preferring the University of Toronto site.

==============================

PORTING NOTES

See ../INSTALL for how to do an installation on a system to which lq-text
has been ported already; this involves running "configure".

This document explains how to add a new machine to the configure database.
It isn't hard, don't panic...


Likely problems:
* configure doesn't work at all
  It needs a shell with shell functions.
  Type this and see if you get a syntax error:
##############
feet()
{
    echo bare
}
##############
  If you dont get an error message, check that typing
feet
  produces the message
bare
  If you got errors, or you didn't get the "bare" message, you are faced
  with some choices:
  (1) find another shell.
      On Ultrix systems, /bin/sh5 will do.
      Bash is another possibility, as is ksh.

      for example, instead of
configure
      type
bash configure
      and see what happens.
  
  (2) do the configure by hand
      look in config.dir to see if you are using a machine listed there;
      for each machine, there is a directory for each operating system which
      that machine can run.  If your system is there, you're in luck.
      For example, if you are using an Intel 586 system running Solaris 2.4,
      look for
	config.dir/x86/solaris-2.4
      and if it's there, you've got a config directory.

      In this case, there may be some files ready for you:
	Makefile.tpl
	Makefile
	cflags.def
	port.h
	port2.h
	build.sh
      
      [1] Copy Makefile to src/Makefile
	  If it's not there, and you have only Makefile.tpl,
	  edit src/Makefile by hand.

	  You can look at cflags.def to see what C compilers other
	  people have used to compile lq-text, and copy the appropriate
	  part of cflags.def into Makefile.

      [2] copy port.h to src/h/port.h

	  If there isn't a port.h, you can look at build.sh to see the
	  settings for the various variables, and edit h/port.h accordingly.

      [4] copy port2.h to src/port2.h

	  This file is optional, so don't panic if you don't have one --
	  simply make it an empty file.
      
      Now proceed with the installation instructions in ../install as if
      configure had worked.  Please accept my apologies, and feel free to
      let me know what system this is and what problems you had, so that
      I can try and make configure work better on it next time.

  (3) Treat it as a new port -- see `Extending Configure' below.


* if you have multiple machines sharing the same database, and they do not
  all use the same byte-ordering, you will need to do some hacking.
  The headers in pblock.{c,h}, and Filelist/WordInfo.c will all need
  changing.  They have to read and write fixed-length unsigned longs,
  and very quickly too!  In addition, versions of dbm other than db will
  not be suitable.  It's best simply not to do this.

* db didn't compile
  You can use sdbm instead.  Look at Makefile for the things to change.
  If you use gdbm, please be careful to read COPYRIGHT and compare it to
  the GNU copyright.  If it's OK, you can proceed...
  If you end up fixing db, you can mail me (lee@@sq.com) or Keith Bostic
  (his address is in the db package) or, better, both, to let us know.
  Please contact me (lee) with problems in the first instance, though,
  in case they are to do with the lq-text environment.

* On mixed model architectures, make sure that you can have arrays larger
  then 64KBytes, that a pointer (char *) fits into an unsigned long, and
  that you have a good supply of coffee.

* see the TODO file for functionality not yet available

* Problems with Curses are common.
  In the lqtext program, you can use control-D as a synonym for F1.


By all means mail me with questions, providing that you have at least tried
to get somewhere youself.

Lee

lee@@sq.com (Liam R. E. Quin)


Extending Configure
===================

:overview

The lq-text "configure" is a (fairly complex) shell script that:
* asks you what kind of machine you are using
* asks you which operating saystem you are running
* uses these to work out a default configuration for compiling and installing
  lq-text.

It uses a directory structure like this:

lq-text/configure -- the shell script
lq-text/config.dir -- the library of information about ports

The result of running configure is normally that you have the following
files installed:
    src/Makefile -- top-level Makefile for lq-text
    src/h/port.h -- platform-specific C definitions
    src/h/port2.h - a place-holder for local definitions

Every lq-text source file includes "globals.h", and this in turn includes
port.h at the top, and port2.h at the end.  It is *much* better to make
changes to port2.h than to globals.h, as then your changes can be used by
other people on your platform without affecting other platforms -- globals.h
is used on all systems.

If you don't want to use configure, you don't have to.  You can edit the
three files yourself and go ahead with "make".  But if you are doing a new
port, and send me (lee@@sq.com) your new config.dir subdirectory, as
explained below, I will almost certainly include it in the next release,
along with any changes to the actual C files, and you will have much less
work to do next time round, as will other people using the same platform.

I have used my own "configure" script because I couldn't find one that
did what I needed, didn't do lots of other things, and didn't use a
licence incompatible with the lq-text COPYRIGHT.


:detailed-description

config.dir contains these files:
  config.dir/local.sh -- previous settings, or an empty file
    as lq-text is shipped, this is set up for a Sun SPARC running SunOS 4.x,
    because this is the most common networked Unix system.
  
  config.dir/default.sh
    this is used if there isn't a "build.sh"; if your local.sh is ill,
    you can remove it and configure will start again with default.sh.
  
In addition, there is a directory for each kind of CPU or hardware,
such as sparc, x86, mips, etc., and a directory called default.

There is also a directory called .tests, described later.


Each of the per-CPU directories contains a directory for each supported
operating system, and also a directory called "default".

The default directory is used as a starting point for a new port.


When you tell configure that you have some kind of computer it doesn't
know about, it asks you again (in case you made a typo) and gives you
the list of ones it knows about -- i.e. the directories under config.dir.
If you insist :-), a new directory will be created, and it will contain
a directory "default", whose files are copied from the default directory,
config.dir/defauilt/default/*

If the hardware directory already existed, but the operating system didn't,
and you insist (again), configure will create a new directory underneath
config.dir/${HARDWARE}, so if (for example) you choose x86 as your hardware
and solaris-2.4 as the operating system, and that didn't exist, configure
would create the directory x86/solaris-2.4, and copy x86/default/* into
that new directory.

I'm telling you this so that when you do your port, you can change the
default files too if you need to.

The files are:
* Makefile.tpl -- a template makefile that gets edited later
* cflags.def   -- information about the C compilers on this system
* build.sh     -- contains default variable values for this platform.
These files are describes in more detail below.


Once you have chosen hardware and operating system, configure checks each
of the variables in the .tests/scripts file that is unset or is set to
unknown in the build.sh in the porting directory.

For each such variable, there is (or should be!) an entry in
	.tests/scripts
that includes a shell-script to run to determine the value.  There are 
some comment in .tests/scripts that may help you add to this if you need
to; more about that later!


When it's finishd with tests, configure writes out some files in the porting
directory:
[1] Makefile
    This is a copy of Makefile.tpl in the same directory, but with the
    following changes between the lines that say

## Local Changes, generated by the configure script:

## End of Configure output. 

    No changes are made to Makefile.tpl anywhere else.

    The changes are:
    * the cflags.def file is included, all commented out except for the
      section that starts with
      @@CC=${CC}
      and p to the next line starting with an @@-sign;
      all @@-signs are turned into #-signs.
      This may seem odd, but it lets you put comments inside the cflags.def
      file on lines starting with a #, and they'll get copied through to
      the Makefile -- the @@ is considered "out of band", and would be
      illegal at the start of a line in most versions of make.

    * all of the variables in the .tests/scripts file that are marked as
      being of type "make" are included with theur values.
    


@
