Kirill Simonov avatar Kirill Simonov committed 16f3d9b

Added installation guide.

Also, shortened `INSTALL`, included it to the long description of the package.
Added tables of data types and formatters to the reference.

Comments (0)

Files changed (7)

 Installation Instructions
 =========================
 
-The following installation instructions were tested under a fresh installation
-of Ubuntu 10.04 Server, but they could be easily adapted to other Linux
-distributions and package managers.
-
-
-TL;DR version
--------------
-
 1. Install Python and required Python modules::
 
-    # apt-get install python
-    # apt-get install python-setuptools python-yaml python-psycopg2
+        # apt-get install python
+        # apt-get install python-setuptools python-yaml python-psycopg2
 
 2. Install Mercurial and download HTSQL source code::
 
-    # apt-get install mercurial
-    # hg clone http://bitbucket.org/prometheus/htsql
+        # apt-get install mercurial
+        # hg clone http://bitbucket.org/prometheus/htsql
 
 3. Build and install HTSQL::
 
-    # cd htsql
-    # make build
-    # make install
+        # cd htsql
+        # make build
+        # make install
 
-   This should create a ``htsql-ctl`` script.  Run::
+   This creates a ``htsql-ctl`` script.
+   
+4. For general help and a list of commands, run::
 
-    $ htsql-ctl help
+        $ htsql-ctl help
 
-   for general help and list of commands.  Run::
+   To start a command-line HTSQL shell, run::
 
-    $ htsql-ctl server ENGINE://USERNAME:PASSWORD@HOST:PORT/DATABASE [HOST [PORT]]
+        $ htsql-ctl shell DBURI
 
-   to start an HTSQL server on the address `HOST:PORT` against the specified
-   database.  In particular, to run the HTSQL server against a PostgreSQL
-   database deployed on the same machine with credentials of the current
-   user, run::
+   To start an HTTP server running HTSQL, run:
 
-    $ htsql-ctl server pgsql:///DATABASE
+        $ htsql-ctl server DBURI [HOST [PORT]]
 
+   ``DBURI`` specifies how to connect to the database and has the form::
 
-Installing prerequisites
-------------------------
+        ENGINE://USER:PASS@HOST:PORT/DATABASE
 
-HTSQL requires Python 2.5 or newer, but does not support Python 3 yet.
-Python 2.6 is the recommended version.  In some distributions, Python is
-already installed; if not, you could install it by running::
+See also:
 
-    # apt-get install python
+    http://htsql.org/doc/install.html
+        Installation and Administration Guide
 
