Mercurial > repo

comparison interps/c-intercal/README @ 996:859f9b4339e6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
<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.