Berkeley DB SQL API
===============================================================================

Content overview:
===============================================================================
1) sql/adapter: the source files that implement the changes to SQLite in order
   to use Berkeley DB as a storage engine, instead of the default btree
   implementation in SQLite.

2) sql/sqlite: The unpacked archive of SQLite source, "as extracted from
   the version control system", modified to use Berkeley DB as the backend.

3) sql/generated: Contains pre-generated versions of files used by amalgamated
   and Windows builds.

Building
===============================================================================
Linux/Unix/Cygwin:
  Simply add the "--enable-sql" switch to the configure command.
  In more detail:

  It is possible to generate a few different outputs using configure.
  They are:
  1) libdb_sqlXX.{so|la} - A C API library, that exactly mirrors the SQLite
     C API.
  2) dbsql - A command line SQL interpreter, that exactly matches
     the default sqlite3 command line interpreter.
  3) sqlite.{so|la} - A C API library, that exactly mirrors the SQLite C API,
     and has the same name as the library generated by a SQLite build.
  4) sqlite3 - A command line SQL interpreter, that exactly matches the 
     semantics and name of the default sqlite3 command line interpreter.
  5) sql/testfixture - The SQLite Tcl test runner. This can be used to run
     the test cases in the sql/sqlite/test directory.

  The flags required to generate the above components are:

  --enable-sql - will generate 1, 2
  --enable-sql_compat - will generate 1, 2, 3, 4
  --enable-sql --enable-test --with-tcl=blah will generate 1, 2, 5
  --enable-sql_compat --enable-test --with-tcl=blah will generate 1, 2, 3, 4, 5

Windows with Visual Studio 2005 or newer:

 - Open the build_windows/Berkeley_DB.sln file in Visual Studio.
 - There are three project relevant to the SQL API:
   - db_sql - the C API library, output as libdb_sqlXX.dll
   - db_sql_shell - the SQL command line interpreter
   - db_sql_testfixture - the testfixture Tcl test runner application. It is 
     necessary to have Tcl installed and available in Visual Studio to build
     the testfixture component.


Running tests
===============================================================================
Configure based builds:
	$ cd build_unix/sql
	$ ./testfixture ../../lang/sql/sqlite/test/insert.test
		(for tests that come with the SQLite package)
	$ ./testfixture ../../test/sql/bdb_multi_proc.test
		(for tests written specifically for Berkeley DB's SQLite API)

	To debug into the SQLite code:
	$ gdb --args ./.libs/testfixture ../sqlite-3.*/test/insert.test

	At the GDB prompt type "run", then retry with other tests, etc.

Windows based builds:
	Open the Berkeley_DB.sln solution file in Visual Studio 2005 or newer.
	Build the db_sql_testfixture project.
	If debugging via Visual Studio, set the command line options in the
	project settings to: ../../sql/sqlite/test/insert.test (or any other
        test you want to run). Then start a debug session.

More information
===============================================================================
See the Using the Berkeley DB SQL documentation on www.oracle.com.

