README for C-INTERCAL

This package is an implementation of the language INTERCAL designed by Don Woods and James Lyon, who have since spent decades trying to live it down.

This implementation was created by Eric S. Raymond <esr@snark.thyrsus.com> during a fit of lunacy from which he has since mostly recovered. It has been considerably hacked upon and improved by Steve Swales, Michael Ernst, Louis Howell, Brian Raiter, Alex Smith, Joris Huizer and others. For detailed credits see NEWS.

The compiler itself is in the src directory. You can choose where to install it with the --prefix argument to configure, or by setting DESTDIR in the Makefile. The doc directory contains (surprise!) documentation, and pit contains various examples of INTERCAL source code, writhing in agony.

The files included are:

First, note that there is a much fuller manual than this file available. For full information about C-INTERCAL, including extensive installation and usage instructions, see that one; run ‘info -f doc/ick.inf’, or failing that read the plain text version at doc/ick.txt. (You can build a variety of other formats as well, such as HTML and PDF, using the Makefile in the doc directory.) After C-INTERCAL is installed, the manual is also available with just ‘info ick’ for information about running ick, the compiler, or ‘info C-INTERCAL’ for the available information about ick and C-INTERCAL. (If you installed C-INTERCAL in a directory that did not contain the main Info documentation tree, instead ‘info ick’ will do what ‘info C-INTERCAL’ should do, and ‘info C-INTERCAL’ will not work at all.)

You want a man page? Man pages are for wimps. (However, Debian wrote one anyway, and it’s available in the distribution as doc/ick.1.) To compile an INTERCAL program ‘foo.i’ to executable code, just do

There are many other useful options available, which used to be listed in this README but it eventually became several long unreadable run-on sentences; interested readers are referred to the Revamped Manual, or to ick -@ (which prints a usage message).

Every compiled INTERCAL program also accepts certain options at runtime (code by Steve Swales). These include help, traditional, and wimpmode. The help option (with either + or -) triggers a usage message. The +traditional option is presently a no-op. Also available are printflow, which gives information that may or may not be helpful for debugging a program, and mystery, which is deliberately undocumented.

Steve writes: "The wimpmode option is the most interesting. I found myself always running my test programs with filters on both ends to work around the 'nifty' INTERCAL number representations. This was so painful that I decided it would be LESS painful (and a lot less code) if I added a 'wimp' option. With the +wimpmode option, the user is subjected to a humiliating message about what a wimp he or she is to use this mode, but after that is allowed to use conventional numerical notation. While such a mode doubtless violates to some extent the INTERCAL philosophy, the fact that a 'unbutcher' command has been posted clearly indicates the need for it. Anyway… if you don’t like it, don’t use it… the default is -wimpmode (i.e. NOT wimp mode)."

There is an INTERCAL Resource Page at http://www.catb.org/intercal, and another at http://intercal.freeshell.org. Both point at the same C-INTERCAL repository, which lives at git://gitorious.org/intercal/intercal.git; the freeshell page also distributes CLC-INTERCAL, a variant implementation.

There is, in addition, an occasionally active USENET newsgroup devoted to the language: alt.lang.intercal. (It is a somewhat unusual newsgroup, as although large numbers of people are known to read it hardly anyone ever writes in it; occasionally someone asks if the newsgroup is dead and gets several responses claiming it isn’t. Mostly it’s full of C-INTERCAL release notices, and is thus a good way to determine the most recent version of C-INTERCAL.)

C-INTERCAL now uses a GNU Autotools-based build system, this is something like the fourth build system that has been tried for it, and hopefully it now works (we’ve given the build system several interesting twists, of course; for instance, automake dumps things like the prebuilt parser in the root of the distribution by default, which is ugly, so we moved them to the prebuilt directory.) It is possible to build with the straightforward configure/make/ make install routine, just as most other distributed software does; however, this dumps all the generated files into the root of the distribution, which violates the author’s sense of aesthetics, and so the recommended approach is to build out-of-tree; create a directory anywhere you like, and run configure from that directory, then make and install there. You can give configure arguments (see configure --help for details); probably the only one you’ll want to use is --prefix, which selects the directory to install C-INTERCAL into (--prefix=/usr and --prefix=/usr/local (the default) are both likely choices, but you may want to install into a subdirectory of your home directory to avoid the need for root priveleges). Some revious versions of C-INTERCAL required various information to be specified by the user; the build system now figures this all out for itself, so you can relax and not need to worry (in theory).

Building on DOS (via DJGPP) and Windows (via Cygwin) both work fine the same way as builds on POSIX-like systems like Linux, Mac OS X, and BSD.

I have come across lexes whose default limits for various things aren’t high enough to handle INTERCAL’s various lexing conundrums. In this case, pay attention to the error messages they give you, and alter the source file src/lexer.l accordingly. This should not happen on most modern systems, as most modern lexers allocate memory dynamically and so can handle source files of any length.

The build now uses your default compiler and compiler options; you can change either of these by specifying them as options to configure (for instance, configure CC=gcc CFLAGS=-O3 -funroll-loops). (You can also set the appropriate environment variables instead.) The default options are -g on all compilers, and also -O2 if you’re using gcc, and the default compiler is calculated automatically by configure; note in particular that if you’re using a non-gcc compiler you’ll have to request optimisation yourself by setting the CFLAGS if you want an optimising build.

Although the build system tries to find a good high-resolution timing function to use for profiling, such functions are often system-specific; you may be able to get better profiling output by tinkering with yuk.h to specify a different method of profiling.

PIC C compilers tend to differ substantially in the way they handle various language constructs. As a result, this compiler will only compile to C (not to hex or asm) when compiling a PIC-INTERCAL program. There are two header files, pick1.h and pick2.h in the /src directory; these need to be placed somewhere your compiler can find them, and pick1.h will need to be modified to contain compiler-specific data (like the names of data types and the syntax for specifying the device type, fuses, and various commands).

Code is provided to allow linking of Funge-98 programs to INTERCAL programs; however, this requires a Funge-98 interpreter, which is not present in this distribution. Therefore, in order to do this, a Funge-98 interpreter must first be downloaded and prepared for use with C-INTERCAL. At present, code is only available for linking with cfunge, a Funge-98 interpreter written in C. You can get the latest sources for that interpreter from the Internet via the bzr version-control system by running this command:

Once you have the source code to cfunge, you can compile it into a library suitable for use by C-INTERCAL by changing to the /etc directory of the C-INTERCAL distribution, and running the cftoec.sh shell script in that directory with the path to the cfunge distribution as an argument. The script will make a copy of cfunge, modify it as required, and then place the resulting library (libick_ecto_b98.a) in the /prebuilt directory of the C-INTERCAL distribution; installing (or reinstalling) C-INTERCAL after that will copy that library into the correct location in your filesystem.

For information on actually using this system once you’ve set it up, consult the Revamped Manual.

C-INTERCAL is now distributed under the GNU General Public License version 2 (or at your choice any later version), except for the C skeleton file which is explicitly not GPLed in order to avoid the (possibly mythical) "license virus" effect, and the Revamped Manual, which is licenced under the GNU Free Documentation Licence version 1.2. See the file COPYING for details on the General Public License, and the file doc/fdl-1-2.txi (which is also included as a chapter in each of the compiled versions of the documentation, in case you don’t feel like reading Texinfo) for information on the GNU Free Documentation Licence.