Mercurial > repo
comparison interps/c-intercal/README @ 996:859f9b4339e6
<Gregor> tar xf egobot.tar.xz
author | HackBot |
---|---|
date | Sun, 09 Dec 2012 19:30:08 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
995:6883f5911eb7 | 996:859f9b4339e6 |
---|---|
1 Release Notes for C-INTERCAL | |
2 | |
3 DISCREDITS | |
4 | |
5 This package is an implementation of the language INTERCAL designed by Don | |
6 Woods and James Lyon, who have since spent more than twenty years trying to | |
7 live it down. | |
8 | |
9 This implementation was created by Eric S. Raymond <esr@snark.thyrsus.com> | |
10 during a fit of lunacy from which he has since mostly recovered. It has been | |
11 considerably hacked upon and improved by Steve Swales, Michael Ernst, Louis | |
12 Howell, Brian Raiter, Alex Smith, Joris Huizer and others. For detailed | |
13 credits see NEWS. | |
14 | |
15 FILES | |
16 | |
17 The compiler itself is in the src directory. You can choose where to | |
18 install it with the --prefix argument to configure, or by setting DESTDIR | |
19 in the Makefile. The doc directory contains (surprise!) documentation, and | |
20 pit contains various examples of INTERCAL source code, writhing in agony. | |
21 | |
22 The files included are: | |
23 | |
24 README -- this file | |
25 BUGS -- current bug and to-do list | |
26 NEWS -- info on features and fixes new in this release | |
27 COPYING -- copyright and licence information | |
28 MANIFEST -- a list of all files in the distribution | |
29 | |
30 doc/READ.ME -- historical notes on the docs | |
31 doc/ick.txi -- the Revamped Manual sources, a newer manual | |
32 doc/fdl-1-2.txi -- the GNU FDL version 1.2 in Texinfo format | |
33 doc/ick.txt -- the Revamped Manual in plain text format | |
34 doc/ick.info -- the Revamped Manual in Info format | |
35 doc/ickstyle.css -- styling rules for the Revamped Manual in HTML | |
36 doc/tidy.cfg -- HTML tidying rules for the Revamped Manual | |
37 doc/fix83.pl -- script to fixup the HTML output for 8.3 systems | |
38 doc/intercal.mm -- the old manual in groffable form | |
39 doc/Makefile -- makefile to build old and new manuals | |
40 doc/THEORY.txt -- some notes on the internals of the INTERCAL compiler | |
41 doc/chipspec.txt -- plans for an INTERCAL-based microprocessor | |
42 doc/ick.1 -- man page for ick | |
43 doc/convickt.1 -- man page for convickt | |
44 | |
45 src/abcess.h -- interface to functions linked with programs | |
46 src/arrgghh.c -- option argument parsing for generated programs | |
47 src/bin2c.c -- creates C code representations of binary files | |
48 src/cesspool.c -- the INTERCAL runtime support code | |
49 src/clc-cset.c -- compatibility code for CLC-INTERCAL character sets | |
50 src/csetstub.c -- small file to allow convickt to link | |
51 src/configh.in -- config.h template generated by autoheader | |
52 src/configdj.h -- config.h substitute for DJGPP without config.sh | |
53 src/convickt.c -- command line character set converter | |
54 src/coopt.sh -- script to help out the -F optimizer (POSIX only) | |
55 src/dekludge.c -- INTERCAL optimizer wrapper and utility functions | |
56 src/feh.h -- interface to INTERCAL-to-C code generator | |
57 src/feh2.c -- INTERCAL-to-C code generator | |
58 src/fiddle.[ch] -- the INTERCAL operators | |
59 src/ick-wrap.c -- the driver for generated C-from-INTERCAL code | |
60 src/ick.h -- compilation types and defines | |
61 src/ick_ec.[ch] -- external call support for INTERCAL | |
62 src/ick_lose.[ch] -- INTERCAL compile- and run-time error handling | |
63 src/idiotism.oil -- list of INTERCAL idioms to optimize | |
64 src/lexer.l -- the lexical analyzer specification (in LEX) | |
65 src/numerals.c -- numerals table for INTERCAL input | |
66 src/oil.y -- compiler to translate idiotism.oil into C | |
67 src/oil.h -- name mangling for OIL files | |
68 src/parser.y -- the grammar specification (in YACC) | |
69 src/perpet.c -- main routine for compiler | |
70 src/pick1.h -- template for compiler-dependent PIC C headers | |
71 src/pick2.h -- runtime support for compiled PIC-INTERCAL | |
72 src/pickwrap.c -- the driver for generated PIC C-from-INTERCAL code | |
73 src/sizes.h -- variables defining the numeric base | |
74 src/uncommon.[ch] -- code common to the compiler and debugger | |
75 src/unravel.c -- multithreading functions | |
76 src/yuk.[ch] -- INTERCAL debugger and profiler | |
77 src/*.bin -- character set definitions for clc-cset and convickt | |
78 | |
79 prebuilt/parser.[ch] -- Prebuilt parser (for systems without bison) | |
80 prebuilt/lexer.c -- Prebuilt lexer (for systems without flex) | |
81 prebuilt/oil-oil.c -- Prebuilt OIL compiler (again, for bisonless systems) | |
82 | |
83 etc/intercal.el -- elisp for editing INTERCAL code under GNU Emacs | |
84 etc/intercal.vim -- INTERCAL syntax higlighting information for vim | |
85 etc/cftoec.sh -- script to convert cfunge to a library (see below) | |
86 etc/IFFI* -- input to that script | |
87 etc/cfunge.patch -- more input to that script | |
88 etc/temp -- temporary directory used by that script | |
89 | |
90 configure -- GNU Autoconf script that generates a Makefile | |
91 configure.ac -- autoconf source for configure | |
92 Makefile.in -- template Makefile for compiling C-INTERCAL | |
93 Makefile.am -- automake source for Makefile.in | |
94 | |
95 buildaux/* -- helper scripts for the build provided by automake | |
96 aclocal.m4 -- helper file needed to build the build system itself | |
97 | |
98 pit/* -- sample INTERCAL code; see pit/CATALOG | |
99 pit/explib/* -- source code for expansion libraries | |
100 pit/lib/syslib.*i -- source code for the system libraries | |
101 | |
102 HOW TO GET STARTED | |
103 | |
104 First, note that there is a much fuller manual than this file available. For | |
105 full information about C-INTERCAL, including extensive installation and usage | |
106 instructions, see that one; run `info -f doc/ick.inf', or failing that read | |
107 the plain text version at doc/ick.txt. (You can build a variety of other | |
108 formats as well, such as HTML and PDF, using the Makefile in the doc | |
109 directory.) After C-INTERCAL is installed, the manual is also available with | |
110 just `info ick' for information about running ick, the compiler, or `info | |
111 C-INTERCAL' for the available information about ick and C-INTERCAL. (If you | |
112 installed C-INTERCAL in a directory that did not contain the main Info | |
113 documentation tree, instead `info ick' will do what `info C-INTERCAL' should | |
114 do, and `info C-INTERCAL' will not work at all.) | |
115 | |
116 You want a man page? Man pages are for wimps. (However, Debian wrote one | |
117 anyway, and it's available in the distribution as doc/ick.1.) To compile an | |
118 INTERCAL program `foo.i' to executable code, just do | |
119 | |
120 ick foo.i | |
121 | |
122 There are many other useful options available, which used to be listed in this | |
123 README but it eventually became several long unreadable run-on sentences; | |
124 interested readers are referred to the Revamped Manual, or to ick -@ (which | |
125 prints a usage message). | |
126 | |
127 Every compiled INTERCAL program also accepts certain options at runtime (code | |
128 by Steve Swales). These include [+/-]help, [+/-]traditional, and | |
129 [+/-]wimpmode. The help option (with either + or -) triggers a 'usage' | |
130 message. The +traditional option is presently a no-op. Also available are | |
131 [+/-] printflow, which gives information that may or may not be helpful for | |
132 debugging a program, and [+/-] mystery, which is deliberately undocumented. | |
133 | |
134 Steve writes: "The wimpmode option is the most interesting. I found myself | |
135 always running my test programs with filters on both ends to work around the | |
136 'nifty' INTERCAL number representations. This was so painful that I decided it | |
137 would be LESS painful (and a lot less code) if I added a 'wimp' option. With | |
138 the +wimpmode option, the user is subjected to a humiliating message about what | |
139 a wimp he or she is to use this mode, but after that is allowed to use | |
140 conventional numerical notation. While such a mode doubtless violates to some | |
141 extent the INTERCAL philosophy, the fact that a 'unbutcher' command has been | |
142 posted clearly indicates the need for it. Anyway... if you don't like it, don't | |
143 use it... the default is -wimpmode (i.e. NOT wimp mode)." | |
144 | |
145 SPREADING THE BLAME | |
146 | |
147 There is an INTERCAL Resource Page at http://www.catb.org/intercal | |
148 | |
149 The latest version of INTERCAL is also kept available at the Retrocomputing | |
150 Museun, http://www.catb.org/retro. | |
151 | |
152 (The above two paragraphs are somewhat out of date, but I kept them there, | |
153 including the typos, for historical purposes. Looking through the | |
154 alt.lang.intercal archives is usually the best way to find out what the latest | |
155 version of C-INTERCAL (and you'll find out how to get its rival too, for that | |
156 matter) is nowadays; they tend to pop up in various unusual places, so giving | |
157 a URL might be misleading. Note also that contact details, and even who to | |
158 contact, often end up out of date; the newsgroup is also a good way to find | |
159 out who to contact. | |
160 | |
161 As of when I wrote this, the current homepage for C-INTERCAL and CLC-INTERCAL | |
162 is http://intercal.freeshell.org.) | |
163 | |
164 There is, in addition, an occasionally active USENET newsgroup devoted to the | |
165 language: alt.lang.intercal. (It is a somewhat unusual newsgroup, as although | |
166 large numbers of people are known to read it hardly anyone ever writes in it; | |
167 occasionally someone asks if the newsgroup is dead and gets several responses | |
168 claiming it isn't. Mostly it's full of C-INTERCAL release notices, and is thus | |
169 a good way to determine the most recent version of C-INTERCAL.) | |
170 | |
171 BUILDING C-INTERCAL | |
172 | |
173 C-INTERCAL now uses a GNU Autotools-based build system, this is something like | |
174 the fourth build system that has been tried for it, and hopefully it now works | |
175 (we've given the build system several interesting twists, of course; for | |
176 instance, automake dumps things like the prebuilt parser in the root of the | |
177 distribution by default, which is ugly, so we moved them to the prebuilt | |
178 directory.) It is possible to build with the straightforward configure/make/ | |
179 make install routine, just as most other distributed software does; however, | |
180 this dumps all the generated files into the root of the distribution, which | |
181 violates the author's sense of aesthetics, and so the recommended approach is | |
182 to build out-of-tree; create a directory anywhere you like, and run configure | |
183 from that directory, then make and install there. You can give configure | |
184 arguments (see configure --help for details); probably the only one you'll | |
185 want to use is --prefix, which selects the directory to install C-INTERCAL | |
186 into (--prefix=/usr and --prefix=/usr/local (the default) are both likely | |
187 choices, but you may want to install into a subdirectory of your home | |
188 directory to avoid the need for root priveleges). Some revious versions of | |
189 C-INTERCAL required various information to be specified by the user; the build | |
190 system now figures this all out for itself, so you can relax and not need to | |
191 worry (in theory). | |
192 | |
193 Building on DOS (via DJGPP) and Windows (via Cygwin) both work fine the same | |
194 way as builds on POSIX-like systems like Linux, Mac OS X, and BSD. | |
195 | |
196 I have come across lexes whose default limits for various things aren't high | |
197 enough to handle INTERCAL's various lexing conundrums. In this case, pay | |
198 attention to the error messages they give you, and alter the source file | |
199 src/lexer.l accordingly. This should not happen on most modern systems, as | |
200 most modern lexers allocate memory dynamically and so can handle source files | |
201 of any length. | |
202 | |
203 The build now uses your default compiler and compiler options; you can change | |
204 either of these by specifying them as options to configure (for instance, | |
205 configure CC=gcc CFLAGS=-O3 -funroll-loops). (You can also set the appropriate | |
206 environment variables instead.) The default options are -g on all compilers, | |
207 and also -O2 if you're using gcc, and the default compiler is calculated | |
208 automatically by configure; note in particular that if you're using a non-gcc | |
209 compiler you'll have to request optimisation yourself by setting the CFLAGS if | |
210 you want an optimising build. | |
211 | |
212 Although the build system tries to find a good high-resolution timing function | |
213 to use for profiling, such functions are often system-specific; you may be | |
214 able to get better profiling output by tinkering with yuk.h to specify a | |
215 different method of profiling. | |
216 | |
217 NOTES ON COMPILING PIC-INTERCAL | |
218 | |
219 PIC C compilers tend to differ substantially in the way they handle various | |
220 language constructs. As a result, this compiler will only compile to C (not to | |
221 hex or asm) when compiling a PIC-INTERCAL program. There are two header files, | |
222 pick1.h and pick2.h in the /src directory; these need to be placed somewhere | |
223 your compiler can find them, and pick1.h will need to be modified to contain | |
224 compiler-specific data (like the names of data types and the syntax for | |
225 specifying the device type, fuses, and various commands). | |
226 | |
227 NOTES ON THE C-INTERCAL / CFUNGE EXTERNAL CALLS SYSTEM | |
228 | |
229 Code is provided to allow linking of Funge-98 programs to INTERCAL programs; | |
230 however, this requires a Funge-98 interpreter, which is not present in this | |
231 distribution. Therefore, in order to do this, a Funge-98 interpreter must | |
232 first be downloaded and prepared for use with C-INTERCAL. At present, code is | |
233 only available for linking with 'cfunge', a Funge-98 interpreter written in | |
234 C. You can get the latest sources for that interpreter from the Internet via | |
235 the bzr version-control system by running this command: | |
236 | |
237 bzr branch http://rage.kuonet.org/~anmaster/bzr/cfunge | |
238 | |
239 Once you have the source code to cfunge, you can compile it into a library | |
240 suitable for use by C-INTERCAL by changing to the /etc directory of the | |
241 C-INTERCAL distribution, and running the cftoec.sh shell script in that | |
242 directory with the path to the cfunge distribution as an argument. The script | |
243 will make a copy of cfunge, modify it as required, and then place the | |
244 resulting library (libick_ecto_b98.a) in the /prebuilt directory of the | |
245 C-INTERCAL distribution; installing (or reinstalling) C-INTERCAL after that | |
246 will copy that library into the correct location in your filesystem. | |
247 | |
248 For information on actually using this system once you've set it up, consult | |
249 the Revamped Manual. | |
250 | |
251 LICENSING | |
252 | |
253 C-INTERCAL is now distributed under the General Public License version 2 (or | |
254 at your choice any later version), except for the C skeleton file which is | |
255 explicitly *not* GPLed in order to avoid the (possibly mythical) "license | |
256 virus" effect, and the Revamped Manual, which is licenced under the GNU Free | |
257 Documentation Licence version 1.2. See the file COPYING for details on the | |
258 General Public License, and the file doc/fdl-1-2.txi (which is also included | |
259 as a chapter in each of the compiled versions of the documentation, in case | |
260 you don't feel like reading Texinfo) for information on the GNU Free | |
261 Documentation Licence. |