home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / i / icon / 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 imple