|
996
|
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.
|
