SQLite is a Self-contained, embeddable, zero-configuration SQL database
engine. For information about SQLite, see the main README or check the
site here: http://www.sqlite.org

This is the Amiga version of sqlite-3.6.1 and can be considered stable.
The regression tests either succeed without failure or reported errors can 
be explained or document limitations of this version.  See below for a list
of limitations in the Amiga version.

There have been several attempts to port SQLite to AmigaOS.  Please browse
Aminet for a list.  Several of the previous ports made use of the Posix/
ixemul interface that provides a Unix-like emulation of what is needed by
the SQLite low level file access.

This port is different in that it only uses AmigaOS 3 native functions
for implementing the OS interface.  The changes to the original version
3.5.4 are in writing a custom Makefile for Amiga, implementing the OS module 
for AmigaOS, adding some work-arounds for char to 64bit integer conversion
bugs in the gcc-3.4.0 compiler, and making some other minor changes in 
several flies.  A complete diff of all changes can be found in the file 
amiga-diff.txt.

Note that this version fully supports 64bit integers.  This, however, 
requires a compiler that supports 64bit integers and rules out, e.g. SAS-C.

The os_amiga.c file contains an implementation of all necessary OS functions.
This module was written by taking os_unix.c as a start, looking at os_win.c 
sometimes to get an idea on how else things can be done, by careful reading 
the autodocs of AmigaDOS, by testing some of the more advanced functions in 
AmigaDOS 3.0+ (e.g. LockRecord which seems to be unimplemented on most 
filesystems), and by running the regression tests and tweaking the code
to ensure a correct implementation.  If you are interested, you can find 
many comments in os_amiga.c, in particular about how to do the file locking.

The library and the sqlite3 shell have been compiled for m68k-AmigaOS
using gcc-3.4.0.  The compiled binaries can be found in build-m68k-amigaos.
The binaries also contain the 'testfixture' program for running 
the regression test suite.  As 'testfixture' needs a tcl interpreter, 
I ported tcl-8.4.14 to AmigaOS using the ixemul library interface and 
also compiled 'testfixture' against it.  Note that the sqlite3 shell and 
libraries are compiled with the -noixemul switch and are thus are true 
'Amiga-like' binaries.

Mathias Parnaudeau provides the AmigaOS 4 binaries under directory
build-ppc-amigaos and Ilkka Lehtoranta the MorphOS binaries under directory
build-ppc-morphos. 

The regression tests reported below have been run for the AmigaOS 3 version
(under UAE).  Test results for MorphOS are also available and are similar 
to the results on Amiga OS3 but haven't been fully analyzed yet.

Limitations

- No support for large files (LFS).  To the best of my knowledge files
  under AmigaOS can be at most (2**31 - 1) bytes.  This limitation arises
  from the LONG parameters in dos.library.
  Compile switch -DSQLITE_DISABLE_LFS
  (AOS4 and MorphOS introduce support for large files and implementation is
  in progress).
  
- No byte-range-locking.  I tried several file systems (OFS, FFS) but they
  do not seem to support the LockRecord/UnLockRecord calls (The RAM: disk
  does support it and maybe SFS also has it implemented).  Therefore, the
  default way of locking is by using (several) .lock files.  Read os_amiga.c
  if you want to know more about this.

- Truncate file by replace.  The dos.library/SetFileSize call is unsupported
  by most file systems (OFS, FFS) and therefore truncating a file to a
  target size doesn't work.  My workaround to this is to write a new file
  of the target size and replace the files.  This does not always work
  though if the file is still opened by another process/handle.  In this
  case truncating fails which means that the 'VACUUM' command of sqlite
  fails.  Use a file system that supports SetFileSize (try SFS) if you need
  to rely on a proper functioning of the VACUUM command.

- 71 errors in 58122 tests remain. (see build-m68k-amigaos/test-stripped.log).
  The errors can be categorized into the following classes which explain 
  what is happening:

    * rounding error on double  : lack of precision in the math implementation
                                  of double precision floating point numbers.
      Test cases: date-*, expr-13.*, main-3.2.*, misc3-2.4, misc3-6.11,
                nan-*, printf-2.3.10.*, printf-10.3, printf-11.7, table-13.2.*

    * representation of double  : NaN/Inf is differenlty represented 
                                  or handled in the math libs.
      Test cases: expr-2.26[b], nan-*, printf-7.*

    * stat on exlusive open file: trying to open/access a file where a process
                                  holds an exclusive lock on.
      Test cases: exclusive-3.*, io-4.*, misc1-14.2,
      
    * ixemul vs AmigaDOS path   : /home/a/b/c vs. home:a/b/c
      Test cases: pragma-9.*, shared-1.11.9, shared-2.11.9

    * delete on open file error : the replace-file-when-truncating operation
                                  failed because some process still holds
                                  a handle on the file.
      Test cases: shared-2.3.1.*, vacuum-2.2, vacuum2-3.13

    * Others: minor errors, need more investigation
      Test cases: tkt2854-1.5, tkt2854-1.16.

  You can reproduce these results by running 'testfixture ../test/quick.test'.
  Prior to running this test, make sure the stack is at least 500kBytes large
  as the tcl interpreter uses a lot of stack in recursive calls.

Steffen Gutmann, 20.10.2008