git.gag.com Git - debian/yforth/blob - README

   1 yForth? v0.1beta - READ THIS (AND ONLY THIS) TO GET yForth? RUNNING.
   2
   3 0) Hello world!
   4 Here's a little file which will help you having yForth? running in few
   5 minutes on your system.
   6
   7 1) What's yForth? ?
   8 yForth? is a Forth environment written entirely in ANSI C, making it
   9 extremely portable. The first thing I want to tell you about yForth? is
  10 that it seems a joke compared to other systems such as gForth or PFE.
  11 The only things it has in common with PFE are that it's written in C, and
  12 it's been written for fun.
  13 It's rude, it hasn't anything odd, there's no reason to choose yForth? instead
  14 of other Forth environments.
  15 Nevertheless, you could find yForth? nice, in this case you're invited to
  16 explore yForth? in the following lines.
  17 yForth? is based on the draft of ANS Forth, but it's NOT complete.
  18 The reason is very simple: not all the words included in ANS Forth can be
  19 written using only ANSI C. In particular, those words which interact with
  20 system hardware almost directly, such as words which control the terminal,
  21 can't be written using solely ANSI C (and related libraries).
  22 In fact, you'll find that all the device dependent routines are grouped
  23 together in the file "udio.c". If you're using Turbo C, Borland C, or any
  24 compiler which supplies the "conio.h", you can define HAVE_CONIO in
  25 your "config.h" file and go.
  26 Note that even if in file "udio.c" you'll see some lines telling you:
  27 #ifdef HAVE_CURSES
  28 or similar, yForth? actually doesn't support CURSES library. I've decided to
  29 stop my work as soon as something machine depended that was too messy has
  30 came around.
  31
  32 2) Where does the name yForth? came from?
  33 I've been charmed by Forth since the first time I "played" with it, but
  34 I've never been able to find some book (here in Italy, obviously) to learn it.
  35 When I've put my hands on the draft of ANS Forth I thought that
  36 the best way to learn it was to write an environment. I was wondering what
  37 features made Forth so popular. I asked myself: Why Forth?
  38
  39 3) How do I compile yForth? for my system?
  40 It's simple. First of all you'll have to modify "config.h" accordingly with
  41 your system AND compiler requirements. In order:
  42 - modules
  43 You can exclude some modules to make a smaller environment, but keep
  44 in mind that all the modules will be compiled anyway. You must rely on
  45 your compiler "smart-linking" to cut off unused functions.
  46 - big/little endian
  47 Define LITTLE_ENDIAN if your machine "is" little-endian (e.g. Intel),
  48 undefine it if it's big-endian (e.g. Motorola, SPARC).
  49 - double-cell transfer
  50 You can choose two ways for moving a DCell data from data stack to C internal
  51 variables. If DCELL_MEM is defined moving is performed via memory copy,
  52 if it's undefined moving is performed via shift operators (<< and >>).
  53 - data types
  54 The most important thing is choosing what C types will identify Cells and
  55 Double Cells in yForth?. Be sure that 2 * sizeof(Cell) == sizeof(DCell).
  56 Note that using GCC makes this things trivial, since it has a "long long"
  57 type which allows having 32bit Cells. Using Turbo C that's not possible.
  58 Below data definition you'll have to change the maximum values of your
  59 system. See "limits.h".
  60 - terminal
  61 Finally, define HAVE_CONIO if you're using Turbo C, Borland C or GCC for DOS.
  62 You'll have some nice words such as "page"...
  63 - special functions
  64 "asinh", "acosh", "atanh" aren't provided by all the libraries, if you don't
  65 have them delete the definitions at the end of "config.h".
  66
  67 The second thing to do now is configuring the "Makefile". I know, it's rude,
  68 but yForth? is drifting on my system for too long, I want to finish it
  69 within 1996.
  70 At the moment "Makefile" is ready for GCC (under Linux), it's simple and
  71 you won't find any problem modifying it.
  72
  73 Third, type "make all". Yes, that's all.
  74
  75 4) I have yForth? running, and now?
  76 It's your, you can make anything you want with. If you want an explanation
  77 of the words provided by yForth? please refer to the draft of ANS Forth or
  78 something equivalent. The Net will help you.
  79 Do not expect the prompt "ok" to come up when you run yForth?, the standard
  80 says that "ok" shall be printed AFTER every succesful command execution...
  81
  82 5) What about yForth? in 1997?
  83 Well, I think yForth? will be available since January 1997, and at the moment
  84 I've no idea of some future developlment. I've learned a lot writing it, both
  85 Forth and C, but I can't say I've learned programming in Forth.
  86 Ideas come and go, now they're all gone. But don't despair, if you have some
  87 fantastic intuition you want to share, email me, I'll listen to you!
  88 Furthermore, this package is still incomplete. The source code can be better
  89 organized, more documentation could be written, and so on. If you want to
  90 work on it, you can, and I'd be happy to work together to make some improvement.
  91
  92 6) Hey, just a moment!
  93 Don't forget:
  94         - yForth? is a "beta" release, I think it has bugs, but, most
  95                 important, I'm afraid that some words don't behave as the
  96                 standard says they have to.
  97         - yForth? comes with no warranty, I don't make any warranty about it.
  98         - yForth? is completely free. You can use, modify, doing anything
  99                 you want with it. If you're going to use it in any project,
 100                 I would be grateful if you cite me, but you're no obliged.
 101         - yForth? is NOT a complete ANS Forth.
 102         - yForth? is written in ANSI C. Ok, you could see some warning while
 103                 compiling it, and I've to check it with lint, but it
 104                 doesn't make use of any capability other than those provided
 105                 by the standard (well, "long long" doesn't belong to the
 106                 standard, but you're anxious to work whit 32bit Cells,
 107                 aren't you?).
 108         - yForth? comes with it's nice logo (yforthlogo.gif).
 109         - yForth? comes with some word not included in ANS Forth. The most
 110                 useful ones are those you find in "ycore.c". Each comes with
 111                 a short description just before its implementation.
 112         - yForth? may not support "page" on systems where "conio.h" is unknown.
 113                 Since I love clearing screens, here's a little tip, define:
 114                 : page s" clear" system drop ;
 115                 And you'll have "page" working on your Unix system.
 116
 117 7) Please report bugs
 118 I'll be very happy if you report me some bug. Obviously I'll be happy even
 119 more if you tell me how fo fix it, but I can't pretend so much, even 'cause
 120 my C is not very readable (few comments...).
 121
 122 8) Who am I?
 123 Luca Padovani
 124 v. Cormons, 12
 125 48100 Ravenna (RA)
 126 Italy
 127
 128 email: lpadovan@cs.unibo.it
 129
 130 Enjoy yForth?