Development

This document describes how to develop PGroonga.

Build

It's recommended that you build both PostgreSQL and PGroonga with debug options.

It's better that you build Groonga with debug options (Groonga's configure provides --enable-debug option) too. If you use packaged Groonga, you need to install development package. It's libgroonga-dev for Debian family distribution and groonga-devel for Red Hat family distribution.

How to build PostgreSQL

Download source from the PostgreSQL site. Here are command lines to download the source of PostgreSQL 10.0 and extract it:

% wget https://ftp.postgresql.org/pub/source/v10.0/postgresql-10.0.tar.bz2
% tar xf postgresql-10.0.tar.bz2
% cd postgresql-10.0

Run configure with CFLAGS="-O0 -g3" argument. It enables debug build. --prefix=/tmp/local is optional:

% ./configure CFLAGS="-O0 -g3" --prefix=/tmp/local

Build and install PostgreSQL:

% make -j8 > /dev/null
% make install > /dev/null

Initialize and run PostgreSQL:

% mkdir -p /tmp/local/var/lib
% /tmp/local/bin/initdb --locale C --encoding UTF-8 -D /tmp/local/var/lib/postgresql
% /tmp/local/bin/postgres -D /tmp/local/var/lib/postgresql

The following one liner is useful to reset all PostgreSQL related data. You store the one liner in your shell history, you can rerun the one linear quickly:

% rm -rf /tmp/local/var/lib/postgresql && \
    mkdir -p /tmp/local/var/lib/postgresql &&
    /tmp/local/bin/initdb \
      --locale C \
      --encoding UTF-8 \
      -D /tmp/local/var/lib/postgresql && \
   /tmp/local/bin/postgres -D /tmp/local/var/lib/postgresql

How to build and test PGroonga

It's recommended that you use the latest PGroonga instead of released PGroonga. Here are command lines to clone the latest PGroonga source:

% git clone git@github.com:pgroonga/pgroonga.git
% cd pgroonga

PGroonga has two test types:

Normally, you only use the former. test/run-sql-test.sh is the test runner for the former. It builds and installs PGroonga and runs SQL based regression tests. PATH=/tmp/local/bin:$PATH is needed because PostgreSQL is built with --prefix=/tmp/local. pg_config exists in /tmp/local/bin:

% PATH=/tmp/local/bin:$PATH test/run-sql-test.sh

Test

You should create a regression test when you implement a new feature or fix a bug.

Summary

Regression tests exist under sql/ directory. For example, sql/full-text-search/text/single/match-v2/indexscan.sql is a test for the following case:

The expected outputs exist under expected/ directory. Directory structure is the same as sql/ but the expected outputs use .out extension such as expected/full-text-search/text/single/match-v2/indexscan.out.

How to create a regression test

You create a new file under sql/ and put test scenario in SQL into the file. Then, run the file like the following:

% PATH=/tmp/local/bin:$PATH test/run-sql-test.sh sql/.../XXX.sql

The newly created test is failed and test/run-sql-test.sh shows the output of the test scenario. If the output is correct, copy the output and paste it to expected/.../XXX.out.

You should confirm the test is passed by updating expected/.../XXX.out:

% PATH=/tmp/local/bin:$PATH test/run-sql-test.sh sql/.../XXX.sql