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

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

2) sql/sqlite: configuration and other needed files from SQLite source,
   modified to use Berkeley DB as the backend.

3) sql/generated: 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.

  If you wish to use the SQLite Tcl test runner "testfixture" and the 
  SQLite test suite, you will have to download the test code as modified
  for the Berkeley DB backend. You can request it on the OTN Forum at

https://community.oracle.com/community/database/berkeley_db_family/berkeley_db.

  Use of the --enable-test configure flag together with --enable-sql 
  requires this test code. 

  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 2010 or newer:

 - Open the build_windows/Berkeley_DB_vsYYYY.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. It is also necessary to request and install
     the test code as mentioned above. 


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_vsYYYY.sln solution file in Visual Studio 2010 
	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 Berkeley DB SQL API documentation distributed with this package or
available at www.oracle.com/technetwork/database-technologies/berkeleydb/
documentation/index.html. 

