| 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: <[email protected]> |
| 262 |
|
| 263 |
Anders Christensen e-mail: [email protected] |
| 264 |
SINTEF RUNIT |
| 265 |
Hogskoleringen 7i |
| 266 |
N-7034 Trondheim, Norway |