regina/README.07a

   1 Welcome to version 0.07a of the Regina Rexx interpreter.
   2
   3 But first, the copyright and copying conditions. The code is
   4 'copylefted', which means that it is copyrighted, but that you are
   5 allowed to use, copy, modify, redistribute and sell the code, under
   6 the conditions listed in the "GNU Library General Public License". See
   7 the file COPYING-LIB for more information.
   8
   9 Note that this has changed since version 0.06, which was covered by
  10 the 'ordinary' GPL. The reason for the change is simply that Regina is
  11 becoming more and more library-like, and the LGPL seemed more
  12 appropriate than the GPL.
  13
  14 The source has been built and tested on several platforms. Generally,
  15 'all' you need a Standard C compiler (i.e. ANSI C), a 'lex' program
  16 and a 'yacc' program. In addition, your machine should be POSIX
  17 compliant. The latest version of Regina is stored on the anonymous ftp
  18 site ftp.pvv.unit.no (129.241.36.200), in the '/pub/regina' directory.
  19
  20 To build the interpreter:
  21
  22 1) Edit the Makefiles (in particular the one in the 'src' subdirectory,
  23    and uncomment a suitable definition of the macros CC and CEXTRA.
  24    You may want to make a new one if none of the existing ones fit
  25    your exact needs.
  26
  27 2) Run the command   make
  28
  29    If you like to make the dynamic library curses.rxlib, then you must
  30    issue the command  make curses.rxlib  while in the src subdirectory.
  31    Note that dynamic loading of libraries will not work on all systems.
  32
  33 3) The Makefile does not install targets. There is a make-target
  34    'install', which installs programs. Check the settings of macros in
  35    the makefile before running make for target 'install'.
  36
  37 4) You might want to run the documentation through the LaTeX
  38    textformatter.  If you don't have the 'block' and 'a4' style
  39    options for tex (these are not standard LaTeX options), just
  40    edit them out, letting the first line become:
  41
  42       \documentstyle{report}
  43
  44    Preformatted version of the documentation is supposed to be
  45    available from flipper in the directory 'pub/rexx/doc', there is
  46    one file which contains the whole documentation as a PostScript
  47    document. In addition, there is a set of ASCII files, which is the
  48    preformatted version, divided by chapters.
  49
  50 There are sometimes problems when compiling Regina under SunOS. The
  51 main problem is that SunOS is one of few Unix systems still in use which
  52 is neither POSIX nor ANSI. Note that Solaris is OK. But SunOS 4.1.1 has
  53 the following problems:
  54
  55  * Lacks the memmove() function; use bcopy() instead
  56  * Lacks the strerror() function; access sys_errlist[] directrly for
  57    circumvent this.
  58
  59 There are several other omisions and bugs in the include file of SunOS,
  60 but the rest of them are likely to 'just' generate warnings. The two
  61 above, however, _must_ be fixed if compilation shall succeed. If the
  62 preprocessor symbol SunKludges is defined, these two problems are
  63 automatically fixed in config.h; however, that fix may not suit all
  64 situations.
  65
  66 In general, this depends on the interpreter you are using. Some
  67 versions of gcc (at least 2.5.2) will declare strerror() and
  68 memmove(); thus an error is provoked if compiled with SunKludges.
  69 Also, there are some other problems, like the SEEK_{SET,END,CUR}
  70 macros not being defined.
  71
  72 Also, SunOS has a bug, the _file member of FILE has type char, but
  73 fileno() should return an integer or -1 if error. However, if your
  74 max-number-of-files limit exceeds 128, fileno() will return -128 as
  75 file descriptor. Obviously, this is incorrect, and obviously, this can
  76 not be fixed by casting fileno() to unsigned char (it would be
  77 incompatible and then -1 and 255 would overlap). You should (a)
  78 complain about this to your SunOS vendor, and (b) never set the max
  79 open files limit higher than 128. I've tried to circumvent it by
  80 casting the return value from fileno to unsigned char. But it doesn't
  81 seem to work, probably because other I/O functions use _file without
  82 taking any precautions. Thus, you should never use max open files
  83 greater than 128 under SunOS; else, bad things will happen, both in
  84 Regina and in other programs. (Use limit or ulimit to display/set
  85 this max limit.)
  86
  87 If you want to compile it for VMS, you need a lex and a yacc program.
  88 You can get the GNU versions of these tools, or you can run the lex
  89 and yacc on another machine, and copy the results of these programs
  90 from that machine. Unfortunately, I've not been able to test the VMS
  91 version for some time now, so it might need some 'help' to compile
  92 correctly.
  93
  94 I have built it on the following platforms:
  95
  96    - gcc, lex and yacc on a Uniline 88
  97    - gcc, lex and yacc on Sun 3
  98    - c89 (unbundled), lex and yacc on Decstation 5000, under Ultrix 4.2
  99    - cc, lex and yacc on Irix Indigo and Onyx, under IRIX 4 and 5
 100    - acc (unbundled), lex and yacc on Sun Sparc, under Sunos 4.2
 101    - cc, lex and yacc on Decstation 3100, under OSF/1
 102    - c89, lex and yacc on HP 9000, under HP/UX 8.05
 103    - cc, lex and yacc on IBM RS6000 under AIX
 104    - cc, lex and yacc on Cray under UNICOS
 105    - cc, lex and yacc on Linux 0.99
 106    - cc on a VAX/VMS, getting yacc and lex output from a Sun.
 107    - cc, lex and yacc on a DEC alpha running OSF/1
 108
 109 Read the file README.VMS to get more information about how to build
 110 Regina on a computer running VMS, and what functionality is present in
 111 the VMS version of Regina. In addition to VMS and Unix, this version
 112 of Regina has also been successfully built for OS/2 and MS-DOS, using
 113 the EMX development environment under OS/2. However, Regina does not
 114 yet have any specific support for these systems.
 115
 116 This version of Regina also has support for dynamic loading of object
 117 files. I.e. that you can load an object module containing definitions
 118 for extra 'built-in' functions. This interface uses the same interface
 119 as the RXFUNCADD(), RXFUNCDROP() and RXFUNCQUERY() functions in SAA
 120 Rexx. Only one library of extra functions are available, it is a
 121 curses interface library (although not all curses functions are
 122 implemented in it yet.) To load these function into the interpreter,
 123 use:
 124
 125    lib = './curses.rxlib'
 126    if rxfuncadd('CURSES', '/path/curses.rxlib', 'curses')  then do
 127       say 'An error occured when trying to load the library: "'lib'"'
 128       say 'The error message returned was: "'rxfuncerrmsg()'"'
 129       say 'Exiting...'
 130       exit
 131       end
 132    else
 133       call curses('CUR_')
 134
 135 Actually, this 'just' loads and executes a function CURSES() in the
 136 library. However, this special function will load all the other
 137 functions in the library. The parameter given to CURSES() is the
 138 prefix to prepend on all function names. See the file hanoi.rexx in
 139 the code directory for an example.
 140
 141 Note that dynamic linking is only supported for those. Also note the
 142 the normal 'make' setup will not by default compile the curses
 143 library. To do that, do:
 144
 145    make curses.rxlib
 146
 147 after having made the rest of Regina.
 148
 149 If you are unable to get Regina to work on your computer, because you
 150 don't have one or several of the programs needed to build it, you can
 151 try to build the GNU tools on your computer. Regina will compile with
 152 these tools (and using them is a good idea anyway). You can get them
 153 by anonymous ftp from prep.ai.mit.edu, ugle.unit.no and several other
 154 places.
 155
 156 The areas where it is not POSIX compliant are:
 157
 158    - It uses "struct timeval" and gettimeofday().  You can control
 159      this through the HAS_TIMEVAL option in config.h.  Comment it out
 160      if your machine does not eat the code.  Consequences: The
 161      interpreter will have a time granularity of 1 second.
 162
 163    - It uses ftruncate().  If you do not have that, comment out the
 164      HAS_FTRUNCATE option on config.h.  Consequences: When writing to
 165      the middle of a file with lineout(), the file will not be
 166      truncated after the line written.
 167
 168    - It uses putenv() to set an environment variable. While POSIX do
 169      have the getenv() call, it does not have a way of setting
 170      environment variables. Fortunately, most machines have a way of
 171      doing this, but you might have to link in an extra library or
 172      something. If you can't find a putenv() on your machine, you can
 173      undefine the HAS_PUTENV macro in config.h.  Consequences: Trying
 174      to set en environment variable will cause a syntax error
 175
 176 The interpreter has bugs and missing feature. I consider this release
 177 of Regina a beta release, and I will continue to do so, until:
 178
 179    - Regina is a full implementation of Rexx as described in the book:
 180      "The Rexx Language", by Mike Cowlishaw;
 181
 182    - the most important extensions from CMS have been implemented;
 183
 184    - a full implementation of the Rexx SAA API, as documented for
 185      OS/2, has been implemented;
 186
 187    - all important extensions suggested by the ANSI Rexx committee
 188      have been implemented;
 189
 190    - an extensive test suite which test most parts of the features
 191      listed above have been implemented, and Regina is able to run it
 192      without problems; and
 193
 194    - the documentation for Regina has been completed.
 195
 196 If you find bugs or incompatibilities, please send me e-mail
 197 describing the bug. It is important that your bugreport contains:
 198
 199    - Description of what equipment you used, i.e. hardware
 200      platform, operating system, compiler version, compiler
 201      options used, version of Regina etc.
 202
 203    - A description of the buggy behavior (and the behavior that
 204      you expected to see).
 205
 206    - Preferably a program that demonstrates the behavior.  The
 207      program should be as small as possible, preferably not more
 208      than 10 lines or so.
 209
 210    - If you have already fixed the bug, please append a context
 211      diff of the changes you made to the source.
 212
 213 Please make sure that the bug is really a bug in the interpreter, not
 214 just a bug in your program. And also make sure that you've got the
 215 latest release of Regina. If possible, run your program on other REXX
 216 interpreters to see how they behave, and check with a REXX manual if
 217 you have access to one. Bugreports are welcome, as well as other types
 218 of comments. You can send bugreports directly to my email address,
 219 listed below.
 220
 221 There are four subdirectories.
 222
 223    - The first is 'trip' which is the start of a "triptest" for a REXX
 224      interpreter, which is supposed to test most REXX interpreter
 225      features.  If enough tests are gathered in this triptest, any
 226      REXX interpreter that manages to run it would be fairly REXX
 227      compatible. Such a trip test is not a perfect way of ensuring
 228      compatibility, but it is far better than none.
 229
 230    - The next subdirectory is the 'demo', which contains some small
 231      demo programs for REXX, mainly demonstrations of special
 232      programming features in REXX. Also included are some common test
 233      programs and routines distributed on the net. Note that the
 234      programs in this directory are not covered by the GPL.
 235
 236    - The src directory, containing the source code for Regina.
 237
 238    - The 'doc' subdirectory, containing the documentation for Regina.
 239      Unfortunately, this documentation is not complete, nor it is
 240      completely correct at the moment, since I want to finish the
 241      coding before continuing the work in the doc.
 242
 243 Some of the things the interpreter does not have:
 244
 245    - The documentation is far from finished. It has lower priority
 246      for the moment, until I have finished the interpreter itself.
 247
 248    - For the (external) commands, there is not a consistent shell in
 249      the background to which commands are sent.  Instead either there
 250      is a shell that is started up each time (ADDRESS SYSTEM), or the
 251      command is run directly (ADDRESS PATH and COMMAND).  This will
 252      be fixed ...
 253
 254    - I still need to test a lot of functionality that has been
 255      implemented and are supposed to work.
 256
 257    - Lots of other things ...
 258
 259 There is a mailing list for announcements of new versions of Regina.
 260 If you want to be on that list, send a request to be put on the list
 261 to the address: <rexx-request@pvv.unit.no>
 262
 263 Anders Christensen                     e-mail: anders@pvv.unit.no
 264 SINTEF RUNIT
 265 Hogskoleringen 7i
 266 N-7034 Trondheim, Norway