mirror of
https://github.com/GrammaticalFramework/gf-core.git
synced 2026-04-09 13:09:33 -06:00
560 lines
15 KiB
HTML
560 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
<HTML>
|
||
<HEAD>
|
||
<META NAME="generator" CONTENT="http://txt2tags.org">
|
||
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
|
||
<LINK REL="stylesheet" TYPE="text/css" HREF="../css/style.css">
|
||
<TITLE>GF Developers Guide</TITLE>
|
||
</HEAD><BODY BGCOLOR="white" TEXT="black">
|
||
<CENTER>
|
||
<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">Last update: 2013-01-30, 15:11</FONT>
|
||
</CENTER>
|
||
|
||
<P></P>
|
||
<HR NOSHADE SIZE=1>
|
||
<P></P>
|
||
|
||
<UL>
|
||
<LI><A HREF="#toc1">Before you start</A>
|
||
<LI><A HREF="#toc2">Setting up your system for building GF</A>
|
||
<UL>
|
||
<LI><A HREF="#toc3">The Haskell Platform</A>
|
||
<LI><A HREF="#toc4">Darcs</A>
|
||
<LI><A HREF="#toc5">The haskeline library</A>
|
||
</UL>
|
||
<LI><A HREF="#toc6">Getting the source</A>
|
||
<UL>
|
||
<LI><A HREF="#toc7">Read-only access</A>
|
||
<LI><A HREF="#toc8">Read-write access</A>
|
||
<LI><A HREF="#toc9">Further information about Darcs</A>
|
||
</UL>
|
||
<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>
|
||
|
||
<P></P>
|
||
<HR NOSHADE SIZE=1>
|
||
<P></P>
|
||
|
||
<A NAME="toc1"></A>
|
||
<H2>Before you start</H2>
|
||
|
||
<P>
|
||
This guide is intended for people who want to contribute to
|
||
the development of the GF compiler or the Resource Grammar Library. If
|
||
you are a GF user who just wants to download and install GF
|
||
(e.g to develop your own grammars), the simpler guide on
|
||
<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>
|
||
<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-devel</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 2012.4.0.0. Downloads
|
||
and installation instructions are available from here:
|
||
</P>
|
||
<P>
|
||
<A HREF="http://hackage.haskell.org/platform/">http://hackage.haskell.org/platform/</A>
|
||
</P>
|
||
<P>
|
||
Once you have installed the Haskell Platform, open a terminal
|
||
(Command Prompt on Windows) and try to execute the following command:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ ghc --version
|
||
</PRE>
|
||
|
||
<P>
|
||
This command should show you which version of GHC you have. If the installation
|
||
of the Haskell Platform was successful you should see a message like:
|
||
</P>
|
||
|
||
<PRE>
|
||
The Glorious Glasgow Haskell Compilation System, version 7.4.2
|
||
</PRE>
|
||
|
||
<P>
|
||
Other required tools included in the Haskell Platform are
|
||
<A HREF="http://www.haskell.org/cabal/">Cabal</A>
|
||
and
|
||
<A HREF="http://www.haskell.org/happy/">Happy</A>.
|
||
</P>
|
||
|
||
<A NAME="toc4"></A>
|
||
<H3>Darcs</H3>
|
||
|
||
<P>
|
||
To get the GF source code, you also need <I>Darcs</I>, version 2 or later. Darcs
|
||
is a distributed version control system, see <A HREF="http://darcs.net/">http://darcs.net/</A> 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.
|
||
</P>
|
||
|
||
<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>
|
||
|
||
<UL>
|
||
<LI>On Ubuntu: <CODE>sudo apt-get install libghc6-haskeline-dev</CODE>
|
||
<LI>On Fedora: <CODE>sudo yum install ghc-haskeline-devel</CODE>
|
||
</UL>
|
||
|
||
<A NAME="toc6"></A>
|
||
<H2>Getting the source</H2>
|
||
|
||
<P>
|
||
Once you have all tools in place you can get the GF source code. 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 source code but if you
|
||
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.
|
||
</P>
|
||
|
||
<A NAME="toc7"></A>
|
||
<H3>Read-only access</H3>
|
||
|
||
<H4>Getting a fresh copy for read-only access</H4>
|
||
|
||
<P>
|
||
Anyone can get the latest development version of GF by running (all on one line):
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs get --lazy --set-scripts-executable http://www.grammaticalframework.org/ gf
|
||
</PRE>
|
||
|
||
<P>
|
||
This will create a directory called <CODE>gf</CODE> in the current
|
||
directory.
|
||
</P>
|
||
|
||
<H4>Updating your copy</H4>
|
||
|
||
<P>
|
||
To get all new patches from the main repo:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs pull -a
|
||
</PRE>
|
||
|
||
<P>
|
||
This can be done anywhere in your local repository, i.e. in the <CODE>gf</CODE>
|
||
directory, or any of its subdirectories.
|
||
Without <CODE>-a</CODE>, you can choose which patches you want to get.
|
||
</P>
|
||
|
||
<A NAME="record"></A>
|
||
<H4>Recording local changes</H4>
|
||
|
||
<P>
|
||
Since every copy is a repository, you can have local version control
|
||
of your changes.
|
||
</P>
|
||
<P>
|
||
If you have added files, you first need to tell your local repository to
|
||
keep them under revision control:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs add file1 file2 ...
|
||
</PRE>
|
||
|
||
<P>
|
||
To record changes, use:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs record
|
||
</PRE>
|
||
|
||
<P>
|
||
This creates a patch against the previous version and stores it in your
|
||
local repository. You can record any number of changes before
|
||
pushing them to the main repo. In fact, you don't have to push them at
|
||
all if you want to keep the changes only in your local repo.
|
||
</P>
|
||
<P>
|
||
If you think there are too many questions about what to record, you
|
||
can use the <CODE>-a</CODE> flag to <CODE>record</CODE>. Or answer <CODE>a</CODE> to the first
|
||
question. Both of these record all the changes you have in your local
|
||
repository.
|
||
</P>
|
||
|
||
<H4>Submitting patches</H4>
|
||
|
||
<P>
|
||
If you are using read-only access, send your patches by email to
|
||
someone with write-access. First record your changes in your local
|
||
repository, as described above. You can send any number of recorded
|
||
patches as one patch bundle. You create the patch bundle with:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs send -o mypatch.patch
|
||
$ gzip mypatch.patch
|
||
</PRE>
|
||
|
||
<P>
|
||
(where <CODE>mypatch</CODE> is hopefully replaced by a slightly more
|
||
descriptive name). Since some e-mail setups change text attachments
|
||
(most likely by changing the newline characters) you need to send
|
||
the patch in some compressed format, such as GZIP, BZIP2 or ZIP.
|
||
</P>
|
||
<P>
|
||
Send it as an e-mail attachment. If you have
|
||
sendmail or something equivalent installed, it is possible to send the
|
||
patch directly from darcs. If so, replace <CODE>-o mypatch.patch</CODE> with
|
||
<CODE>--to=EMAIL</CODE> where <CODE>EMAIL</CODE> is the address to send it to.
|
||
</P>
|
||
|
||
<A NAME="toc8"></A>
|
||
<H3>Read-write access</H3>
|
||
|
||
<P>
|
||
If you have a user account on <CODE>www.grammaticalframework.org</CODE>, you can
|
||
get read-write access over SSH to the GF repository.
|
||
</P>
|
||
|
||
<H4>Getting a fresh copy</H4>
|
||
|
||
<P>
|
||
Get your copy with (all on one line),
|
||
replacing <CODE>bringert</CODE> with your own username on <CODE>www.grammaticalframework.org</CODE>:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs get --lazy --set-scripts-executable bringert@www.grammaticalframework.org:/usr/local/www/GF/ gf
|
||
</PRE>
|
||
|
||
<P>
|
||
The option <CODE>--lazy</CODE> means that darcs defers downloading all the
|
||
history for the repository. This saves space, bandwidth and CPU time,
|
||
and most people don't need the full history of all changes in the
|
||
past.
|
||
</P>
|
||
|
||
<H4>Updating your copy</H4>
|
||
|
||
<P>
|
||
Get all new patches from the main repo:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs pull -a
|
||
</PRE>
|
||
|
||
<P>
|
||
Without <CODE>-a</CODE>, you can choose which patches you want to get.
|
||
</P>
|
||
|
||
<H4>Commit your changes</H4>
|
||
|
||
<P>
|
||
There are two steps to commiting a change to the main repo. First you
|
||
have to record the changes that you want to commit
|
||
(see <A HREF="#record">Recording local changes</A> above), then you push them
|
||
to the main repo. If you are using ssh-access, all you need to do is:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs push
|
||
</PRE>
|
||
|
||
<P>
|
||
If you use the <CODE>-a</CODE> flag to push, all local patches which are not in
|
||
the main repo are pushed.
|
||
</P>
|
||
|
||
<H4>Apply a patch from someone else</H4>
|
||
|
||
<P>
|
||
Use:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ darcs apply < mypatch.patch
|
||
</PRE>
|
||
|
||
<P>
|
||
This applies the patch to your local repository. To commit it to the
|
||
main repo, use <CODE>darcs push</CODE>.
|
||
</P>
|
||
|
||
<A NAME="toc9"></A>
|
||
<H3>Further information about Darcs</H3>
|
||
|
||
<P>
|
||
For more info about what you can do with darcs, see <A HREF="http://darcs.net/manual/">http://darcs.net/manual/</A>
|
||
</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.3.3\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>
|
||
<H3>Clean</H3>
|
||
|
||
<P>
|
||
Sometimes you want to clean up the compilation and start again from clean
|
||
sources. Use the clean command for this purpose:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ cabal clean
|
||
</PRE>
|
||
|
||
<A NAME="toc15"></A>
|
||
<H2>Compilation with make</H2>
|
||
|
||
<P>
|
||
If you feel more comfortable with Makefiles then there is a thin Makefile
|
||
wrapper arround Cabal for you. If you just type:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ make
|
||
</PRE>
|
||
|
||
<P>
|
||
the configuration phase will be run automatically if needed and after that
|
||
the sources will be compiled. If you don't want to compile the resource library
|
||
every time then you can use:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ make gf
|
||
</PRE>
|
||
|
||
<P>
|
||
For installation use:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ make install
|
||
</PRE>
|
||
|
||
<P>
|
||
For cleaning:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ make clean
|
||
</PRE>
|
||
|
||
<A NAME="toc16"></A>
|
||
<H2>Running the testsuite</H2>
|
||
|
||
<P>
|
||
<B>NOTE:</B> The test suite has not been maintained recently, so expect many
|
||
tests to fail.
|
||
</P>
|
||
<P>
|
||
GF has testsuite. It is run with the following command:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ cabal test
|
||
</PRE>
|
||
|
||
<P>
|
||
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.
|
||
This is everything that we need to organize a testsuite. The root of the
|
||
testsuite is the testsuite/ directory. It contains subdirectories which
|
||
themself contain GF batch files (with extension .gfs). The above command
|
||
searches the subdirectories of the testsuite/ directory for files with extension
|
||
.gfs and when it finds one it is executed with the GF interpreter.
|
||
The output of the script is stored in file with extension .out and is compared
|
||
with the content of the corresponding file with extension .gold, if there is one.
|
||
If the contents are identical the command reports that the test was passed successfully.
|
||
Otherwise the test had failed.
|
||
</P>
|
||
<P>
|
||
Every time when you make some changes to GF that have to be tested, instead of
|
||
writing the commands by hand in the GF shell, add them to one .gfs file in the testsuite
|
||
and run the test. In this way you can use the same test later and we will be sure
|
||
that we will not incidentaly break your code later.
|
||
</P>
|
||
<P>
|
||
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:
|
||
</P>
|
||
|
||
<PRE>
|
||
$ cabal test testsuite/compiler
|
||
</PRE>
|
||
|
||
<P>
|
||
will run only the testsuite for the compiler.
|
||
</P>
|
||
|
||
<!-- html code generated by txt2tags 2.6 (http://txt2tags.org) -->
|
||
<!-- cmdline: txt2tags -thtml ./doc/gf-developers.t2t -->
|
||
</BODY></HTML>
|