Debian Codegraph @

README

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