diff options
| -rw-r--r-- | doc/gf-developers-old-cabal.t2t | 201 | ||||
| -rw-r--r-- | doc/gf-developers.t2t | 120 |
2 files changed, 202 insertions, 119 deletions
diff --git a/doc/gf-developers-old-cabal.t2t b/doc/gf-developers-old-cabal.t2t new file mode 100644 index 000000000..0f583bec8 --- /dev/null +++ b/doc/gf-developers-old-cabal.t2t @@ -0,0 +1,201 @@ +GF Developer's Guide: Old installation instructions with Cabal + + +This page contains the old installation instructions from the [Developer's Guide ../doc/gf-developers.html]. +We recommend Stack as a primary installation method, because it's easier for a Haskell beginner, and we want to keep the main instructions short. +But if you are an experienced Haskeller and want to keep using Cabal, here are the old instructions using ``cabal install``. + +Note that some of these instructions may be outdated. Other parts may still be useful. + +== Compilation from source with Cabal == + +The build system of GF is based on //Cabal//, 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 + +``` +$ cabal 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. + +If you want more control, the process can also be split up into the usual +//configure//, //build// and //install// steps. + +=== 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: + +``` +$ 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. + +==== Parallel builds ==== + +If you have Cabal>=1.20 you can enable parallel compilation by using + +``` +$ cabal build -j +``` + +or by putting a line +``` +jobs: $ncpus +``` +in your ``.cabal/config`` file. Cabal +will pass this option to GHC when building the GF compiler, if you +have GHC>=7.8. + +Cabal also passes ``-j`` to GF to enable parallel compilation of the +Resource Grammar Library. This is done unconditionally to avoid +causing problems for developers with Cabal<1.20. You can disable this +by editing the last few lines in ``WebSetup.hs``. + +=== 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.3.3\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 +sources. Use the clean command for this purpose: + +``` +$ cabal clean +``` + + +%=== SDist === +% +%You can use the command: +% +%% 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. + +=== Known problems with Cabal === + +Some versions of Cabal (at least version 1.16) seem to have a bug that can +cause the following error: + +``` +Configuring gf-3.x... +setup: Distribution/Simple/PackageIndex.hs:124:8-13: Assertion failed +``` + +The exact cause of this problem is unclear, but it seems to happen +during the configure phase if the same version of GF is already installed, +so a workaround is to remove the existing installation with + +``` +ghc-pkg unregister gf +``` + +You can check with ``ghc-pkg list gf`` that it is gone. + +== Compilation with make == + +If you feel more comfortable with Makefiles then there is a thin Makefile +wrapper arround Cabal for you. If you just type: +``` +$ make +``` +the configuration phase will be run automatically if needed and after that +the sources will be compiled. + +%% cabal build rgl-none does not work with recent versions of Cabal +%If you don't want to compile the resource library +%every time then you can use: +%``` +%$ make gf +%``` + +For installation use: +``` +$ make install +``` +For cleaning: +``` +$ make clean +``` +%and to build source distribution archive run: +%``` +%$ make sdist +%``` + + +== Partial builds of RGL == + +**NOTE**: The following doesn't work with recent versions of ``cabal``. //(This comment was left in 2015, so make your own conclusions.)// +%% // TH 2015-06-22 + +%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 grammar library can 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 +``` diff --git a/doc/gf-developers.t2t b/doc/gf-developers.t2t index 840fa3762..ffaf06699 100644 --- a/doc/gf-developers.t2t +++ b/doc/gf-developers.t2t @@ -138,125 +138,7 @@ source code as described above, is $ cabal 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. - -If you want more control, the process can also be split up into the usual -//configure//, //build// and //install// steps. - -=== 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: - -``` -$ 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. - -==== Parallel builds ==== - -If you have Cabal>=1.20 you can enable parallel compilation by using - -``` -$ cabal build -j -``` - -or by putting a line -``` -jobs: $ncpus -``` -in your ``.cabal/config`` file. Cabal -will pass this option to GHC when building the GF compiler, if you -have GHC>=7.8. - -Cabal also passes ``-j`` to GF to enable parallel compilation of the -Resource Grammar Library. This is done unconditionally to avoid -causing problems for developers with Cabal<1.20. You can disable this -by editing the last few lines in ``WebSetup.hs``. - - -==== Partial builds ==== - -**NOTE**: The following doesn't work with recent versions of ``cabal``. -%% // TH 2015-06-22 - -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.3.3\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 -sources. Use the clean command for this purpose: - -``` -$ cabal clean -``` +//The old (partially outdated) instructions for Cabal are moved to a [separate page ../doc/gf-developers-old-cabal.html]. If you run into trouble with ``cabal install``, you may want to take a look.// %=== SDist === |