initial import of the C runtime

src/runtime/c/README

@@ -0,0 +1,119 @@
+
+This is a preview release of libpgf, a native-code library for parsing
+and linearization of the PGF grammars produced by the Grammatical 
+Framework <http://www.grammaticalframework.org/>.
+
+This release is not yet ready for production use: essential
+functionality is still missing, the API is still likely to change, and
+the documentation is incomplete. This release is primarily meant for
+developers who are interested in using libpgf, and who wish to
+contribute to its design.
+
+
+PREREQUISITES
+-------------
+
+This is a self-contained library: only a C99-conformant C compiler is
+needed. The code is mostly portable C, although it makes some very
+general assumptions about the architecture (mostly regarding the
+representation of addresses) that should hold on modern systems. Still,
+the code has only been tested on Linux-x86(-64) so far. Reports of
+porting problems on other platforms are appreciated.
+
+Although the code "only" requires C99-conformance, it seems that many
+compilers fail at it subtly. In particular:
+
+- Clang does not currently support "extern inline" properly.
+
+- Sun C 5.9 apparently has a bug in its treatment of sizeof on compound
+  array literals.
+
+As a consequence, these compilers cannot be used in the current state of
+the code. Modern versions of GCC, on the other hand, seem to work fine.
+
+
+INSTALLING
+----------
+
+This is a standard GNU Autotools package. Read the attached INSTALL file
+for generic installation instructions. There are currently no
+interesting special configuration options.
+
+Pkg-config configuration files for the library are also provided.
+
+
+STATUS
+------
+
+Currently only very basic PGF functionality is supported, enough to
+translate sentences of the Phrasebook grammar in the GF distribution.
+Among missing features are:
+
+- querying a parser for tokens expected next
+- literals and custom categories
+- higher-order abstract syntax variables
+- type checking and inference
+- generation of random syntax trees
+
+Most of these will eventually get added.
+
+
+PROGRAMS
+--------
+
+There are two small programs included. These are mainly for testing
+purposes and for demonstrating how to use the library.
+
+The pgf2yaml program simply reads a PGF file from the standard input and
+dumps it to the standard output in YAML <http://yaml.org/> format.
+
+The pgf-translate program translates sentences of one language in a PGF
+grammar into another. It is invoked:
+
+pgf-translate PGF CAT FROM_LANG TO_LANG
+
+Where PGF is a PGF file, CAT is the name of the category whose sentences
+are to be translated, and FROM_LANG and TO_LANG are names of concrete
+grammars within the PGF file.
+
+The program prompts for a line containing a full sentence of the
+specified category in the source language, and displays the syntax trees
+and destination language linearizations of all possible parses of that
+sentence.
+
+
+LIBGU
+-----
+
+Along with libpgf proper, this distribution includes libgu, a
+general-purpose utility library that libpgf is based on. Libgu is usable
+independently of libpgf, and may eventually be split into a separate
+package. Do give it a try if you are looking for a library to make C
+programming less painful.
+
+
+DOCUMENTATION
+-------------
+
+Documentation is still fragmentary, but some of the most important
+headers have documentation comments. If you have Doxygen
+<http://doxygen.org/> installed, "make doxygen-doc" will generate HTML
+documentation for the library.
+
+The sources in utils/pgf-translate.c have some comments which may also
+clarify how to use the library.
+
+
+FEEDBACK
+--------
+
+Please report bugs to the Grammatical Framework bug tracker
+<https://code.google.com/p/grammatical-framework/issues/>.
+
+For general questions, comments and suggestions on libpgf, write to the
+GF mailing list at <mailto:gf-dev@googlegroups.com> or
+<https://groups.google.com/group/gf-dev>.
+
+For questions and comments that are related to the core libgu library,
+but not to PGF, please write directly to the author at
+<mailto:lealanko@ling.helsinki.fi>.