README

   1    #       #   #                #
   2   ######## #   # ######### ########## ##########
   3  #       # #   # #       #      #             #
   4 #      ##  #   # #       #   #  # #          #
   5      ##       #  #       #  #   #  #      # #
   6    ##        #   ######### #   ##   #      #
   7  ##        ##                   #           #
   8
   9 horde: a forth written in haskell
  10
  11 1 - intro: what is horde?
  12 2 - installation
  13  2.1 - binaries
  14  2.2 - from source
  15   2.2.0 - prerequisites
  16   2.2.2 - development version
  17   2.2.3 - stable version
  18   2.2.4 - building
  19   2.2.5 - debug builds, profiling, etc..
  20 3 - usage
  21  3.1 - examples
  22  3.2 - as a library
  23 4 - documentation
  24 5 - development, bugs, contact, etc.
  25
  26
  27
  28
  29  ========================================
  30 | 1 - intro: what is horde?              |
  31  ========================================
  32  horde is a Forth implementation written in the purely functional language,
  33 Haskell. it is designed to be a fully compliant ANS Forth implementation in
  34 the same kin as gforth, while also optionally embeddable as a haskell library.
  35
  36
  37
  38
  39
  40  ========================================
  41 |2 - installation                        |
  42  ========================================
  43  there are two modes for installing horde: from binaries and from source code
  44
  45
  46
  47  ----------------------------------------
  48 | 2.1 - binaries                         |
  49  ----------------------------------------
  50  binary packages of horde are currently not yet available for microsoft windows
  51 or gnu/linux.
  52
  53
  54
  55  ----------------------------------------
  56 | 2.2 - from source                      |
  57  ----------------------------------------
  58  if you wish to install horde from source, simply follow the below
  59
  60
  61 ++++++++++++++++++++++++++++++++++++++++++
  62 + 2.2.1 - prerequisites                  +
  63 ++++++++++++++++++++++++++++++++++++++++++
  64
  65  * the glasgow haskell compiler
  66     http://haskell.org/ghc (v6.6.x or v6.8.1 will suffice)
  67  * cabal >= 1.2 installed for the compiler (comes with ghc 6.8.1)
  68     http://haskell.org/cabal/
  69  * the haskell harpy library >= 0.2
  70     http://hackage.haskell.org/cgi-bin/hackage-scripts/package/harpy
  71
  72
  73 ++++++++++++++++++++++++++++++++++++++++++
  74 + 2.2.2 - stable version                 +
  75 ++++++++++++++++++++++++++++++++++++++++++
  76  (this is the recommended version to grab if you wish to use it and
  77 compile from source.)
  78
  79  you may download tarballs of horde from here:
  80 http://hackage.haskell.org/cgi-bin/hackage-scripts/package/horde
  81
  82
  83 ++++++++++++++++++++++++++++++++++++++++++
  84 + 2.2.3 - development version            +
  85 ++++++++++++++++++++++++++++++++++++++++++
  86  if you wish to get the development version of horde, run:
  87
  88   $ git clone git://repo.or.gz/horde.git
  89
  90  note: this is only recommended for people interested in hacking on
  91 horde; there's no guarantee it will work properly or even build in whatever
  92 state you get.
  93
  94
  95 ++++++++++++++++++++++++++++++++++++++++++
  96 + 2.2.4 - building                       +
  97 ++++++++++++++++++++++++++++++++++++++++++
  98  after you have gotten the source to horde, building it is easy and
  99 can be done in a few steps.
 100
 101   $ runghc Setup.lhs configure --prefix=$HOME
 102
 103  this will configure horde to do a local installation with the
 104 root set to your $HOME. if you wish to do a global install, you may
 105 omit the --prefix flag.
 106  NOTE: if you are using ghc 6.6, and do not have the split up base
 107 package installed (which you probably don't,) be SURE to configure
 108 as such:
 109
 110   $ runghc Setup.lhs configure -fold-base
 111
 112  ghc 6.8 did a massive package split of the base libraries,
 113 and without this flag, you will get plenty of 'unsatisified
 114 dependency' errors.
 115
 116  after configuring, installing can be done in two steps:
 117
 118   $ runghc Setup.lhs build
 119   $ runghc Setup.lhs install --user
 120
 121  if you did not configure horde with the --prefix flag in the configure
 122 step, the --user in the install step may be omitted.
 123
 124
 125  horde is now installed!
 126
 127
 128 ++++++++++++++++++++++++++++++++++++++++++
 129 + 2.2.5 - debug builds, profiling, etc.. +
 130 ++++++++++++++++++++++++++++++++++++++++++
 131  if you're a developer and hacking on horde, you should know that when
 132 building from source, by providing certain flags to the configuration
 133 step you can enable:
 134
 135 * debugging msgs, etc -- pass -fdebug to the configure step
 136 * profiling           -- pass -fprof to the configure step
 137 * code coverage       -- pass -fcoverage to the configure step
 138 * all above           -- pass -fdebug-all to the configure step
 139
 140  it's encouraged you turn these options on while developing. by providing
 141 none of them, horde does a 'release build' which is basically none of
 142 this plus optimizations turned on.
 143
 144 note, in order to compile with profiling, you will need a profiled version
 145 of harpy available, which can be done by configuring it with the flag
 146 '--enable-library-profiling' and building.
 147
 148
 149
 150
 151
 152  ========================================
 153 | 3 - usage                              |
 154  ========================================
 155  you have two options when using horde: simply as a
 156 standalone, Forth interpreter, or as an embedded language
 157 in Haskell as a library.
 158
 159
 160
 161  ----------------------------------------
 162 | 3.1 - examples                         |
 163  ----------------------------------------
 164
 165
 166
 167  ----------------------------------------
 168 | 3.2 - as a library                     |
 169  ----------------------------------------
 170
 171
 172
 173
 174
 175  ========================================
 176 | 4 - documentation                      |
 177  ========================================
 178  in order to build documentation for horde as a library, you may run:
 179
 180   $ runghc Setup.lhs configure
 181   $ runghc Setup.lhs haddock
 182
 183  this will require you to have the haskell documentation tool, haddock, installed.
 184 see http://haskell.org/haddock/
 185
 186
 187
 188
 189
 190  =========================================
 191 | 5 - development, bugs, contact, etc.    |
 192  =========================================
 193  horde uses the git content tracker for source control. patches from anybody
 194 wishing to contribute my be sent using `git-format-patch' from the git repository to:
 195
 196
 197 austin at youareinferior dot net
 198 (or, alternatively:)
 199 mad dot one at gmail dot com
 200
 201
 202  feature additions, optimizations (to the compiler, executable, forth libs,
 203 etc) and bug fixes are all tremendously welcome.
 204  if you wish to be added as a horde developer, give me a ring at one of the
 205 above addresses so I may add you to the project as a user on http://repo.or.cz
 206
 207  also, as a side note, the horde project hosted on repo.or.cz will also have
 208 the mob user available. this will allow anybody to commit to the project's mob
 209 branch, allowing collaberation (i.e. wikipedia) without necessarily being added
 210 as an actual user. for more info, please see http://repo.or.cz/mob.html and
 211 follow the instructions there.
 212  DISCLAIMER: i do not take any responsibility for any code in that branch, what it will do,
 213 or what state it is in. if it fires the missles, don't blame me.
 214
 215
 216  questions may also be sent to the above address[es].
 217
 218  otherwise, happy hacking and thinking forth!
 219 -- austin s, 2007