home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / languages / icon_1 / DOCS / IPD238_DOC < prev    next >
Text File  |  1995-12-01  |  47KB  |  1,717 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                  Configuring the Source Code for
  11.                         Version 9 of Icon
  12.  
  13.               Gregg M. Townsend, Ralph E. Griswold,
  14.                      and Clinton L. Jeffery
  15.                Department of Computer Science, The
  16.                       University of Arizona
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23. 1.__Background
  24.  
  25.    The implementation of the Icon programming language is large
  26. and sophisticated [1-3].  The implementation is, however, written
  27. almost entirely in C and RTL [4], a superset of C, for which a
  28. translator to C is provided.  A small amount of assembly-language
  29. code is needed for the context switch used by co-expressions.
  30. See Appendix B.  This code is optional and only affects co-
  31. expressions.
  32.  
  33.    There presently are implementations of Icon for the Acorn
  34. Archimedes, the Amiga, the Atari ST, the Macintosh, MS-DOS, MVS,
  35. OS/2, UNIX, VM/CMS, and VMS.
  36.  
  37.    All implementations of Icon are obtained from the same source
  38. code, using conditional compilation and defined constants to
  39. select and configure platform-dependent code. Consequently,
  40. installing Icon on a new platform is largely a matter of select-
  41. ing appropriate values for configuration parameters, deciding
  42. among alternative definitions, and possibly adding some code that
  43. is dependent on the specific computer, operating system, and C
  44. compiler used.
  45.  
  46.    This document describes the process of configuring Version 9
  47. of the Icon source code for a platform on which it has not previ-
  48. ously been installed.
  49.  
  50.    Since there are several existing configurations for UNIX and
  51. MS-DOS, configuring a new platform for one of these operating
  52. systems is easier than for other platforms. See Sections 5, 6,
  53. and 7 for specific information concerning UNIX and MS-DOS plat-
  54. forms.
  55.  
  56.    Building Icon with a new C compiler on an operating system for
  57. which Icon has previously been installed usually is a fairly sim-
  58. ple task and normally can be done by adjusting a few configura-
  59. tion parameters.
  60.  
  61.  
  62.  
  63.  
  64. IPD238b                       - 1 -              November 1, 1995
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.    Installing Icon on a new operating system is more complex;
  74. read this report carefully, especially Section 8, before under-
  75. taking such a project.
  76.  
  77.  
  78. 2.__Requirements
  79.  
  80. C_Data_Sizes
  81.  
  82.    Icon places the following requirements on C data sizes:
  83.  
  84.      +   chars must be 8 bits.
  85.  
  86.      +   ints must be 16, 32, or 64 bits.
  87.  
  88.      +   longs and pointers must be 32 or 64 bits.
  89.  
  90.      +   All pointers must be the same length.
  91.  
  92.      +   longs and pointers must be the same length.
  93.  
  94. If your C data sizes do not meet these requirements, do not
  95. attempt to configure Icon.
  96.  
  97. The_C_Compiler
  98.  
  99.    The main requirement for implementing Icon is a production-
  100. quality C compiler that supports at least the ``K&R'' standard
  101. [5].  An ANSI C compiler is preferable.  The term ``production
  102. quality'' implies robustness, correctness, the ability to address
  103. large amounts of memory, the ability to handle large files and
  104. complicated expressions, and a comprehensive run-time library.
  105.  
  106.    The C preprocessor should conform either to the ANSI C stan-
  107. dard [6] or to the K&R standard for UNIX C preprocessors.  In
  108. particular, Icon uses the C preprocessor to concatenate strings
  109. and substitute arguments within quotation marks. For the ANSI
  110. preprocessor standard, the following definitions are used:
  111.  
  112.         #define Cat(x, y) x##y
  113.         #define Lit(x) #x
  114.  
  115. For the UNIX K&R standard, the following definitions are used:
  116.  
  117.         #define Ident(x) x
  118.         #define Cat(x, y) Ident(x)y
  119.         #define Lit(x) "x"
  120.  
  121. The following program can be used to test these preprocessor
  122. facilities:
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130. IPD238b                       - 2 -              November 1, 1995
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.         Cat(ma, in)()
  140.         {
  141.            printf(Lit(Hello world\n));
  142.         }
  143.  
  144. If this program does not compile and print Hello world using one
  145. of the sets of definitions above, there is no point in proceed-
  146. ing.  Contact the Icon Project for alternative approaches.
  147.  
  148. Memory
  149.  
  150.    The Icon programming language requires a substantial amount of
  151. memory to run.  The practical minimum depends somewhat on the
  152. platform; 640KB is typical.
  153.  
  154. File_Space
  155.  
  156.    The source code for Icon is large - about 3.5MB.  Test pro-
  157. grams and other auxiliary files take additional room, as does
  158. compilation and testing.  While the implementation can be divided
  159. into components that can be built separately, this approach may
  160. be painful.
  161.  
  162.  
  163. 3.__File_Structure
  164.  
  165.    The files for Icon are organized in a hierarchy. The top
  166. level, assuming the hierarchy is rooted in icon is:
  167.  
  168.                |-bin------    executable binaries and support files
  169.                |-config---    configurations
  170.      |-icon----|-src------    source code
  171.                |-tests----    tests
  172.  
  173.  
  174. There are several subdirectories in config for different operat-
  175. ing systems:
  176.  
  177.                |-acorn----
  178.                |-amiga----
  179.                |-atari_st-
  180.                |-ibm370---
  181.      --config--|-macintosh
  182.                |-msdos----
  183.                |-os2------
  184.                |-unix-----
  185.                |-vms------
  186.  
  187.  
  188. Not all of these subdirectories are included in all distributions
  189. of Icon.  Some configuration directories contain subdirectories
  190. for different platforms. These subdirectories contain various
  191. files, depending on the platform.
  192.  
  193.  
  194.  
  195.  
  196. IPD238b                       - 3 -              November 1, 1995
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.    The directory src contains the source code for various com-
  206. ponents of Icon.
  207.  
  208.                |-common----   common source
  209.                |-h---------   header files
  210.                |-iconc-----   Icon compiler source
  211.      -src------|-icont-----   Icon translator source
  212.                |-preproc---   C preprocessor source
  213.                |-rtt-------   run-time translator source
  214.                |-vtran-----   variant translator support
  215.                |-wincap----   BMP image-file format support
  216.                |-xpm-------   XPM image-file format support
  217.  
  218.  
  219.    The directory tests contains the test material for various
  220. components of Icon.
  221.  
  222.                |-bench-----   benchmarks
  223.                |-calling---   calling C functions from Icon
  224.                |-general---   general tests
  225.                |-graphics--   tests for graphics
  226.      -tests----|-ipl-------   tests for the Icon program library
  227.                |-preproc---   C preprocessor tests
  228.                |-samples---   short sample programs
  229.                |-special---   tests of special features
  230.                |-vtran-----   tests variant translators
  231.  
  232.  
  233. Some distributions contain other, optional components of Icon.
  234. The Icon compiler is not included in all distributions of Icon.
  235.  
  236.  
  237. 4.__Parameters_and_Definitions
  238.  
  239.    There are many defined constants and macros in the source code
  240. for Icon that vary from platform to platform.  Over the range of
  241. possible platforms, there are many possibilities. A complete list
  242. is given in Appendix A.  Do not be intimidated by the large
  243. number of options listed there; most are provided only for
  244. unusual situations and only a few are needed for any one plat-
  245. form.
  246.  
  247.    The defined constants and macros needed for a specific plat-
  248. form are placed in src/h/define.h.  There are many existing
  249. define.h files that can be used as guides.  One for a ``vanilla''
  250. 32-bit platform is:
  251.  
  252.         #define HostStr "new host"
  253.         #define NoCoexpr
  254.  
  255.         #define PORT 1
  256.  
  257. HostStr provides the value used in the Icon keyword &host and
  258. should be changed as appropriate.  NoCoexpr causes Icon to be
  259.  
  260.  
  261.  
  262. IPD238b                       - 4 -              November 1, 1995
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. configured without co-expressions.  This definition can be
  272. removed when co-expressions are implemented.  See Appendix B.
  273. PORT indicates an implementation for an unspecified operating
  274. system. It should be changed to a name for the operating system
  275. for the new platform (see Section 8). Other definitions probably
  276. need to be added, of course.
  277.  
  278.  
  279. 5.__Configuring_Icon_for_a_UNIX_Platform
  280.  
  281.    Since Icon has been implemented for many UNIX platforms, the
  282. easiest way to configure Icon for a new UNIX platform usually is
  283. to copy an existing configuration for a platform that is similar
  284. to the new one.  A few modifications then often suffice to get
  285. Icon running on the new platform.
  286.  
  287.    In addition to define.h, a UNIX configuration also contains
  288. headers used to construct Makefiles. These headers are named
  289. *.hdr. Check these headers for appropriateness.
  290.  
  291.    See also [7] for information concerning the installation of
  292. Icon on a UNIX platform.
  293.  
  294.  
  295. 6.__Adding_Configuration_Information_for_the_X_Window_System
  296.  
  297.    If your platform has X Window software, you may wish to con-
  298. figure Icon Version 9 with X support. Icon's X support consists
  299. of a collection of Icon functions that call Xlib, the standard C
  300. interface to X.  At present, configuration of X Window facilities
  301. is provided only for UNIX platforms.
  302.  
  303.    In order to build Icon with these X Window functions, you will
  304. need to know what library or libraries are required to link in
  305. the X facilities into C programs; this library information is
  306. needed when iconx is built and when iconc links a compiled Icon
  307. executable. Normally, the answer will be -lX11, but on some plat-
  308. forms additional libraries or alternate paths are required.  Con-
  309. sult appropriate manuals to find out what libraries are needed.
  310.  
  311.    If your platform requires the default -lX11, no additional
  312. steps are required in creating your configuration. If your plat-
  313. form requires additional libraries, you will need to add files to
  314. the configuration directory for your particular system.
  315.  
  316.    The files xiconx.mak and xiconc.def, if they are present, are
  317. used during Icon configuration to supply non-default library
  318. information to the interpreter and the compiler.
  319.  
  320.    If, for example, your platform requires an additional pseudo-
  321. terminal library and a BSD-compatibility package in order to link
  322. X applications, you would add an xiconx.mak file with the line
  323.  
  324.  
  325.  
  326.  
  327.  
  328. IPD238b                       - 5 -              November 1, 1995
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.         XLIB= -L../../bin -lX11 -lpt -lbsd
  338.  
  339. and a corresponding xiconc.def file with the line
  340.  
  341.         #define ICONC_XLIB "-lX11 -lpt -lbsd"
  342.  
  343. The former file gets prepended to the Makefile that builds iconx,
  344. while the latter file gets included and compiled into iconc when
  345. X is configured.  Then proceed to the make X-Configure build
  346. step.
  347.  
  348.    In order to build Icon with X support, some platforms also
  349. will have to specify the location of the X header files. Normally
  350. they are in /usr/include/X11; if they are in some other location
  351. on your platform, you will need to locate them and identify the
  352. appropriate option to add to the C compiler command line, usually
  353. -I path, where path is the directory above the X11 include direc-
  354. tory.
  355.  
  356.    For the Icon compiler, this option is added via the COpts
  357. macro in define.h for your configuration. The COpts macro must
  358. define a quoted C string. For the interpreter, the option is
  359. added to the CFLAGS argument of the common.hdr, icont.hdr,
  360. runtime.hdr, and xpm.hdr Makefile headers for your configuration.
  361.  
  362.  
  363. 7.__Configuring_Icon_for_an_MS-DOS_Platform
  364.  
  365.    In the case of MS-DOS, the primary considerations in configur-
  366. ing Icon have to do with the C compiler that is used. There are
  367. existing configurations for several 16- and 32-bit C compilers.
  368.  
  369.    The easiest approach to configuring Icon for a new MS-DOS C
  370. compiler is to copy an existing configuration for a C compiler
  371. that most closely matches the new one.
  372.  
  373.    An MS-DOS configuration includes Makefiles, batch scripts, and
  374. response files for linking. These files should be modified for
  375. the new platform as appropriate. See [8] for more information
  376. concerning the installation of Icon on an MS-DOS platform.
  377.  
  378.  
  379.  
  380. 8.__Configuring_Icon_for_a_New_Operating_System
  381.  
  382.    The conditional compilation for specific operating systems is
  383. concerned primarily with matters such as differences in file nam-
  384. ing, the handling of input and output, and environmental factors.
  385.  
  386.    The presently supported operating systems and their defined
  387. constants are
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394. IPD238b                       - 6 -              November 1, 1995
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.         constant    operating system
  404.         AMIGA       AmigaDos
  405.         ARM         RISC OS for the Acorn Archimedes
  406.         ATARI_ST    Atari ST TOS
  407.         MACINTOSH   Macintosh
  408.         MSDOS       MS-DOS
  409.         MVS         MVS
  410.         OS2         OS/2
  411.         PORT        new
  412.         UNIX        UNIX
  413.         VM          VM/CMS
  414.         VMS         VMS
  415.  
  416. Conditional compilation uses logical expressions composed from
  417. these symbols.  An example is:
  418.  
  419.                        .
  420.                        .
  421.                        .
  422.         #if MSDOS
  423.                        .
  424.                        .              /* code for MS-DOS */
  425.                        .
  426.         #endif
  427.  
  428.         #if UNIX || VMS
  429.                        .
  430.                        .              /* code for UNIX and VMS */
  431.                        .
  432.         #endif
  433.                        .
  434.                        .
  435.                        .
  436.  
  437. Each symbol is defined to be either 1 (for the target operating
  438. system) or 0 (for all other operating systems).  This is accom-
  439. plished by defining the symbol for the target operating system to
  440. be 1 in define.h. In config.h, which includes define.h, all other
  441. operating-system symbols are defined to be 0.
  442.  
  443.    Logical conditionals with #if are used instead of defined or
  444. undefined names with #ifdef to avoid nested conditionals, which
  445. become very complicated and difficult to understand when there
  446. are several alternative operating systems.  Note that it is
  447. important not to use #ifdef accidentally in place of #if, since
  448. all the names are defined.
  449.  
  450.    The file define.h for a different operating system should ini-
  451. tially contain
  452.  
  453.         #define PORT 1
  454.  
  455. as indicated in Section 4.  You can use PORT during the confi-
  456. guration for a different operating system.  Later you should come
  457.  
  458.  
  459.  
  460. IPD238b                       - 7 -              November 1, 1995
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. back and change PORT to some more appropriate name.
  470.  
  471.    Note: The PORT sections contain deliberate syntax errors (so
  472. marked) to prevent sections from being overlooked during confi-
  473. guration. These syntax errors must, of course, be removed before
  474. compilation.
  475.  
  476.    To make it easy to locate places where there is code that may
  477. be dependent on the operating system, such code usually is brack-
  478. eted by unique comments of the following form:
  479.  
  480.         /*
  481.          * The following code is operating-system dependent.
  482.          */
  483.                        .
  484.                        .
  485.                        .
  486.         /*
  487.          * End of operating-system specific code.
  488.          */
  489.  
  490. Between these beginning and ending comments, the code for dif-
  491. ferent operating systems is provided using conditional expres-
  492. sions such as those indicated above.
  493.  
  494.    Look through some of the files for such segments to get an
  495. idea of what is involved.  Each segment contains comments that
  496. describe the purpose of the code.  In some cases, the most likely
  497. code or a suggestion is given in the conditional code under PORT.
  498. In some cases, no code will be needed. In others, code for an
  499. existing operating system may suffice for the new one.
  500.  
  501.    In any event, code for the new operating system name must be
  502. added to each such segment, either by adding it to a logical dis-
  503. junction to take advantage of existing code for other operating
  504. systems, as in
  505.  
  506.         #if MSDOS || UNIX || PORT
  507.              .
  508.              .
  509.              .
  510.         #endif
  511.  
  512.         #if VMS
  513.              .
  514.              .
  515.              .
  516.         #endif
  517.  
  518. and removing the present code for PORT or by filling in the seg-
  519. ment with the appropriate code, as in
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526. IPD238b                       - 8 -              November 1, 1995
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.         #if PORT
  536.              .
  537.              .    /* code for the new operating system */
  538.              .
  539.         #endif
  540.  
  541. If no code is needed for the target operating system in a partic-
  542. ular situation, a comment should be provided so that it is clear
  543. that the situation has been considered.
  544.  
  545.    You may find need for code that is operating-system dependent
  546. at a place where no such dependency presently exists.  If the
  547. situation is idiosyncratic to your operating system, which is
  548. most likely, simply use a conditional for PORT as shown above.
  549. If the situation appears to need different code for several
  550. operating systems, add a new segment similar to the other ones,
  551. being sure to provide something appropriate for all operating
  552. systems.
  553.  
  554.    Do not use #else constructions in these segments; this
  555. increases the probability of logical errors and obscures the
  556. mutually exclusive nature of operating system differences.
  557.  
  558.  
  559. 9.__Trouble_Reports_and_Feedback
  560.  
  561.    If you run into problems, contact us at the Icon Project:
  562.  
  563.         Icon Project
  564.         Department of Computer Science
  565.         The University of Arizona
  566.         P.O. Box 210077
  567.         Tucson, AZ   85721-0077
  568.         U.S.A.
  569.         (520) 621-6613 (voice)
  570.         (520) 621-4246 (fax)
  571.         icon-project@cs.arizona.edu
  572.  
  573.  
  574.  
  575.    Please also let us know of any suggestions for improvements to
  576. the configuration process.
  577.  
  578.    Once you have completed your installation, please send us
  579. copies of any files that you modified so that we can make
  580. corresponding changes in the central version of the source code.
  581. Once this is done, you can get a new copy of the source code
  582. whenever changes or extensions are made to the implementation.
  583. Be sure to include documentation on any features that are not
  584. implemented in your installation or any changes that would affect
  585. users.
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592. IPD238b                       - 9 -              November 1, 1995
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601. References
  602.  
  603.  
  604. 1. R. E. Griswold and M. T. Griswold, The Implementation of the
  605.    Icon Programming Language, Princeton University Press, 1986.
  606.  
  607. 2. R. E. Griswold, Supplementary Information for the
  608.    Implementation of Version 8 of Icon, The Univ. of Arizona Icon
  609.    Project Document IPD112, 1995.
  610.  
  611. 3. R. E. Griswold, Supplementary Information for the
  612.    Implementation  of Version 9 of Icon, The Univ. of Arizona
  613.    Icon Project Document IPD239, 1995.
  614.  
  615. 4. K. Walker, The Run-Time Implementation Language for Icon, The
  616.    Univ. of Arizona Icon Project Document IPD261, 1994.
  617.  
  618. 5. B. W. Kernighan and D. M. Ritchie, The C Programming Language,
  619.    Prentice-Hall, Inc., Englewood Cliffs, NJ, first edition,
  620.    1978.
  621.  
  622. 6. American National Standard for Information Systems -
  623.    Programming Language - C, ANSI X3.159-1989, American National
  624.    Standards Institute, New York, 1990.
  625.  
  626. 7. R. E. Griswold, C. L. Jeffery and G. M. Townsend, Installing
  627.    Version 9 of Icon on UNIX Platforms, The Univ. of Arizona Icon
  628.    Project Document IPD243, 1995.
  629.  
  630. 8. R. E. Griswold, Building Version 9 of Icon for MS-DOS, The
  631.    Univ. of Arizona Icon Project Document IPD249, 1995.
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658. IPD238b                      - 10 -              November 1, 1995
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.        Appendix A - Configuration Parameters and Definitions
  668.  
  669.  
  670. C_Compiler_Considerations
  671.  
  672.    Although the source code for Icon does not require an ANSI C
  673. compiler, installation is likely to be much easier if such a
  674. compiler is used.  It is necessary to specify that the compiler
  675. is ANSI-conformant in order to take advantage of ANSI features.
  676.  
  677.    If your C compiler is completely ANSI-conformant, add
  678.  
  679.         #define Standard
  680.  
  681. to define.h.
  682.  
  683.    Alternatively, you can define one or more of the following
  684. constants if only a portion of your C compiler is ANSI-
  685. conformant:
  686.  
  687.         #define StandardPP  /* standard preprocessor */
  688.         #define StandardC   /* standard compiler proper */
  689.         #define StandardLib /* standard library */
  690.  
  691.  
  692.    If your C compiler supports the void type but is not ANSI-
  693. conformant, add
  694.  
  695.         #define VoidType
  696.  
  697. to define.h.
  698.  
  699.    If your C compiler supports function prototypes but is not
  700. ANSI-conformant, add
  701.  
  702.         #define Prototypes
  703.  
  704.  
  705.    Icon normally defines the C language const with an empty
  706. definition to remove its effect. If you have an ANSI C compiler
  707. and this definition causes problems, add
  708.  
  709.         #define AllowConst
  710.  
  711. to define.h.
  712.  
  713.    On some platforms it may be necessary to provide a different
  714. typedef for pointer than is provided by default.  For example, on
  715. the huge-memory-model implementation of Icon for Microsoft C on
  716. MS-DOS, its define.h contains
  717.  
  718.         typedef huge void *pointer;
  719.  
  720. If an alternative typedef is used for pointer, add
  721.  
  722.  
  723.  
  724. IPD238b                      - 11 -              November 1, 1995
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.         #define PointerDef
  734.  
  735. to define.h to avoid the default one.
  736.  
  737.    Sometimes computing the difference of two pointers causes
  738. problems.  Pointer differences are computed using the macro
  739. DiffPtrs(p1, p2), which has the default definition:
  740.  
  741.         #define DiffPtrs(p1, p2) (word)((p1)-(p2))
  742.  
  743. where word is a typedef that is provided automatically and
  744. usually is long int.
  745.  
  746.    This definition can be overridden in define.h. For example,
  747. Microsoft C for the MS-DOS large memory model uses
  748.  
  749.         #define DiffPtrs(p1, p2) ((word)(p1)-(word)(p2))
  750.  
  751. If you provide an alternate definitions for pointer differencing,
  752. be careful to enclose all arguments in parentheses.
  753.  
  754. Character_Set
  755.  
  756.    The default character set for Icon is ASCII.  If you are
  757. configuring Icon for a platform that uses the EBCDIC character
  758. set, add
  759.  
  760.         #define EBCDIC 1
  761.  
  762. to define.h.
  763.  
  764. Data_Sizing_and_Alignment
  765.  
  766.    There are two constants that relate to the size of C data:
  767.  
  768.         WordBits    (default: 32)
  769.         IntBits     (default: WordBits)
  770.  
  771. IntBits is the number of bits in a C int. It may be 16, 32, or
  772. 64. WordBits is the number of bits in a C long (Icon's ``word'').
  773. It may be 32 or 64.
  774.  
  775.    If your C library expects doubles to be aligned at double-word
  776. boundaries, add
  777.  
  778.         #define Double
  779.  
  780. to define.h.
  781.  
  782.    The word alignment of stacks used by co-expressions is
  783. controlled by
  784.  
  785.         StackAlign  (default: 2)
  786.  
  787.  
  788.  
  789.  
  790. IPD238b                      - 12 -              November 1, 1995
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799. If your platform needs a different alignment, provide an
  800. appropriate definition in define.h.
  801.  
  802.    Most computers have downward-growing C stacks, for which stack
  803. addresses decrease as values are pushed. If you have an upward-
  804. growing stack, for which stack addresses increase as values are
  805. pushed, add
  806.  
  807.         #define UpStack
  808.  
  809. to define.h.
  810.  
  811. Floating-Point_Arithmetic
  812.  
  813.    There are three optional definitions related to floating-point
  814. arithmetic:
  815.  
  816.         Big         (default: 9007199254740092.)
  817.         LogHuge     (default: 309)
  818.         Precision   (default: 10)
  819.  
  820. The values of Big, LogHuge, and Precision give, respectively, the
  821. largest floating-point number that does not lose precision, the
  822. maximum base-10 exponent + 1 of a floating-point number, and the
  823. number of digits provided in the string representation of a
  824. floating-point number. If the default values given above do not
  825. suit the floating-point arithmetic on your platform, add
  826. appropriate definitions to define.h.
  827.  
  828. Options_for_Opening_Files
  829.  
  830.    The options for opening files with fopen() are given by the
  831. following constants:
  832.  
  833.         ReadBinary  (default: "rb")
  834.         ReadText    (default: "r")
  835.         WriteBinary (default: "wb")
  836.         WriteText   (default: "w")
  837.  
  838. These defaults can be changed by definitions in define.h.
  839.  
  840. Library_Routines
  841.  
  842.    Support from some library routines varies from platform to
  843. platform, and names vary. The relevant definitions are:
  844.  
  845.         IconEcvt
  846.         NoIconGcvt
  847.         NoSelect
  848.         SysMem
  849.         SysOpt
  850.         index
  851.         rindex
  852.  
  853.  
  854.  
  855.  
  856. IPD238b                      - 13 -              November 1, 1995
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865. All are undefined by default.
  866.  
  867.    By default, Icon uses the version of ecvt() in the C library.
  868. If you prefer to use Icon's version, add
  869.  
  870.         #define IconEcvt
  871.  
  872. to define.h.
  873.  
  874.    By default, Icon provides its own version of gcvt() to
  875. minimize the differences in the string representations of
  876. floating-point numbers between different platforms. If you prefer
  877. to use the version of gcvt() in your C library, add
  878.  
  879.         #define NoIconGcvt
  880.  
  881. to define.h.
  882.  
  883.    The Icon function delay() uses the C function select().  If
  884. your C library does not have select(), add
  885.  
  886.         #define NoSelect
  887.  
  888. to define.h. The effect of this is that delay() fails and does
  889. not delay execution.
  890.  
  891.    If SysMem is defined and IntBits == WordBits, the C library
  892. routines memcpy() and memset() are used in place of the
  893. corresponding Icon routines memcopy() and memfill().  SysMem is
  894. automatically defined if Standard or StandardLib is defined.
  895.  
  896.    If SysOpt is defined, the C library function getopt() is used
  897. instead of Icon's private version.
  898.  
  899.    Different C compilers use different names for the routines for
  900. locating substrings within strings. The source code for Icon uses
  901. index and rindex. The other possibilities are strchr and strrchr.
  902. If your platform uses the latter names, add
  903.  
  904.         #define index strchr
  905.         #define rindex strrchr
  906.  
  907. to define.h.
  908.  
  909.    Icon uses unlink for the routine that deletes a file.  The
  910. other common name is remove. If your platform uses this name, for
  911. example, add
  912.  
  913.         #define unlink remove
  914.  
  915. to define.h.
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922. IPD238b                      - 14 -              November 1, 1995
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931. Storage_Region_Sizes
  932.  
  933.    The default sizes of Icon's run-time storage regions for
  934. allocated data normally are the same for all implementations.
  935. However, different values can be set:
  936.  
  937.         MaxAbrSize  (default: 500000)
  938.         MaxStrSize  (default: 500000)
  939.  
  940. Since users can override the set values with environment
  941. variables, it is unwise to change them from their defaults except
  942. in unusual cases.
  943.  
  944.    The sizes for Icon's main interpreter stack and co-expression
  945. stacks also can be set:
  946.  
  947.         MStackSize  (default: 10000)
  948.         StackSize   (default: 2000)
  949.  
  950. As for the block and string storage regions, it is unwise to
  951. change the default values except in unusual cases.
  952.  
  953.    Finally, a list used for pointers to strings during garbage
  954. collection, can be sized:
  955.  
  956.         QualLstSize (default: 5000)
  957.  
  958. Like the sizes above, this one normally is best left unchanged.
  959.  
  960. Allocation_Sizing
  961.  
  962.    malloc() is used to allocate space for Icon's storage regions.
  963. This limits region sizes to the value of the largest unsigned
  964. int. Some platforms provide alternative allocation routines for
  965. allocating larger regions.  To change the allocation procedure
  966. for regions, add a definition for AllocReg to define.h. For
  967. example, the huge-memory-model implementation of Icon for
  968. Microsoft C uses the following:
  969.  
  970.         #define AllocReg(n) halloc((long)n, sizeof(char))
  971.  
  972. Note: Icon still uses malloc() for allocating other blocks.  If
  973. this is a problem, it may be possible to change this by defining
  974. malloc in define.h, as in
  975.  
  976.         #define malloc lmalloc
  977.  
  978. where lmalloc() is a local routine for allocating large blocks of
  979. memory.  If this is done, and the size of the allocation is not
  980. unsigned int, add an appropriate definition for the type by
  981. defining AllocType in define.h, such as
  982.  
  983.         #define AllocType unsigned long int
  984.  
  985.  
  986.  
  987.  
  988. IPD238b                      - 15 -              November 1, 1995
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.    It is also necessary to add a definition for the limit on the
  998. size of an Icon region:
  999.  
  1000.         #define MaxBlock n
  1001.  
  1002. where n is the maximum size allowed (the default for MaxBlock is
  1003. MaxUnsigned, the largest unsigned int). It generally is not
  1004. advisable to set MaxBlock to the largest size an alternative
  1005. allocation routine can return. For the huge-memory-model
  1006. implementation mentioned above, MaxBlock is 256000.
  1007.  
  1008. File_Name_Suffixes
  1009.  
  1010.    The suffixes used to identify Icon source programs, ucode
  1011. files, and icode files may be specified in define.h:
  1012.  
  1013.         #define SourceSuffix(default: ".icn")
  1014.         #define U1Suffix    (default: ".u1")
  1015.         #define U2Suffix    (default: ".u2")
  1016.         #define USuffix     (default: ".u")
  1017.         #define IcodeSuffix (default: "")
  1018.         #define IcodeASuffix(default: "")
  1019.  
  1020. USuffix is used for the abbreviation that icont understands in
  1021. place of the complete U1Suffix or U2Suffix. IcodeASuffix is an
  1022. alternative suffix that iconx uses when searching for icode files
  1023. specified without a suffix. For example, on MS-DOS, IcodeSuffix
  1024. is ".icx" and IcodeASuffix is ".ICX".
  1025.  
  1026.    If values other than the defaults are specified, care must be
  1027. taken not to introduce conflicts or collisions among names of
  1028. different types of files.
  1029.  
  1030. Paths
  1031.  
  1032.    If icont is given a source program in a directory different
  1033. from the local one (``current working directory''), there is a
  1034. question as to where ucode and icode files should be created: in
  1035. the local directory or in the directory that contains the source
  1036. program. On most platforms, the appropriate place is in the local
  1037. directory (the user may not have write permission in the
  1038. directory that contains the source program).  However, on some
  1039. platforms, the directory that contains the source file is
  1040. appropriate. By default, the directory for creating new files is
  1041. the local directory. The other choice can be selected by adding
  1042.  
  1043.         #define TargetDir SourceDir
  1044.  
  1045.  
  1046. UNIX_Bootstrap_Headers
  1047.  
  1048.    A bootstrap header is used to make UNIX icode files
  1049. executable.  This header normally is a simple shell script. To
  1050. use an executable program for a header, as in Version 8 of Icon,
  1051.  
  1052.  
  1053.  
  1054. IPD238b                      - 16 -              November 1, 1995
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063. add
  1064.  
  1065.         #define NoShellHeader
  1066.  
  1067. to define.h.  The space reserved for an executable program header
  1068. is determined by
  1069.  
  1070.         #define MaxHdr (default: 4096)
  1071.  
  1072.  
  1073.    On some UNIX platforms, many routines may be included in the
  1074. header even if they are not needed.  Start by assuming this is
  1075. not a problem, but if MaxHeader has to be made impractically
  1076. large, you can eliminate the header by adding
  1077.  
  1078.         #define NoHeader
  1079.  
  1080. to define.h.  Note: If NoHeader is defined, the values of MaxHdr
  1081. and NoShellHeader are irrelevant.
  1082.  
  1083.    The effect of this definition is to render Icon programs non-
  1084. executable. Instead, they must be run by using the -x option
  1085. after the program name when icont is used, as in
  1086.  
  1087.         icont prog.icn -x
  1088.  
  1089. Such a program also can be run as an argument of iconx, as in
  1090.  
  1091.         iconx prog
  1092.  
  1093. where prog is the result of translating and linking prog.icn as
  1094. in the previous example.
  1095.  
  1096. Command-Line_Options
  1097.  
  1098.    The command-line options that are supported by icont and iconc
  1099. are defined by IconOptions. The default value (see config.h) will
  1100. do for most platforms, but an alternative can be included in
  1101. define.h.
  1102.  
  1103.    Similarly, the error message produced for erroneous command
  1104. lines is defined by TUsage for icont and CUsage for iconc. The
  1105. default values, which should correspond to the value of
  1106. IconOptions, are in config.h, but may be overridden by
  1107. definitions in define.h.
  1108.  
  1109. Environment_Variables
  1110.  
  1111.    If your platform does not support environment variables (via
  1112. the run-time library routine getenv), add the following line to
  1113. define.h:
  1114.  
  1115.         #define NoEnvVars
  1116.  
  1117.  
  1118.  
  1119.  
  1120. IPD238b                      - 17 -              November 1, 1995
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129. This disables Icon's ability to change internal parameters to
  1130. accommodate special user needs (such as using memory region sizes
  1131. different from the defaults), but does not otherwise interfere
  1132. with the use of Icon.
  1133.  
  1134. Host_Identification
  1135.  
  1136.    The identification of the host computer as given by the Icon
  1137. keyword &host needs to be specified in define.h.  The usual way
  1138. to to this is to add
  1139.  
  1140.         #define HostStr "identification"
  1141.  
  1142. to define.h.
  1143.  
  1144.    Several alternatives are available on UNIX platforms for host
  1145. identification.  To use one of these, remove the definition of
  1146. HostStr and provide an alternative as follows.
  1147.  
  1148.    On some versions of UNIX, notably Version 7 and 4.1bsd, the
  1149. file /usr/include/whoami.h contains the host name. If your system
  1150. has this file and you want to use this name, add
  1151.  
  1152.         #define WhoHost
  1153.  
  1154. to define.h.
  1155.  
  1156.    Some versions of UNIX, notably 4.2bsd and 4.3bsd, provide the
  1157. host name via the gethostname(2) system call. If your system
  1158. supports this system call and you want to use this name, add
  1159.  
  1160.         #define GetHost
  1161.  
  1162. to define.h.
  1163.  
  1164.    Some versions of UNIX, such as System V, provide the host name
  1165. via the uname(2) system call. If your system supports this call
  1166. and you want to use this name, add
  1167.  
  1168.         #define UtsName
  1169.  
  1170. to define.h.
  1171.  
  1172.    Note: Only one of these methods of specifying the host name
  1173. can be used.
  1174.  
  1175. Exit_Codes
  1176.  
  1177.    Exit codes are determined by the following definitions:
  1178.  
  1179.         NormalExit  (default: 0)
  1180.         ErrorExit   (default: 1)
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186. IPD238b                      - 18 -              November 1, 1995
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195. Clock_Rate
  1196.  
  1197.    Hz defines the units returned by the times() function call.
  1198. Check the documentation for this function on your platform. If it
  1199. says that times are returned in terms of 1/60 second, no action
  1200. is needed. Otherwise, define Hz in define.h to be the number of
  1201. times() units in one second.
  1202.  
  1203.    The documentation may refer you to an additional file such as
  1204. /usr/include/sys/param.h. If so, check the value there, and
  1205. define Hz accordingly.
  1206.  
  1207. Dynamic_Hashing_Constants
  1208.  
  1209.    Four parameters configure the implementation of tables and
  1210. sets:
  1211.  
  1212.         HSlots      Initial number of hash buckets; it must be a
  1213.                     power of 2
  1214.  
  1215.         HSegs       Maximum number of hash bucket segments
  1216.  
  1217.         MaxHLoad    Maximum allowable loading factor
  1218.  
  1219.         MinHLoad    Minimum loading factor for new structures
  1220.  
  1221.    The default values (listed below) are appropriate for most
  1222. platforms. If you want to change the values, read the discussion
  1223. that follows.
  1224.  
  1225.    Every set or table starts with HSlots hash buckets, using one
  1226. bucket segment.  When the average hash bucket exceeds MaxHLoad
  1227. entries, the number of buckets is doubled and one more segment is
  1228. consumed.  This repeats until HSegs segments are in use; after
  1229. that, structure still grows but no more hash buckets are added.
  1230.  
  1231.    MinHLoad is used only when copying a set or table or when
  1232. creating a new set through the intersection, union, or difference
  1233. of two other sets.  In these cases a new set may be more lightly
  1234. loaded than otherwise, but never less than MinHLoad if it exceeds
  1235. a single bucket segment.
  1236.  
  1237.    For all machines, the default load factors are 5 for MaxHLoad
  1238. and 1 for MinHLoad.  Because splitting or combining buckets
  1239. halves or doubles the load factor, MinHLoad should be no more
  1240. than half MaxHLoad.  The average number of elements in a hash
  1241. bucket over the life of a structure is about 2/3xMaxHLoad,
  1242. assuming the structure is not so huge as to be limited by HSegs.
  1243. Increasing MaxHLoad delays the creation of new hash buckets,
  1244. reducing memory demands at the expense of increased search times.
  1245. It has no effect on the memory requirements of minimally-sized
  1246. structures.
  1247.  
  1248.    HSlots and HSegs interact to determine the minimum size of a
  1249.  
  1250.  
  1251.  
  1252. IPD238b                      - 19 -              November 1, 1995
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261. structure and its maximum efficient capacity.  The size of an
  1262. empty set or table is directly related to HSegs+HSlots; smaller
  1263. values of these parameters reduce the memory needs of programs
  1264. using many small structures.  Doubling HSlots delays the onset of
  1265. the first structure reorganization until twice as many elements
  1266. have been inserted.  It also doubles the capacity of a structure,
  1267. as does increasing HSegs by 1.
  1268.  
  1269.    The maximum number of hash buckets is HSlotsx(2^(HSegs-1)).  A
  1270. structure can be considered ``full'' when it contains MaxHLoad
  1271. times that many entries; beyond that, lookup times gradually
  1272. increase as more elements are added.  Until a structure becomes
  1273. full, the values of HSlots and HSegs do not affect lookup times.
  1274.  
  1275.    For machines with 16-bit ints, the defaults are 4 for HSlots
  1276. and 6 for HSegs.  Sets and tables grow from 4 hash buckets to a
  1277. maximum of 128, and become full at 640 elements.  For other
  1278. machines, the defaults are 8 for HSlots and 10 for HSegs.  sets
  1279. and tables grow from 8 hash buckets to a maximum of 4096, and
  1280. become full at 20480 elements.
  1281.  
  1282. Keyboard_Functions
  1283.  
  1284.    If your platform supports the keyboard functions getch(),
  1285. getche(), and kbhit(), add
  1286.  
  1287.         #define KeyboardFncs
  1288.  
  1289. to define.h.
  1290.  
  1291.    Some UNIX platforms are capable of supporting the keyboard
  1292. functions. A UNIX platform should be able to to support the
  1293. keyboard functions if it supports ioctl() in a manner that is
  1294. compatible with either BSD/SunOS or System V. The keyboard
  1295. functions are enabled by default on platforms known to be
  1296. compatible, including SunOS, Xenix, System V/386, and a few
  1297. others.
  1298.  
  1299.    On other platforms, in addition to adding
  1300.  
  1301.         #define KeyboardFncs
  1302.  
  1303. to define.h as described above, select one of two methods for
  1304. calling ioctl() supported in the source code for Icon, and add it
  1305. to define.h:
  1306.  
  1307.         #define HaveTioc
  1308.  
  1309. or
  1310.  
  1311.         #define HaveTermio
  1312.  
  1313.  
  1314. Use HaveTioc if you have a BSD-based platform and have the system
  1315.  
  1316.  
  1317.  
  1318. IPD238b                      - 20 -              November 1, 1995
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327. include files <sys/ioctl.h>, <errno.h>, and <sys/signal.h>. The
  1328. system ioctl() call must support TIOCSETN, TIOCGETP, TIOCGETC,
  1329. and FIONREAD.
  1330.  
  1331.    Use HaveTermio if you have a System V, Xenix 386, or
  1332. compatible platform and have the system include files
  1333. <sys/termio.h>, <sys/ioctl>, <sys/errno.h>, and <sys/signal.h>.
  1334. The system ioctl() call must support TCSETA, TCGETA, and (unless
  1335. it is a Xenix platform), FIONREAD.
  1336.  
  1337.    If your platform supports neither of these methods, you may be
  1338. able to write your own keyboard functions. See
  1339. src/runtime/fsys.r.
  1340.  
  1341. Co-Expressions
  1342.  
  1343.    The implementation of co-expressions requires an assembly-
  1344. language context switch.  If your platform does not have a co-
  1345. expression context switch, you can implement one as described in
  1346. Appendix B. Alternatively, you can disable co-expressions by
  1347. adding
  1348.  
  1349.         #define NoCoexpr
  1350.  
  1351. to define.h.
  1352.  
  1353. Other_Optional_Features
  1354.  
  1355.    Some features of Icon are optional. Some of these normally are
  1356. enabled, while others normally are disabled. The features that
  1357. normally are enabled can be disabled to, for example, reduce the
  1358. size of the executable files. A negative form of definition is
  1359. used for these, as in
  1360.  
  1361.         #define NoLargeInts
  1362.  
  1363. which can be added to define.h to disable large-integer
  1364. arithmetic. It may be necessary to disable large-integer
  1365. arithmetic on computers with a small amount of memory, since the
  1366. feature increases the size of the run-time system by 15-20%.
  1367.  
  1368.    If your platform supports the system() function for executing
  1369. command line, add
  1370.  
  1371.         #define SystemFnc
  1372.  
  1373. to define.h.
  1374.  
  1375.    If your platform supports the dlopen() and dlsym() functions
  1376. for dynamic loading, add
  1377.  
  1378.         #define LoadFunc
  1379.  
  1380. to define.h
  1381.  
  1382.  
  1383.  
  1384. IPD238b                      - 21 -              November 1, 1995
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393. X_Window_Facilities
  1394.  
  1395.    The files needed to build Icon with X Window facilities are
  1396. not in the same places on all platforms. If Icon fails to build
  1397. because an include file needed by X cannot be found, it may be
  1398. necessary to edit src/h/sys.h to reflect the local location.
  1399.  
  1400.    Some early versions of X Window Systems, notably X11R3, do not
  1401. support the attribute iconic. If this is the case for your
  1402. platform, add
  1403.  
  1404.         #define NoIconify
  1405.  
  1406. to define.h. This disables the attribute iconic, causing
  1407. references to it to fail.
  1408.  
  1409. Compiler_Options
  1410.  
  1411.    The C compiler called by the Icon compiler to process its
  1412. output defaults to cc. If you want to use a different C compiler,
  1413. add
  1414.  
  1415.         #define CComp "name"
  1416.  
  1417. to define.h, where name is the name of the C compiler you want
  1418. the Icon compiler to use. Note the quotation marks surrounding
  1419. the name. For example, to use Gnu C, add
  1420.  
  1421.         #define CComp "gcc"
  1422.  
  1423.  
  1424.    By default, the C compiler is called with no options. If you
  1425. want specific options, add
  1426.  
  1427.         #define COpts "options"
  1428.  
  1429. to define.h. Again, note the quotation marks.  For example, to
  1430. request C optimizations, you might add
  1431.  
  1432.         #define COpts "-O"
  1433.  
  1434.  
  1435.    If your system does not have ranlib, add
  1436.  
  1437.         #define NoRanlib
  1438.  
  1439. to define.h.
  1440.  
  1441. Debugging_Code
  1442.  
  1443.    Icon contains some code to assist in debugging. It is enabled
  1444. by the definitions
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450. IPD238b                      - 22 -              November 1, 1995
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.         #define DeBugTrans       /* debugging code for the translator in icont */
  1460.         #define DeBugLinker      /* debugging code for the linker in icont */
  1461.         #define DeBugIconx       /* debugging code for the run-time */
  1462.  
  1463. All three of these are automatically defined if DeBug is defined.
  1464.  
  1465.    The debugging code for the translator consists of functions
  1466. for dumping symbol tables (see icont/tsym.c). These functions are
  1467. rarely needed and there are no calls to them in the source code
  1468. as it is distributed.
  1469.  
  1470.    The debugging code for the linker consists of a function for
  1471. dumping the code region (see icont/lcode.c) and code for
  1472. generating a debugging file that is a printable image of the
  1473. icode file produced by the linker. This debugging file, which is
  1474. produced if the option -L is given on the command line when icont
  1475. is run, may be useful if icode files are incorrect.
  1476.  
  1477.    The debugging code for the executor consists of a few validity
  1478. checks at places where problems have been encountered in the
  1479. past. It also provides functions for dumping Icon values. See
  1480. runtime/rmisc.r and runtime/rmemmgt.r.
  1481.  
  1482.  
  1483.    When installing Icon on a new operating system, it is
  1484. advisable to enable the debugging code until Icon is known to be
  1485. running properly.  The code produced is innocuous and adds only a
  1486. few percent to the size of the executable files. It should be
  1487. removed by deleting the definition listed above from define.h as
  1488. the final step in the implementation for a new operating system.
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516. IPD238b                      - 23 -              November 1, 1995
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.     Appendix B - Implementing a Co-Expression Context Switch
  1526.  
  1527.  
  1528.  
  1529.    If your platform does not have a co-expression context switch,
  1530. you can implement one as described in this appendix.  Note: If
  1531. your platform does not allow the C stack to be at an arbitrary
  1532. place in memory, there is probably little hope of implementing
  1533. co-expressions.
  1534.  
  1535.    The routine coswitch() is needed for context switching. This
  1536. routine requires assembly language, since it must manipulate
  1537. hardware registers.  It either can be written as a C routine with
  1538. asm directives or directly as an assembly language routine.
  1539.  
  1540.    Calls to the context switch have the form
  1541. coswitch(old_cs,new_cs,first), where old_cs is a pointer to an
  1542. array of words (C longs) that contain C state information for the
  1543. current co-expression, new_cs is a pointer to an array of words
  1544. that hold C state information for a co-expression to be
  1545. activated, and first is 1 or 0, depending on whether or not the
  1546. new co-expression has or has not been activated before.  The
  1547. zeroth element of a C state array always contains the hardware
  1548. stack pointer (sp) for that co-expression. The other elements can
  1549. be used to save any C frame pointers and any other registers your
  1550. C compiler expects to be preserved across calls.
  1551.  
  1552.    The default size of the array for saving the C state is 15.
  1553. This number may be changed by adding
  1554.  
  1555.         #define CStateSize n
  1556.  
  1557. to define.h, where n is the number of elements needed.
  1558.  
  1559.    The first thing coswitch does is to save the current pointers
  1560. and registers in the old_cs array. Then it tests first.  If first
  1561. is zero, coswitch sets sp from new_cs[0], clears the C frame
  1562. pointers, and calls new_context. If first is not zero, it loads
  1563. the (previously saved) sp, C frame pointers, and registers from
  1564. new_cs and returns.
  1565.  
  1566.    Written in C, coswitch has the form:
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582. IPD238b                      - 24 -              November 1, 1995
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.         /*
  1592.          * coswitch
  1593.          */
  1594.         coswitch(old_cs, new_cs, first)
  1595.         long *old_cs, *new_cs;
  1596.         int first;
  1597.         {
  1598.                             .
  1599.                             .
  1600.                             .
  1601.                     /* save sp, frame pointers, and other registers in old_cs */
  1602.                             .
  1603.                             .
  1604.                             .
  1605.            if (first == 0) {          /* this is first activation */
  1606.                             .
  1607.                             .
  1608.                             .
  1609.                     /* load sp from new_cs[0] and clear frame pointers */
  1610.                             .
  1611.                             .
  1612.                             .
  1613.               new_context(0, 0);
  1614.               syserr("new_context() returned in coswitch");
  1615.               }
  1616.  
  1617.  
  1618.            else {
  1619.                             .
  1620.                             .
  1621.                             .
  1622.                     /* load sp, frame pointers, and other registers from new_cs */
  1623.                             .
  1624.                             .
  1625.                             .
  1626.            }
  1627.         }
  1628.  
  1629.  
  1630.    After you implement coswitch, remove the #define NoCoexpr from
  1631. define.h.  Verify that StackAlign and UpStack, if needed, are
  1632. properly defined.
  1633.  
  1634.    To test your context switch, run the programs in
  1635. tests/general/coexpr.lst.  Ideally, there should be no
  1636. differences in the comparison of outputs.
  1637.  
  1638.    If you have trouble with your context switch, the first thing
  1639. to do is double-check the registers that your C compiler expects
  1640. to be preserved across calls - different C compilers on the same
  1641. computer may have different requirements.
  1642.  
  1643.    Another possible source of problems is built-in stack
  1644. checking.  Co-expressions rely on being able to specify an
  1645.  
  1646.  
  1647.  
  1648. IPD238b                      - 25 -              November 1, 1995
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657. arbitrary region of memory for the C stack. If your C compiler
  1658. generates code for stack probes that expects the C stack to be at
  1659. a specific location, you may need to disable this code or replace
  1660. it with something more appropriate.
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714. IPD238b                      - 26 -              November 1, 1995
  1715.  
  1716.  
  1717.