msyds/gf-core
1
0
Fork 0
forked from GitHub/gf-core
Code Pull Requests Activity

Updated the GF Developers Guide

Browse Source 
+ The instructions have been modernized and simplified slightly and should now
  work again. (I have not verified it on Windows.)
  Using 'cabal' instead of 'runghc Setup.hs' avoids some problems.
+ Also, download/index.html has simpler installation instructions sufficient
  for many users, so mention it in the main README file.
+ Also adjusted the main Makefile.
This commit is contained in:
hallgren
2012-08-06 16:14:47 +00:00
parent 3601b796e5
commit 06c9e4999f
5 changed files with 456 additions and 432 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
Makefile
View File

@@ -1,28 +1,28 @@
.PHONY: all build install doc clean sdist gf .PHONY: all build install doc clean gf # sdist
all: build all: build
dist/setup-config: gf.cabal dist/setup-config: gf.cabal Setup.hs
chmod u+x lib/src/mkPresent cabal configure
chmod u+x lib/src/mkMinimal
runghc Setup.hs configure
build: dist/setup-config build: dist/setup-config
runghc Setup.hs build cabal build
install: install:
runghc Setup.hs install cabal copy
cabal register
doc: doc:
runghc Setup.hs haddock cabal haddock
clean: clean:
runghc Setup.hs clean cabal clean
#sdist:
# cabal sdist
sdist:
runghc Setup.hs sdist
gf: gf:
runghc Setup.hs build rgl-none cabal build rgl-none
strip dist/build/gf/gf strip dist/build/gf/gf
html:: html::

3
README
View File

@@ -30,4 +30,5 @@ GF particularly addresses four aspects of grammars:
COMPILATION and INSTALLATION of source distribution: COMPILATION and INSTALLATION of source distribution:
See doc/gf-developers.html for installation instructions. See download/index.html for installation instructions.
(More details can be found in doc/gf-developers.html.)

6
css/style.css
View File

