Mercurial > repo
diff interps/c-intercal/README @ 996:859f9b4339e6
<Gregor> tar xf egobot.tar.xz
author | HackBot |
---|---|
date | Sun, 09 Dec 2012 19:30:08 +0000 |
parents | |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/interps/c-intercal/README Sun Dec 09 19:30:08 2012 +0000 @@ -0,0 +1,261 @@ + Release Notes for C-INTERCAL + + DISCREDITS + +This package is an implementation of the language INTERCAL designed by Don +Woods and James Lyon, who have since spent more than twenty years 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. + + 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 +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/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/abcess.h -- 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/csetstub.c -- small file to allow convickt to link +src/configh.in -- config.h template generated by autoheader +src/configdj.h -- config.h substitute for DJGPP without config.sh +src/convickt.c -- command line character set converter +src/coopt.sh -- script to help out the -F optimizer (POSIX only) +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_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/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 +etc/temp -- temporary directory used by 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 for the build provided by automake +aclocal.m4 -- helper file needed to build the build system itself + +pit/* -- sample INTERCAL code; see pit/CATALOG +pit/explib/* -- source code for expansion libraries +pit/lib/syslib.*i -- source code for the system libraries + + 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.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 + + 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 + +The latest version of INTERCAL is also kept available at the Retrocomputing +Museun, http://www.catb.org/retro. + +(The above two paragraphs are somewhat out of date, but I kept them there, +including the typos, for historical purposes. Looking through the +alt.lang.intercal archives is usually the best way to find out what the latest +version of C-INTERCAL (and you'll find out how to get its rival too, for that +matter) is nowadays; they tend to pop up in various unusual places, so giving +a URL might be misleading. Note also that contact details, and even who to +contact, often end up out of date; the newsgroup is also a good way to find +out who to contact. + +As of when I wrote this, the current homepage for C-INTERCAL and CLC-INTERCAL +is http://intercal.freeshell.org.) + +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 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. + + 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 http://rage.kuonet.org/~anmaster/bzr/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 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.