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