Updated the GF Developers Guide

+ 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.
author: hallgren <hallgren@chalmers.se> 2012-08-06 16:14:47 +0000
committer: hallgren <hallgren@chalmers.se> 2012-08-06 16:14:47 +0000
commit: 06c9e4999f8d6ab25ce4c533df45060806ca80ed (patch)
tree: 123888e9b1dc9010054f778a3ad856ea2c1f3fd1 /doc/gf-developers.html
parent: 3601b796e51bd4a26383ac972ce2ccf575171979 (diff)
1 files changed, 190 insertions, 203 deletions
diff --git a/doc/gf-developers.html b/doc/gf-developers.html
index 93897031d..fd6b95d1e 100644
--- a/doc/gf-developers.html
+++ b/doc/gf-developers.html
@@ -7,152 +7,157 @@
 <TITLE>GF Developers Guide</TITLE>
 </HEAD><BODY BGCOLOR="white" TEXT="black">
 <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">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>
 
 <P></P>
 <HR NOSHADE SIZE=1>
 <P></P>
 
-  <UL>
-  <LI><A HREF="#toc1">Setting up your system for building GF</A>
-  <LI><A HREF="#toc2">Getting the sources</A>
     <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>
-      <LI><A HREF="#toc4">Getting a fresh copy for read-only access</A>
-      <LI><A HREF="#toc5">Updating your copy</A>
-      <LI><A HREF="#toc6">Recording local changes</A>
-      <LI><A HREF="#toc7">Submitting patches</A>
+      <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="#toc8">Read-write access</A>
+    <LI><A HREF="#toc6">Getting the source</A>
       <UL>
-      <LI><A HREF="#toc9">Getting a fresh copy</A>
-      <LI><A HREF="#toc10">Getting other people's changes?</A>
-      <LI><A HREF="#toc11">Commit your changes</A>
-      <LI><A HREF="#toc12">Apply a patch from someone else</A>
+      <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="#toc13">Further information about Darcs</A>
-    </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>
+    <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>
-  <LI><A HREF="#toc20">Compilation with make</A>
-  <LI><A HREF="#toc21">Running the testsuite</A>
-  </UL>
 
 <P></P>
 <HR NOSHADE SIZE=1>
 <P></P>
 
 <A NAME="toc1"></A>
-<H1>Setting up your system for building GF</H1>
+<H2>Before you start</H2>
 
 <P>
-Before to build GF from sources you need to install some tools on your system.
-GF is written in Haskell, so first of all you need recent version of the Haskell compiler GHC.
-Currently we use GHC 6.10.3 and we recommend that you should use the same version
-as well. This version is not backward compatible with the previous major releases
-so you cannot use previous versions. GHC is available from here:
+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>
-<A HREF="http://www.haskell.org/ghc/">http://www.haskell.org/ghc/</A>
+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>
-Once you have installed GHC, open a terminal (Command Prompt on Windows) and try
-to execute the following command:
+<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>
 
-<PRE>
-  $ ghc --version
-</PRE>
+<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>
-This command should show you which version of GHC you have. If the installation
-of GHC was successful you should see message like:
+<B>On Mac OS and Windows</B>, the tools can be downloaded from their respective
+web sites, as described below.
 </P>
 
-<PRE>
-  The Glorious Glasgow Haskell Compilation System, version 6.10.3
-</PRE>
+<A NAME="toc3"></A>
+<H3>The Haskell Platform</H3>
 
 <P>
-The other two tools that we use are the lexer generator for Haskell - Alex:
-<A HREF="http://www.haskell.org/alex/">http://www.haskell.org/alex/</A>
-and the parser generator - Happy:
-<A HREF="http://www.haskell.org/happy/">http://www.haskell.org/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.
+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>
+    <A HREF="http://hackage.haskell.org/platform/">http://hackage.haskell.org/platform/</A>
 </P>
 <P>
-It is also a good idea to have either readline, editline or haskeline installed.
-This are libraries for user friendly command line editing. On Linux, without some of this
-libraries, the command line editor is very basic. Actually the only key for editing
-that you can use is backspace. On Windows you get much more user friendly editor
-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:
+Once you have installed the Haskell Platform, open a terminal
+(Command Prompt on Windows) and try to execute the following command:
 </P>
 
-<UL>
-<LI>haskeline
-<LI>readline
-<LI>editline
-</UL>
+<PRE>
+  $ ghc --version
+</PRE>
 
 <P>
-the first that is found will be used in the compilation. The libraries are also written
-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:
+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>
-  $ ghc-pkg list
+  The Glorious Glasgow Haskell Compilation System, version 7.0.4
 </PRE>
 
 <P>
-which shows the list of all installed libraries. 
+Other required tools included in the Haskell Platform are 
+<A HREF="http://www.haskell.org/cabal/">Cabal</A>, 
+<A HREF="http://www.haskell.org/alex/">Alex</A> and
+<A HREF="http://www.haskell.org/happy/">Happy</A>.
 </P>
+
+<A NAME="toc4"></A>
+<H3>Darcs</H3>
+
 <P>
-Haskeline is the easiest to install because it is a pure Haskell library but currently
-with this editor GF doesn't provide word completion. With editline we provide word completion
-but the library is harder to install because it is a Haskell binding to a
-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.
+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>
-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.
+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>
 
-<A NAME="toc2"></A>
-<H1>Getting the sources</H1>
+<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 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.
+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="toc3"></A>
-<H2>Read-only access</H2>
+<A NAME="toc7"></A>
+<H3>Read-only access</H3>
 
-<A NAME="toc4"></A>
-<H3>Getting a fresh copy for 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):
@@ -167,8 +172,7 @@ This will create a directory called <CODE>gf</CODE> in the current
 directory.
 </P>
 
