= 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 <email@example.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.
A compiler for the INTERCAL language. INTERCAL is the original esoteric language, a farrago of features that will test the mettle of any programmer and bend the minds of most. Includesa compiler, debugger, and sample code.