-HTSQL depends on the following external Python packages:
-
- * `setuptools` (0.6c9 or newer);
- * `PyYAML` (3.07 or newer, compiled with LibYAML bindings);
- * `psycopg2` (2.0.10 or newer, earlier versions are known to segfault).
-
-To install the packages, run::
-
-    # apt-get install python-setuptools python-yaml python-psycopg2
-
-Alternatively, you could install these Python modules from sources using the
-`easy_install` script from `setuptools`.  To do that, you need to install
-header files for Python, PostgreSQL and LibYAML::
-
-    # apt-get install build-essential python-dev libpq-dev libyaml-dev
-    # apt-get install python-setuptools
-    # easy_install PyYAML
-    # easy_install psycopg2
-
-This method allows you to choose the directory where the external Python
-packages will be installed.  By default, `easy_install` installs packages
-under ``/usr/local`` directory.  To install Python packages under your home
-directory, create a file ``.pydistutils.cfg`` in your home directory with
-the following content::
-
-    [install]
-    user=true
-
-and set the environment variable ``PYTHONUSERBASE``::
-
-    export PYTHONUSERBASE=$HOME
-
-Then running `easy_install` will install Python libraries to
-``~/lib/python2.6/site-packages`` (when running under Python 2.6) and Python
-scripts to ``~/bin``.
-
-For more details on customizing the location of external Python modules, see
-`distutils` and `setuptools` documentation.
-
-
-Installing HTSQL
-----------------
-
-Once HTSQL is officially released, you will be able to install it using the
-`easy_install` script::
-
-    # easy_install HTSQL
-
-That will download, build and install the latest released version of HTSQL.
-
-Alternatively, you can install HTSQL from the Mercurial repository at
-BitBucket.  You need a Mercurial client::
-
-    # apt-get install mercurial
-
-Then download HTSQL sources::
-
-    # hg clone http://bitbucket.org/prometheus/htsql
-
-To build and install HTSQL, run::
-
-    # cd htsql
-    # make build
-    # make install
-
-To install HTSQL in the development mode, run::
-
-    # make develop
-
-When HTSQL is installed in the development mode, any changes in the source
-files are reflected immediately without having to reinstall it again.
-
-HTSQL comes with a comprehensive test suite.  Running the regression tests
-requires a PostgreSQL server instance.  By default, the regression tests
-assume that the database server is installed locally and the current user
-has administrative permissions.  To install a local PostgreSQL server, run::
-
-    # apt-get install postgresql
-
-To add a database user with the same name as your login name, run::
-
-    # su - postgres -c "createuser -s $USER"
-
-If the host is a single user machine, it is often convenient to allow
-any user on the system connect to the database under any database user
-name.  To do it, open the file ``/etc/postgresql/8.4/main/pg_hba.conf``
-(replace the version number with the actual version), find the lines::
-
-    # "local" is for Unix domain socket connections only
-    local   all         all                               ident
-
-and replace them with::
-
-    # "local" is for Unix domain socket connections only
-    local   all         all                               trust
-
-Reload the server configuration::
-
-    # service postgresql-8.4 reload
-
-Alternatively, if you already have a PostgreSQL server installed somewhere,
-you can specify the address and connection parameters explicitly.  Copy the
-file ``Makefile.env.sample`` to ``Makefile.env``, open the latter, and edit
-the values of variables: ``PGSQL_ADMIN_USERNAME``, ``PGSQL_ADMIN_PASSWORD``,
-``PGSQL_HOST``, ``PGSQL_PORT``.  They should contain the credentials of
-an administrative user and the address of the server respectively.
-
-To run HTSQL regression tests, run::
-
-    # make test
-
-Running regression tests creates a database user called ``htsql_regress``
-with the password ``secret``, and a database called ``htsql_regress``.  Feel
-free to use this database for playing with HTSQL.
-
-To remove any database users and databases deployed by the regression tests,
-run::
-
-    # make cleanup
-
-To build the documentation that comes with HTSQL, run
-
-    # make doc
-
-Note that this requires Sphinx 1.0+.
-
-
-Running HTSQL
--------------
-
-If HTSQL is installed successfully, you should be able to run the
-`htsql-ctl` script::
-
-    $ htsql-ctl
-
-The script has a number of subcommands called *routines*.  In general, the
-command line has the form::
-
-    htsql-ctl <routine> [options] [arguments]
-
-where ``<routine>`` is the routine name, ``options`` is any routine options
-in short (``-X``) or long (``--option-name``) form, and ``arguments`` is the
-routine arguments.  Run::
-
-    $ htsql-ctl help
-
-to get a list of routines and::
-
-    $ htsql-ctl help <routine>
-
-to describe a specific routine.
-
-To start an HTSQL server, run
-
-    $ htsql-ctl server ENGINE://USERNAME:PASSWORD@HOST:PORT/DATABASE
-
-Here `ENGINE` is either ``pgsql`` or ``sqlite``; `USERNAME:PASSWORD` are
-used for authentication; `HOST:PORT` is the address of the database server;
-and `DATABASE` is the name of the database to connect.  All parameters
-except for `ENGINE` and `DATABASE` are optional.  For instance::
-
-    $ htsql-ctl server pgsql:///htsql_regress
-
-will start the HTSQL server against the HTSQL regression database (provided
-it is deployed by running the regression tests).
-
-By default the server is listening on ``localhost:8080``.  To specify a
-different address of the HTSQL server, use optional arguments `HOST` and
-`PORT`::
-
-    $ htsql-ctl server ENGINE://USERNAME:PASSWORD@HOST:PORT/DATABASE HOST PORT
-
-For more help on the ``server`` routine, run::
-
-    $ htsql-ctl help server
-
-The script also allows you to run HTSQL queries from the console using the
-``shell`` routine.  To start the shell, run::
-
-    $ htsql-ctl shell ENGINE://USERNAME:PASSWORD@HOST:PORT/DATABASE
-
-This will display the command prompt where you could type and execute HTSQL
-queries.  For more details, run
-
-    $ htsql-ctl help shell
-
-or type ``help`` in the shell.
-
-
-.. TODO: Installing on MS Windows
-
-
-Have fun and enjoy!
-
 	@echo "  train-routine: to run tests for htsql-ctl tool in the train mode"
 	@echo "  train-sqlite: to run SQLite-specific tests in the train mode"
 	@echo "  train-pgsql: to run PostgreSQL-specific tests in the train mode"
