= README for C-INTERCAL =
== Discredits ==
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, Joris Huizer and others. Alex Smith took over as
maintainer from version 0.25 onwards; this release, 0.29, is a unified deforking
of C-INTERCAL with Alex Smith and Eric S. Raymond as comaintainers. For detailed
credits see NEWS.
== Files ==
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:
|========================================================================
|README | this file
|BUGS | current bug and to-do list
|NEWS | info on features and fixes new in this release
|HISTORY | Longer-form history of the code tree
|COPYING | copyright and licence information
|MANIFEST | a list of all files in the distribution
|doc/READ.ME | historical notes on the docs
|doc/ick.txi | the Revamped Manual sources, a newer manual
|doc/fdl-1-2.txi | the GNU FDL version 1.2 in Texinfo format
|doc/ick.txt | the Revamped Manual in plain text format
|doc/ick.info* | the Revamped Manual in Info format
|doc/ickstyle.css | styling rules for the Revamped Manual in HTML
|doc/tidy.cfg | HTML tidying rules for the Revamped Manual
|doc/fix83.pl | script to fixup the HTML output for 8.3 systems
|doc/fixtoc.pl | script to format the manual table of contents
|doc/intercal.mm | the old manual in groffable form
|doc/Makefile | makefile to build old and new manuals
|doc/THEORY.txt | some notes on the internals of the INTERCAL compiler
|doc/chipspec.txt | plans for an INTERCAL-based microprocessor
|doc/ick.1 | man page for ick
|doc/convickt.1 | man page for convickt
|src/abcessh.in | template interface to functions linked with programs
|src/arrgghh.c | option argument parsing for generated programs
|src/bin2c.c | creates C code representations of binary files
|src/cesspool.c | the INTERCAL runtime support code
|src/clc-cset.c | compatibility code for CLC-INTERCAL character sets
|src/convickt.c | command line character set converter
|src/cooptsh.in | template for script to help out the -F optimizer
|src/dekludge.c | INTERCAL optimizer wrapper and utility functions
|src/feh.h | interface to INTERCAL-to-C code generator
|src/feh2.c | INTERCAL-to-C code generator
|src/fiddle.[ch] | the INTERCAL operators
|src/ick-wrap.c | the driver for generated C-from-INTERCAL code
|src/ick.h | compilation types and defines
|src/ick_bool.h | unified boolean handling
|src/ick_ec.[ch] | external call support for INTERCAL
|src/ick_lose.[ch] | INTERCAL compile- and run-time error handling
|src/idiotism.oil | list of INTERCAL idioms to optimize
|src/lexer.l | the lexical analyzer specification (in LEX)
|src/numerals.c | numerals table for INTERCAL input
|src/oil.y | compiler to translate idiotism.oil into C
|src/oil.h | name mangling for OIL files
|src/parser.y | the grammar specification (in YACC)
|src/perpet.c | main routine for compiler
|src/pick1.h | template for compiler-dependent PIC C headers
|src/pick2.h | runtime support for compiled PIC-INTERCAL
|src/pickwrap.c | the driver for generated PIC C-from-INTERCAL code
|src/sizes.h | variables defining the numeric base
|src/uncommon.[ch] | code common to the compiler and debugger
|src/unravel.c | multithreading functions
|src/yuk.[ch] | INTERCAL debugger and profiler
|src/*.bin | character set definitions for clc-cset and convickt
|prebuilt/parser.[ch] | Prebuilt parser (for systems without bison)
|prebuilt/lexer.c | Prebuilt lexer (for systems without flex)
|prebuilt/oil-oil.c | Prebuilt OIL compiler (again, for bisonless systems)
|etc/intercal.el | elisp for editing INTERCAL code under GNU Emacs
|etc/intercal.vim | INTERCAL syntax higlighting information for vim
|etc/interfuzz.pl | fuzz-tester for the optimiser
|etc/cftoec.sh | script to convert cfunge to a library (see below)
|etc/IFFI* | input to that script
|etc/cfunge.patch | more input to that script
|configure | GNU Autoconf script that generates a Makefile
|configure.ac | autoconf source for configure
|Makefile.in | template Makefile for compiling C-INTERCAL
|Makefile.am | automake source for Makefile.in
|buildaux/* | helper scripts and templates used by the build
|aclocal.m4 | helper file needed to build the build system itself
|pit/* | sample INTERCAL code; see pit/CATALOG
|pit/tests/* | INTERCAL code provided specifically for testing
|pit/explib/* | source code for expansion libraries
|pit/lib/*.i | sample INTERCAL libraries
|pit/lib/syslib*.*i | source code for the system libraries
|pit/*.doc | documentation for sample INTERCAL code
|pit/*.tst | sample inputs for sample INTERCAL code
|pit/*.chk | sample outputs for sample INTERCAL code
|========================================================================
== How to Get Started ==
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.info', 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
ick foo.i
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)."
== Spreading the Blame ==
There is an INTERCAL Resource Page at http://www.catb.org/intercal, and another
at http://intercal.freeshell.org; http://c.intercal.org.uk contains a few
bare-bones details about this compiler in particular. All 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.)
== Building 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 previous 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 Windows (via Cygwin) works fine much the same way as builds on
POSIX-like systems like Linux, Mac OS X, and BSD; to build on DOS, via DJGPP,
use bash as your shell, cd to the buildaux directory, and run the script
build-dj.sh, which will set things up appropriately for a DJGPP build, then
do the build itself (into a subdirectory "build" of the main build tree);
you should use the makefile build/makefile to rebuild from then on, though,
rather than rerun the script.
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. If you don't have a lex-like lexer generator or yacc-like
parser generator at all, prebuilt versions of the parsers and lexers will be
used rather than compiling from scratch.
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.
== Notes on compiling PIC-INTERCAL ==
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).
== Notes on the C-INTERCAL / Cfunge external calls system ==
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:
bzr branch lp:cfunge
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.
== Licensing ==
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.