@@ -2,9 +2,9 @@
body { background-color: #f2f2f2; } body { background-color: #f2f2f2; }
h1,h2,h3 { font-family: sans-serif; color: #303030; h1,h2,h3,h4 { font-family: sans-serif; color: #303030;
text-shadow: rgba(0,0,0,0.25) 2px 2px 5px; text-shadow: rgba(0,0,0,0.25) 2px 2px 5px;
} }
h1 { text-align: center; } h1 { text-align: center; }
h2 { border-bottom: 2px solid #303030; clear: right; } h2 { border-bottom: 2px solid #303030; clear: right; }

513
doc/gf-developers.html
View File

@@ -7,67 +7,93 @@
<TITLE>GF Developers Guide</TITLE> <TITLE>GF Developers Guide</TITLE>
</HEAD><BODY BGCOLOR="white" TEXT="black"> </HEAD><BODY BGCOLOR="white" TEXT="black">
<CENTER> <CENTER>
<H1>GF Developers Guide</H1> <H1><a href="../"><IMG src="../doc/Logos/gf0.png"></a>GF Developers Guide</H1>
<FONT SIZE="4"><I>Authors: Björn Bringert, Krasimir Angelov and Thomas Hallgren</I></FONT><BR> <FONT SIZE="4"><I>Authors: Björn Bringert, Krasimir Angelov and Thomas Hallgren</I></FONT><BR>
<FONT SIZE="4">Last update: Tue May 15 14:51:04 2012, but some information here is outdated</FONT> <FONT SIZE="4">Last update: 2012-08-06, 18:08</FONT>
</CENTER> </CENTER>
<P></P> <P></P>
<HR NOSHADE SIZE=1> <HR NOSHADE SIZE=1>
<P></P> <P></P>
<UL>
<LI><A HREF="#toc1">Setting up your system for building GF</A>
<LI><A HREF="#toc2">Getting the sources</A>
<UL> <UL>
<LI><A HREF="#toc3">Read-only access</A> <LI><A HREF="#toc1">Before you start</A>
<LI><A HREF="#toc2">Setting up your system for building GF</A>
<UL> <UL>
<LI><A HREF="#toc4">Getting a fresh copy for read-only access</A> <LI><A HREF="#toc3">The Haskell Platform</A>
<LI><A HREF="#toc5">Updating your copy</A> <LI><A HREF="#toc4">Darcs</A>
<LI><A HREF="#toc6">Recording local changes</A> <LI><A HREF="#toc5">The haskeline library</A>
<LI><A HREF="#toc7">Submitting patches</A>
</UL> </UL>
<LI><A HREF="#toc8">Read-write access</A> <LI><A HREF="#toc6">Getting the source</A>
<UL> <UL>
<LI><A HREF="#toc9">Getting a fresh copy</A> <LI><A HREF="#toc7">Read-only access</A>
<LI><A HREF="#toc10">Getting other people's changes?</A> <LI><A HREF="#toc8">Read-write access</A>
<LI><A HREF="#toc11">Commit your changes</A> <LI><A HREF="#toc9">Further information about Darcs</A>
<LI><A HREF="#toc12">Apply a patch from someone else</A>
</UL> </UL>
<LI><A HREF="#toc13">Further information about Darcs</A> <LI><A HREF="#toc10">Compilation from source</A>
<UL>
<LI><A HREF="#toc11">Configure</A>
<LI><A HREF="#toc12">Build</A>
<LI><A HREF="#toc13">Install</A>
<LI><A HREF="#toc14">Clean</A>
</UL>
<LI><A HREF="#toc15">Compilation with make</A>
<LI><A HREF="#toc16">Running the testsuite</A>
</UL> </UL>
<LI><A HREF="#toc14">Compilation from sources</A>
<UL>
<LI><A HREF="#toc15">Configure</A>
<LI><A HREF="#toc16">Build</A>
<LI><A HREF="#toc17">Install</A>
<LI><A HREF="#toc18">Clean</A>
<LI><A HREF="#toc19">SDist</A>
</UL>
<LI><A HREF="#toc20">Compilation with make</A>
<LI><A HREF="#toc21">Running the testsuite</A>
</UL>
<P></P> <P></P>
<HR NOSHADE SIZE=1> <HR NOSHADE SIZE=1>
<P></P> <P></P>
<A NAME="toc1"></A> <A NAME="toc1"></A>
<H1>Setting up your system for building GF</H1> <H2>Before you start</H2>
<P> <P>
Before to build GF from sources you need to install some tools on your system. This guide is intended for people who want to contribute to
GF is written in Haskell, so first of all you need recent version of the Haskell compiler GHC. the development of the GF compiler or the Resource Grammar Library. If
Currently we use GHC 6.10.3 and we recommend that you should use the same version you are a GF user who just wants to download and install GF
as well. This version is not backward compatible with the previous major releases (e.g to develop your own grammars), the simpler guide on
so you cannot use previous versions. GHC is available from here: <A HREF="../download/index.html">the GF download page</A> should be sufficient.
</P>
<A NAME="toc2"></A>
<H2>Setting up your system for building GF</H2>
<P>
To build GF from source you need to install some tools on your
system: the <I>Haskell Platform</I>, <I>Darcs</I> and the <I>Haskeline library</I>.
</P> </P>
<P> <P>
<A HREF="http://www.haskell.org/ghc/">http://www.haskell.org/ghc/</A> <B>On Linux</B> the best option is to install the tools via the standard
software distribution channels, i.e. by using the <I>Software Center</I>
in Ubuntu or the corresponding tool in other popular Linux distributions.
Or, from a Terminal window, the following command should be enough:
</P>
<UL>
<LI>On Ubuntu: <CODE>sudo apt-get install haskell-platform darcs libghc6-haskeline-dev</CODE>
<LI>On Fedora: <CODE>sudo yum install haskell-platform darcs ghc-haskeline-devevel</CODE>
</UL>
<P>
<B>On Mac OS and Windows</B>, the tools can be downloaded from their respective
web sites, as described below.
</P>
<A NAME="toc3"></A>
<H3>The Haskell Platform</H3>
<P>
GF is written in Haskell, so first of all you need
the <I>Haskell Platform</I>, version 2010.2.0.0 or later. Downloads
and installation instructions are available from here:
</P> </P>
<P> <P>
Once you have installed GHC, open a terminal (Command Prompt on Windows) and try <A HREF="http://hackage.haskell.org/platform/">http://hackage.haskell.org/platform/</A>
to execute the following command: </P>
<P>
Once you have installed the Haskell Platform, open a terminal
(Command Prompt on Windows) and try to execute the following command:
</P> </P>
<PRE> <PRE>
@@ -76,83 +102,62 @@ to execute the following command:
<P> <P>
This command should show you which version of GHC you have. If the installation This command should show you which version of GHC you have. If the installation
of GHC was successful you should see message like: of the Haskell Platform was successful you should see a message like:
</P> </P>
<PRE> <PRE>
The Glorious Glasgow Haskell Compilation System, version 6.10.3 The Glorious Glasgow Haskell Compilation System, version 7.0.4
</PRE> </PRE>
<P> <P>
The other two tools that we use are the lexer generator for Haskell - Alex: Other required tools included in the Haskell Platform are
<A HREF="http://www.haskell.org/alex/">http://www.haskell.org/alex/</A> <A HREF="http://www.haskell.org/cabal/">Cabal</A>,
and the parser generator - Happy: <A HREF="http://www.haskell.org/alex/">Alex</A> and
<A HREF="http://www.haskell.org/happy/">http://www.haskell.org/happy/</A>. <A HREF="http://www.haskell.org/happy/">Happy</A>.
Again after the installation check that the tools are available from the terminal.
If they are not then probably you have to update the current search path in your system.
</P> </P>
<A NAME="toc4"></A>
<H3>Darcs</H3>
<P> <P>
It is also a good idea to have either readline, editline or haskeline installed. To get the GF source code, you also need <I>Darcs</I>, version 2 or later. Darcs
This are libraries for user friendly command line editing. On Linux, without some of this is a distributed version control system, see <A HREF="http://darcs.net/">http://darcs.net/</A> for
libraries, the command line editor is very basic. Actually the only key for editing more information. There are precompiled packages for many platforms
that you can use is backspace. On Windows you get much more user friendly editor available at and source code if you want to compile it yourself. Darcs
by default but with it you cannot use the GF specific tab completion. In any case if you is also written in Haskell and so you can use GHC to compile it.
plan to use GF for continuous development then it is recomended to install </P>
some of these libraries. The GF configuration script checks the libraries
in the following order: <A NAME="toc5"></A>
<H3>The haskeline library</H3>
<P>
GF uses <I>haskeline</I> to enable command line editing in the GF shell.
This should work automatically on Mac OS and Windows, but on Linux one
extra step is needed to make sure the C libraries required by <I>haskeline</I>
are installed. Here is one way to do this:
</P> </P>
<UL> <UL>
<LI>haskeline <LI>On Ubuntu: <CODE>sudo apt-get install libghc6-haskeline-dev</CODE>
<LI>readline <LI>On Fedora: <CODE>sudo yum install ghc-haskeline-devel</CODE>
<LI>editline
</UL> </UL>
<P> <A NAME="toc6"></A>
the first that is found will be used in the compilation. The libraries are also written <H2>Getting the source</H2>
in Haskell and could be found on Hackage: <A HREF="http://hackage.haskell.org/packages/archive/pkg-list.html">http://hackage.haskell.org/packages/archive/pkg-list.html</A>. If you want to check whether,
you already have some of these you can use the following command:
</P>
<PRE>
$ ghc-pkg list
</PRE>
<P> <P>
which shows the list of all installed libraries. Once you have all tools in place you can get the GF source code. If you
</P> just want to compile and use GF then it is enough to have read-only
<P> access. It is also possible to make changes in the source code but if you
Haskeline is the easiest to install because it is a pure Haskell library but currently want these changes to be applied back to the main source repository you will
with this editor GF doesn't provide word completion. With editline we provide word completion have to send the changes to us. If you plan to work continuously on
but the library is harder to install because it is a Haskell binding to a GF then you should consider getting read-write access.
library with the same name written in C. If you do not have the C library you will have to install
it first. Unfortunately editline does not have good support for Unicode. This will be a problem
if you tend to work on non-Latin language. Finaly readline supports both word completion
and Unicode. Currently this is the best supported library.
</P>
<P>
Before to get the GF sources you also need Darcs, version 2 or later.
Darcs is a decentralized revision control system,
see <A HREF="http://darcs.net/">http://darcs.net/</A> for more information. There are precompiled packages for many platforms available at
<A HREF="http://darcs.net/DarcsWiki/CategoryBinaries">http://darcs.net/DarcsWiki/CategoryBinaries</A>. There is also source code if you want to compile it yourself. Darcs is
also written in Haskell and so you can use GHC to compile it.
</P> </P>
<A NAME="toc2"></A> <A NAME="toc7"></A>
<H1>Getting the sources</H1> <H3>Read-only access</H3>
<P> <H4>Getting a fresh copy for read-only access</H4>
Once you have all tools in place you can get the GF sources. If you just want to compile and use GF
then it is enough to have read-only access. It is also possible to make changes in the sources but if
you want these changes to be applied back to the main sources you will have to send the changes to us.
If you plan to work continuously on GF then you should consider to get read-write access.
</P>
<A NAME="toc3"></A>
<H2>Read-only access</H2>
<A NAME="toc4"></A>
<H3>Getting a fresh copy for read-only access</H3>
<P> <P>
Anyone can get the latest development version of GF by running (all on one line): Anyone can get the latest development version of GF by running (all on one line):
@@ -167,8 +172,7 @@ This will create a directory called <CODE>gf</CODE> in the current
directory. directory.
</P> </P>
<A NAME="toc5"></A> <H4>Updating your copy</H4>
<H3>Updating your copy</H3>
<P> <P>
To get all new patches from the main repo: To get all new patches from the main repo:
@@ -184,8 +188,8 @@ directory, or any of its subdirectories.
Without <CODE>-a</CODE>, you can choose which patches you want to get. Without <CODE>-a</CODE>, you can choose which patches you want to get.
</P> </P>
<A NAME="toc6"></A> <A NAME="record"></A>
<H3>Recording local changes</H3> <H4>Recording local changes</H4>
<P> <P>
Since every copy is a repository, you can have local version control Since every copy is a repository, you can have local version control
@@ -221,8 +225,7 @@ question. Both of these record all the changes you have in your local
repository. repository.
</P> </P>
<A NAME="toc7"></A> <H4>Submitting patches</H4>
<H3>Submitting patches</H3>
<P> <P>
If you are using read-only access, send your patches by email to If you are using read-only access, send your patches by email to
@@ -250,15 +253,14 @@ patch directly from darcs. If so, replace <CODE>-o mypatch.patch</CODE> with
</P> </P>
<A NAME="toc8"></A> <A NAME="toc8"></A>
<H2>Read-write access</H2> <H3>Read-write access</H3>
<P> <P>
If you have a user account on <A HREF="http://www.grammaticalframework.org">www.grammaticalframework.org</A>, you can If you have a user account on <A HREF="http://www.grammaticalframework.org">www.grammaticalframework.org</A>, you can
get read-write access over SSH to the GF repository. get read-write access over SSH to the GF repository.
</P> </P>
<A NAME="toc9"></A> <H4>Getting a fresh copy</H4>
<H3>Getting a fresh copy</H3>
<P> <P>
Get your copy with (all on one line), Get your copy with (all on one line),
@@ -276,8 +278,7 @@ and most people don't need the full history of all changes in the
past. past.
</P> </P>
<A NAME="toc10"></A> <H4>Updating your copy</H4>
<H3>Getting other people's changes?</H3>
<P> <P>
Get all new patches from the main repo: Get all new patches from the main repo:
@@ -291,15 +292,13 @@ Get all new patches from the main repo:
Without <CODE>-a</CODE>, you can choose which patches you want to get. Without <CODE>-a</CODE>, you can choose which patches you want to get.
</P> </P>
<A NAME="toc11"></A> <H4>Commit your changes</H4>
<H3>Commit your changes</H3>
<P> <P>
There are two steps to commiting a change to the main repo. First you There are two steps to commiting a change to the main repo. First you
have to record the changes that you want to commit, then you push them have to record the changes that you want to commit
to the main repo. For instructions on recording your changes locally, (see <A HREF="#record">Recording local changes</A> above), then you push them
see "Recording local changes" above. Then you can push the patch(es) to to the main repo. If you are using ssh-access, all you need to do is:
the main repo. If you are using ssh-access, all you need to do is:
</P> </P>
<PRE> <PRE>
@@ -311,8 +310,7 @@ If you use the <CODE>-a</CODE> flag to push, all local patches which are not in
the main repo are pushed. the main repo are pushed.
</P> </P>
<A NAME="toc12"></A> <H4>Apply a patch from someone else</H4>
<H3>Apply a patch from someone else</H3>
<P> <P>
Use: Use:
@@ -327,132 +325,140 @@ This applies the patch to your local repository. To commit it to the
main repo, use <CODE>darcs push</CODE>. main repo, use <CODE>darcs push</CODE>.
</P> </P>
<A NAME="toc13"></A> <A NAME="toc9"></A>
<H2>Further information about Darcs</H2> <H3>Further information about Darcs</H3>
<P> <P>
For more info about what you can do with darcs, see <A HREF="http://darcs.net/manual/">http://darcs.net/manual/</A> For more info about what you can do with darcs, see <A HREF="http://darcs.net/manual/">http://darcs.net/manual/</A>
</P> </P>
<A NAME="toc10"></A>
<H2>Compilation from source</H2>
<P>
The build system of GF is based on <I>Cabal</I>, which is part of the
Haskell Platform, so no extra steps are needed to install it. In the simplest
case, all you need to do to compile and install GF, after downloading the
source code as described above, is
</P>
<PRE>
$ cd gf
$ cabal install
</PRE>
<P>
This will automatically download any additional Haskell libraries needed to
build GF. If this is the first time you use Cabal, you might need to run
<CODE>cabal update</CODE> first, to update the list of available libraries.
</P>
<P>
If you want more control, the process can also be split up into the usual
<I>configure</I>, <I>build</I> and <I>install</I> steps.
</P>
<A NAME="toc11"></A>
<H3>Configure</H3>
<P>
During the configuration phase Cabal will check that you have all
necessary tools and libraries needed for GF. The configuration is
started by the command:
</P>
<PRE>
$ cabal configure
</PRE>
<P>
If you don't see any error message from the above command then you
have everything that is needed for GF. You can also add the option
<CODE>-v</CODE> to see more details about the configuration.
</P>
<P>
You can use <CODE>cabal configure --help</CODE> to get a list of configuration options.
</P>
<A NAME="toc12"></A>
<H3>Build</H3>
<P>
The build phase does two things. First it builds the GF compiler from
the Haskell source code and after that it builds the GF Resource Grammar
Library using the already build compiler. The simplest command is:
</P>
<PRE>
$ cabal build
</PRE>
<P>
Again you can add the option <CODE>-v</CODE> if you want to see more details.
</P>
<P>
Sometimes you just want to work on the GF compiler and don't want to
recompile the resource library after each change. In this case use
this extended command:
</P>
<PRE>
$ cabal build rgl-none
</PRE>
<P>
The resource library could also be compiled in two modes: with present
tense only and with all tenses. By default it is compiled with all
tenses. If you want to use the library with only present tense you can
compile it in this special mode with the command:
</P>
<PRE>
$ cabal build present
</PRE>
<P>
You could also control which languages you want to be recompiled by
adding the option <CODE>langs=list</CODE>. For example the following command
will compile only the English and the Swedish language:
</P>
<PRE>
$ cabal build langs=Eng,Swe
</PRE>
<A NAME="toc13"></A>
<H3>Install</H3>
<P>
After you have compiled GF you need to install the executable and libraries
to make the system usable.
</P>
<PRE>
$ cabal copy
$ cabal register
</PRE>
<P>
This command installs the GF compiler for a single user, in the standard
place used by Cabal.
On Linux and Mac this could be <CODE>$HOME/.cabal/bin</CODE>.
On Mac it could also be <CODE>$HOME/Library/Haskell/bin</CODE>.
On Windows this is <CODE>C:\Program Files\Haskell\bin</CODE>.
</P>
<P>
The compiled GF Resource Grammar Library will be installed
under the same prefix, e.g. in
<CODE>$HOME/.cabal/share/gf-3.3.3/lib</CODE> on Linux and
in <CODE>C:\Program Files\Haskell\gf-3.1\lib</CODE> on Windows.
</P>
<P>
If you want to install in some other place then use the <CODE>--prefix</CODE>
option during the configuration phase.
</P>
<A NAME="toc14"></A> <A NAME="toc14"></A>
<H1>Compilation from sources</H1> <H3>Clean</H3>
<P>
The build system of GF is based on Cabal (see <A HREF="http://www.haskell.org/cabal/">http://www.haskell.org/cabal/</A> for more information).
Cabal is installed by default together with the GHC compiler. This is actually a library which could
be used from Haskell to compile projects written in Haskell. The entry point is a script
called Setup.hs which is placed in the top directory of every project managed with Cabal.
The three main steps that are needed for compilation are much like what you do in a project
written in C, you have: configure, build and install.
</P>
<A NAME="toc15"></A>
<H2>Configure</H2>
<P>
During the configuration phase Cabal will check that you have all necessary tools and libraries
needed for GF. The configuration is started by the command:
</P>
<PRE>
$ runghc Setup.hs configure
</PRE>
<P>
The command <CODE>`runghc`</CODE> comes with the GHC compiler and is batch interpreter which executes
the specified script without the need to compile it advance. Setup.hs is our compilation driver
which is based on Cabal. If you don't see any error message from the above command then
you have everything that is needed for GF. You can also add the option <CODE>`-v`</CODE> to see
more details about the configuration.
</P>
<A NAME="toc16"></A>
<H2>Build</H2>
<P>
The build phase does two things. First it builds the GF compiler from the Haskell sources
and after that it builds the GF Resource Grammar Library using the already build compiler.
The simplest command is:
</P>
<PRE>
$ runghc Setup.hs build
</PRE>
<P>
Again you can add the option <CODE>`-v`</CODE> if you want to see more details.
</P>
<P>
Sometimes you just want to work on the GF compiler and don't want to recompile the resource
library after each change. In this case use this extended command:
</P>
<PRE>
$ runghc Setup.hs build rgl-none
</PRE>
<P>
The resource library could also be compiled in two modes: with present tense only and
with all tenses. By default it is compiled with all tenses. If you want to use
the library with only present tense you can compile it in this special mode with
the command:
</P>
<PRE>
$ runghc Setup.hs build present
</PRE>
<P>
Before to use this command make sure that the script lib/src/mkPresent has executable
permissions on Linux.
</P>
<P>
You could also control which languages you want to be recompiled by adding the option
<CODE>`langs=list`</CODE>. For example the following command will compile only the English and the Swedish
language:
</P>
<PRE>
$ runghc Setup.hs build langs=Eng,Swe
</PRE>
<A NAME="toc17"></A>
<H2>Install</H2>
<P>
After you have compiled GF you can install the binaries to make the system usable.
On Linux you will need root privileges to do this. Use the command:
</P>
<PRE>
$ su
</PRE>
<P>
and enter the root password. This step should be skipped on Windows.
</P>
<P>
The installation itself is started with the command:
</P>
<PRE>
$ runghc Setup.hs install
</PRE>
<P>
This command installs the GF compiler in the default place for executable
files in your system. For example on Linux this is usualy /usr/local/bin and on
Windows this is c:\Program Files\Haskell\bin. If you want to install in some
other place then use the <CODE>`--prefix`</CODE> option during the configuration phase.
</P>
<P>
The compiled GF Resource Grammar Library will be installed in /usr/local/share/gf-3.1/lib
on Linux and in c:\Program Files\Haskell\gf-3.1\lib on Windows. Again the location could
be changed using the <CODE>`--prefix`</CODE> option.
</P>
<A NAME="toc18"></A>
<H2>Clean</H2>
<P> <P>
Sometimes you want to clean up the compilation and start again from clean Sometimes you want to clean up the compilation and start again from clean
@@ -460,26 +466,11 @@ sources. Use the clean command for this purpose:
</P> </P>
<PRE> <PRE>
$ runghc Setup.hs clean $ cabal clean
</PRE> </PRE>
<A NAME="toc19"></A> <A NAME="toc15"></A>
<H2>SDist</H2> <H2>Compilation with make</H2>
<P>
You can use the command:
</P>
<PRE>
$ runghc Setup.hs sdist
</PRE>
<P>
to prepare archive with all source codes needed to compile GF.
</P>
<A NAME="toc20"></A>
<H1>Compilation with make</H1>
<P> <P>
If you feel more comfortable with Makefiles then there is a thin Makefile If you feel more comfortable with Makefiles then there is a thin Makefile
@@ -516,23 +507,19 @@ For cleaning:
$ make clean $ make clean
</PRE> </PRE>
<A NAME="toc16"></A>
<H2>Running the testsuite</H2>
<P> <P>
and to build source distribution archive run: <B>NOTE:</B> The test suite has not been maintained recently, so expect many
tests to fail.
</P> </P>
<PRE>
$ make sdist
</PRE>
<A NAME="toc21"></A>
<H1>Running the testsuite</H1>
<P> <P>
GF has testsuite. It is run with the following command: GF has testsuite. It is run with the following command:
</P> </P>
<PRE> <PRE>
$ runghc Setup.hs test $ cabal test
</PRE> </PRE>
<P> <P>
@@ -560,7 +547,7 @@ in which you are interested. For example:
</P> </P>
<PRE> <PRE>
$ runghc Setup.hs test testsuite/compiler $ cabal test testsuite/compiler
</PRE> </PRE>
<P> <P>

340
doc/gf-developers.t2t
View File

@@ -1,6 +1,6 @@
GF Developers Guide GF Developers Guide
Authors: Björn Bringert, Krasimir Angelov and Thomas Hallgren Authors: Björn Bringert, Krasimir Angelov and Thomas Hallgren
Last update: %%mtime(%c), but some information here is outdated Last update: %%mtime(%F, %H:%M)
% NOTE: this is a txt2tags file. % NOTE: this is a txt2tags file.
% Create an html file from this file using: % Create an html file from this file using:
@@ -10,81 +10,90 @@ Last update: %%mtime(%c), but some information here is outdated
%!target:html %!target:html
%!options(html): --toc %!options(html): --toc
%!encoding:utf-8 %!encoding:utf-8
%!postproc(html): <H1> <H1><a href="../"><IMG src="../doc/Logos/gf0.png"></a>
= Setting up your system for building GF = == Before you start ==
Before to build GF from sources you need to install some tools on your system. This guide is intended for people who want to contribute to
GF is written in Haskell, so first of all you need recent version of the Haskell compiler GHC. the development of the GF compiler or the Resource Grammar Library. If
Currently we use GHC 6.10.3 and we recommend that you should use the same version you are a GF user who just wants to download and install GF
as well. This version is not backward compatible with the previous major releases (e.g to develop your own grammars), the simpler guide on
so you cannot use previous versions. GHC is available from here: [the GF download page ../download/index.html] should be sufficient.
http://www.haskell.org/ghc/ == Setting up your system for building GF ==
Once you have installed GHC, open a terminal (Command Prompt on Windows) and try To build GF from source you need to install some tools on your
to execute the following command: system: the //Haskell Platform//, //Darcs// and the //Haskeline library//.
**On Linux** the best option is to install the tools via the standard
software distribution channels, i.e. by using the //Software Center//
in Ubuntu or the corresponding tool in other popular Linux distributions.
Or, from a Terminal window, the following command should be enough:
- On Ubuntu: ``sudo apt-get install haskell-platform darcs libghc6-haskeline-dev``
- On Fedora: ``sudo yum install haskell-platform darcs ghc-haskeline-devevel``
**On Mac OS and Windows**, the tools can be downloaded from their respective
web sites, as described below.
=== The Haskell Platform ===
GF is written in Haskell, so first of all you need
the //Haskell Platform//, version 2010.2.0.0 or later. Downloads
and installation instructions are available from here:
http://hackage.haskell.org/platform/
Once you have installed the Haskell Platform, open a terminal
(Command Prompt on Windows) and try to execute the following command:
``` ```
$ ghc --version $ ghc --version
``` ```
This command should show you which version of GHC you have. If the installation This command should show you which version of GHC you have. If the installation
of GHC was successful you should see message like: of the Haskell Platform was successful you should see a message like:
``` ```
The Glorious Glasgow Haskell Compilation System, version 6.10.3 The Glorious Glasgow Haskell Compilation System, version 7.0.4
``` ```
The other two tools that we use are the lexer generator for Haskell - Alex:
http://www.haskell.org/alex/
and the parser generator - Happy:
http://www.haskell.org/happy/.
Again after the installation check that the tools are available from the terminal.
If they are not then probably you have to update the current search path in your system.
It is also a good idea to have either readline, editline or haskeline installed. Other required tools included in the Haskell Platform are
This are libraries for user friendly command line editing. On Linux, without some of this [Cabal http://www.haskell.org/cabal/],
libraries, the command line editor is very basic. Actually the only key for editing [Alex http://www.haskell.org/alex/] and
that you can use is backspace. On Windows you get much more user friendly editor [Happy http://www.haskell.org/happy/].
by default but with it you cannot use the GF specific tab completion. In any case if you
plan to use GF for continuous development then it is recomended to install
some of these libraries. The GF configuration script checks the libraries
in the following order:
- haskeline === Darcs ===
- readline
- editline To get the GF source code, you also need //Darcs//, version 2 or later. Darcs
is a distributed version control system, see http://darcs.net/ for
more information. There are precompiled packages for many platforms
available at and source code if you want to compile it yourself. Darcs
is also written in Haskell and so you can use GHC to compile it.
the first that is found will be used in the compilation. The libraries are also written === The haskeline library ===
in Haskell and could be found on Hackage: http://hackage.haskell.org/packages/archive/pkg-list.html. If you want to check whether,
you already have some of these you can use the following command:
```
$ ghc-pkg list
```
which shows the list of all installed libraries.
Haskeline is the easiest to install because it is a pure Haskell library but currently GF uses //haskeline// to enable command line editing in the GF shell.
with this editor GF doesn't provide word completion. With editline we provide word completion This should work automatically on Mac OS and Windows, but on Linux one
but the library is harder to install because it is a Haskell binding to a extra step is needed to make sure the C libraries required by //haskeline//
library with the same name written in C. If you do not have the C library you will have to install are installed. Here is one way to do this:
it first. Unfortunately editline does not have good support for Unicode. This will be a problem
if you tend to work on non-Latin language. Finaly readline supports both word completion
and Unicode. Currently this is the best supported library.
Before to get the GF sources you also need Darcs, version 2 or later. - On Ubuntu: ``sudo apt-get install libghc6-haskeline-dev``
Darcs is a decentralized revision control system, - On Fedora: ``sudo yum install ghc-haskeline-devel``
see http://darcs.net/ for more information. There are precompiled packages for many platforms available at
http://darcs.net/DarcsWiki/CategoryBinaries. There is also source code if you want to compile it yourself. Darcs is
also written in Haskell and so you can use GHC to compile it.
= Getting the sources = == Getting the source ==
Once you have all tools in place you can get the GF sources. If you just want to compile and use GF Once you have all tools in place you can get the GF source code. If you
then it is enough to have read-only access. It is also possible to make changes in the sources but if just want to compile and use GF then it is enough to have read-only
you want these changes to be applied back to the main sources you will have to send the changes to us. access. It is also possible to make changes in the source code but if you
If you plan to work continuously on GF then you should consider to get read-write access. want these changes to be applied back to the main source repository you will
have to send the changes to us. If you plan to work continuously on
GF then you should consider getting read-write access.
== Read-only access == === Read-only access ===
=== Getting a fresh copy for read-only access === ==== Getting a fresh copy for read-only access ====
Anyone can get the latest development version of GF by running (all on one line): Anyone can get the latest development version of GF by running (all on one line):
@@ -96,7 +105,7 @@ This will create a directory called ``gf`` in the current
directory. directory.
=== Updating your copy === ==== Updating your copy ====
To get all new patches from the main repo: To get all new patches from the main repo:
``` ```
@@ -107,7 +116,7 @@ directory, or any of its subdirectories.
Without ``-a``, you can choose which patches you want to get. Without ``-a``, you can choose which patches you want to get.
=== Recording local changes === ==== Recording local changes ====[record]
Since every copy is a repository, you can have local version control Since every copy is a repository, you can have local version control
of your changes. of your changes.
@@ -136,7 +145,7 @@ question. Both of these record all the changes you have in your local
repository. repository.
=== Submitting patches === ==== Submitting patches ====
If you are using read-only access, send your patches by email to If you are using read-only access, send your patches by email to
someone with write-access. First record your changes in your local someone with write-access. First record your changes in your local
@@ -162,13 +171,13 @@ patch directly from darcs. If so, replace ``-o mypatch.patch`` with
== Read-write access == === Read-write access ===
If you have a user account on www.grammaticalframework.org, you can If you have a user account on www.grammaticalframework.org, you can
get read-write access over SSH to the GF repository. get read-write access over SSH to the GF repository.
=== Getting a fresh copy === ==== Getting a fresh copy ====
Get your copy with (all on one line), Get your copy with (all on one line),
replacing ``bringert`` with your own username on code.haskell.org: replacing ``bringert`` with your own username on code.haskell.org:
@@ -183,7 +192,7 @@ and most people don't need the full history of all changes in the
past. past.
=== Getting other people's changes? === ==== Updating your copy ====
Get all new patches from the main repo: Get all new patches from the main repo:
@@ -195,13 +204,12 @@ Without ``-a``, you can choose which patches you want to get.
=== Commit your changes === ==== Commit your changes ====
There are two steps to commiting a change to the main repo. First you There are two steps to commiting a change to the main repo. First you
have to record the changes that you want to commit, then you push them have to record the changes that you want to commit
to the main repo. For instructions on recording your changes locally, (see [Recording local changes #record] above), then you push them
see "Recording local changes" above. Then you can push the patch(es) to to the main repo. If you are using ssh-access, all you need to do is:
the main repo. If you are using ssh-access, all you need to do is:
``` ```
$ darcs push $ darcs push
@@ -212,7 +220,7 @@ the main repo are pushed.
=== Apply a patch from someone else === ==== Apply a patch from someone else ====
Use: Use:
@@ -223,106 +231,130 @@ $ darcs apply < mypatch.patch
This applies the patch to your local repository. To commit it to the This applies the patch to your local repository. To commit it to the
main repo, use ``darcs push``. main repo, use ``darcs push``.
== Further information about Darcs == === Further information about Darcs ===
For more info about what you can do with darcs, see http://darcs.net/manual/ For more info about what you can do with darcs, see http://darcs.net/manual/
= Compilation from sources = == Compilation from source ==
The build system of GF is based on Cabal (see http://www.haskell.org/cabal/ for more information). The build system of GF is based on //Cabal//, which is part of the
Cabal is installed by default together with the GHC compiler. This is actually a library which could Haskell Platform, so no extra steps are needed to install it. In the simplest
be used from Haskell to compile projects written in Haskell. The entry point is a script case, all you need to do to compile and install GF, after downloading the
called Setup.hs which is placed in the top directory of every project managed with Cabal. source code as described above, is
The three main steps that are needed for compilation are much like what you do in a project
written in C, you have: configure, build and install.
== Configure ==
During the configuration phase Cabal will check that you have all necessary tools and libraries
needed for GF. The configuration is started by the command:
``` ```
$ runghc Setup.hs configure $ cd gf
``` $ cabal install
The command ```runghc``` comes with the GHC compiler and is batch interpreter which executes
the specified script without the need to compile it advance. Setup.hs is our compilation driver
which is based on Cabal. If you don't see any error message from the above command then
you have everything that is needed for GF. You can also add the option ```-v``` to see
more details about the configuration.
== Build ==
The build phase does two things. First it builds the GF compiler from the Haskell sources
and after that it builds the GF Resource Grammar Library using the already build compiler.
The simplest command is:
```
$ runghc Setup.hs build
```
Again you can add the option ```-v``` if you want to see more details.
Sometimes you just want to work on the GF compiler and don't want to recompile the resource
library after each change. In this case use this extended command:
```
$ runghc Setup.hs build rgl-none
```
The resource library could also be compiled in two modes: with present tense only and
with all tenses. By default it is compiled with all tenses. If you want to use
the library with only present tense you can compile it in this special mode with
the command:
```
$ runghc Setup.hs build present
```
Before to use this command make sure that the script lib/src/mkPresent has executable
permissions on Linux.
You could also control which languages you want to be recompiled by adding the option
```langs=list```. For example the following command will compile only the English and the Swedish
language:
```
$ runghc Setup.hs build langs=Eng,Swe
``` ```
== Install == This will automatically download any additional Haskell libraries needed to
build GF. If this is the first time you use Cabal, you might need to run
``cabal update`` first, to update the list of available libraries.
After you have compiled GF you can install the binaries to make the system usable. If you want more control, the process can also be split up into the usual
On Linux you will need root privileges to do this. Use the command: //configure//, //build// and //install// steps.
```
$ su
```
and enter the root password. This step should be skipped on Windows.
The installation itself is started with the command: === Configure ===
```
$ runghc Setup.hs install
```
This command installs the GF compiler in the default place for executable
files in your system. For example on Linux this is usualy /usr/local/bin and on
Windows this is c:\Program Files\Haskell\bin. If you want to install in some
other place then use the ```--prefix``` option during the configuration phase.
The compiled GF Resource Grammar Library will be installed in /usr/local/share/gf-3.1/lib During the configuration phase Cabal will check that you have all
on Linux and in c:\Program Files\Haskell\gf-3.1\lib on Windows. Again the location could necessary tools and libraries needed for GF. The configuration is
be changed using the ```--prefix``` option. started by the command:
== Clean == ```
$ cabal configure
```
If you don't see any error message from the above command then you
have everything that is needed for GF. You can also add the option
``-v`` to see more details about the configuration.
You can use ``cabal configure --help`` to get a list of configuration options.
=== Build ===
The build phase does two things. First it builds the GF compiler from
the Haskell source code and after that it builds the GF Resource Grammar
Library using the already build compiler. The simplest command is:
```
$ cabal build
```
Again you can add the option ``-v`` if you want to see more details.
Sometimes you just want to work on the GF compiler and don't want to
recompile the resource library after each change. In this case use
this extended command:
```
$ cabal build rgl-none
```
The resource library could also be compiled in two modes: with present
tense only and with all tenses. By default it is compiled with all
tenses. If you want to use the library with only present tense you can
compile it in this special mode with the command:
```
$ cabal build present
```
You could also control which languages you want to be recompiled by
adding the option ``langs=list``. For example the following command
will compile only the English and the Swedish language:
```
$ cabal build langs=Eng,Swe
```
=== Install ===
After you have compiled GF you need to install the executable and libraries
to make the system usable.
```
$ cabal copy
$ cabal register
```
This command installs the GF compiler for a single user, in the standard
place used by Cabal.
On Linux and Mac this could be ``$HOME/.cabal/bin``.
On Mac it could also be ``$HOME/Library/Haskell/bin``.
On Windows this is ``C:\Program Files\Haskell\bin``.
The compiled GF Resource Grammar Library will be installed
under the same prefix, e.g. in
``$HOME/.cabal/share/gf-3.3.3/lib`` on Linux and
in ``C:\Program Files\Haskell\gf-3.1\lib`` on Windows.
If you want to install in some other place then use the ``--prefix``
option during the configuration phase.
=== Clean ===
Sometimes you want to clean up the compilation and start again from clean Sometimes you want to clean up the compilation and start again from clean
sources. Use the clean command for this purpose: sources. Use the clean command for this purpose:
``` ```
$ runghc Setup.hs clean $ cabal clean
``` ```
== SDist ==
You can use the command: %=== SDist ===
``` %
$ runghc Setup.hs sdist %You can use the command:
``` %
to prepare archive with all source codes needed to compile GF. %% This does *NOT* include everything that is needed // TH 2012-08-06
%```
%$ cabal sdist
%```
%
%to prepare archive with all source codes needed to compile GF.
= Compilation with make = == Compilation with make ==
If you feel more comfortable with Makefiles then there is a thin Makefile If you feel more comfortable with Makefiles then there is a thin Makefile
wrapper arround Cabal for you. If you just type: wrapper arround Cabal for you. If you just type:
@@ -343,16 +375,20 @@ For cleaning:
``` ```
$ make clean $ make clean
``` ```
and to build source distribution archive run: %and to build source distribution archive run:
``` %```
$ make sdist %$ make sdist
``` %```
= Running the testsuite = == Running the testsuite ==
**NOTE:** The test suite has not been maintained recently, so expect many
tests to fail.
%% // TH 2012-08-06
GF has testsuite. It is run with the following command: GF has testsuite. It is run with the following command:
``` ```
$ runghc Setup.hs test $ cabal test
``` ```
The testsuite architecture for GF is very simple but still very flexible. The testsuite architecture for GF is very simple but still very flexible.
GF by itself is an interpreter and could execute commands in batch mode. GF by itself is an interpreter and could execute commands in batch mode.
@@ -374,6 +410,6 @@ that we will not incidentaly break your code later.
If you don't want to run the whole testsuite you can write the path to the subdirectory If you don't want to run the whole testsuite you can write the path to the subdirectory
in which you are interested. For example: in which you are interested. For example:
``` ```
$ runghc Setup.hs test testsuite/compiler $ cabal test testsuite/compiler
``` ```
will run only the testsuite for the compiler. will run only the testsuite for the compiler.