-	@echo "  purge-test: to purge state test output data"
+	@echo "  purge-test: to purge stale test output data"
 	@echo "  lint: detect errors in the source code"
 	@echo
 	@echo "  *** Shell and Server ***"
 Generous support for HTSQL was provided by the Simons Foundation.
 This material is also based upon work supported by the National
 Science Foundation under Grant #0944460.
+
    showcase
    tutorial
    reference
+   install
    roadmap
    design
    api
+*****************************************
+  Installation and Administration Guide
+*****************************************
+
+.. highlight:: console
+
+The following instructions assume a recent Debian_ or `Debian-derived`_
+system, but could be easily adapted to other Linux distributions and
+package managers.
+
+.. _Debian: http://debian.org/
+.. _Debian-derived: http://ubuntu.com/
+
+
+Quick Start
+===========
+
+1. Install Python_ and required Python modules (setuptools_, pyyaml_,
+   psycopg2_)::
+
+        # apt-get install python
+        # apt-get install python-setuptools python-yaml python-psycopg2
+
+2. Install Mercurial_ and download `HTSQL source code`_::
+
+        # apt-get install mercurial
+        $ hg clone http://bitbucket.org/prometheus/htsql
+
+3. Build and install HTSQL::
+
+        $ cd htsql
+        $ make build
+        # make install
+
+4. The previous step creates an ``htsql-ctl`` executable.  For general
+   help and a list of commands, run::
+
+        $ htsql-ctl help
+
+   To start a command-line HTSQL shell, run::
+
+        $ htsql-ctl shell DBURI
+
+   To start an HTTP server running HTSQL on on the address ``HOST:PORT``,
+   type::
+
+        $ htsql-ctl server DBURI [HOST [PORT]]
+
+   The parameter ``DBURI`` specifies how to connect to a database.  For
+   a SQLite database, ``DBURI`` has the form:
+
+   .. sourcecode:: text
+
+        sqlite:/path/to/database
+
+   For a PostgreSQL database, ``DBURI`` has the form:
+
+   .. sourcecode:: text
+
+        pgsql://user:pass@host:port/database
+
+   Both ``user:pass`` and ``host:port`` components are optional.
+
+.. _Python: http://python.org/
+.. _setuptools: http://pypi.python.org/pypi/setuptools
+.. _pyyaml: http://pypi.python.org/pypi/PyYAML
+.. _psycopg2: http://pypi.python.org/pypi/psycopg2
+.. _Mercurial: http://mercurial.selenic.com/
+.. _HTSQL source code: http://bitbucket.org/prometheus/htsql
+
+
+Installation
+============
+
+Installing Prerequisites
+------------------------
+
+HTSQL requires Python 2.5 or newer, but does not yet support Python 3.
+Python 2.6 is the recommended version.  In most distributions, Python
+is already installed; if not, install it by running::
+
+    # apt-get install python
+
+HTSQL depends on the following Python libraries:
+
+* setuptools_ (``0.6c9`` or newer);
+* pyyaml_ (``3.07`` or newer);
+* psycopg2_ (``2.0.10`` or newer).
+
+To install the libraries, run::
+
+    # apt-get install python-setuptools python-yaml python-psycopg2
+
+Installing HTSQL
+----------------
+
+Since HTSQL is still at an early stage of development, we recommend
+installing HTSQL directly from the `HTSQL source repository`_.  You need
+a Mercurial client::
+
+    # apt-get install mercurial
+
+To download `HTSQL source code`_::
+
+    $ hg clone http://bitbucket.org/prometheus/htsql
+
+To build and install HTSQL, run::
+
+    $ cd htsql
+    $ make build
+    # make install
+
+That installs the HTSQL executable ``htsql-ctl`` to ``/usr/local/bin``
+and HTSQL library files to ``/usr/local/lib``.
+
+To install HTSQL in a development mode, run::
+
+    # make develop
+
+When HTSQL is installed in the development mode, any changes in the
+source files are reflected immediately without need to reinstall.
+
+HTSQL comes with a comprehensive suite of regression tests.  By default,
+the suite assumes that a PostgreSQL instance is running on the same machine
+and the current user has administrative permissions.  To run the tests::
+
+    $ make test
+
+Connection parameters to the test server could be specified explicitly.  Copy
+the file ``Makefile.env.sample`` to ``Makefile.env`` and open the latter.  To
+set the credentials of an administrative user, update parameters
+``PGSQL_ADMIN_USERNAME`` and ``PGSQL_ADMIN_PASSWORD``.  To set the address of
+the database server, update parameters ``PGSQL_HOST`` and ``PGSQL_PORT``.
+
+Running regression tests creates a PostgreSQL database ``htsql_regress`` and a
+database user with the same name.  To remove any database users and databases
+deployed by the regression tests, run::
+
+    $ make cleanup
+
+To learn other ``make`` targets, run::
+
+    $ make
+
+.. _HTSQL source repository: http://bitbucket.org/prometheus/htsql
+
+
+Usage
+=====
+
+The ``htsql-ctl`` Executable
+----------------------------
+
+Installing HTSQL creates an ``htsql-ctl`` command-line application::
+
+    $ htsql-ctl
+
+The ``htsql-ctl`` script is a collection of subcommands called
+*routines*.  The command-line syntax of ``htsql-ctl`` is
+
+::
+
+    $ htsql-ctl <routine> [options] [arguments]
+
+* ``<routine>`` is the routine name;
+* ``options`` are any routine options in short (``-X``)
+  or long (``--option-name``) form;
+* ``arguments`` are routine arguments.
+
+To get a list of routines, run::
+
+    $ htsql-ctl help
+
+To describe a specific routine, run::
+
+    $ htsql-ctl help <routine>
+
+Database Connection
+-------------------
+
+Many routines require a ``DBURI`` parameter, which specifies how to
+connect to a database.  ``DBURI`` has the form:
+
+.. sourcecode:: text
+
+    engine://user:pass@host:port/database
+
+* ``engine`` is the type of the database server; ``sqlite`` for SQLite,
+  ``pgsql`` for PostgreSQL;
+* ``user:pass`` are authentication parameters;
+* ``host:port`` is the address of the database server;
+* ``database`` is the name of the database.
+
+For SQLite, ``user:pass`` and ``host:port`` are omitted, and ``database``
+specifies the path to the database file.  Thus, for SQLite, ``DBURI`` has
+the form:
+
+.. sourcecode:: text
+
+    sqlite:/path/to/database
+
+For PostgreSQL, if ``user:pass`` is omitted, the credentials of the
+current user are used; if ``host:port`` is omitted, the server is
+assumed to run on the local machine.  Thus, to connect to a database
+running on the same host under credentials of the current user, use
+the form:
+
+.. sourcecode:: text
+
+    pgsql:database
+
+Command-line Shell
+------------------
+
+To start a command-line HTSQL shell, run::
+
+    $ htsql-ctl shell DBURI
+
+That starts an interactive HTSQL shell, where you could type and execute
+HTSQL queries against the specified database.
+
+For more details on the ``shell`` routine, run::
+
+    $ htsql-ctl help shell
+
+HTTP Server
+-----------
+
+To start an HTTP server running HTSQL, run::
+
+    $ htsql-ctl server DBURI [HOST [PORT]]
+
+That starts an HTTP server on the address ``HOST:PORT``.  If ``HOST``
+and ``PORT`` are omitted, the server is started on ``*:8080``.
+
+For more details on the ``server`` routine, run::
+
+    $ htsql-ctl help server
+
+

