Add README.md, remove README-GIT, update odb-tests/README.md

3 files changed, 184 insertions, 6 deletions

diff --git a/README-GIT b/README-GIT
deleted file mode 100644
index 865beac..0000000
--- a/README-GIT
+++ /dev/null
@@ -1,6 +0,0 @@
-The checked out libodb/odb/version-build2.hxx and
-libodb-*/odb/*/version-build2.hxx files will be overwritten during the build
-process but these changes should be ignored. To do this automatically, run:
-
-git update-index --assume-unchanged \
-  libodb/odb/version-build2.hxx libodb-*/odb/*/version-build2.hxx
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4b72b98
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+# ODB - ORM for C++
+
+ODB is an open-source, cross-platform, and cross-database object-relational
+mapping (ORM) system for C++. It allows you to persist C++ objects to a
+relational database without having to deal with tables, columns, or SQL and
+without manually writing any mapping code. ODB supports MySQL, SQLite,
+PostgreSQL, Oracle, and Microsoft SQL Server relational databases. It also
+comes with optional profiles for Boost and Qt which allow you to seamlessly
+use value types, containers, and smart pointers from these libraries in your
+persistent C++ classes.
+
+For further information, including licensing conditions, documentation, and
+binary packages, refer to the [ODB project
+page](https://codesynthesis.com/products/odb/).
+
+NOTE: the steps described below are more appropriate for the development of
+ODB as opposed to consumption. In case you just want to use ODB:
+
+* If you want to use a binary package, see the [DOB download
+  page](https://codesynthesis.com/products/odb/download.xhtml).
+
+* If you want to build ODB from source and use the result from a project that
+  uses a build system other than `build2`, then see [Installing DOB with
+  `build2`](https://codesynthesis.com/products/odb/doc/install-build2.xhtml)
+  for the step-by-step instructions.
+
+* If you want to use ODB from a project that uses `build2` as the build
+  system, then see the accompanying `PACKAGE-README.md` file.
+
+The development setup for ODB uses multiple build configurations: a single
+host configuration for the ODB compiler and a target configuration per
+database. For example:
+
+```
+git clone .../odb.git
+cd odb
+
+bdep init --empty
+
+bdep config create @host ../odb-host --type host cc config.cxx=g++
+bdep config create @sqlite ../odb-sqlite cc config.cxx=g++
+bdep config create @pgsql ../odb-pgsql cc config.cxx=g++
+bdep config create @mysql ../odb-mysql cc config.cxx=g++
+
+bdep init @host -d odb
+bdep init @sqlite -d libodb -d libodb-sqlite -d odb-tests
+bdep init @pgsql -d libodb -d libodb-pgsql -d odb-tests
+bdep init @mysql -d libodb -d libodb-mysql -d odb-tests
+```
+
+Note that while the target configurations can use any compiler (and you can
+create multiple such configurations for different compilers), the host
+configuration must use GCC because the ODB compiler is implemented as a GCC
+plugin.
+
+You can use system-installed versions of the client libraries and tools
+instead of building them from source. For example:
+
+```
+bdep config link @pgsql @host
+bdep config link @mysql @host
+
+bdep init @sqlite -d libodb -d libodb-sqlite -d odb-tests ?sys:libsqlite3
+bdep init @pgsql -d libodb -d libodb-pgsql -d odb-tests ?sys:libpq { @host }+ ?sys:psql/*
+bdep init @mysql -d libodb -d libodb-mysql -d odb-tests ?sys:libmysqlclient { @host }+ ?sys:mysql/*
+```
+
+You can also create a target configuration for testing multi-database
+support. For example:
+
+```
+bdep config create @multi ../odb-multi cc config.cxx=g++
+
+bdep init @multi -d libodb -d libodb-sqlite -d libodb-pgsql -d libodb-mysql
+bdep init @multi -d odb-tests config.odb_tests.database='sqlite pgsql mysql'
+```
+
+See `odb-tests/README.md` for instructions on setting up various databases to
+run tests.
+
+To generate the documentation in the `.ps` and `.pdf` formats, the `html2ps`
+and `ps2pdf14` programs are required (the latter is from `ghostscript`). A
+warning is issued in the development mode if these programs are not available.
+
+To test installation of the ODB compiler, create a separate target
+configuration (it will automatically resolve any build-time dependencies from
+`host`):
+
+```
+bdep config create @install ../odb-install --type target cc config.cxx=g++ \
+  config.install.root=/tmp/install
+
+bdep init @install -d odb
+
+b install: ../odb-install/odb/
+```
+
+Note that if building manually (that is, without `bdep`) and in-source, then
+the checked out `libodb/odb/version-build2.hxx` and
+`libodb-*/odb/*/version-build2.hxx` files will be overwritten during the build
+but these changes should be ignored. To do this automatically, run:
+
+```
+git update-index --assume-unchanged \
+  libodb/odb/version-build2.hxx libodb-*/odb/*/version-build2.hxx
+```
diff --git a/odb-tests/README.md b/odb-tests/README.md
index 24d3bf7..dd540d8 100644
--- a/odb-tests/README.md
+++ b/odb-tests/README.md
@@ -2,3 +2,81 @@
 
 This package contains tests for `odb`, object-relational mapping (ORM)
 compiler for C++.
+
+## Setting up PostgreSQL for running tests
+
+1. Install the PostgreSQL server. On Linux this is normally done using
+   distribution packages.
+
+2. In `/etc/postgresql/N/main/pg_hba.conf` add the following line after the
+   `local all postgres ...` line:
+
+   ```
+   local   odb_test        odb_test                                trust
+   ```
+
+   If you want to be able to run tests on a different host and access
+   PostgreSQL via TCP/IP, also add the following line (adjusting the IP
+   network to match your setup -- never specify a public IP network here since
+   the access is unauthenticated):
+
+   ```
+   host    odb_test        odb_test        192.168.0.0/24          trust
+   ```
+
+   You will also need to edit `/etc/postgresql/N/main/postgresql.conf` and
+   change `listen_address` to `*`. You may also need to open port `5432` in
+   your firewall.
+
+   Restart the PostgreSQL server.
+
+3. Add the `odb_test` user and the `odb_test` database.
+
+   First login:
+
+   ```
+   sudo -u postgres psql
+   ```
+
+   Then execute the following statements:
+
+   ```
+   CREATE USER odb_test;
+   CREATE DATABASE odb_test;
+   GRANT ALL PRIVILEGES ON DATABASE odb_test TO odb_test;
+   \c odb_test
+   GRANT ALL PRIVILEGES ON SCHEMA public TO odb_test;
+   ```
+
+## Setting up MySQL for running tests
+
+1. Install the MySQL server. On Linux this is normally done using distribution
+   packages.
+
+2. Setup remote access (optional).
+
+   If you want to be able to run tests on a different host and access MySQL
+   via TCP/IP (never do this on a public server since the access is
+   unauthenticated), then edit `/etc/mysql/.../mysqld.cnf`, the `[mysqld]`
+   section, and change `bind-address` to `0.0.0.0`. You may also need to open
+   port `3306` in your firewall.
+
+   Restart the MySQL server.
+
+3. Add the `odb_test` user and the `odb_test` database.
+
+   First login:
+
+   ```
+   sudo mysql
+   ```
+
+   Then execute the following statements:
+
+   ```
+   CREATE USER odb_test@'%';
+   CREATE USER odb_test@'localhost';
+   CREATE DATABASE odb_test;
+   GRANT ALL PRIVILEGES ON odb_test.* to odb_test@'%';
+   FLUSH PRIVILEGES;
+   ```