docs/install-fermat-on-linux.txt

   1
   2 How to install and use FermaT on a Linux machine
   3 ================================================
   4
   5 These instructions should work on most distributions from the Debian family
   6 (Ubuntu, Mint, CrunchBang, ...) and with small changes on any other Linux or
   7 BSD system.  The main changes are in the usage of the package system -
   8 Debian uses ".deb" packages and the "apt-get" command, others use yum,
   9 packman etc.
  10
  11 The machine that these instructions were tested with was a fresh Ubuntu
  12 install, more precisely Lubuntu 14.04, 64 bit version.  It came with gcc
  13 4.8.2 (4.8.2-19ubuntu1) installed.
  14 It was also tested on a fresh install of CrunchBang Waldorf (based on
  15 Debian Wheezy), 64 bit version. It came with gcc (Debian 4.7.2-5) 4.7.2.
  16
  17 Dependencies
  18 ============
  19
  20 GNU Compiler Collection (C)
  21 ---------------------------
  22
  23 For building FermaT you need a working C compiler, GCC recommended. In
  24 Ubuntu there is a convenient package "build-essential" that will
  25 install most of the needed packages for building software.
  26
  27 Debian:
  28
  29   sudo apt-get install build-essential
  30
  31 Mageia:
  32
  33   urpmi gcc make
  34
  35 Fedora:
  36
  37   yum install gcc make
  38
  39 When trying to build FermaT it might complain about a missing
  40 "sys/cdefs.h". This file can be found in libc6-dev package,
  41 but you might also need to install "libc6-dev-i386" (even though
  42 it is a 64 bit system, the shared file is in the old library).
  43
  44
  45 Perl
  46 ----
  47
  48 Perl is included by default, but you also need some extra modules -
  49 Bit::Vector and Set::IntRange.
  50
  51 If these modules are not installed WSL will work in most cases, but
  52 not all. To be sure everything is OK run "make test" and check that
  53 all the tests succeeded.
  54
  55 Debian:
  56
  57 You can use "cpanm" command from the "cpanminus" package for
  58 installing modules. It will automatically find and install any missing
  59 module dependencies.
  60
  61 You can install them globally on the system with
  62
  63   sudo cpanm Bit::Vector
  64   sudo cpanm Set::IntRange
  65
  66 If you don't want to (or can't) install them globally, you can
  67 configure local modules. Try running cpanm without sudo for
  68 suggestions how to do this.
  69
  70 Mageia, Fedora and other Linux versions:
  71
  72 If your system does not have cpanm, you can use the CPAN module directly:
  73
  74   sudo perl -MCPAN -e shell
  75
  76 This will start the CPAN shell. Type:
  77
  78   install Set::IntRange
  79
  80 to install Set::IntRange and Bit::Vector.
  81
  82
  83 Main build
  84 ==========
  85
  86 You need to download and extract fermat3:
  87
  88   wget http://www.cse.dmu.ac.uk/~mward/fermat3.tar.gz
  89      OR
  90   wget http://www.gkc.org.uk/fermat3.tar.gz
  91
  92   tar -xf fermat3.tar.gz
  93
  94 To compile and test FermaT:
  95
  96   cd fermat3
  97   make test
  98
  99 To run the FermaT scripts from the command line (wsl, dotrans,
 100 make-fermat etc) you need to ensure that the fermat3/bin directory
 101 is in your path and the FermaT environment variable is set.
 102
 103 A simple way to do this is to "source" the appropriate DOIT file
 104 from the fermat3 directory.
 105
 106 Most Linux systems use the bash shell by default:
 107
 108   cd fermat3
 109   source DOIT.bash
 110
 111 If you use csh or tcsh then:
 112
 113   cd fermat3
 114   source DOIT.csh
 115
 116 After setting the environment variable and path, you can recompile FermaT
 117 with the command:
 118
 119   make-fermat
 120
 121 You can test some basic WSL commands with:
 122
 123   test-fermat
 124
 125 and test some transformations with:
 126
 127   test-trans
 128
 129 If everything is OK you should be able to enter "wsl" in the command
 130 line and get a usage message.
 131
 132
 133 Running WSL
 134 ===========
 135
 136 FermaT does not install system-wide on it's own.  If you want
 137 to use it in a command line you need to source DOIT again.
 138 Since DOIT.bash uses pwd (print working directory) you need to run
 139 it in the fermat3 directory.
 140
 141 Alternatively you can make a copy of the file (let's call it myDOIT.bash)
 142 and change the line "Fermat=`pwd` to refer to the install folder directly,
 143 for instance if we extracted fermat3 in our home:
 144
 145 FermaT=$HOME/fermat3
 146
 147 You can then run that file from anywhere and it will setup the values
 148 properly. For instance you can put this file somewhere on the PATH. A
 149 convenient place is to make a "bin" folder in your home if there isn't
 150 one already. This will be included by bash automatically. Then
 151 you could run
 152
 153   source myDOIT.bash
 154
 155 from any terminal that you want to run WSL in.
 156
 157 If you want to have access to wsl in all of the shells you can add
 158 these lines to your .bashrc file (in the home directory).
 159
 160
 161 End notes
 162 =========
 163
 164 Copyright (C) 2014 Doni Pracner, Martin Ward; Released under the GNU Free Documentation
 165 Licence https://www.gnu.org/licenses/fdl.html