doc/reference.rst

         literal      ::= STRING | NUMBER
 
 
+Data Types
+==========
+
++----------------------+---------------------------+---------------------------+----------------------+
+| Type                 | Description               | Example Input             | Output               |
++======================+===========================+===========================+======================+
+| `boolean`            | logical data type, with   | ``true()``                |                      |
+|                      | two values: *TRUE* and    +---------------------------+----------------------+
+|                      | *FALSE*                   | ``false()``               |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `integer`            | binary integer type       | ``4096``                  |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `decimal`            | arbitrary-precision       | ``124.49``                |                      |
+|                      | exact numeric type        |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `float`              | IEEE 754 floating-point   | ``271828e-5``             |                      |
+|                      | inexact numeric type      |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `string`             | text data type            | ``string('HTSQL')``       |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `enum`               | enumeration data type,    |                           |                      |
+|                      | with predefined set of    |                           |                      |
+|                      | valid string values       |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `date`               | date data type            | ``date('2010-04-15')``    |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `opaque`             | unrecognized data type    |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+
+Special Data Types
+==================
+
++----------------------+---------------------------+---------------------------+----------------------+
+| Type                 | Description               | Example Input             | Output               |
++======================+===========================+===========================+======================+
+| `untyped`            | initially assigned type   | ``'HTSQL'``               |                      |
+|                      | of quoted literals        |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `tuple`              | type of chain expressions |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `void`               | type without any valid    |                           |                      |
+|                      | values                    |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+
+
 Function Syntax
 ===============
 
 +----------------------+---------------------------+---------------------------+----------------------+
 
 