-<A NAME="toc5"></A>
-<H3>Updating your copy</H3>
+<H4>Updating your copy</H4>
 
 <P>
 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.
 </P>
 
-<A NAME="toc6"></A>
-<H3>Recording local changes</H3>
+<A NAME="record"></A>
+<H4>Recording local changes</H4>
 
 <P>
 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.
 </P>
 
-<A NAME="toc7"></A>
-<H3>Submitting patches</H3>
+<H4>Submitting patches</H4>
 
 <P>
 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>
 
 <A NAME="toc8"></A>
-<H2>Read-write access</H2>
+<H3>Read-write access</H3>
 
 <P>
 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.
 </P>
 
-<A NAME="toc9"></A>
-<H3>Getting a fresh copy</H3>
+<H4>Getting a fresh copy</H4>
 
 <P>
 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.
 </P>
 
-<A NAME="toc10"></A>
-<H3>Getting other people's changes?</H3>
+<H4>Updating your copy</H4>
 
 <P>
 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.
 </P>
 
-<A NAME="toc11"></A>
-<H3>Commit your changes</H3>
+<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, then you push them
-to the main repo. For instructions on recording your changes locally,
-see "Recording local changes" above. Then you can push the patch(es) to 
-the main repo. If you are using ssh-access, all you need to do is:
+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>
@@ -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.
 </P>
 
-<A NAME="toc12"></A>
-<H3>Apply a patch from someone else</H3>
+<H4>Apply a patch from someone else</H4>
 
 <P>
 Use:
@@ -327,159 +325,152 @@ This applies the patch to your local repository. To commit it to the
 main repo, use <CODE>darcs push</CODE>.
 </P>
 
-<A NAME="toc13"></A>
-<H2>Further information about Darcs</H2>
+<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="toc14"></A>
-<H1>Compilation from sources</H1>
-
-<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>
+<A NAME="toc10"></A>
+<H2>Compilation from source</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:
+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>
-  $ runghc Setup.hs configure
+  $ cd gf
+  $ cabal install
 </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.
+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="toc16"></A>
-<H2>Build</H2>
+<A NAME="toc11"></A>
+<H3>Configure</H3>
 
 <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:
+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 build
+  $ cabal configure
 </PRE>
 
 <P>
-Again you can add the option <CODE>`-v`</CODE> if you want to see more details.
+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>
-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:
+You can use <CODE>cabal configure --help</CODE> to get a list of configuration options.
 </P>
 
-<PRE>
-  $ runghc Setup.hs build rgl-none
-</PRE>
+<A NAME="toc12"></A>
+<H3>Build</H3>
 
 <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:
+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>
-  $ runghc Setup.hs build present
+  $ cabal build
 </PRE>
 
 <P>
-Before to use this command make sure that the script lib/src/mkPresent has executable
-permissions on Linux.
+Again you can add the option <CODE>-v</CODE> if you want to see more details.
 </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:
+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 langs=Eng,Swe
+  $ cabal build rgl-none
 </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:
+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>
-  $ su
+  $ cabal build present
 </PRE>
 
 <P>
-and enter the root password. This step should be skipped on Windows.
+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>
-The installation itself is started with the command:
+After you have compiled GF you need to install the executable and libraries
+to make the system usable.
 </P>
 
 <PRE>
-  $ runghc Setup.hs install
+  $ cabal copy
+  $ cabal register
 </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.
+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 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.
+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>
-
-<A NAME="toc18"></A>
-<H2>Clean</H2>
-
 <P>
-Sometimes you want to clean up the compilation and start again from clean
-sources. Use the clean command for this purpose:
+If you want to install in some other place then use the <CODE>--prefix</CODE>
+option during the configuration phase.
 </P>
 
-<PRE>
-  $ runghc Setup.hs clean
-</PRE>
-
-<A NAME="toc19"></A>
-<H2>SDist</H2>
+<A NAME="toc14"></A>
+<H3>Clean</H3>
 
 <P>
-You can use the command:
+Sometimes you want to clean up the compilation and start again from clean
+sources. Use the clean command for this purpose:
 </P>
 
 <PRE>
-  $ runghc Setup.hs sdist
+  $ cabal clean
 </PRE>
 
-<P>
-to prepare archive with all source codes needed to compile GF.
-</P>
-
-<A NAME="toc20"></A>
-<H1>Compilation with make</H1>
+<A NAME="toc15"></A>
+<H2>Compilation with make</H2>
 
 <P>
 If you feel more comfortable with Makefiles then there is a thin Makefile
@@ -516,23 +507,19 @@ For cleaning:
   $ make clean
 </PRE>
 
+<A NAME="toc16"></A>
+<H2>Running the testsuite</H2>
+
 <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>
-
-<PRE>
-  $ make sdist
-</PRE>
-
-<A NAME="toc21"></A>
-<H1>Running the testsuite</H1>
-
 <P>
 GF has testsuite. It is run with the following command:
 </P>
 
 <PRE>
-  $ runghc Setup.hs test
+  $ cabal test
 </PRE>
 
 <P>
@@ -560,7 +547,7 @@ in which you are interested. For example:
 </P>
 
 <PRE>
-  $ runghc Setup.hs test testsuite/compiler
+  $ cabal test testsuite/compiler
 </PRE>
 
 <P>
author	hallgren <hallgren@chalmers.se>	2012-08-06 16:14:47 +0000
committer	hallgren <hallgren@chalmers.se>	2012-08-06 16:14:47 +0000
commit	06c9e4999f8d6ab25ce4c533df45060806ca80ed (patch)
tree	123888e9b1dc9010054f778a3ad856ea2c1f3fd1 /doc/gf-developers.html
parent	3601b796e51bd4a26383ac972ce2ccf575171979 (diff)