diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.htm | 16 | ||||
| -rw-r--r-- | doc/cfuncs.htm | 459 | ||||
| -rw-r--r-- | doc/cygwin.htm | 66 | ||||
| -rw-r--r-- | doc/docguide.htm | 36 | ||||
| -rw-r--r-- | doc/extlvals.htm | 288 | ||||
| -rw-r--r-- | doc/faq.htm | 102 | ||||
| -rw-r--r-- | doc/faq.txt | 312 | ||||
| -rw-r--r-- | doc/files.htm | 26 | ||||
| -rw-r--r-- | doc/icon.txt | 14 | ||||
| -rw-r--r-- | doc/icont.txt | 14 | ||||
| -rw-r--r-- | doc/index.htm | 13 | ||||
| -rw-r--r-- | doc/install.htm | 12 | ||||
| -rw-r--r-- | doc/istyle.css | 1 | ||||
| -rw-r--r-- | doc/macintosh.htm | 45 | ||||
| -rw-r--r-- | doc/port.htm | 12 | ||||
| -rw-r--r-- | doc/relnotes.htm | 142 |
16 files changed, 1181 insertions, 377 deletions
diff --git a/doc/build.htm b/doc/build.htm index d494b94..1982cb6 100644 --- a/doc/build.htm +++ b/doc/build.htm @@ -1,7 +1,7 @@ <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML> <HEAD> - <TITLE>Building Version 9.4 of Icon from Source</TITLE> + <TITLE>Building Version 9.5 of Icon from Source</TITLE> <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> </HEAD> @@ -10,20 +10,20 @@ <P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> -<H1>Building Version 9.4 of Icon from Source</H1> +<H1>Building Version 9.5 of Icon from Source</H1> <P> Gregg M. Townsend <BR> <SMALL> Department of Computer Science </SMALL> <BR> <SMALL> The University of Arizona </SMALL> -<P> <SMALL> www.cs.arizona.edu/icon/v943/build.htm -<BR> Last updated November 8, 2005 </SMALL> -<!-- $Id: build.htm,v 1.26 2005/11/08 23:24:34 gmt Exp $ --> +<P> <SMALL> www.cs.arizona.edu/icon/v950/build.htm +<BR> Last updated November 8, 2009 </SMALL> +<!-- $Id: build.htm,v 1.27 2009/11/08 21:53:08 gmt Exp $ --> <H2> Introduction </H2> <P> These instructions explain how to build and install the source code of -<A HREF=relnotes.htm>Version 9.4 of Icon</A> under Unix. +<A HREF=relnotes.htm>Version 9.5 of Icon</A> under Unix. For instructions on installing a binary release, see <A HREF=install.htm>Installing Icon Binaries</A>. @@ -48,7 +48,7 @@ any special considerations given in its status report. port the code. This is usually a fairly simple matter that involves copying an existing configuration and editing it to match the target system. -See <A HREF=port.htm>Porting Icon</A>. +See <A HREF=port.htm>Porting Icon</A>.) </SMALL> <P> Most Unix systems include the X11 window system; type @@ -72,7 +72,7 @@ by e-mail to <H2> Building </H2> <P> After Configuring, type <CODE>make</CODE> to build the Icon system. -This single step now builds: +This single step builds: <UL> <LI> The Icon translator and interpreter <LI> Program library procedures diff --git a/doc/cfuncs.htm b/doc/cfuncs.htm new file mode 100644 index 0000000..4243559 --- /dev/null +++ b/doc/cfuncs.htm @@ -0,0 +1,459 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Loading C Functions in Icon</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P> <A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + + +<H1> Loading C Functions in Icon</H1> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v950/cfuncs.htm +<BR> Adapted from +<A HREF="http://www.cs.arizona.edu/icon/analyst/backiss/IA36.pdf"> +<CITE>Icon Analyst 36</CITE></A> +<BR> Last updated October 27, 2009 </SMALL> +<!-- $Id: cfuncs.htm,v 1.3 2009/10/27 17:35:53 gmt Exp $ --> + + +<P> Dynamic loading allows Icon programs to use functions coded in C +without modifying the Icon system itself. The C code is +compiled and placed in a library, then loaded +from the library when the Icon program runs. +Here is a discussion of the use and construction of such functions. + + +<H2> Program library functions </H2> + +<P> The +<A HREF="http://www.cs.arizona.edu/icon/library/ipl.htm">Icon +program library</A> +includes an assortment of loadable Unix +interfaces and special-purpose functions. +Some are there for their general utility, +some for illustration, and some to fill specialized needs. +Here is a sampling: +<BLOCKQUOTE> +<CODE>bitcount(i)</CODE> — count the bits set in an integer +<BR><CODE>chmod(s, i)</CODE> — change the permissions of a file +<BR><CODE>fpoll(f, i)</CODE> — poll a file for input, with timeout +<BR><CODE>getpid()</CODE> — return the process identification number +<BR><CODE>kill(i1, i2)</CODE> — send a signal to a process +<BR><CODE>lgconv(i)</CODE> — convert a large integer to a string +<BR><CODE>tconnect(s, i)</CODE> — connect a file to a TCP port +<BR><CODE>umask(i)</CODE> — change the process permission mask +</BLOCKQUOTE> + +<P> The full set of functions can be found in the +library's <CODE>cfuncs</CODE> directory. +Documentation and code are also +<A HREF="http://www.cs.arizona.edu/icon/library/fcfuncs.htm">available +on line</A>. +These functions are available automatically to an Icon program +that includes <CODE>link cfunc</CODE>. +The <CODE>bitcount()</CODE> function +is a good example for detailed examination. + + +<H2> Loading a function </H2> + +<P> The built-in Icon function <CODE>loadfunc(libname, funcname)</CODE> +loads the C function <CODE>funcname()</CODE> from +the library file <CODE>libname</CODE> and returns a procedure +value. If the function cannot be loaded, the program is terminated. + +<P> If <CODE>loadfunc(libname, "myfunc")</CODE> produces <CODE>p</CODE>, +then +<UL> +<LI><CODE>p(</CODE>arguments<CODE>)</CODE> calls <CODE>myfunc()</CODE> + with a list of arguments +<LI><CODE>type(p)</CODE> returns <CODE>"procedure"</CODE> +<LI><CODE>image(p)</CODE> returns <CODE>"function myfunc"</CODE> +<LI><CODE>proc("myfunc")</CODE> returns <CODE>p</CODE> +<LI><CODE>proc("myfunc", 0)</CODE> fails +</UL> + +<P> The following program loads the function +<CODE>bitcount()</CODE> and assigns it to a global variable of the +same name. Assigning it to a global variable makes +it available to other procedures, although that's not +needed here. The <CODE>bitcount()</CODE> function returns the +number of bits that are set in the binary representation of an integer. +<BLOCKQUOTE><PRE> +$define Library "/icon/bin/libcfunc.so" +global bitcount + +procedure main() + local i + bitcount := loadfunc(Library, "bitcount") + every i := 250 to 260 do + write(i, " ", bitcount(i)) +end +</PRE></BLOCKQUOTE> + +<P> When this program is run, it lists the integers +from 250 to 260 along with their bit counts: +<BLOCKQUOTE><PRE> +250 6 +251 7 +252 6 +253 7 +254 7 +255 8 +256 1 +257 2 +258 2 +259 3 +260 2 +</PRE></BLOCKQUOTE> + + +<H2> Loading from a path </H2> + +<P> Embedding a file name such as <CODE>/icon/bin/libcfunc.so</CODE> +in the program is undesirable. An alternative is for the +program to find the library file +using information from the program environment. + +<P> The Icon library procedure +<CODE>pathload(libname, funcname)</CODE> +searches the set of directories given by +the <CODE>FPATH</CODE> environment variable to find <CODE>libname</CODE> +and load <CODE>funcname</CODE>. +As is usual in Icon path searching, the current +directory is searched first. If the +function cannot be loaded, the program is terminated. + +<P> The <CODE>pathload()</CODE> procedure is included +by linking <CODE>pathfind</CODE> from the Icon program library. Using +<CODE>pathload()</CODE>, the example program becomes: +<BLOCKQUOTE><PRE> +$define Library "libcfunc.so" +link pathfind +global bitcount + +procedure main() + local i + bitcount := pathload(Library, "bitcount") + every i := 250 to 260 do + write(i, " ", bitcount(i)) +end +</PRE></BLOCKQUOTE> + +<P> The default <CODE>FPATH</CODE> includes the current directory +and the installed Icon program library directory. +To find a library located elsewhere, +<CODE>FPATH</CODE> must be set explicitly before the program is run. + + +<H2> Implicit function loading </H2> + +<P> It is possible to encapsulate the loading process so that the body of +an Icon program is unaware +that it is calling a C function. Consider this example: +<BLOCKQUOTE><PRE> +$define Library "libcfunc.so" +link pathfind + +procedure main() + local i + every i := 250 to 260 do + write(i, " ", bitcount(i)) +end + +procedure bitcount(n) + bitcount := pathload(Library, "bitcount") + return bitcount(n) +end +</PRE></BLOCKQUOTE> + +<P> First of all, notice that there is no longer a +global declaration for <CODE>bitcount</CODE>, and that the main +procedure no longer calls <CODE>pathload()</CODE>. As far as the +main procedure is concerned, <CODE>bitcount()</CODE> is just +another procedure to call, with no special requirements. This is a nice +simplification. + +<P> The new <CODE>bitcount()</CODE> procedure is a bit tricky, +though. To understand it, you must know that an +Icon procedure declaration creates a global variable with an initial +value of that procedure. A +global variable is subject to assignment. + +<P> When <CODE>main()</CODE> calls <CODE>bitcount()</CODE> for the first time, +the <CODE>bitcount()</CODE> procedure loads the <CODE>bitcount()</CODE> +C function from the library. The result is assigned to the +global variable <CODE>bitcount</CODE>, replacing the current procedure value. +Consequently, all subsequent calls +to <CODE>bitcount()</CODE> use the loaded function. + +<P> The first call to <CODE>bitcount()</CODE> remains incomplete +after loading the function; the bits of <CODE>n</CODE> still must be +counted. So, following loading, the procedure calls +<CODE>bitcount(n)</CODE>. Although this looks like a recursive +call, it isn't — the call uses the current value of the +global variable <CODE>bitcount</CODE>, and so it calls the loaded C +function. The bits of <CODE>n</CODE> are counted and returned, +completing the first call. + +<P> After the first time, calls to <CODE>bitcount()</CODE> +go directly to the loaded code. The Icon procedure +<CODE>bitcount()</CODE> is no longer accessible. + + +<H2> Implicit library loading </H2> + +<P> The Icon program library provides an implicit loading procedure for +each of the C functions +in the library. Small procedures like the <CODE>bitcount()</CODE> +procedure shown above are included by linking +<CODE>cfunc</CODE>. Using the library interface procedure, our +example now can be simplified to this: +<BLOCKQUOTE><PRE> +link cfunc + +procedure main() + local i + every i := 250 to 260 do + write(i, " ", bitcount(i)) +end +</PRE></BLOCKQUOTE> + +<P> The <CODE>link cfunc</CODE> declaration is the only hint that +<CODE>bitcount()</CODE> is written in C. + + +<H2> Making connections </H2> + +<P> The bit counting example doesn't really illustrate the full potential +of using C functions in an +Icon program. Bit counting, after all, can be done in +Icon. Here's something that can't. + +<P> The library function +<CODE>tconnect(host, port)</CODE> establishes a TCP connection +to a specified port +number on an Internet host. TCP is a communication protocol used by +telnet programs, news servers, web servers, and many other network +services. + +<P> The following program makes a connection +to the Icon web server and writes the contents of +the Icon home page — in its original HTML markup +language, of course. +<BLOCKQUOTE><PRE> +link cfunc + +procedure main() + local f + f := tconnect("www.cs.arizona.edu", 80) + writes(f, "GET /icon/ HTTP/1.0\n\n") + flush(f) + seek(f, 1) + while write(read(f)) +end +</PRE></BLOCKQUOTE> + +<P> The <CODE>tconnect()</CODE> call establishes the connection +and returns a file that is open for both input and +output. The internet host <CODE>www.cs.arizona.edu</CODE> is +the web server for the University of Arizona's +Department of Computer Science. +(Port 80 is the standard web server port number.) +The program then transmits a request for the +<CODE>/icon/</CODE> web page. The details of the request string +are specified by the +<A HREF="http://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext +Transfer Protocol</A>, not discussed here. + +<P> The <CODE>flush()</CODE> call ensures that all the data is +actually sent, and then the <CODE>seek()</CODE> call resets the file +in preparation for a switch from output to input. In +this situation <CODE>seek()</CODE> does not actually reposition +the file, but it's required when switching modes. + +<P> Finally, lines are read and echoed until an +end-of-file is received. + + +<H2> Writing loadable C functions </H2> + +<P> Now consider the construction of library functions. +Because the Icon system expects C functions +to implement a certain interface, dynamic loading +usually requires specially written C functions. In +general, it is not possible to use an existing C +function without writing an intermediate "glue" +function. + +<P> C functions must deal with the data types +used by the Icon run-time system, notably the +"descriptors" that represent all Icon values. While +an understanding of +<A HREF="http://www.cs.arizona.edu/icon/ibsale.htm">the +Icon run-time system</A> is helpful, +it is possible to create useful functions by +modeling them after existing library functions. +Integer and string values are most easily handled. + +<P> A loadable C function has the prototype +<BLOCKQUOTE><CODE>int funcname(int argc, descriptor *argv)</CODE></BLOCKQUOTE> +where <CODE>argc</CODE> is the number of arguments and <CODE>argv</CODE> is +an array of argument descriptors. +The first element, <CODE>argv[0]</CODE>, is used to return an Icon value, and +is initialized to a descriptor for the null value. This +element is not included in the count <CODE>argc</CODE>. The +actual arguments begin with <CODE>argv[1]</CODE>. + +<P> If the C function returns zero, the call from +Icon succeeds. A negative value indicates failure. If +a positive value is returned, it is interpreted as an +error number and a fatal error with that number is +signalled. In this case, if <CODE>argv[0]</CODE> is non-null, it is +reported as the "offending value". There is no way +for a C function to suspend, and no way to indicate +a null value as an offending value in the case of an +error. + + +<H2> Interface macros </H2> + +<P> The C file <CODE>icall.h</CODE> contains a set of macros for +use in writing loadable functions. Documentation +is included as comments. This file can be found in the +<CODE>cfuncs</CODE> directory in the source code of the Icon +program library. Alternatively, it can be loaded +<A HREF="http://www.cs.arizona.edu/icon/library/src/cfuncs/icall.h">from +the web</A>. Macros are provided for: +<UL> +<LI>inspecting the type of an Icon value +<LI>validating the type of an argument +<LI>converting an Icon value into a C value +<LI>returning a C value in Icon form +<LI>failing or signaling an error +</UL> + +<P> Most macros deal with integers or strings. +Some support also is provided for handling real +and file values. +The macros expect the C arguments to be declared with the +names of <CODE>argc</CODE> and <CODE>argv</CODE>. + + +<H2> Counting bits, again </H2> + +<P> For a concrete example of a C function, consider the source code +of the <CODE>bitcount()</CODE> function used earlier: +<BLOCKQUOTE><PRE> +#include "icall.h" + +int bitcount(int argc, descriptor *argv) +{ + unsigned long v; + int n; + ArgInteger(1); + v = IntegerVal(argv[1]); + n = 0; + while (v != 0) { + n += v & 1; + v >>= 1; + } + RetInteger(n); +} +</PRE></BLOCKQUOTE> + +<P> Like all loadable functions, <CODE>bitcount()</CODE> is an +integer function with two parameters, <CODE>argc</CODE> and +<CODE>argv</CODE>. + +<P> The <CODE>ArgInteger</CODE> macro call verifies that argument 1 is a simple +integer. (Large integers are +typically rejected by C functions because of the +extra work involved.) If argument 1 is missing or +has the wrong type, <CODE>ArgInteger</CODE> makes the function +return error code 101 (integer expected or out of +range). + +<P> The <CODE>IntegerVal</CODE> macro call extracts the value +of the first argument. + +<P> In each pass through the <CODE>while</CODE> loop, the low order bit of +<CODE>v</CODE> is +extracted (<CODE>v & 1</CODE>), added to <CODE>n</CODE>, and +shifted off (<CODE>v >>= 1</CODE>). When no more nonzero bits +are left, the loop exits. Note that <CODE>v</CODE> is declared +unsigned to ensure that only zero bits are inserted +by the shift operation. + +<P> The <CODE>RetInteger</CODE> macro call returns the value +of <CODE>n</CODE> as an Icon integer. + + +<H2> External data values </H2> + +<P> Loadable functions can create and return data structures +that are treated as an opaque <CODE>external</CODE> type by Icon. +The use of external types is described <A HREF="extlvals.htm">separately</A>. + + +<H2> Preparing a library </H2> + +<P> To be used in an Icon program, a C function +must be built and installed in a library. Compilation comes first, +usually involving a command such as +<BLOCKQUOTE><CODE>cc –c bitcount.c</CODE></BLOCKQUOTE> +to produce an object file <CODE>bitcount.o</CODE>. +The <CODE>–c</CODE> option causes a relocatable object file +to be produced instead of a stand-alone executable program. +If <CODE>icall.h</CODE> is not in the current directory, +an additional option may be needed to specify its location. +Other options, such as optimization options, also could be specified. + +<P> A C function can be loaded only from a "shared library". +Even if there is just one function, it must be placed in a library. +Library names conventionally end with a <CODE>.so</CODE> suffix. + +<P> It seems that every system has a different +way to create libraries, usually involving special +flags to <CODE>cc</CODE> or <CODE>ld</CODE>. +The shell script <CODE>mklib.sh</CODE> +embodies our understanding of shared library creation. +It takes one argument naming the library to be created and one or more +additional arguments listing object file names. +For example, the command +<BLOCKQUOTE><CODE>mklib.sh mylib.so bitcount.o</CODE></BLOCKQUOTE> +creates a file <CODE>mylib.so</CODE> containing the functions read +from <CODE>bitcount.o</CODE>. +Like <CODE>icall.h</CODE>, <CODE>mklib.sh</CODE> is available in +the program library source code or +<A HREF="http://www.cs.arizona.edu/icon/library/src/cfuncs/mklib.sh">from +the web</A>. + + +<H2> Summary </H2> + +<P> +<UL> +<LI> Icon programs can load and call functions written in C. +<LI> The C functions must be tailored to Icon's requirements. +<LI> Each function must be loaded before it can be called. +<LI> A simple Icon procedure can be used to hide the loading details. +<LI> <CODE>pathload()</CODE> searches <CODE>FPATH</CODE> + to find a function library. +<LI> C functions can embed data in opaque <CODE>external</CODE> values. +<LI> Some useful functions are provided in the Icon program library. +</UL> + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/cygwin.htm b/doc/cygwin.htm index 88e0a54..c206af1 100644 --- a/doc/cygwin.htm +++ b/doc/cygwin.htm @@ -16,10 +16,10 @@ ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> <BR> <SMALL> Department of Computer Science </SMALL> <BR> <SMALL> The University of Arizona </SMALL> -<P> <SMALL> www.cs.arizona.edu/icon/v943/cygwin.htm +<P> <SMALL> www.cs.arizona.edu/icon/v950/cygwin.htm <BR> -Last updated November 8, 2005 </SMALL> -<!-- $Id: cygwin.htm,v 1.5 2005/11/08 23:24:34 gmt Exp $ --> +Last updated November 8, 2009</SMALL> +<!-- $Id: cygwin.htm,v 1.11 2009/11/08 21:53:08 gmt Exp $ --> <H2> Introduction </H2> @@ -38,12 +38,20 @@ Successful use of Cygwin requires familiarity with both Windows and Unix. <P> This document describes some of the peculiarities of the Cygwin -port of Version 9.4 of Icon. +port of Icon. These differences are not necessarily identified in other documentation. <H2> Building Icon </H2> +<P> Icon is built in a Cygwin shell window using the same process as on +on other platforms. +See the <A HREF=build.htm>installation documentation</A> for instructions. +There are two possible choices for configuration name: +The <CODE>cygwin</CODE> configuration uses the native Windows graphics system; +the <CODE>xcygwin</CODE> configuration uses the X window system and thus +is closer to other Unix implementations of Icon. + <P> The Cygwin package is available from <A HREF="http://www.cygwin.com/">www.cygwin.com</A>. A custom installation of the Cygwin system is required; @@ -52,14 +60,8 @@ insufficient for building software. Icon requires a C compiler and the usual tools and utilities available on a standard POSIX development system; these are found in the <CODE>gcc-core</CODE> and <CODE>make</CODE> packages. -The <CODE>xorg</CODE> family of packages is also needed -to build Icon with graphics enabled. - -<P> Icon is built in a Cygwin shell window. -The process is the same as on other platforms -and uses the configuration named <CODE>cygwin</CODE>. -See the <A HREF=build.htm>installation documentation</A> -for instructions on building Icon. +The <CODE>xinit</CODE> and <CODE>libXt-devel</CODE> packages are also needed +to build the <CODE>xcygwin</CODE> configuration with graphics enabled. <H2> Running Icon programs </H2> @@ -74,29 +76,34 @@ and <A HREF=icont.txt><CODE>icont</CODE></A> describe the command options in a traditionally cryptic manner. -<H2> Interpreter path </H2> +<H2> Interpreter path and environment</H2> <P> Icon programs require an interpreter for execution. On Windows, the path of the interpreter is not embedded in an executable program. The program must be able to find -<CODE>iconx.exe</CODE> in one of these locations: -<UL> - <LI> in the file named by the <CODE>ICONX</CODE> environment variable - <LI> in the same directory as the executable program - <LI> in the search path -</UL> +<CODE>iconx.exe</CODE> in the search path. + +<P> The Cygwin X server must be running, with a correct <CODE>DISPLAY</CODE> +variable in the environment, to execute graphics programs built by the +<CODE>xcygwin</CODE> configuration of Icon. + +<P> When the environment is correctly set, +with <CODE>cygwin1.dll</CODE> in the Windows path, +a compiled Icon program may be run from the Cygwin shell or by +double-clicking its graphical icon. <H2> Extra built-in functions </H2> <P> For compatibility with an earlier port of Icon to Windows, -this implementation includes some extra built-in functions. -The functions are described in section 6.2 of +the <CODE>cygwin</CODE> configuration includes some extra built-in functions. +These are described in section 6.2 of <A HREF="http://www.cs.arizona.edu/icon/docs/ipd271.htm">IPD271</A>, which documents that earlier port. <P> These unsupported functions are not part of Icon on other platforms, +nor of the <CODE>xcygwin</CODE> configuration, so their use renders a program non-portable. @@ -104,25 +111,20 @@ so their use renders a program non-portable. <P> The symbols <CODE>_MS_WINDOWS</CODE> and <CODE>_CYGWIN</CODE> are defined by the Icon preprocessor. +The symbol <CODE>_UNIX</CODE> is not defined. The symbol <CODE>_GRAPHICS</CODE> is defined if Icon is built with -graphics enabled. -The symbols <CODE>_UNIX</CODE> and <CODE>_X_WINDOW_SYSTEM</CODE> -are not defined. +graphics enabled; +the symbol <CODE>_X_WINDOW_SYSTEM</CODE> is also defined +in the <CODE>xcygwin</CODE> configuration. The corresponding strings are produced or omitted, as appropriate, by the <CODE>&features</CODE> keyword. -<H2> No dynamic loading </H2> - -The dynamic loading interface — <CODE>loadfunc()</CODE> — -is not implemented. - - <H2> Known bugs </H2> <UL> - <LI>Some Unix dependencies cause tests <CODE>io</CODE>, <CODE>tpp</CODE>, - and <CODE>opts</CODE> to fail. + <LI>Some Unix dependencies cause the <CODE>tpp</CODE> + and <CODE>opts</CODE> tests to fail. <LI> Resizing a window sends a large number of events to the program. </UL> diff --git a/doc/docguide.htm b/doc/docguide.htm index 9bb4121..6601f1b 100644 --- a/doc/docguide.htm +++ b/doc/docguide.htm @@ -16,9 +16,9 @@ ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> <BR> <SMALL> Department of Computer Science </SMALL> <BR> <SMALL> The University of Arizona </SMALL> -<P> <SMALL> www.cs.arizona.edu/icon/v943/docguide.htm -<BR> Last updated November 9, 2005 </SMALL> -<!-- $Id: docguide.htm,v 1.28 2005/11/09 18:03:59 gmt Exp $ --> +<P> <SMALL> www.cs.arizona.edu/icon/v950/docguide.htm +<BR> Last updated November 16, 2009</SMALL> +<!-- $Id: docguide.htm,v 1.33 2009/11/16 22:11:13 gmt Exp $ --> <H2> Introduction </H2> @@ -26,14 +26,18 @@ ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> <P> Icon is distributed with a small set of documentation pages: <UL> <LI> This documentation guide +<LI> The <A href="icon.txt"><CODE>icon</CODE></A> + and <A href="icont.txt"><CODE>icont</CODE></A> commands <LI> <A HREF=relnotes.htm> Release notes</A> +<LI> <A HREF=macintosh.htm> Icon on Macintosh</A> +<LI> <A HREF=cygwin.htm> Icon on Cygwin</A> +<LI> <A HREF=faq.htm> Frequently asked questions</A> <LI> <A HREF=install.htm> Installation instructions</A> (for binary releases) <LI> <A HREF=build.htm> Build instructions</A> (for source releases) -<LI> <A HREF=port.htm> Porting instructions</A> <LI> <A HREF=files.htm> File organization</A> -<LI> <A HREF=macintosh.htm> Icon on Macintosh</A> -<LI> <A HREF=cygwin.htm> Icon on Cygwin</A> -<LI> <A HREF=faq.htm> Frequently asked questions about Icon</A> +<LI> <A HREF=port.htm> Porting instructions</A> +<LI> <A HREF=cfuncs.htm> Loading C functions dynamically</A> +<LI> <A HREF=extlvals.htm> External values</A> </UL> <P> This guide provides an overview of additional available information. @@ -124,6 +128,7 @@ of the Icon books: <LI> Path searching improvements <LI> Reading directory contents <LI> Reading foreign text files + <LI> <A HREF="extlvals.htm">External values</A> </UL> These features are more fully described in the <A HREF=relnotes.htm>release notes</A>. @@ -168,15 +173,6 @@ http://www.cs.arizona.edu/icon/docs/ipd239.htm</A> <A HREF="http://www.cs.arizona.edu/icon/ftp/doc/ipd261.pdf"> www.cs.arizona.edu/icon/ftp/doc/ipd261.pdf</A> (PDF). -<P> The construction of loadable C functions is described in -the <CITE>Dynamic Loading</CITE> section of IPD240, -<A HREF="http://www.cs.arizona.edu/icon/docs/ipd240.htm"> -www.cs.arizona.edu/icon/docs/ipd240.htm</A>. -Also see the examples in the -<A HREF="http://www.cs.arizona.edu/icon/library/ccfuncs.htm"> -<CODE>cfuncs</CODE></A> section of the library, which use -a simpler set of interface macros. - <H2> Technical Reports </H2> @@ -186,11 +182,11 @@ The index is found at <A HREF="http://www.cs.arizona.edu/icon/docs/docs.htm"> www.cs.arizona.edu/icon/docs/docs.htm</A>. -<P> Many of these reports are historical and describe past research -experiments. -Those cited above are among the most current, +<P> Most of these reports are historical and +many describe past research experiments. +The reports cited above are among the most current, although they may not be completely correct with respect -to Version 9.4. +to Version 9.5. <H2> Discussion Group </H2> diff --git a/doc/extlvals.htm b/doc/extlvals.htm new file mode 100644 index 0000000..2229067 --- /dev/null +++ b/doc/extlvals.htm @@ -0,0 +1,288 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Icon External Values</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1> Icon External Values </H1> + +<P> Carl Sturtivant +<BR> <SMALL> Computer Science & Engineering Department </SMALL> +<BR> <SMALL> University of Minnesota </SMALL> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v950/extlvals.htm +<BR> +Last updated March 25, 2010</SMALL> +<!-- $Id: extlvals.htm,v 1.18 2010/03/25 23:33:10 gmt Exp $ --> + + +<H2> Introduction </H2> + + +<P> External values provide a way for +<A HREF="cfuncs.htm">dynamically loaded C functions</A> +to create and return opaque data structures to an Icon program. +This allows state to be maintained across multiple calls of +loaded functions. + +<P> The creation of an external value in C defines +not just the data itself but also some related attributes. +These control the sorting behavior, image, and other such aspects. +Icon provides defaults and also adds a serial number +similar to those of lists, sets, and tables. + +<P> The specification of attributes effectively creates a number +of distinct types. +Each loadable library can define the types it needs for its own purposes. +From an object-oriented perspective, these can be seen as subtypes +of a common <CODE>external</CODE> type. + + +<H2> External Values in an Icon Program </H2> + +<P> External values are opaque to Icon. They are <EM>created</EM> only by +dynamically +loaded C functions, any of which in turn may have access to their internals. In +this way a library of Icon functions to work with a specific kind of external +value is possible. However, such values can be seen and manipulated (assigned, +passed to procedures or functions, sorted, copied, etc.) in Icon. The +behavior of an external value in Icon may be modified to some extent by the +implementation of the dynamically loaded function that is used to create it, as +described below. + +<P> In what follows let <CODE>E</CODE>, <CODE>E1</CODE>, and <CODE>E2</CODE> +be external values +produced by some loaded function or functions. Icon prescribes the following +default behavior of such values, which is exhibited if the functions that +created them did not override such at the time of creation. Otherwise behavior +in the following contexts is determined by the external values' creators. + +<P> External values always sort after values of all other types. +Within themselves external +values are first sorted by type name (which is a set by the creator, +is returned by the Icon function <CODE>type</CODE>, +and specifies a subtype of the external type). +The default sort within such a subtype is by serial number. Only sorting +within a subtype (i.e., externals with a specific type name) can be overridden +by the creator. See the next section for a description of the relevant C +internals. The default behavior follows. + +<BLOCKQUOTE><DL> +<DT><CODE>type(E)</CODE> + <DD>returns the string <CODE>"external"</CODE> +<DT><CODE>image(E)</CODE> + <DD>returns a string indicating the type, serial number, + and the number of data words, + <I>e.g.</I> <CODE>"external_12(3)"</CODE> +<DT><CODE>copy(E)</CODE> + <DD>returns <CODE>E</CODE> itself without copying +<DT><CODE>sort()</CODE> + <DD>external values sort first by type name and then by serial number +<DT><CODE>E1 === E2</CODE> + <DD>produces <CODE>E1</CODE> when <CODE>E1</CODE> and <CODE>E2</CODE> + are the same external object; otherwise fails +<DT><CODE>E1 ~=== E2</CODE> + <DD>produces <CODE>E2</CODE> when <CODE>E1</CODE> and <CODE>E2</CODE> + are distinct; otherwise fails +</DL></BLOCKQUOTE> + + +<H2> Creating and Using External Values in C </H2> + +<P>These next sections describe the C interface for a reader who is +familiar with the use of loadable functions. + +<P> An Icon external value is implemented by a descriptor that points +to an external block containing several components. +The data area and the function list are the most important of these. + +<P> An integer word count indicates the size of the data area. +This is specified when the external block is created. +Often external data is a single pointer to other data (a handle) +and so only one word is required. + +<P> The function list allows the programmer to override, +for all values of the same external type, +the default behaviors listed in the previous section. +The list is a callback table pointing to programmer-defined C functions +as described in more detail below. +The function list also acts as a unique type identifier, because external +values with different function lists behave as values of distinct type. + +<P> A dynamically loaded C function allocates an external value by including +<CODE>ipl/cfuncs/icall.h</CODE> and calling <CODE>alcexternal</CODE>: + +<BLOCKQUOTE> +<DL> +<DT> +<CODE>externalblock *alcexternal</CODE>(long size, funclist *funcs, void *data) +</DT><DD> + allocates and returns a pointer to an external block. + <BR><VAR>size</VAR> specifies the number of bytes + in the entire external block (and by implication + the size of the data block inside it). + <BR><VAR>funcs</VAR>, if not null, specifies a list of functions to + override the default behavior. See the next section. + <BR><VAR>data</VAR>, if not null, specifies the location of data + that is copied in to initialize the data block (until it is full). +</DD></DL> +</BLOCKQUOTE> + +<P> +A typical call might be +<BLOCKQUOTE> + blk = alcexternal(sizeof(externalblock) + sizeof(mydata), funcs, &mydata); +</BLOCKQUOTE> +The result is returned to Icon by the macro call +<CODE>RetExternal(</CODE>blk<CODE>)</CODE>. +The block may eventually be freed by garbage collection if it +is not saved or if it later becomes inaccessible to the Icon program. + +<P> A loadable function that accepts an external value as an argument can call +<BLOCKQUOTE> + ArgExternal(i,f); +</BLOCKQUOTE> +to validate argv[i] as an external value of the type associated +with function list f, and can then call +<BLOCKQUOTE> + blk = ExternalBlock(i); +</BLOCKQUOTE> +to get the address of the associated external block; +the associated data is at blk–>data. + +<P>A more complete example is found in the file +<CODE>ipl/cfuncs/external.c</CODE>. + + +<H2> The Function List Passed to alcexternal </H2> + +<P> The function list associated with an external value is a struct +containing pointers to C functions. +It is reminiscent of a "dispatch table" or "class pointer" +for dynamic method calls in an implementation of an object oriented programming +language. Indeed an Icon external value is very much like a traditional object +with its own data and methods. Typically such a function list would be static +and shared among many Icon external values of the same kind ("class" or "type"). + +<P> Every external value has a function list; a default list is supplied +if NULL is passed to alcexternal. A null entry within a function list +produces the default behavior for the associated action. + +<P> Functions in the list use the same interface as loadable C functions. +Incoming arguments are passed beginning at argv[1]. +A result is produced by storing it in argv[0] +and returning 0 as the outcome of the function. +When extlcmp is called, argc has a value of 2; +for the other functions, argc is 1. + +<P> The possible custom functions are as follows: + +<BLOCKQUOTE> +<DL> + +<DT> +<CODE>int extlcmp</CODE>(int argc, descriptor *argv) +</DT><DD> +returns an Icon integer +for use in sorting two external values that both have this function list +and are therefore considered to be of the same external subtype. +The function result should be negative if the first external value is +deemed less than the second, zero if they are deemed equal, and positive +if the first is deemed greater than the second. +This overrides the default behavior of the <CODE>sort</CODE> function +which compares serial numbers. +</DD> + +<DT> +<CODE>int extlcopy</CODE>(int argc, descriptor *argv) +</DT><DD> +returns an external value defined as a copy of its argument. +This overrides the default behavior of the <CODE>copy</CODE> function, +which is to return another reference to the external value without copying. +</DD> + +<DT> +<CODE>int extlname</CODE>(int argc, descriptor *argv) +</DT><DD> +returns an Icon string naming the type of the external value. +This overrides the default behavior of the <CODE>type</CODE> function, and thus +also affects the ordering relative to other external values when sorting. +</DD> + +<DT> +<CODE>int extlimage</CODE>(int argc, descriptor *argv) +</DT><DD> +returns an Icon string to serve as the image of the external value. +This overrides the default behavior of the <CODE>image</CODE> function. +</DD> + +</DL> +</BLOCKQUOTE> + + +<H2> Implementation Details </H2> + +<SMALL>This section supplements the Icon +<A HREF="http://www.cs.arizona.edu/icon/ibsale.htm"> +implementation book</A>.</SMALL> + +<P> A descriptor for an external value has a vword containing the bit pattern +D_External which contains the value T_External indicating the external type, +along with the bit F_Nqual indicating that the value is not a string and the +bit F_Ptr indicating to the garbage collector that the dword is a pointer that +needs tending. The dword contains a pointer to an external block. This block is +implemented as a C struct with a pointer to a function block C struct as +follows. The structs below, along with types word and descriptor, +are defined in ipl/cfuncs/icall.h. + +<PRE> +typedef struct funclist { /* list of user defined callbacks */ + int (*extlcmp) (int argc, descriptor *argv); /* compare */ + int (*extlcopy) (int argc, descriptor *argv); /* copy */ + int (*extlname) (int argc, descriptor *argv); /* type name */ + int (*extlimage) (int argc, descriptor *argv); /* image */ +} funclist; + +typedef struct externalblock { + word title; /* the block header, including type */ + word size; /* the number of bytes in the block */ + word id; /* the serial number */ + funclist *funcs; /* pointer to the callback list */ + word data[]; /* arbitrary custom data */ +} externalblock; +</PRE> + +<P> A call of alcexternal initializes all fields of an external block. +Data is copied without interpretation, and the function +list pointer is stored. The header is assigned an appropriate constant for the +garbage collector, and the size is set. alcexternal maintains a static +count of the number of external blocks allocated, and this is incremented and +assigned to id. + +<P> The following error code numbers are assigned for use with external values: +<BLOCKQUOTE><TABLE> +<TR><TH>errno<TH>errtext<TH>meaning +<TR><TD><CODE>131</CODE><TD><CODE>external expected</CODE> + <TD>not an external value +<TR><TD><CODE>132</CODE><TD><CODE>incorrect external type</CODE> + <TD>external of wrong flavor +<TR><TD><CODE>133</CODE><TD><CODE>invalid external value</CODE> + <TD>right flavor in wrong context +<TR><TD><CODE>134</CODE><TD><CODE>malformed external value</CODE> + <TD>data is bogus, not just inappropriate +</TABLE></BLOCKQUOTE> + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/faq.htm b/doc/faq.htm index 50175fc..ad3d10d 100644 --- a/doc/faq.htm +++ b/doc/faq.htm @@ -11,8 +11,8 @@ <H1>Frequently Asked Questions about the Icon programming language</H1> <A HREF="http://www.cs.arizona.edu/icon/faq.htm"> www.cs.arizona.edu/icon/faq.htm</A> -<BR>Last updated November 14, 2005<BR> -<!-- $Id: faq.htm,v 1.45 2005/11/14 16:24:44 gmt Exp $ --> +<BR>Last updated April 12, 2010<BR> +<!-- $Id: faq.htm,v 1.57 2010/04/12 20:39:24 gmt Exp $ --> <P><STRONG>Learning about Icon</STRONG><BR> <A HREF="#whatsicon">A1. What is Icon?</A><BR> @@ -124,12 +124,15 @@ What are Icon's distinguishing characteristics?</H3> <H3><A NAME="library">A4.</A> What is the Icon program library?</H3> <P> The library is a collection of programs and procedures written in Icon. -User contributions are welcome and form a significant portion of the library. +User contributions form a significant portion of the library. <P> Library procedures effectively augment the built-in functions available to an Icon program. A wide variety of procedures currently exists, and most graphically-based programs are built around library procedures. +The <A HREF="http://www.cs.arizona.edu/icon/library/src/procs/core.icn">core</A> +and <A HREF="http://www.cs.arizona.edu/icon/library/src/gprocs/graphics.icn"> +graphics core</A> modules are the most carefully vetted. <P> The programs in the library range from simple demonstrations to handy tools to complex graphical applications. @@ -161,6 +164,13 @@ Here are some good places to start. <A HREF="http://www.nmt.edu/tcc/help/lang/icon/"> www.nmt.edu/tcc/help/lang/icon</A> </UL> +<P> +For the graphics facilities: +<UL> +<LI> The Icon Project Overview: + <A href="http://www.cs.arizona.edu/icon/ftp/doc/ipd281.pdf"> + www.cs.arizona.edu/icon/ftp/doc/ipd281.pdf</A> +</UL> <H3><A NAME="examples">A6.</A> Where are some simple examples?</H3> <P> @@ -203,7 +213,7 @@ describe subsequent changes. Printed copies of the <CITE>Language</CITE> and <CITE>Graphics</CITE> books are available from Jeffery Systems -(<A HREF="http://www.zianet.com/jeffery/books/">www.zianet.com/jeffery/books</A>). +(<A HREF="http://unicon.org/books/">http://unicon.org/books/</A>). All three books can be downloaded at no charge from the Icon books page, <A HREF="http://www.cs.arizona.edu/icon/books.htm"> www.cs.arizona.edu/icon/books.htm</A>. @@ -219,39 +229,39 @@ www.cs.arizona.edu/icon/library/ipl.htm</A>. <P> There is a large amount of additional information at the Icon web site, -<A HREF="http://www.cs.arizona.edu/icon/">www.cs.arizona.edu/icon</A>. +<A HREF="http://www.cs.arizona.edu/icon/">www.cs.arizona.edu/icon</A>, +including complete sets of back issues of the +<A HREF="http://www.cs.arizona.edu/icon/inl/inl.htm"> +<CITE>Icon Newsletter</CITE></A> and +<A HREF="http://www.cs.arizona.edu/icon/analyst/ia.htm"> +<CITE>Icon Analyst</CITE></A>. <P><HR><H2>Implementations</H2> <H3><A NAME="platforms">B1.</A> What platforms support Icon?</H3> <P> -Current implementations with graphics support -are available for Unix (including Linux) and Windows. -The Unix implementation also runs on Darwin, -the Macintosh development environment, or the +The current implementation of Icon is a Unix implementation. +This includes Linux, BSD, Solaris, Macintosh, and the <A HREF="http://www.cygwin.com/">Cygwin</A> environment under Windows. -Older versions of Icon are available for some other systems. +Version 9.5 of Icon has been tested on all these platforms. +<P> +Older versions are available for Windows and some other systems. An alternative Java-based implementation for Unix, <A HREF="http://www.cs.arizona.edu/icon/jcon/">Jcon</A>, is also available. +<P> +None of these environments includes a window-based development environment. +While Icon programs can open windows and use graphics, +programming is done using Unix editors and other tools from a command shell. <H3><A NAME="getstarted">B2.</A> How do I get started with Icon?</H3> <P> -Version 9.4.3 of Icon for <STRONG>Unix</STRONG> can be downloaded from -<A HREF="http://www.cs.arizona.edu/icon/v943/"> -www.cs.arizona.edu/icon/v943</A>. +The current version of Icon for Unix can be downloaded from +<A HREF="http://www.cs.arizona.edu/icon/current/"> +www.cs.arizona.edu/icon/current</A>. Source and binary packages are available, each with the complete Icon program library. <P> -Version 9.3 of Icon for <STRONG>Windows</STRONG> is compatible -at the source level with version 9.4.3. -It can be downloaded from -<A HREF="http://www.cs.arizona.edu/icon/v93w.htm"> -www.cs.arizona.edu/icon/v93w.htm</A>. -The Version 9.4.3 library can be obtained separately from -<A HREF="http://www.cs.arizona.edu/icon/v943/"> -www.cs.arizona.edu/icon/v943</A>. -<P> For older implementations, start at <A HREF="http://www.cs.arizona.edu/icon/implver.htm"> www.cs.arizona.edu/icon/implver.htm</A>. @@ -268,14 +278,11 @@ but a Unicode version of Jcon might be possible. <H3><A NAME="iconc">B4.</A> What happened to the compiler?</H3> <P> -For a while, Unix distributions included both an interpreter and a compiler; -but the interpreter is is usually fast enough even for production work, and -most people found that using the compiler wasn't worth the extra compilation -time or the hassles involved. -We no longer advertise the compiler or produce binaries for it. -It is still part of the source code distribution, -and we have not deliberately broken it, -but we no longer support it and we cannot offer help if problems arise. +For a while, Unix distributions included both an interpreter and a compiler. +The compiler was an interesting research project but it has not been +maintained and is no longer supported. +The interpreter is much easier to use and is generally quite fast enough, +even for production applications. <P><HR><H2>Administration</H2> @@ -290,11 +297,9 @@ Department of Computer Science at the University of Arizona. <H3><A NAME="updates">C2.</A> How often is the on-line material updated?</H3> <P> -New material is added when it's available. -Established implementations usually are updated only when there's a -new version. -This typically is every year or two. -The Icon program library is updated on a similar schedule. +The Icon implementation is now in maintenance mode, with new releases +produced only when necessary. This typically happens every few years when a +change in the Gnu tools cause the source to stop building. <H3><A NAME="lineage">C3.</A> Where did Icon come from?</H3> <P> @@ -329,7 +334,7 @@ but there's no good solution to that problem. <P> We continue to use Icon on a daily basis, but no significant changes are planned. -We expect to support the Unix version for the forseeable future, +We expect to support the Unix version for the foreseeable future, and to distribute ports to other systems as supplied by volunteers. <P> The Unicon project is developing an object-oriented language based on Icon. @@ -364,10 +369,6 @@ For <STRONG>porting</STRONG> assistance or <STRONG>Unix</STRONG> problems, contact <A HREF="mailto:icon-project@cs.arizona.edu">icon-project@cs.arizona.edu</A>. <LI> -For problems with the <STRONG>Windows</STRONG> implementation, -contact the implementor, -<A HREF="mailto:jeffery@cs.nmsu.edu">jeffery@cs.nmsu.edu</A>. -<LI> For general information and additional documentation, visit the Icon web site: <A HREF="http://www.cs.arizona.edu/icon/">www.cs.arizona.edu/icon</A>. </UL> @@ -398,26 +399,21 @@ A simple reference suffices, as in it's not necessary to actually call it. <P> (Why does the linker remove unreferenced procedures? -Because this can save <EM>huge</EM> amounts of memory for -programs that use the library.) +To <EM>significantly</EM> reduce the memory requirements of +programs that use the library. +There was a time when this mattered.) <H3><A NAME="callc">E3.</A> How can I call a C function?</H3> <P> -You can't call an arbitrary C function, -but if you're willing to write a function to Icon's specifications, -there are two approaches. -Under Unix, which provides <CODE>loadfunc()</CODE>, -you can load one or more functions from a shared library, -and then treat them as if they had been written in Icon. +You can't call an arbitrary C function, but you can load and call one +that is written to Icon's specifications. +A tutorial appears in +<a href="http://www.cs.arizona.edu/icon/analyst/backiss/IA36.pdf"> +Icon Analyst 36</a>. Some examples can be found in the <A HREF="http://www.cs.arizona.edu/icon/library/ccfuncs.htm"> <CODE>cfuncs</CODE></A> and <CODE>packs/loadfuncs</CODE> directories of the Icon program library. -The more cumbersome approach is to add code to the Icon interpreter -and rebuild it; some hooks are provided for this purpose. -Both approaches are discussed in <CITE>Calling C Functions from Icon</CITE>, -<A HREF="http://www.cs.arizona.edu/icon/docs/ipd240.htm"> -www.cs.arizona.edu/icon/docs/ipd240.htm</A>. <P> The <A HREF="http://www.cs.arizona.edu/icon/jcon/">Jcon</A> implementation allows Icon programs to call Java code that is written to Jcon specifications. diff --git a/doc/faq.txt b/doc/faq.txt index 91b4eb9..8538984 100644 --- a/doc/faq.txt +++ b/doc/faq.txt @@ -1,8 +1,7 @@ - Frequently Asked Questions about the Icon programming language www.cs.arizona.edu/icon/faq.htm - Last updated November 14, 2005 + Last updated April 12, 2010 Learning about Icon A1. What is Icon? @@ -23,7 +22,7 @@ C1. What is the Icon Project? C2. How often is the on-line material updated? C3. Where did Icon come from? - C4. Where is Icon going? + C4. Where is Icon going? Support D1. Is there a users' group for Icon? @@ -41,41 +40,43 @@ Learning about Icon A1. What is Icon? Icon is a very high level general-purpose programming language with - extensive features for processing strings (text) and data structures. Icon - is an imperative, procedural language with a syntax that is reminiscent of C - and Pascal, but with semantics at a much higher level. + extensive features for processing strings (text) and data structures. + Icon is an imperative, procedural language with a syntax that is + reminiscent of C and Pascal, but with semantics at a much higher + level. Icon has a novel expression-evaluation mechanism that integrates goal-directed evaluation and backtracking with conventional control - structures. It has a string scanning facility for pattern matching that - avoids the tedious details usually associated with analyzing strings. Icon's - built-in data structures include sets and tables with associative lookup, - lists that can be used as vectors or stacks and queues, and records. + structures. It has a string scanning facility for pattern matching + that avoids the tedious details usually associated with analyzing + strings. Icon's built-in data structures include sets and tables with + associative lookup, lists that can be used as vectors or stacks and + queues, and records. Icon is a strongly, though not statically, typed language. It provides - transparent automatic type conversion: For example, if an integer is used in - an operation that requires a string, the integer is automatically converted - to a string. + transparent automatic type conversion: For example, if an integer is + used in an operation that requires a string, the integer is + automatically converted to a string. - Several implementations of Icon have high-level graphics facilities with an - easily programmed window interface. + Several implementations of Icon have high-level graphics facilities + with an easily programmed window interface. - Icon manages storage automatically. Objects are created as needed during - program execution and space is reclaimed by garbage collection as needed. - The sizes of strings and data structures are limited only by the amount of - available memory. + Icon manages storage automatically. Objects are created as needed + during program execution and space is reclaimed by garbage collection + as needed. The sizes of strings and data structures are limited only + by the amount of available memory. A2. What is Icon good for? As a general-purpose programming language with a large computational - repertoire, Icon can be used for most programming tasks. It's especially - strong at building software tools, for processing text, and for experimental - and research applications. + repertoire, Icon can be used for most programming tasks. It's + especially strong at building software tools, for processing text, and + for experimental and research applications. Icon is designed to make programming easy; it emphasizes the value of - programmer's time and the importance of getting programs to work quickly. - Consequently, Icon is used both for short, one-shot tasks and for very - complex applications. + programmer's time and the importance of getting programs to work + quickly. Consequently, Icon is used both for short, one-shot tasks and + for very complex applications. A3. What are Icon's distinguishing characteristics? @@ -85,7 +86,8 @@ Learning about Icon * Usually interpreted * Evolved from programming languages (vs. scripting languages) - * Procedural control flow plus generators and goal-directed evaluation + * Procedural control flow plus generators and goal-directed + evaluation * Values have types; variables are typeless, accept any value * Static scoping: global or (procedure) local @@ -97,14 +99,17 @@ Learning about Icon * Also has sets, tables, records (structs), reals (doubles), more * No second-class "primitive types" - * Not "object-oriented" (no classes, inheritance, or instance methods) + * Not "object-oriented" (no classes, inheritance, or instance + methods) * No exception catching - * No concurrency (no threads, monitors, semaphores, or synchronization) + * No concurrency (no threads, monitors, semaphores, or + synchronization) * Has co-expressions (coroutines) * Basic least-common-denominator system interface (a la ANSI C) - * Procedural graphics (event-driven paradigm available but not mandated) + * Procedural graphics (event-driven paradigm available but not + mandated) * Retained windows (programs are never called to repaint) * Simple GUI builder that can re-edit its generated code * Turtle graphics package @@ -113,15 +118,17 @@ Learning about Icon A4. What is the Icon program library? - The library is a collection of programs and procedures written in Icon. User - contributions are welcome and form a significant portion of the library. + The library is a collection of programs and procedures written in + Icon. User contributions form a significant portion of the library. - Library procedures effectively augment the built-in functions available to - an Icon program. A wide variety of procedures currently exists, and most - graphically-based programs are built around library procedures. + Library procedures effectively augment the built-in functions + available to an Icon program. A wide variety of procedures currently + exists, and most graphically-based programs are built around library + procedures. The core and graphics core modules are the most carefully + vetted. - The programs in the library range from simple demonstrations to handy tools - to complex graphical applications. + The programs in the library range from simple demonstrations to handy + tools to complex graphical applications. The library is a resource for both new and experienced programmers. In addition to their basic utility, its programs and procedures serve as @@ -138,32 +145,37 @@ Learning about Icon www.mitchellsoftwareengineering.com/icon * John Shipman's tutorial: www.nmt.edu/tcc/help/lang/icon + For the graphics facilities: + * The Icon Project Overview: + www.cs.arizona.edu/icon/ftp/doc/ipd281.pdf + A6. Where are some simple examples? - For some simple text-based programs, see any of those introductory documents - in the preceding question. For some simple graphics programs, see - www.cs.arizona.edu/icon/gb/progs/progs.htm. + For some simple text-based programs, see any of those introductory + documents in the preceding question. For some simple graphics + programs, see www.cs.arizona.edu/icon/gb/progs/progs.htm. - Many more examples, typically larger, are found in the Icon program library; - see the indexes of Basic Programs and Graphics Programs. + Many more examples, typically larger, are found in the Icon program + library; see the indexes of Basic Programs and Graphics Programs. A7. How about comprehensive documentation? - Two books define the Icon language. The core language is covered in The Icon - Programming Language (third edition), by Griswold and Griswold. Graphics - facilities are described in Graphics Programming in Icon by Griswold, - Jeffery, and Townsend. These books contain both tutorial and reference - material. + Two books define the Icon language. The core language is covered in + The Icon Programming Language (third edition), by Griswold and + Griswold. Graphics facilities are described in Graphics Programming in + Icon by Griswold, Jeffery, and Townsend. These books contain both + tutorial and reference material. - Icon's internals are detailed in The Implementation of the Icon Programming - Language by Griswold and Griswold. Although considerable changes have - occurred since Version 6, described in the book, the basic structure of Icon - remains the same. Two technical reports, IPD112 and IPD239, describe - subsequent changes. + Icon's internals are detailed in The Implementation of the Icon + Programming Language by Griswold and Griswold. Although considerable + changes have occurred since Version 6, described in the book, the + basic structure of Icon remains the same. Two technical reports, + IPD112 and IPD239, describe subsequent changes. - Printed copies of the Language and Graphics books are available from Jeffery - Systems (www.zianet.com/jeffery/books). All three books can be downloaded at - no charge from the Icon books page, www.cs.arizona.edu/icon/books.htm. + Printed copies of the Language and Graphics books are available from + Jeffery Systems (http://unicon.org/books/). All three books can be + downloaded at no charge from the Icon books page, + www.cs.arizona.edu/icon/books.htm. The Icon Programming Language Handbook, by Thomas W. Christopher, is available on the web at www.tools-of-computing.com/tc/CS/iconprog.pdf. @@ -171,101 +183,107 @@ Learning about Icon An on-line index to the Icon program library is found at www.cs.arizona.edu/icon/library/ipl.htm. - There is a large amount of additional information at the Icon web site, - www.cs.arizona.edu/icon. + There is a large amount of additional information at the Icon web + site, www.cs.arizona.edu/icon, including complete sets of back issues + of the Icon Newsletter and Icon Analyst. _________________________________________________________________ Implementations B1. What platforms support Icon? - Current implementations with graphics support are available for Unix - (including Linux) and Windows. The Unix implementation also runs on Darwin, - the Macintosh development environment, or the Cygwin environment under - Windows. Older versions of Icon are available for some other systems. An - alternative Java-based implementation for Unix, Jcon, is also available. + The current implementation of Icon is a Unix implementation. This + includes Linux, BSD, Solaris, Macintosh, and the Cygwin environment + under Windows. Version 9.5 of Icon has been tested on all these + platforms. - B2. How do I get started with Icon? + Older versions are available for Windows and some other systems. An + alternative Java-based implementation for Unix, Jcon, is also + available. - Version 9.4.3 of Icon for Unix can be downloaded from - www.cs.arizona.edu/icon/v943. Source and binary packages are available, each - with the complete Icon program library. + None of these environments includes a window-based development + environment. While Icon programs can open windows and use graphics, + programming is done using Unix editors and other tools from a command + shell. + + B2. How do I get started with Icon? - Version 9.3 of Icon for Windows is compatible at the source level with - version 9.4.3. It can be downloaded from www.cs.arizona.edu/icon/v93w.htm. - The Version 9.4.3 library can be obtained separately from - www.cs.arizona.edu/icon/v943. + The current version of Icon for Unix can be downloaded from + www.cs.arizona.edu/icon/current. Source and binary packages are + available, each with the complete Icon program library. - For older implementations, start at www.cs.arizona.edu/icon/implver.htm. - Jcon is at www.cs.arizona.edu/icon/jcon. + For older implementations, start at + www.cs.arizona.edu/icon/implver.htm. Jcon is at + www.cs.arizona.edu/icon/jcon. B3. Is there a Unicode version of Icon? - No. Icon is defined in terms of 8-bit characters, and changing this presents - several design challenges that would likely break existing programs. Also, - modifying the C implementation is probably infeasible, but a Unicode version - of Jcon might be possible. + No. Icon is defined in terms of 8-bit characters, and changing this + presents several design challenges that would likely break existing + programs. Also, modifying the C implementation is probably infeasible, + but a Unicode version of Jcon might be possible. B4. What happened to the compiler? - For a while, Unix distributions included both an interpreter and a compiler; - but the interpreter is is usually fast enough even for production work, and - most people found that using the compiler wasn't worth the extra compilation - time or the hassles involved. We no longer advertise the compiler or produce - binaries for it. It is still part of the source code distribution, and we - have not deliberately broken it, but we no longer support it and we cannot - offer help if problems arise. + For a while, Unix distributions included both an interpreter and a + compiler. The compiler was an interesting research project but it has + not been maintained and is no longer supported. The interpreter is + much easier to use and is generally quite fast enough, even for + production applications. _________________________________________________________________ Administration C1. What is the Icon Project? - The Icon Project is a name used by the group that distributes and supports - the Icon programming language. The project maintains the Icon web site at - www.cs.arizona.edu/icon. A non-commercial organization, the project is - supported by the Department of Computer Science at the University of - Arizona. + The Icon Project is a name used by the group that distributes and + supports the Icon programming language. The project maintains the Icon + web site at www.cs.arizona.edu/icon. A non-commercial organization, + the project is supported by the Department of Computer Science at the + University of Arizona. C2. How often is the on-line material updated? - New material is added when it's available. Established implementations - usually are updated only when there's a new version. This typically is every - year or two. The Icon program library is updated on a similar schedule. + The Icon implementation is now in maintenance mode, with new releases + produced only when necessary. This typically happens every few years + when a change in the Gnu tools cause the source to stop building. C3. Where did Icon come from? - Icon is the latest in a series of high-level programming languages designed - to facilitate programming tasks involving strings and structures. The - original language, SNOBOL, was developed at Bell Telephone Laboratories in - the early 1960s. SNOBOL evolved into SNOBOL4, which is still in use. - Subsequent languages were developed at the University of Arizona with - support from the National Science Foundation. Although it has similar - objectives and many similar capabilities, Icon bears little superficial - resemblance to SNOBOL4. - - Icon implementations were developed by faculty, staff, and students at the - University of Arizona, with significant contributions from volunteers around - the world. An Icon history by Ralph and Madge Griswold appears in the - preprints of the second History of Programming Languages Conference - (HOPL-II), ACM SIGPLAN Notices, March 1993 (Vol 28, No 3). + Icon is the latest in a series of high-level programming languages + designed to facilitate programming tasks involving strings and + structures. The original language, SNOBOL, was developed at Bell + Telephone Laboratories in the early 1960s. SNOBOL evolved into + SNOBOL4, which is still in use. Subsequent languages were developed at + the University of Arizona with support from the National Science + Foundation. Although it has similar objectives and many similar + capabilities, Icon bears little superficial resemblance to SNOBOL4. + + Icon implementations were developed by faculty, staff, and students at + the University of Arizona, with significant contributions from + volunteers around the world. An Icon history by Ralph and Madge + Griswold appears in the preprints of the second History of Programming + Languages Conference (HOPL-II), ACM SIGPLAN Notices, March 1993 (Vol + 28, No 3). The name Icon is not an acronym, nor does it stand for anything in - particular, although the word iconoclastic was mentioned when the name was - chosen. The name predates the now common use of icon to refer to small - images used in graphical user interfaces. This sometimes misleads people - into thinking that Icon is designed to create or manipulate icons, but - there's no good solution to that problem. + particular, although the word iconoclastic was mentioned when the name + was chosen. The name predates the now common use of icon to refer to + small images used in graphical user interfaces. This sometimes + misleads people into thinking that Icon is designed to create or + manipulate icons, but there's no good solution to that problem. C4. Where is Icon going? - We continue to use Icon on a daily basis, but no significant changes are - planned. We expect to support the Unix version for the forseeable future, - and to distribute ports to other systems as supplied by volunteers. + We continue to use Icon on a daily basis, but no significant changes + are planned. We expect to support the Unix version for the foreseeable + future, and to distribute ports to other systems as supplied by + volunteers. - The Unicon project is developing an object-oriented language based on Icon. - For more information, see unicon.sourceforge.net. An earlier object-oriented - extension to Icon, Idol, can be found in the Icon program library. + The Unicon project is developing an object-oriented language based on + Icon. For more information, see unicon.sourceforge.net. An earlier + object-oriented extension to Icon, Idol, can be found in the Icon + program library. _________________________________________________________________ Support @@ -277,61 +295,59 @@ Support D2. How do I get technical support? - The Icon Project is not a commercial organization, and its capacity for - providing technical support is limited. Please use the appropriate resource - when you need assistance: + The Icon Project is not a commercial organization, and its capacity + for providing technical support is limited. Please use the appropriate + resource when you need assistance: * For programming questions, submit a query to the Usenet newsgroup comp.lang.icon. * For porting assistance or Unix problems, contact icon-project@cs.arizona.edu. - * For problems with the Windows implementation, contact the implementor, - jeffery@cs.nmsu.edu. - * For general information and additional documentation, visit the Icon web - site: www.cs.arizona.edu/icon. + * For general information and additional documentation, visit the + Icon web site: www.cs.arizona.edu/icon. _________________________________________________________________ Programming E1. Why doesn't read() work with every? - every s := read() do {...} doesn't loop because read() produces a single - value and then fails if resumed. Other "consumer" procedures such as get() - and pop() work the same way. Use a while loop with these procedures, and - save every for use with generators such as !x or key(T). + every s := read() do {...} doesn't loop because read() produces a + single value and then fails if resumed. Other "consumer" procedures + such as get() and pop() work the same way. Use a while loop with these + procedures, and save every for use with generators such as !x or + key(T). E2. Why doesn't string invocation such as "foo"() work? - String invocation works if the procedure is present; the catch is that the - linker removes unreferenced procedures. To ensure a procedure's presence, - reference it in the main() procedure. A simple reference suffices, as in - refs := [foo, bar, baz]; it's not necessary to actually call it. + String invocation works if the procedure is present; the catch is that + the linker removes unreferenced procedures. To ensure a procedure's + presence, reference it in the main() procedure. A simple reference + suffices, as in refs := [foo, bar, baz]; it's not necessary to + actually call it. - (Why does the linker remove unreferenced procedures? Because this can save - huge amounts of memory for programs that use the library.) + (Why does the linker remove unreferenced procedures? To significantly + reduce the memory requirements of programs that use the library. There + was a time when this mattered.) E3. How can I call a C function? - You can't call an arbitrary C function, but if you're willing to write a - function to Icon's specifications, there are two approaches. Under Unix, - which provides loadfunc(), you can load one or more functions from a shared - library, and then treat them as if they had been written in Icon. Some - examples can be found in the cfuncs and packs/loadfuncs directories of the - Icon program library. The more cumbersome approach is to add code to the - Icon interpreter and rebuild it; some hooks are provided for this purpose. - Both approaches are discussed in Calling C Functions from Icon, - www.cs.arizona.edu/icon/docs/ipd240.htm. + You can't call an arbitrary C function, but you can load and call one + that is written to Icon's specifications. A tutorial appears in Icon + Analyst 36. Some examples can be found in the cfuncs and + packs/loadfuncs directories of the Icon program library. The Jcon implementation allows Icon programs to call Java code that is written to Jcon specifications. E4. Can I open a bidirectional pipe? - No, this is not possible. Although the concept is simple — write a line to a - program via a pipe, then read that program's output — it probably wouldn't - work. Most I/O libraries don't write anything to a pipe until they've filled - a buffer, and the most likely consequence would be a deadlock, with each - program waiting for the other to send more data. + No, this is not possible. Although the concept is simple -- write a + line to a program via a pipe, then read that program's output -- it + probably wouldn't work. Most I/O libraries don't write anything to a + pipe until they've filled a buffer, and the most likely consequence + would be a deadlock, with each program waiting for the other to send + more data. _________________________________________________________________ - This FAQ is edited by Gregg Townsend. It includes contributions from Ralph - Griswold, Cliff Hathaway, Clint Jeffery, Bob Alexander, and Todd Proebsting. + This FAQ is edited by Gregg Townsend. It includes contributions from + Ralph Griswold, Cliff Hathaway, Clint Jeffery, Bob Alexander, and Todd + Proebsting. diff --git a/doc/files.htm b/doc/files.htm index fd7fef0..83855b7 100644 --- a/doc/files.htm +++ b/doc/files.htm @@ -1,7 +1,7 @@ <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML> <HEAD> - <TITLE>File Organization in Version 9.4 of Icon</TITLE> + <TITLE>File Organization in Versions Icon Installations</TITLE> <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> </HEAD> @@ -10,15 +10,15 @@ <P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> -<H1> File Organization in Version 9.4 of Icon </H1> +<H1> File Organization in Icon Installations</H1> <P> Gregg M. Townsend <BR> <SMALL> Department of Computer Science </SMALL> <BR> <SMALL> The University of Arizona </SMALL> -<P> <SMALL> www.cs.arizona.edu/icon/v943/files.htm -<BR> Last updated November 8, 2005 </SMALL> -<!-- $Id: files.htm,v 1.17 2005/11/08 23:24:35 gmt Exp $ --> +<P> <SMALL> www.cs.arizona.edu/icon/v950/files.htm +<BR> Last updated November 16, 2009 </SMALL> +<!-- $Id: files.htm,v 1.19 2009/11/16 22:11:13 gmt Exp $ --> <H2> Introduction </H2> @@ -35,13 +35,13 @@ programs; yet the IPL had been treated as a separate product. A complete Icon system required two downloads and two installation efforts, with proper coordination. -<P> With Icon 9.4, the complete set of basic and graphics library +<P> Now, the complete set of basic and graphics library procedures is included with every binary Icon distribution. Also present are the associated <CODE>$include</CODE> files and a selected few programs from the library — notably VIB, the visual interface builder. -<P> Source distributions of Icon 9.4 include the full library, +<P> Source distributions of Icon include the full library, which also continues to be available separately. <H2> Installation directory structure </H2> @@ -64,9 +64,9 @@ and "ucode" (<CODE>.u1</CODE>/<CODE>.u2</CODE>) files of program library procedures. This directory is system independent. -<P> The <CODE>man</CODE> directory holds the Unix <CODE>man</CODE> page -for <CODE>icont</CODE>, and the <CODE>doc</CODE> directory holds -HTML (<CODE>.htm</CODE>) documentation files. +<P> The <CODE>man</CODE> directory holds the Unix <CODE>man</CODE> pages +for <CODE>icon</CODE> and <CODE>icont</CODE>, and the <CODE>doc</CODE> +directory holds HTML (<CODE>.htm</CODE>) documentation files. These directories are also system independent. <P> This structure is similar to that of binary distributions of Icon 9.3. @@ -108,7 +108,7 @@ The <CODE>iconx</CODE> location was configured by editing <CODE>patchstr</CODE> utility to edit the <CODE>icont</CODE> executable when installing a binary distribution. -<P> In version 9.4, <CODE>icont</CODE> deduces its own location, +<P> Now, <CODE>icont</CODE> deduces its own location, and from this it infers the location of <CODE>iconx</CODE> in the same directory. No configuration of <CODE>icont</CODE> is needed, and the correct @@ -128,7 +128,7 @@ path must be edited to match the installed location of <CODE>iconx</CODE>. The <CODE>ipatch</CODE> utility performed this task when installing binary distributions of Icon 9.3. -<P> Icon 9.4 implements a simple search in the shell script that +<P> Icon implements a simple search in the shell script that heads each generated Icon executable. The new header script searches for <CODE>iconx</CODE> in these places: @@ -173,7 +173,7 @@ loadable C functions without requiring explicit user action. distribution are ready for use without modification. The annoying and error-prone Setup step that was necessary with previous versions is no longer required. -With Icon 9.4, installation can be as simple as just unpacking the +Now, installation can be as simple as just unpacking the tar file and adding its <CODE>bin</CODE> directory to the search path. <P> <HR> diff --git a/doc/icon.txt b/doc/icon.txt index 4168ba5..a8b0c04 100644 --- a/doc/icon.txt +++ b/doc/icon.txt @@ -39,12 +39,14 @@ SEE ALSO icont(1), the full-featured interface supporting separate compilation, multiple source files, and other features. - The Icon Programming Language. Griswold and Griswold, Peer-to-Peer, - third edition, 1996. + The Icon Programming Language. + Griswold and Griswold, Peer-to-Peer, third edition, 1996. + http://www.cs.arizona.edu/icon/lb3.htm. - Graphics Programming in Icon. Griswold, Jeffery, and Townsend, Peer- - to-Peer, 1998. + Graphics Programming in Icon. + Griswold, Jeffery, and Townsend, Peer-to-Peer, 1998. + http://www.cs.arizona.edu/icon/gb/index.htm. - Version 9.4.3 of Icon. - http://www.cs.arizona.edu/icon/v943. + Version 9.5.0 of Icon. + http://www.cs.arizona.edu/icon/v950. diff --git a/doc/icont.txt b/doc/icont.txt index a5eb633..ae867bc 100644 --- a/doc/icont.txt +++ b/doc/icont.txt @@ -110,14 +110,16 @@ SEE ALSO icon(1), a simpler command interface for embedding Icon programs in scripts. - The Icon Programming Language. Griswold and Griswold, Peer-to-Peer, - third edition, 1996. + The Icon Programming Language. + Griswold and Griswold, Peer-to-Peer, third edition, 1996. + http://www.cs.arizona.edu/icon/lb3.htm. - Graphics Programming in Icon. Griswold, Jeffery, and Townsend, Peer- - to-Peer, 1998. + Graphics Programming in Icon. + Griswold, Jeffery, and Townsend, Peer-to-Peer, 1998. + http://www.cs.arizona.edu/icon/gb/index.htm. - Version 9.4.3 of Icon. - http://www.cs.arizona.edu/icon/v943. + Version 9.5.0 of Icon. + http://www.cs.arizona.edu/icon/v950. CAVEATS Icon executables are not self-sufficient, but require the iconx inter- diff --git a/doc/index.htm b/doc/index.htm index 0c62d4e..b2806bc 100644 --- a/doc/index.htm +++ b/doc/index.htm @@ -13,15 +13,18 @@ ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> <H1>Icon Documentation</H1> <P> <A HREF=docguide.htm> Documentation guide </A> +<P> The <A href="icon.txt"><CODE>icon</CODE></A> + and <A href="icont.txt"><CODE>icont</CODE></A> commands <P> <A HREF=relnotes.htm> Release notes </A> +<P> <A HREF=macintosh.htm> Icon on Macintosh </A> +<P> <A HREF=cygwin.htm> Icon on Cygwin </A> +<P> <A HREF=faq.htm> Frequently asked questions </A> <P> <A HREF=install.htm>Installation instructions (for binary releases) </A> <P> <A HREF=build.htm> Build instructions (for source releases) </A> -<P> <A HREF=port.htm> Porting instructions </A> <P> <A HREF=files.htm> File organization </A> -<P> <A HREF=macintosh.htm> Icon on Macintosh </A> -<P> <A HREF=cygwin.htm> Icon on Cygwin </A> -<P> <A HREF=faq.htm> Frequently asked questions about Icon </A> - +<P> <A HREF=port.htm> Porting instructions </A> +<P> <A HREF=cfuncs.htm> Loading C functions dynamically</A> +<P> <A HREF=extlvals.htm> External values</A> <P> <HR> diff --git a/doc/install.htm b/doc/install.htm index 900227b..4b6c282 100644 --- a/doc/install.htm +++ b/doc/install.htm @@ -1,7 +1,7 @@ <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML> <HEAD> - <TITLE>Installing Binaries of Version 9.4 of Icon</TITLE> + <TITLE>Installing Binaries of Version 9.5 of Icon</TITLE> <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> </HEAD> @@ -10,20 +10,20 @@ <P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> -<H1>Installing Binaries of Version 9.4 of Icon</H1> +<H1>Installing Binaries of Version 9.5 of Icon</H1> <P> Gregg M. Townsend <BR> <SMALL> Department of Computer Science </SMALL> <BR> <SMALL> The University of Arizona </SMALL> -<P> <SMALL> www.cs.arizona.edu/icon/v943/install.htm -<BR> Last updated November 8, 2005 </SMALL> -<!-- $Id: install.htm,v 1.17 2005/11/08 23:24:35 gmt Exp $ --> +<P> <SMALL> www.cs.arizona.edu/icon/v950/install.htm +<BR> Last updated November 8, 2009 </SMALL> +<!-- $Id: install.htm,v 1.18 2009/11/08 21:53:08 gmt Exp $ --> <P> <P> These instructions explain how to install Unix binaries of -<A HREF=relnotes.htm>Version 9.4 of Icon</A>. +<A HREF=relnotes.htm>Version 9.5 of Icon</A>. For instructions on building an Icon source package, see <A HREF=build.htm>Building Icon from Source</A>. diff --git a/doc/istyle.css b/doc/istyle.css index 820fd71..3e183cc 100644 --- a/doc/istyle.css +++ b/doc/istyle.css @@ -21,6 +21,7 @@ LI { margin-top: 0.2em; } TH, TD { padding-left: 0.4em; padding-right: 0.4em; } TH, TD { vertical-align: top; text-align: left; } +TH { font-weight: normal; font-style: italic; } A:link { background: white; color: #06C; } A:visited { background: white; color: #036; } diff --git a/doc/macintosh.htm b/doc/macintosh.htm index a6b39de..7cdcbc5 100644 --- a/doc/macintosh.htm +++ b/doc/macintosh.htm @@ -18,9 +18,9 @@ <SMALL>Department of Computer Science</SMALL><BR> <SMALL>The University of Arizona</SMALL></P> - <P><SMALL>www.cs.arizona.edu/icon/v943/macintosh.htm<BR> - Last updated November 9, 2005</SMALL> - <!-- $Id: macintosh.htm,v 1.1 2005/11/09 18:03:59 gmt Exp $ --></P> + <P><SMALL>www.cs.arizona.edu/icon/v950/macintosh.htm<BR> + Last updated November 19, 2009</SMALL> + <!-- $Id: macintosh.htm,v 1.5 2009/11/19 18:49:31 gmt Exp $ --></P> <H2>Introduction</H2> @@ -39,33 +39,32 @@ <CITE>cc</CITE> command, supports multiple files, separate compilation, and other features.</P> - <H2>Graphics</H2> + <H2>Co-Expressions</H2> + + <P> + Because MacOS does not implement anonymous semaphores, + each co-expression creates an open file. + Programs with hundreds of active co-expressions may + abort with a <CODE>cannot create semaphore</CODE> system error. + The open file limit can be raised from the typical default of 256 + using a <CODE>limit descriptors <I>n</I></CODE> or + <CODE>ulimit -nS <I>n</I></CODE> command, depending on the shell. - <P>For graphics, Icon uses the X Window System, generally called - <A href="http://www.apple.com/macosx/features/x11/">X11</A> in - Macintosh documentation. X11 is not normally installed as part of - OS X; it must be selected as part of a custom installation. - Alternatively, it can be - <A HREF="http://www.apple.com/support/downloads/x11formacosx.html"> - downloaded</A> from Apple.</P> - <P>The X window system does not start automatically. To run an - Icon graphics program, you must first start the X11 application - and leave it running. The environment variable DISPLAY must be - set in the shell that runs an Icon graphics program. For - example:</P> + <H2>Graphics</H2> - <BLOCKQUOTE> - <P><CODE>setenv DISPLAY :0.0</CODE></P> - </BLOCKQUOTE> + <P>For graphics, Icon uses the X Window System, generally called X11 in + Macintosh documentation. + Beginning with Mac OS 10.5 (Leopard), X11 starts automatically + when needed, and no advance preparations are needed. + An X11 icon appears in the dock when an Icon graphics program + is run and persists innocuously afterward. <H2>Building Icon</H2> <P>Building Icon from source requires the <A href= - "http://www.apple.com/macosx/features/xcode/">Xcode</A> toolbox. - This comes in an extra folder on the OS X installation disc. - When installing XCode, be sure to select a custom - installation and add X11 to the default set.</P> + "http://developer.apple.com/tools/xcode/">Xcode</A> toolbox, + which comes on the OS X installation disk.</P> <P>Icon is built in a Terminal window. The process is the same as on other platforms and uses the configuration named diff --git a/doc/port.htm b/doc/port.htm index 5be8473..f05684b 100644 --- a/doc/port.htm +++ b/doc/port.htm @@ -16,9 +16,9 @@ ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> <BR> <SMALL> Department of Computer Science </SMALL> <BR> <SMALL> The University of Arizona </SMALL> -<P> <SMALL> www.cs.arizona.edu/icon/v943/port.htm -<BR> Last updated November 8, 2005 </SMALL> -<!-- $Id: port.htm,v 1.5 2005/11/08 23:24:35 gmt Exp $ --> +<P> <SMALL> www.cs.arizona.edu/icon/v950/port.htm +<BR> Last updated March 25, 2010 </SMALL> +<!-- $Id: port.htm,v 1.9 2010/03/25 23:33:10 gmt Exp $ --> <H2> Introduction </H2> @@ -47,7 +47,7 @@ although they are not part of the 1992 standard. <H3>C Compiler</H3> -Icon requires a production-quality compiler supporting ANSI C (X3.159-1989). +Icon requires a production-quality compiler supporting C99 (ISO/IEC 9899:1999). <EM>Production quality</EM> implies correctness, robustness, and the ability to handle large files and complicated expressions. @@ -71,8 +71,6 @@ In addition to the standard C library, Icon uses the library functions specified by POSIX.1 (IEEE 1993.1-1996). In particular, Icon uses <DFN>POSIX threads</DFN> and <DFN>semaphores</DFN> to implement context switching for co-expressions. -This eliminates the need for specialized assembly-language code, -some of which can still be seen in older configurations. @@ -141,7 +139,7 @@ The parameters set here are: <DT><CODE>CC</CODE> <DD>The command name for the C compiler. Typical values are - <CODE>cc</CODE>, <CODE>gcc</CODE>, or <CODE>c89</CODE>. + <CODE>cc</CODE>, <CODE>gcc</CODE>, or <CODE>c99</CODE>. <DT><CODE>CFLAGS</CODE> <DD>C compiler flags. A path specification for the X11 libraries diff --git a/doc/relnotes.htm b/doc/relnotes.htm index ae6bf1f..9466806 100644 --- a/doc/relnotes.htm +++ b/doc/relnotes.htm @@ -1,7 +1,7 @@ <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML> <HEAD> - <TITLE>Release Notes for Version 9.4.3 of Icon</TITLE> + <TITLE>Release Notes for Version 9.5 of Icon</TITLE> <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> </HEAD> @@ -10,78 +10,118 @@ <P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> -<H1> Release Notes for Version 9.4.3 of Icon </H1> +<H1> Release Notes for Version 9.5 of Icon </H1> <P> Gregg M. Townsend <BR> <SMALL> Department of Computer Science </SMALL> <BR> <SMALL> The University of Arizona </SMALL> -<P> <SMALL> www.cs.arizona.edu/icon/v943/relnotes.htm -<BR> Last updated November 10, 2005 </SMALL> -<!-- $Id: relnotes.htm,v 1.49 2005/11/10 23:02:06 gmt Exp $ --> +<P> <SMALL> www.cs.arizona.edu/icon/v950/relnotes.htm +<BR> Last updated April 12, 2010</SMALL> +<!-- $Id: relnotes.htm,v 1.74 2010/04/12 20:39:24 gmt Exp $ --> <H2> Introduction </H2> -<P> Version 9.4.3 of Icon is a minor update to version 9.4.2 of Icon. -It incorporates configuration, documentation, and library updates. +<P> Version 9.5.0 of Icon is an update of version 9.4.3 of Icon. +It incorporates configuration, documentation, and library changes. Some minor bugs have been fixed. +Support has been added for "external values" created by +user C functions. -<P> The Icon language is unchanged, and this Unix implementation -remains compatible at the source level with Icon 9.3 for Windows. - -<H2> Changes in version 9.4.3 </H2> +<H2> Changes in version 9.5 </H2> <P> Notable changes in this latest version are listed here. Some code cleanup work and documentation editing has also been done. -<H3> Configurations </H3> +<H3> External Values </H3> + +<P> External code incorporated by <CODE>loadfunc()</CODE> can now create +and return to Icon code opaque values that can be stored and passed +on subsequent calls. +This is similar to a feature of the early Macintosh ProIcon implementation. +See <A HREF=extlvals.htm>External Values</A> for more information. + +<H3> Build Environment </H3> + +<P> This version of Icon is the first to deliberately move beyond the +1989 C standard and make use of features of the 1999 C standard, +specifically the "struct hack". +Consequently, a C99 (or newer) compiler is now required to build Icon. + +<H3> Cygwin Configuration </H3> + +<P> The <CODE>cygwin</CODE> configuration has improved, partially through +removal of unneeded special cases now that Cygwin better approximates Unix. +External functions can now be loaded using <CODE>loadfunc()</CODE>. + +<P> In addition to the <CODE>cygwin</CODE> configuration, which uses +Windows graphics, there is now a new <CODE>xcygwin</CODE> configuration +that uses the X window system. -<P> The system-specific Icon configurations have been reorganized and renamed; -new names focus on operating systems rather than CPU architectures. -The several BSD configurations have been merged into one. +<H3> Implementation Cleanup</H3> -<P> The <CODE>macintosh</CODE> configuration now supports the -<CODE>loadfunc</CODE> function. This configuration has also been -revised to anticipate Apple's announced migration to the x86 architecture. +<P> Large amounts of conditionalized dead code, including the old Icon +compiler, have been removed from the source code. -<P> A new <A HREF=port.htm>porting guide</A> has been written, and a new -<CODE>posix</CODE> configuration has been added -as a starting point in constructing new ports. +<P> All platforms now use POSIX threads for context switching instead of +system- and processor-dependent assembly language code. + +<H3> Minor Fixes </H3> + +<P> The <CODE>loadfunc()</CODE> implementation now specifies to the system +that C globals are to be shared with and among loaded functions. + +<P> The command <CODE>icon nonexistent.icn</CODE> no longer leaves debris +in the /tmp directory. + +<P> The maximum length of a file name has been increased from 256 to 512 +characters. + +<P> Table copying in the Sparc (Solaris) configuration was fixed by +coding a workaround to avoid a GCC 4.2.2 struct assignment bug. <H3> Library changes </H3> -<P> As usual, several files in the Icon program library have been -added or edited. The core library files, however, remain stable. +<P> As usual, some files in the Icon program library have been +added or edited, but the core library files remain stable. Notable changes include: <PRE> -procs/dijkstra new procedures implement Dijkstra's control structures -procs/html add procedure for canonicalization of paths -procs/matrix2 new procedures for matrix manipulation -procs/nestlist new procedures for representing nested lists as strings -procs/printf add %e format and fix a rounding problem - -progs/noise new program for producing a random bitstream -progs/unclog improve logic for combining adjacent entries - -gprogs/dlgvu improve coverage map; allow altitude in GPS data -gprogs/gallery faster thumbnail loading for JPEG images -gprogs/img many new features -gprogs/sier better color choices -gprogs/trkvu accept GPS track logs with altitude as the last field +procs/echo New procedure for interpolating variables in strings. +procs/printf Rewrite parts to fix several bugs, and add test. +procs/random Improve thoroughness of randomize(). + +progs/diffsum Handle output of "cvs diff". +progs/unclog Handle CVS branches; fix indentation. +progs/weblinks Add option to sort output by referencing page. + +gprogs/breakout Make the ball large enough to see. +gprogs/gallery Treat -wnnn and -hnnn options as *minimums*. +gprogs/gallery Handle spaces embedded in JPEG filenames. +gprogs/kaleid Add delay to prevent runaway on fast CPUs. +gprogs/spider Add shortcuts, opt-in logging, congratulatory display. +gprogs/trkvu Limit file legend to onscreen files. +gprogs/tron New video game inspired by Tron. + +packs/loadfuncpp Add C++ interface package. +packs/icondb Add MySQL interface package. + +gpacks/weaving Add "halftone" weaving program htweav.icn. </PRE> -The undocumented <CODE>save</CODE> function, which only worked -on a few platforms, has been removed. +<H3> Documentation Additions </H3> + +<P> Two new documentation pages, <A HREF="cfuncs.htm">Loading C functions</A> +and <A HREF="extlvals.htm">External Values</A>, have been added. <H2> Earlier feature additions </H2> -<P> These features appeared in earlier releases of Icon that followed -publication of the Icon books. +<P> These features appeared in earlier releases of Icon +but subsequent to publication of the Icon books. <H3> Millions of colors </H3> <SMALL> (new with version 9.4.2 of Icon) </SMALL> @@ -102,7 +142,7 @@ which in another form allows a small Icon program to be embedded within a shell script. See the <A HREF="icon.txt">man page</A> for details. The traditional <A HREF="icont.txt"><CODE>icont</CODE></A> command -remains available for less specialized purposes. +remains available when more flexibility is needed. <H3> Path searching </H3> <SMALL> (new with version 9.4.0 of Icon) </SMALL> @@ -116,7 +156,7 @@ The Icon translator and linker search these paths when looking for <P> The Icon program library is now searched automatically, but <CODE>LPATH</CODE> and <CODE>IPATH</CODE> can still be set to control the search order. -For version 9.4, the effective path in each case is: +The effective path in each case is: <OL> <LI> The current directory <LI> Any directories named by the environment variable @@ -201,13 +241,15 @@ for an overview of the available Icon documentation. <H2> Acknowledgments </H2> -<P> -Arthur Eschenlauer contributed the <CODE>matrix2</CODE> -and <CODE>nestlist</CODE> libraries. -Frank Lhota contributed the <CODE>dijkstra</CODE> library. -Nolan Clayton contributed revisions to the <CODE>img</CODE> program. -Michael Glass contributed revisions to the <CODE>printf</CODE> procedure. -Chris Tenaglia and Andreas Almroth contributed configuration files. +<P> Carl Sturtivant inspired and participated in the development +of external values. He also contributed the <CODE>loadfuncpp</CODE> +and <CODE>icondb</CODE> packages. +Eduardo Ochs contributed the <CODE>tron</CODE> game. +Charles L. Hethcoat III contributed the <CODE>echo</CODE> procedure. +Carl Sturtivant and Steve Waldo supplied numerous Cygwin improvements. +Cheyenne Wills improved the flexibility of the configuration process. +Clint Jeffery fixed an ancient linking bug. +Robert Shiplett and Jonathan Kaye helped with testing. <P> <HR> |