+Formatters
+==========
+
++----------------------+---------------------------+---------------------------+----------------------+
+| Function             | Description               | Example Input             | Output               |
++======================+===========================+===========================+======================+
+| `/:html`             | HTML tabular output       |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `/:txt`              | plain text tabular output |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `/:csv`              | CSV (comma-separated      |                           |                      |
+|                      | values) output            |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+| `/:json`             | JSON-serialized output    |                           |                      |
++----------------------+---------------------------+---------------------------+----------------------+
+
 from setuptools import setup, find_packages
 import os.path
 
-# We use the merged content of `README` and `NEWS` as the
+# We use the merged content of `README`, `INSTALL`, and `NEWS` as the
 # long description of the package.
 
 root = os.path.dirname(__file__)
 README = open(os.path.join(root, 'README')).read()
+INSTALL = open(os.path.join(root, 'INSTALL')).read()
 NEWS = open(os.path.join(root, 'NEWS')).read()
 
 # The distutils parameters are defined here.  Do not forget to update
 NAME = "HTSQL"
 VERSION = "2.0.0c1"
 DESCRIPTION = "Query language for the accidental programmer"
-LONG_DESCRIPTION = "\n".join([README, NEWS])
+LONG_DESCRIPTION = "\n".join([README, INSTALL, NEWS])
 AUTHOR = "Clark C. Evans and Kirill Simonov; Prometheus Research, LLC"
 AUTHOR_EMAIL = "cce@clarkevans.com"
 LICENSE = "Free To Use But Restricted"
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.