# # # #
######## # # ######### ########## ##########
# # # # # # # #
# ## # # # # # # # #
## # # # # # # # #
## # ######### # ## # #
## ## # #
horde: a forth written in haskell
1 - intro: what is horde?
2 - installation
2.1 - binaries
2.2 - from source
2.2.0 - prerequisites
2.2.2 - development version
2.2.3 - stable version
2.2.4 - building
2.2.5 - debug builds, profiling, etc..
3 - usage
3.1 - examples
3.2 - as a library
4 - documentation
5 - development, bugs, contact, etc.
========================================
| 1 - intro: what is horde? |
========================================
horde is a Forth implementation written in the purely functional language,
Haskell. it is designed to be a fully compliant ANS Forth implementation in
the same kin as gforth, while also optionally embeddable as a haskell library.
========================================
|2 - installation |
========================================
there are two modes for installing horde: from binaries and from source code
----------------------------------------
| 2.1 - binaries |
----------------------------------------
binary packages of horde are currently not yet available for microsoft windows
or gnu/linux.
----------------------------------------
| 2.2 - from source |
----------------------------------------
if you wish to install horde from source, simply follow the below
++++++++++++++++++++++++++++++++++++++++++
+ 2.2.1 - prerequisites +
++++++++++++++++++++++++++++++++++++++++++
* the glasgow haskell compiler
http://haskell.org/ghc (v6.6.x or v6.8.1 will suffice)
* cabal >= 1.2 installed for the compiler (comes with ghc 6.8.1)
http://haskell.org/cabal/
* the haskell harpy library >= 0.2
http://hackage.haskell.org/cgi-bin/hackage-scripts/package/harpy
++++++++++++++++++++++++++++++++++++++++++
+ 2.2.2 - stable version +
++++++++++++++++++++++++++++++++++++++++++
(this is the recommended version to grab if you wish to use it and
compile from source.)
you may download tarballs of horde from here:
http://hackage.haskell.org/cgi-bin/hackage-scripts/package/horde
++++++++++++++++++++++++++++++++++++++++++
+ 2.2.3 - development version +
++++++++++++++++++++++++++++++++++++++++++
if you wish to get the development version of horde, run:
$ git clone git://repo.or.gz/horde.git
note: this is only recommended for people interested in hacking on
horde; there's no guarantee it will work properly or even build in whatever
state you get.
++++++++++++++++++++++++++++++++++++++++++
+ 2.2.4 - building +
++++++++++++++++++++++++++++++++++++++++++
after you have gotten the source to horde, building it is easy and
can be done in a few steps.
$ runghc Setup.lhs configure --prefix=$HOME
this will configure horde to do a local installation with the
root set to your $HOME. if you wish to do a global install, you may
omit the --prefix flag.
NOTE: if you are using ghc 6.6, and do not have the split up base
package installed (which you probably don't,) be SURE to configure
as such:
$ runghc Setup.lhs configure -fold-base
ghc 6.8 did a massive package split of the base libraries,
and without this flag, you will get plenty of 'unsatisified
dependency' errors.
after configuring, installing can be done in two steps:
$ runghc Setup.lhs build
$ runghc Setup.lhs install --user
if you did not configure horde with the --prefix flag in the configure
step, the --user in the install step may be omitted.
horde is now installed!
++++++++++++++++++++++++++++++++++++++++++
+ 2.2.5 - debug builds, profiling, etc.. +
++++++++++++++++++++++++++++++++++++++++++
if you're a developer and hacking on horde, you should know that when
building from source, by providing certain flags to the configuration
step you can enable:
* debugging msgs, etc -- pass -fdebug to the configure step
* profiling -- pass -fprof to the configure step
* code coverage -- pass -fcoverage to the configure step
* all above -- pass -fdebug-all to the configure step
it's encouraged you turn these options on while developing. by providing
none of them, horde does a 'release build' which is basically none of
this plus optimizations turned on.
note, in order to compile with profiling, you will need a profiled version
of harpy available, which can be done by configuring it with the flag
'--enable-library-profiling' and building.
========================================
| 3 - usage |
========================================
you have two options when using horde: simply as a
standalone, Forth interpreter, or as an embedded language
in Haskell as a library.
----------------------------------------
| 3.1 - examples |
----------------------------------------
----------------------------------------
| 3.2 - as a library |
----------------------------------------
========================================
| 4 - documentation |
========================================
in order to build documentation for horde as a library, you may run:
$ runghc Setup.lhs configure
$ runghc Setup.lhs haddock
this will require you to have the haskell documentation tool, haddock, installed.
see http://haskell.org/haddock/
=========================================
| 5 - development, bugs, contact, etc. |
=========================================
horde uses the git content tracker for source control. patches from anybody
wishing to contribute my be sent using `git-format-patch' from the git repository to:
austin at youareinferior dot net
(or, alternatively:)
mad dot one at gmail dot com
feature additions, optimizations (to the compiler, executable, forth libs,
etc) and bug fixes are all tremendously welcome.
if you wish to be added as a horde developer, give me a ring at one of the
above addresses so I may add you to the project as a user on http://repo.or.cz
also, as a side note, the horde project hosted on repo.or.cz will also have
the mob user available. this will allow anybody to commit to the project's mob
branch, allowing collaberation (i.e. wikipedia) without necessarily being added
as an actual user. for more info, please see http://repo.or.cz/mob.html and
follow the instructions there.
DISCLAIMER: i do not take any responsibility for any code in that branch, what it will do,
or what state it is in. if it fires the missles, don't blame me.
questions may also be sent to the above address[es].
otherwise, happy hacking and thinking forth!
-- austin s, 2007
