![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tr86-11.roff CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / cmd / icon / docs|
Return to tr86-11.roff CVS log | Up to [Research Unix] / researchv10dc / cmd / icon / docs |
1.1 ! root 1: .so tmac.tr ! 2: .ds M \fC ! 3: .de Ta ! 4: .ta .8i +.8i +.8i +.8i +.8i +.8i +.8i ! 5: .. ! 6: .de Px ! 7: .ta 3.5i ! 8: .. ! 9: .ds CF \s10- \\n(PN - \s0 ! 10: .de Ap ! 11: .bp ! 12: .ce 10 ! 13: \f3\\$1\f1 ! 14: .ce 0 ! 15: .sp 2 ! 16: .if !''\\$2' 'so \\$2 ! 17: .. ! 18: .TR 86-11b ! 19: .DA "June 30, 1986" ! 20: .Gi ! 21: .TL ! 22: Installation Guide for Version 6.0 of Icon on UNIX Systems ! 23: .AU ! 24: Ralph E. Griswold ! 25: .AE ! 26: .tr *\(** ! 27: .NH ! 28: Introduction ! 29: .PP ! 30: If you are installing Version 6.0 of Icon on a computer with a version ! 31: of \*U ! 32: for which configuration information already ! 33: .Un ! 34: has been developed \(em a ``supported system'' \(em the installation may be as simple as ! 35: issuing a few \*Mmake\fR commands. ! 36: The presently supported systems are Amdahl 580 (UTS), the AT&T 3B series, ! 37: the HP 9000 (HP-UX), personal computers running PC/IX and XENIX, ! 38: the PDP-11 (Version 7 UNIX), the Pyramid 90x, ! 39: the Ridge 32, the Sun Workstation, and the VAX-11 (Berkeley and System V UNIX). ! 40: .PP ! 41: If you are installing Version 6.0 on a supported system, start with the next section. ! 42: Otherwise, skip to Section 7. ! 43: .PP ! 44: If you are installing Version 6.0 on a system that is running an earlier ! 45: version of Icon, be sure to read Section 6 concerning possible impacts ! 46: of Version 6.0 on present users. ! 47: .NH ! 48: Standard Installation ! 49: .PP ! 50: The standard installation uses configuration information that is ! 51: included with the distribution. This configuration information ! 52: should be correct for most sites. If you want to check it out ! 53: before proceeding, read Section 7. ! 54: .PP ! 55: For the standard installation, all files, including executable binaries, ! 56: are placed ! 57: in the directory \*M/usr/icon/v6\fR\s-2\u\(dg\d\s0. If you want executable binary files ! 58: .FS ! 59: .sp .5 ! 60: \s-2\u\(dg\d\s0\^For HP-UX, the standard location is \*M/users/icon/v6\fR. ! 61: .FE ! 62: in some other location, ! 63: you must edit a file before proceeding. Think twice about this. ! 64: Icon executable binary files are referenced by full path names; they ! 65: cannot be moved, so it is important to select the correct paths at the start. ! 66: See Appendix A if you want to change the location of binary files. ! 67: .PP ! 68: The Icon distribution is rooted in \*Mv6\fR. ! 69: Unload the distribution files ! 70: into the installation directory (the standard installation directory ! 71: is \*M/usr/icon\fR). ! 72: See Appendix B, if necessary, for information on unloading ! 73: the distribution files. ! 74: See Appendix C for a listing of the distribution hierarchy. ! 75: .PP ! 76: In the description that follows, paths are relative to \*Mv6\fR. ! 77: For example, \*MMakefile\fR refers to the \*MMakefile\fR in the ! 78: top level of the distribution hierarchy. ! 79: .PP ! 80: There are four phases of the installation: setup, compilation, ! 81: installation, ! 82: and testing. ! 83: All are done using \*MMakefile\fR in \*Mv6\fR. ! 84: .PP ! 85: Setup is based on the name of the system being installed, ! 86: as shown in the right column of the following ! 87: table: ! 88: .DS ! 89: .ft R ! 90: .ta 2i 3.7i ! 91: .sp .5 ! 92: \fIcomputer UNIX system name\fR ! 93: .sp .5 ! 94: Amdahl 580 UTS \*Mamdahl_uts\fR ! 95: AT&T 3B2/5/15 System V \*Matt3b5\fR ! 96: AT&T 3B20 System V \*Matt3b20\fR ! 97: HP 9000 HP-UX \*Mhp9000\fR ! 98: IBM PC/XT/AT PC/IX \*Mpc_pcix\fR ! 99: IBM AT XENIX \*Mpc_xenix_smm\fR ! 100: PDP-11 (separate I & D spaces) Version 7 \*Mpdp11_v7\fR ! 101: Pyramid 90x Berkeley 4.2bsd \*Mpyramid_bsd\fR ! 102: Ridge 32 ROS \*Mridge\fR ! 103: Sun Workstation UNIX 4.2 \*Msun\fR ! 104: VAX-11 Berkeley 4.1bsd \*Mvax_4.1bsd\fR ! 105: VAX-11 Berkeley 4.2bsd & 4.3bsd \*Mvax_bsd\fR ! 106: VAX-11 System V \*Mvax_sysv\fR ! 107: .DE ! 108: Before proceeding, check the status of the system you plan to install. ! 109: In \*Mv6\fR ! 110: .Ds ! 111: make Status name=\fIname\fR ! 112: .De ! 113: where \fIname\fR is one of those given above. For example, ! 114: .Ds ! 115: make Status name=sun ! 116: .De ! 117: lists the status of Version 6.0 on the Sun Workstation. ! 118: .PP ! 119: There are some supported systems for which not all features of Version ! 120: 6.0 are implemented. If this is the case for your system, ! 121: proceed with the installation, but you may wish to implement the ! 122: missing features later. For this, see Section 7. ! 123: .PP ! 124: Start the installation with ! 125: .Ds ! 126: make Setup name=\fIname\fR ! 127: .De ! 128: where \fIname\fR is the name of your system as described above. ! 129: For example, ! 130: .Ds ! 131: make Setup name=vax_bsd ! 132: .De ! 133: configures Version 6.0 of Icon for a VAX running Berkeley 4.\fIn\fRbsd. ! 134: .PP ! 135: Compilation and installation are done by ! 136: .Ds ! 137: make Icon Install ! 138: .De ! 139: This takes a while. There may be warning messages on some systems, ! 140: but there should be no fatal errors. ! 141: .PP ! 142: For a standard installation, a few simple tests are sufficient to ! 143: check that Icon is running properly. The following does the job: ! 144: .Ds ! 145: make Test-icon ! 146: .De ! 147: This test compares local program output with the expected output. ! 148: There should be no differences. ! 149: .PP ! 150: If all is well, you may wish to copy the manual page \*Micont.1\fR in ! 151: \*Mv6/docs\fR to your local public manual area. ! 152: That's all there is to a standard installation. ! 153: .NH ! 154: Personalized Interpreters ! 155: .PP ! 156: Version 6.0 contains a ``personalized interpreter'' facility ! 157: [1] that allows an individual to modify and ! 158: extend a private copy of Icon's run-time system. To install this optional ! 159: component of Icon, ! 160: .Ds ! 161: make PI ! 162: .De ! 163: For testing, do ! 164: .Ds ! 165: make Test-pi ! 166: .De ! 167: Expect some differences in this test, since one function checks local ! 168: environment variables. ! 169: .PP ! 170: You may want to copy ! 171: the shell script \*Micon_pi\fR, which makes personalized interpreters, ! 172: from \*Mv6\fR to a public area for general use. You also may want to copy ! 173: the manual page ! 174: \*Micon_pi.1\fR in \*Mv6/docs\fR to the public manual area. ! 175: .NH ! 176: Icon Program Library ! 177: .PP ! 178: The Icon program library [2] contains a variety of programs ! 179: and procedures. To install this optional component of the Version 6.0 ! 180: distribution, ! 181: .Ds ! 182: make Ipl ! 183: .De ! 184: This puts compiled programs in \*Mv6/ipl/progs\fR and translated ! 185: procedures in \*Mv6/ipl/procs\fR. To test the library, ! 186: .Ds ! 187: make Test-ipl ! 188: .De ! 189: You can copy ! 190: the programs in \*Mv6/ipl/progs\fR and the translated procedures ! 191: in \*Mv6/ipl/procs\fR to other locations if you want. ! 192: .NH ! 193: Cleaning Up ! 194: .PP ! 195: After Icon and any optional components have be installed, you ! 196: can remove non-source files and test results by ! 197: .Ds ! 198: make Clean ! 199: .De ! 200: You also can remove source files, but think twice about this, ! 201: since source files may be useful to persons using personalized ! 202: interpreters. ! 203: .NH ! 204: User Impacts ! 205: .PP ! 206: The language features of Version 6.0 are very similar to those of ! 207: preceding Versions 5.9 and 5.10. Therefore, most user programs ! 208: that run properly under versions 5.9 and 5.10 should run properly ! 209: under Version 6.0. ! 210: However, users should be encouraged to read the Version 6.0 description ! 211: [3]. ! 212: There are two possible sources of operational problems: version checking ! 213: and link path specifications. ! 214: .PP ! 215: Prior to Version 6.0, there was no check that ucode files produced by the ! 216: Icon translator and executable icode files produced by the Icon linker ! 217: were compatible with the Icon run-time system. ! 218: Incompatible files simply caused mysterious program malfunction. ! 219: Version 6.0 produces ! 220: version-numbered files and checks compatibility. An attempt ! 221: to use a file produced by an earlier version results in a error ! 222: message from Version 6.0 (\*Mucode file has no version identification\fR). ! 223: .PP ! 224: Since executable files contain the full path name of the run-time ! 225: system (\*Miconx\fR), proper installation should avoid problems with ! 226: version numbers in icode files. ! 227: Ucode files, which are typically used in libraries included by ! 228: the \*Mlink\fR declaration, are more troublesome. ! 229: Incompatible versions may be confusing, ! 230: since the source of the ! 231: problem may be hidden. ! 232: Users should be advised to re-translate all ucode files when Version 6.0 ! 233: is installed. ! 234: Similarly, if an earlier version of the Icon program library is in ! 235: use, it should be replaced by the Version 6.0 library, built under ! 236: Version 6.0 as described in Section 4. (Some earlier Icon program ! 237: library material has been deleted in Version 6.0; if such material is ! 238: in use, it can be added to the Version 6.0 library.) ! 239: .PP ! 240: The syntax of the \*MIPATH\fR environment variable, which is used ! 241: by the linker to search for files given in \*Mlink\fR declarations, ! 242: has changed in Version 6.0. Previously the separator was a colon; ! 243: in Version 6.0 it is a blank. Problems with \*MIPATH\fR usually ! 244: are indicated by the linker error message \*MCan't resolve referernce to file ! 245: \&\*(El \fR. ! 246: .NH ! 247: Configuring Version 6.0 for a New System ! 248: .PP ! 249: Version 6.0 of Icon makes two assumptions about sizes: ! 250: .RS ! 251: .IP 1. 4n ! 252: C \fIint\fRs are either 16 or 32 bits long. ! 253: .IP 2. ! 254: The sizes of C \fIint\fRs and C pointers are the same. ! 255: .RE ! 256: .LP ! 257: If your system violates either of these assumptions, don't try to ! 258: go on \(em but check back with us, since we are working on ! 259: removing these restrictions. ! 260: .PP ! 261: To install Icon on a system that is not supported in the ! 262: distribution, you must create a directory to hold files ! 263: containing configuration information. In the description ! 264: that follows, this directory is referred to as your ! 265: configuration directory. ! 266: .PP ! 267: First you need to select a name for your system. ! 268: The name should consist of a mnemonic for the computer, which may be followed ! 269: by an underscore and a mnemonic for the operating system, ! 270: in case there may be more than one operating system for the ! 271: computer. ! 272: Examples are \*Mvax_bsd\fR and \*Mvax_sysv\fR. ! 273: You may want to append an additional ! 274: underscore and a qualification if there is more than more likely ! 275: implementation for a given computer and operating system. An ! 276: example is \*Mpc_xenix_smm\fR for the small memory model ! 277: implementation of Icon on XENIX. ! 278: .PP ! 279: To build and initialize a new configuration directory, ! 280: .Ds ! 281: make System name=\fIname\fR ! 282: .De ! 283: where \fIname\fR is the name of your system. ! 284: .PP ! 285: Now ! 286: .Ds ! 287: cd v6/setup/\fIname\fR ! 288: .De ! 289: where you need to edit some files. The files that may need editing are ! 290: .Ds ! 291: .ta 1.2i ! 292: paths.h \fRpaths for executable binary files\*M ! 293: header.hdr \fRsizing for a bootstrap header file\*M ! 294: icont.hdr \fRflags for command processor \*MMakefile ! 295: iconx.hdr \fRflags and other definitions for the run-time system \*MMakefile ! 296: link.hdr \fRflags for the linker \*MMakefile ! 297: tran.hdr \fRflags for the translator \*MMakefile ! 298: pi.hdr \fRflags for the personalized interpreter \*MMakefile ! 299: config.trl \fRother configuration definitions\*M ! 300: rswitch.c \fRco-expression context switch\*M ! 301: rover.c \fRarithmetic overflow checks\*M ! 302: Ranlib \fRlibrary randomizer for personalized interpreters\*M ! 303: .De ! 304: .NH 2 ! 305: \*Mpaths.h\fR ! 306: .PP ! 307: If \*M/usr/icon/v6\fR is acceptable as a location for all Icon ! 308: files, you don't have to change \*Mpaths.h\fR. ! 309: Otherwise, handle the file \*Mpaths.h\fR as described in Appendix A. ! 310: .NH 2 ! 311: \*Mheader.hdr\fR ! 312: .PP ! 313: The file \*Mheader.hdr\fR contains a definition for \*MMaxHdr\fR, ! 314: which determines the amount of space that is reserved for \*Miconx.hdr\fR, ! 315: the bootstrapping program that gets Icon programs into execution. ! 316: You cannot determine the most appropriate value of \*MMaxHdr\fR until ! 317: after Icon has been compiled. ! 318: An overly large value just wastes file space in compiled Icon programs, ! 319: but a value that is not large enough prevents compiled Icon ! 320: programs from executing. ! 321: .PP ! 322: The value provided, 4096, is more than enough for most systems ! 323: and you can wait to change it until later. Remember, however, ! 324: that if Icon programs fail to execute, this value may be ! 325: too small. ! 326: .PP ! 327: After all else has been done and Icon has been compiled and ! 328: tested, come back to this file and change the value of \*MMaxHdr\fR ! 329: to the size of \*Mv6/src/icont/iconx.hdr\fR. You may need to ! 330: round the size up on some systems. ! 331: In any event, make \*MMaxHdr\fR a hundred or so larger than the ! 332: size of \*Miconx.hdr\fR to allow for a somewhat larger size ! 333: that may be needed for personalized interpreters. ! 334: .PP ! 335: On some systems, particularly UNIX emulators, many routines may be ! 336: included by the loader regardless of need. In this case, the size ! 337: of \*Miconx.hdr\fR may be impractically large. If this is the case ! 338: on your system, the header file can be eliminated altogether by ! 339: adding ! 340: .Ds ! 341: #define NoHeader ! 342: .De ! 343: to \*Mconfig.trl\fR (see Section 7.4). The effect of this definition ! 344: is to render Icon programs non-executable. Instead, they must be ! 345: run by using the \*M\-x\fR option after the program name when ! 346: \*Micont\fR is used, as in ! 347: .Ds ! 348: icont prog.icn -x ! 349: .De ! 350: Such a program also can be run as an argument of \*Miconx\fR, as in ! 351: .Ds ! 352: iconx prog ! 353: .De ! 354: where \*Mprog\fR is the result of translating and linking \*Mprog.icn\fR ! 355: as in the previous example. ! 356: .PP ! 357: If \*MNoHeader\fR is defined, the value of \*MMaxHdr\fR is irrelevant. ! 358: .NH 2 ! 359: \*MMakefile\fR headers ! 360: .PP ! 361: The files \*Micont.hdr\fR, \*Miconx.hdr\fR, \*Mlink.hdr\fR, and \*Mtran.hdr\fR ! 362: provide headers for \*MMakefile\fRs in \*Mv6/src/icont\fR, \*Mv6/src/iconx\fR, ! 363: and so on. These headers are prepended to the standard bodies for the ! 364: \*MMakefile\fRs during setup. ! 365: .PP ! 366: Except for \*Miconx.hdr\fR, these headers serve only to specify flags for ! 367: \fIcc(1)\fR and \fIld(1)\fR via \*MCFLAGS\fR and \*MLDFLAGS\fR. ! 368: If your C optimizer is robust, you may wish to start with ! 369: .Ds ! 370: CFLAGS= -O ! 371: .De ! 372: in all these headers. In fact, if you are installing Icon on a computer ! 373: with a small address space, this flag (as well as others) may be necessary ! 374: to obtain modules small enough to load. However, if you encounter ! 375: problems during testing, suspect your optimizer first and try compiling ! 376: Version 6.0 without the \*M\-O\fR flag. ! 377: .PP ! 378: Other \fIcc\fR and \fIld\fR flags vary considerably from system to system. ! 379: You may want to review your local manual pages for these processors and ! 380: look at the header files in the other configuration areas. ! 381: .PP ! 382: There are two other definitions in \*Miconx.hdr\fR: \*MRSWITCH\fR and ! 383: \*MROVER\fR, which depend on whether the local co-expression ! 384: context switch and arithmetic overflow checks are written in ! 385: C or assembly language. The initial values of these definitions ! 386: are \*Mrswitch.c\fR and \*Mrover.c\fR, and dummy C routines ! 387: are provided. To start out, leave these definitions as they are; ! 388: the default routines can be replaced later. See Sections 7.7 and 7.8. ! 389: .PP ! 390: The file \*Mpi.hdr\fR provides a header for the personalized interpreter ! 391: \*MMakefile\fR, which is in \*Mv6/Pimakefile\fR. In addition to the usual ! 392: \fIcc\fR and \fIld\fR flags, you should provide definitions for ! 393: \*MXCFLAGS\fR and \*MXLDFLAGS\fR that are the same as those for ! 394: \*MCFLAGS\fR and \*MLDFLAGS\fR in \*Micont.hdr\fR. This assures that ! 395: the header file in the personalized interpreter is the same size as ! 396: the one in the regular version of Icon. ! 397: .NH 2 ! 398: \*Mconfig.trl\fR ! 399: .PP ! 400: The remaining configuration information is contained in \*Mconfig.trl\fR. ! 401: The definitions in this file as provided by \*MSetup\fR are for ! 402: a ``vanilla'' 32-bit computer. Changes may be needed as follows: ! 403: .SH ! 404: \*MFork\fR ! 405: .PP ! 406: If your system supports \fIvfork(2)\fR, change the definition of ! 407: \*MFork\fR from \*Mfork\fR to \*Mvfork\fR. ! 408: .SH ! 409: \*MHostStr\fR ! 410: .PP ! 411: Change the definition of \*MHostStr\fR, which provides the value ! 412: of the Icon keyword \*M&host\fR, to some string that adequately ! 413: identifies your installation. If you want to use a local system ! 414: routine to provide the host name automatically, read Appendix D. ! 415: .SH ! 416: \*MHz\fR ! 417: .PP ! 418: If you are running in a 50-hz environment, change the ! 419: definition of \*MHz\fR from \*M60\fR to \*M50\fR. ! 420: .SH ! 421: \*MIntSize\fR, \*MLongSize\fR, and \*MPtrSize\fR ! 422: .PP ! 423: Define these constants to the the sizes, in bits, of you C \*Mint\fRs, ! 424: \*Mlong\fRs and pointers, respectively. ! 425: These values normally are 16 or 32. ! 426: \*MNoOver\fR ! 427: .PP ! 428: Initially, \*Mconfig.trl\fR contains ! 429: .Ds ! 430: #define NoOver ! 431: .De ! 432: This definition disables arithmetic overflow checks, which must be ! 433: written in assembly language. Leave this definition in for the ! 434: first round, although you may want to remove it later (see Section 7.8). ! 435: .SH ! 436: \*MSysTime\fR ! 437: .PP ! 438: The system \*Minclude\fR file \*Mtime.h\fR is in different locations on ! 439: different systems \(em either \*M<time.h>\fR or \*M<sys/time.h>\fR. ! 440: Define \*MSysTime\fR accordingly. ! 441: .PP ! 442: If you give the incorrect location, ! 443: a fatal error will occur during the compilation of \*Mv6/src/iconx/lmisc.c\fR. ! 444: The use of this definition also depends on your C preprocessor ! 445: making macro substitutions in \*M#include\fR directives. Most preprocessors ! 446: do, but if yours does not, edit \*M/v6/src/iconx/lmisc.c\fR and ! 447: replace \*MSysTime\fR there by the appropriate value. If you have to ! 448: do this, make a note to come back later and place the definition under ! 449: the control of conditional compilation as described in Section 7.5. ! 450: .SH ! 451: Names of Indexing Routines ! 452: .PP ! 453: Different versions of UNIX use different names for the routines for ! 454: locating substrings within strings. Version 6.0 of Icon uses ! 455: \*Mindex\fR and \*Mrindex\fR. The other possibilities are \*Mstrchr\fR ! 456: and \*Mstrrchr\fR. If your system uses the latter names, add ! 457: .Ds ! 458: #define index strchr ! 459: #define rindex strrchr ! 460: .De ! 461: to \*Mconfig.trl\fR. ! 462: .SH ! 463: Other Definitions ! 464: .PP ! 465: There are several other configuration details that are needed for ! 466: a few systems. Most of these can be handled by optionally defined ! 467: symbols. ! 468: .PP ! 469: If your system needs a specific check for division by floating-point ! 470: zero, as opposed to relying on a signal, add ! 471: .Ds ! 472: #define ZeroDivide ! 473: .De ! 474: to your \*Mconfig.trl\fR file. ! 475: .PP ! 476: If your system requires C \fIdouble\fRs to be aligned at double-word ! 477: boundaries, add ! 478: .Ds ! 479: #define Double ! 480: .De ! 481: to your \*Mconfig.trl\fR file. ! 482: .PP ! 483: Most computers have down-growing C stacks, for which stack addresses ! 484: decrease as values are pushed. If you have an up-growing stack, for ! 485: which stack addresses increase as values are pushed, add ! 486: .Ds ! 487: #define UpStack ! 488: .De ! 489: to your \*Mconfig.trl\fR file. ! 490: .PP ! 491: Icon includes its own versions of \*Mmalloc\fR and \*Mfree\fR, so that ! 492: it can manage its storage region without interference from allocation ! 493: by the operating system. Normally, Icon's \*Mmalloc\fR and \*Mfree\fR ! 494: are loaded instead of the system library routines. If your system ! 495: insists on loading its own library routines, multiple definitions will ! 496: occur as a result of the \fIld\fR in \*M/v6/src/iconx\fR. ! 497: .PP ! 498: If multiple definitions occur in \*Miconx\fR, go back and add ! 499: .Ds ! 500: #define IconAlloc ! 501: .De ! 502: to \*Mconfig.trl\fR. This definition ! 503: causes Icon's routines to be named differently to avoid collision ! 504: with the system routine names. ! 505: .PP ! 506: One possible effect of this definition is to interfere with Icon's ! 507: expansion of its memory region in case the initial values for allocated ! 508: storage are not large enough to accommodate a program that produces a ! 509: lot of data. ! 510: This problem appears in the form of run-time error 304 or 305 and can ! 511: be circumvented on a case-by-case basis by increasing the ! 512: initial values for allocated storage by setting environment variables [4]. ! 513: .NH 2 ! 514: Modifications to the Distributed Source Code ! 515: .PP ! 516: The configuration system is designed to avoid modifications to ! 517: the distributed source code for Version 6.0. However, on some ! 518: systems, it may be necessary to modify the source code. ! 519: .PP ! 520: If you need to modify the source code, do it under the control of ! 521: conditional compilation keyed to the name of your system. Add ! 522: .Ds ! 523: #define \fINAME\fR ! 524: .De ! 525: where \fINAME\fR is an all-uppercase name that identifies your system. ! 526: For example, the \*Mconfig.trl\fR for Sun Workstations contains ! 527: .Ds ! 528: #define SUN ! 529: .De ! 530: .LP ! 531: Then use ! 532: .Ds ! 533: #ifdef \fINAME\*M ! 534: .do ! 535: #endif \fINAME\*M ! 536: .De ! 537: or similar constructions where you need local source-code modifications. ! 538: For example, this technique can be used to handle the problem that ! 539: may arise with \*MSysTime\fR, described in Section 7.4. Note ! 540: that nested \*M#ifdef\fRs may be needed in places where there are several ! 541: different local modifications. ! 542: .PP ! 543: It is important to be consistent and careful about the use of such ! 544: conditional compilations; if done properly, your modifications can be ! 545: backed into the central version of the source code at the University ! 546: of Arizona and will be in place for you when subsequent ! 547: versions are released. ! 548: See Section 8. ! 549: .NH 2 ! 550: Initial Installation of a New System ! 551: .PP ! 552: Once you have edited the configuration files as described in the ! 553: previous sections, proceed with setup, compilation, and installation ! 554: as described in Section 2. You may need to iterate. ! 555: If you make a change in a configuration file after a compilation, be ! 556: sure to perform the setup again; some aspects of the setup are ! 557: far-reaching and not obvious. ! 558: .PP ! 559: More testing is recommended for a new installation than for one ! 560: that has been successfully installed elsewhere. ! 561: As a start, do ! 562: .Ds ! 563: make Test-icon ! 564: .De ! 565: If that works, ! 566: .Ds ! 567: make Test-large ! 568: .De ! 569: or ! 570: .Ds ! 571: make Test-small ! 572: .De ! 573: depending on whether you defined \*MPtrSize\fR to be 32 or 16 earlier. ! 574: These tests are quite extensive and contain some real grinders; ! 575: be prepared to wait a while. See \*Mv6/tests/Makefile\fR for more ! 576: information. ! 577: .PP ! 578: There will be some differences between local and standard results ! 579: in \*Mcheck\fR, since ! 580: it contains site and time-dependent tests. Other minor discrepancies ! 581: may occur because of differences in the handling of floating-point ! 582: arithmetic on different systems. ! 583: .PP ! 584: Do \fInot\fR run any other tests until you have implemented the ! 585: co-expression context switch (see Section 7.7) and decided what to ! 586: do about arithmetic overflow checking (see Section 7.8). ! 587: .NH 2 ! 588: Co-Expressions ! 589: .PP ! 590: All aspects of co-expression creation and activation are written ! 591: in C in Version 6.0 except for a routine, \*Mcoswitch\fR, that is needed for ! 592: context switching. This routine requires assembly ! 593: language, since it must manipulate hardware registers. ! 594: It can either be written as a C routine with \*Masm\fR directives ! 595: or as an assembly language routine. ! 596: .PP ! 597: When a new configuration directory is set up, a file \*Mrswitch.c\fR is ! 598: provided with ! 599: a version of \*Mcoswitch\fR that results in error termination if an Icon ! 600: program attempts to activate a co-expression. ! 601: .PP ! 602: Calls to the context switch have the form \*Mcoswitch(old_cs,new_cs,first)\fR, ! 603: where \*Mold_cs\fR is a pointer to an array of words that contain C state ! 604: information for the current co-expression, \*Mnew_cs\fR is a pointer to ! 605: an array of words that hold C state information for a co-expression to ! 606: be activated, and \*Mfirst\fR is 1 or 0, depending on whether or not ! 607: the new co-expression has or has not been activated before. ! 608: The zeroth element of a C state array always contains the stack pointer ! 609: (\fIsp\fR) for that co-expression. The other elements (15 are provided) ! 610: can be used to save any C frame pointers and any ! 611: other registers your C compiler expects to be preserved across calls. ! 612: .PP ! 613: The first thing \*Mcoswitch\fR does is to save the current pointers ! 614: and registers in the \*Mold_cs\fR array. Then it tests \*Mfirst\fR. ! 615: If \*Mfirst\fR is zero, \*Mcoswitch\fR sets \fIsp\fR from ! 616: \*Mnew_cs[0]\fR, clears the C frame pointers, and \fIcalls\fR ! 617: \*Minterp\fR. If \*Mfirst\fR is not zero, it loads the (previously saved) ! 618: \fIsp\fR, C frame pointers, and registers from \*Mnew_cs\fR and ! 619: returns. ! 620: .PP ! 621: Written in C, \*Mcoswitch\fR has the form: ! 622: .DS ! 623: .ta 1i ! 624: .ft C ! 625: /* ! 626: * coswitch ! 627: */ ! 628: coswitch(old_cs, new_cs, first) ! 629: int *old_cs, *new_cs; ! 630: int first; ! 631: { ! 632: .do 2i ! 633: /* save sp, frame pointers, and other registers in old_cs */ ! 634: .do 2i ! 635: if (first == 0) { /* this is first activation */ ! 636: .do 2i ! 637: /* load sp from new_cs[0] and clear frame pointers */ ! 638: .do 2i ! 639: interp(0, 0); ! 640: syserr("interp() returned in coswitch"); ! 641: } ! 642: else { ! 643: .do 2i ! 644: /* load sp, frame pointers, and other registers from new_cs */ ! 645: .do 2i ! 646: } ! 647: } ! 648: .DE ! 649: Appendix E contains \*Mcoswitch\fR for the VAX. ! 650: Other examples are contained in the configuration directories in ! 651: \*Mv6/setup\fR. ! 652: .PP ! 653: If you do not want to implement the context switch, the only effect will ! 654: be that Icon programs that attempt to activate a co-expression will ! 655: terminate with an error message. If you chose to implement the context ! 656: switch, replace \*Mrswitch.c\fR in your configuration directory ! 657: by either a new \*Mrswitch.c\fR or an assembly language file named ! 658: \*Mrswitch.s\fR. The setup process will copy your file to the ! 659: appropriate place prior to compilation. If you use \*Mrswitch.s\fR, ! 660: change the definition of \*MRSWITCH\fR in \*Miconx.hdr\fR in your ! 661: configuration area to ! 662: .Ds ! 663: RSWITCH=rswitch.s ! 664: .De ! 665: If your assembler requires special flags, add an appropriate ! 666: definition for \*MOFLAGS\fR to \*Miconx.hdr\fR. ! 667: .PP ! 668: To test your context switch, ! 669: .Ds ! 670: make Test-lcoexpr ! 671: .De ! 672: or ! 673: .Ds ! 674: make Test-scoexpr ! 675: .De ! 676: depending on whether you defined \*MPtrSize\fR to be 32 or 16 earlier. ! 677: There should be no differences in the comparison of outputs. ! 678: .PP ! 679: If you have trouble with your context switch, the first thing to do ! 680: is double-check the registers that your C compiler expects to ! 681: be preserved across calls \(em different C compilers on the same ! 682: computer may have different requirements. ! 683: .PP ! 684: Another possible source of problems is built-in stack checking. ! 685: Co-expressions rely on being able to specify an arbitrary region ! 686: of memory for the C stack. If your C compiler generates code for ! 687: stack probes that expects the C stack to be at a specific location, ! 688: you may need to disable this code or replace it with something ! 689: more appropriate. ! 690: .PP ! 691: If your system does not allow the C stack to be at an arbitrary ! 692: place in memory, there is probably little hope of implementing ! 693: co-expressions. ! 694: .NH 2 ! 695: Arithmetic Overflow Checks ! 696: .PP ! 697: C does not provide overflow checking for integer addition, subtraction, ! 698: or multiplication. Icon, on the other hand, is supposed to check for ! 699: overflow. This requires assembly-language code. ! 700: .PP ! 701: The \*Mconfig.trl\fR file provided when a new configuration area is ! 702: set up provides the definition ! 703: .Ds ! 704: #define NoOver ! 705: .De ! 706: which causes overflow checking to be bypassed. ! 707: .PP ! 708: If you do not want to implement overflow checking, you need do nothing. ! 709: If you want to implement overflow checking, remove the definition ! 710: of \*MNoOver\fR from your \*Mconfig.trl\fR and write routines ! 711: \*Mckadd\fR, \*Mcksub\fR, and \*Mckmul\fR that call \*Mrunerr(203,0)\fR ! 712: in the case of overflow. Appendix F contains the overflow checking ! 713: routine for the VAX. ! 714: Other examples are contained in the configuration directories in ! 715: \*Mv6/setup\fR. ! 716: .PP ! 717: If you supply overflow checking routines, put them in the file ! 718: \*Mrover.s\fR in your configuration directory. The setup will copy ! 719: this file to the appropriate place prior to compilation. ! 720: .PP ! 721: To test overflow checking, ! 722: .Ds ! 723: make Test-over ! 724: .De ! 725: There should be no differences in the comparison of outputs if overflow ! 726: checking is working properly. ! 727: .PP ! 728: You should also rerun previous tests at this point to make sure ! 729: that arithmetic still works properly. ! 730: .NH 2 ! 731: Personalized Interpreters ! 732: .PP ! 733: The personalized interpreter system uses \fIar(1)\fR. On most ! 734: UNIX systems, it is necessary to use \fIranlib(1)\fR so that the ! 735: loader can access the archive. The script \*MRanlib\fR that is ! 736: provided when a new configuration directory is initialized contains ! 737: calls of \fIranlib\fR for this purpose. ! 738: .PP ! 739: Some UNIX systems, notably System V, handle this problem directly ! 740: in \fIar(1)\fR and do not have \fIranlib(1)\fR. If your system does ! 741: not use \fIranlib(1)\fR, change \*MRanlib\fR to an empty script by ! 742: .Ds ! 743: echo "" >Ranlib ! 744: .De ! 745: in your configuration directory. ! 746: . ! 747: .a ! 748: .PP ! 749: Test your personalized interpreter system as described in Section ! 750: 3. If the test programs fail to execute, suspect the size of ! 751: \*Mv6/tests/pi/piconx.hdr\fR, the personalized interpreter ! 752: version of \*Miconx.hdr\fR. If it is larger than \*MMaxHdr\fR, ! 753: something is wrong. Check the file \*Mpi.hdr\fR in your ! 754: configuration directory as described in Section 7.3. ! 755: .NH ! 756: Trouble Reports and Feedback ! 757: .PP ! 758: If you run into problems, contact the Icon Project: ! 759: .DS ! 760: .ft R ! 761: Icon Project ! 762: Department of Computer Science ! 763: The University of Arizona ! 764: Tucson, AZ 85721 ! 765: .sp .5 ! 766: (602) 621-6613 ! 767: .sp .5 ! 768: \*Micon\[email protected] ! 769: {ihnp4,noao,mcnc,utah-cs}!arizona!icon-project ! 770: .DE ! 771: .PP ! 772: Please also let us know of any suggestions for improvements to the ! 773: installation process and corrections or refinements to configuration ! 774: files for supported systems. ! 775: .PP ! 776: If you installed a previously unsupported system, ! 777: send a copy of the files ! 778: in your configuration directory and any files in \*Mv6/src\fR that ! 779: you modified to ! 780: so that we can back them in to the central version of the source. ! 781: .SH ! 782: Acknowledgement ! 783: .PP ! 784: Gregg Townsend made a number of helpful suggestions related to the ! 785: process for installing Version 6.0. ! 786: .SH ! 787: References ! 788: .LP ! 789: 1. Griswold, Ralph E. \fIPersonalized Interpreters for Version 6.0 of Icon\fR, ! 790: Technical Report TR 86-12, Department of Computer Science, The University ! 791: of Arizona. May 1986. ! 792: .LP ! 793: 2. Griswold, Ralph E. \fIThe Icon Program Library; Version 6.0\fR, ! 794: Technical Report TR 86-13, Department of Computer Science, The University ! 795: of Arizona. May 1986. ! 796: .LP ! 797: 3. Griswold, Ralph E., William H. Mitchell, and Janalee O'Bagy. ! 798: \fIVersion 6.0 of Icon\fR, Technical Report TR 86-10, Department of ! 799: Computer Science, The University of Arizona. May 1986. ! 800: .LP ! 801: 4. Griswold, Ralph E. \fIICONT(1)\fR, manual page for \fIUNIX ! 802: Programmer's Manual\fR, Department of Computer Science, The ! 803: University of Arizona. May 1986. ! 804: .Ap "Appendix A \(em Changing the Locations of Version 6.0 Files" ! 805: .sp ! 806: .PP ! 807: As mentioned in Section 2, the distributed files are rooted in \*Mv6\fR. ! 808: The standard location for this hierarchy is \*M/usr/icon/v6\fR\s-2\u1\d\s0. ! 809: .FS ! 810: \s-2\u1\d\s0\^For HP-UX, the standard location is \*M/users/icon/v6\fR. ! 811: The location \*M/usr/icon/v6\fR is used here for convenience. ! 812: .FE ! 813: The hierarchy can be placed somewhere else if you desire, but ! 814: before performing the setup, you must edit a file that ! 815: specifies where the binary files are to be installed. ! 816: .PP ! 817: The directory \*Mv6/setup\fR contains a subdirectory for each ! 818: supported system. For example, \*Mv6/setup/sun\fR contains the ! 819: configuration information for the Sun Workstation. To get to the ! 820: configuration information for your system, ! 821: .Ds ! 822: cd v6/setup/\fIname\fR ! 823: .De ! 824: where \fIname\fR is the name of your system. ! 825: .PP ! 826: The file \*Mpaths.h\fR, ! 827: as distributed, is the same for all systems and contains ! 828: .Ds ! 829: .ta 1.8i ! 830: #define RootPath "/usr/icon/v6" ! 831: #define IcontPath "/usr/icon/v6/bin/icont" ! 832: #define TranPath "/usr/icon/v6/bin/itran" ! 833: #define LinkPath "/usr/icon/v6/bin/ilink" ! 834: #define IconxPath "/usr/icon/v6/bin/iconx" ! 835: #define HeaderPath "/usr/icon/v6/bin/iconx.hdr" ! 836: .De ! 837: \*MRootPath\fR gives the location of the \*Mv6\fR hierarchy. ! 838: .PP ! 839: The five binary files referenced are: ! 840: .Ds ! 841: .ta 1i ! 842: icont \fRIcon command processor \(em all the typical user knows about\*M ! 843: itran \fRIcon translator\*M ! 844: ilink \fRIcon linker\*M ! 845: iconx \fRIcon run-time system\*M ! 846: iconx.hdr \fRbootstrap program that gets Icon programs into execution ! 847: .De ! 848: The command processor \*Micont\fR calls the other programs. ! 849: .PP ! 850: There are two reasons for changing these paths: ! 851: .RS ! 852: .IP 1. 4n ! 853: If \*Mv6\fR is ! 854: unloaded in an area other than \*M/usr/icon/v6\fR, ! 855: you probably want the binary files installed in that area instead of ! 856: \*M/usr/icon/v6\fR. ! 857: .IP 2. ! 858: You may want to install some or all of the binary files in a public ! 859: area. ! 860: .RE ! 861: .LP ! 862: For example, if you want to unload Icon in \*M/usr/irving/v6\fR, ! 863: edit \*Mpaths.h\fR to be ! 864: .Ds ! 865: .ta 1.8i ! 866: #define RootPath "/usr/irving/v6" ! 867: #define IcontPath "/usr/irving/v6/bin/icont" ! 868: #define TranPath "/usr/irving/v6/bin/itran" ! 869: #define LinkPath "/usr/irving/v6/bin/ilink" ! 870: #define IconxPath "/usr/irving/v6/bin/iconx" ! 871: #define HeaderPath "/usr/irving/v6/bin/iconx.hdr" ! 872: .De ! 873: Similarly, if you want \*Micont\fR to reside in \*M/usr/local/icont\fR, ! 874: edit the line for \*Micont\fR to be ! 875: .Ds ! 876: .ta 1i 2i ! 877: #define IcontPath "/usr/local/icont" ! 878: .De ! 879: \fICaution:\fR If you have a previously installed version of Icon, do not ! 880: put \*Miconx\fR at that place \(em ! 881: \*Miconx\fR for Version 6.0 is incompatible with \*Miconx\fR for ! 882: previous versions and replacing a previous \*Miconx\fR by Version 6.0 ! 883: \*Miconx\fR will invalidate all previously compiled Icon programs. ! 884: .Ap "Appendix B \(em Unloading the Distribution Files" ! 885: .sp 2 ! 886: .PP ! 887: The Icon distribution files are distributed in a variety of ways. ! 888: The usual distribution is magnetic tape, although ! 889: it is available on 5-\(14\(fm\(fm diskettes in DOS and ! 890: PC/IX formats. The directions that follow refer to magnetic tape ! 891: distribution only. ! 892: .PP ! 893: The Icon system is provided on tape in \fItar\fR or \fIcpio\fR format, recorded ! 894: at 1600 or 6250 bpi as specified when Version 6.0 is ordered. ! 895: Tapes are written in \fItar\fR format at 1600 bpi if no specification ! 896: is given. ! 897: The format and recording density are marked on the label on the tape. ! 898: .PP ! 899: To unload the tape, ! 900: do a \fIcd\fR to the directory that is to hold ! 901: the Icon hierarchy (that is, the directory in which \*Mv6\fR is to be ! 902: created) and mount the tape. ! 903: The precise ! 904: \fItar\fR or \fIcpio\fR command to unload the distribution ! 905: tape depends on the local environment. ! 906: On a VAX running 4.\fIn\fRbsd, use ! 907: the following command for a 1600 bpi \fItar\fR distribution tape: ! 908: .Ds ! 909: tar x ! 910: .De ! 911: Similarly, on a VAX running System V with a 6250 bpi \fIcpio\fR tape, ! 912: use: ! 913: .Ds ! 914: cpio -icdB </dev/rmt/0h ! 915: .De ! 916: .Ap "Appendix C \(em The Distribution Hierarchy" ! 917: .sp 2 ! 918: .Ds ! 919: .ta 1i +1i +1i +1i +1i +1i +1i +1i ! 920: /v6 \fRroot of the Version 6.0 hierarchy\*M ! 921: /bin \fRstandard location for binary files\*M ! 922: /book \fRprograms from the Icon book\*M ! 923: /docs \fRsource text for documents\*M ! 924: /ipl \fRIcon program library\*M ! 925: /pi \fRpersonalized interpreter system\*M ! 926: /setup \fRsetup and configuration files\*M ! 927: /src \fRsource code for the Icon system\*M ! 928: /tests \fRtest programs\*M ! 929: .De ! 930: .Ap "Appendix D \(em Host Name" ! 931: .sp 2 ! 932: .PP ! 933: The default method for specifying the host name that determines the ! 934: value of \*M&host\fR is the definition of \*MHostStr\fR in ! 935: \*Mconfig.trl\fR in the configuration directory. There are three other ! 936: ways of specifying the host; only one may be used. ! 937: .SH ! 938: \*MWhoHost\fR ! 939: .PP ! 940: On some versions of UNIX, notably Version 7 and 4.1bsd, the file ! 941: \*M/usr/include/whoami.h\fR contains the host name. If your system has ! 942: this file and you want to ! 943: use this name, ! 944: .Ds ! 945: #define WhoHost ! 946: .De ! 947: .SH ! 948: \*MGetHost\fR ! 949: .PP ! 950: Some versions of UNIX, notably 4.2bsd and 4.3bsd, provide the ! 951: host name via the \fIgethostname(2)\fR system call. If your system supports ! 952: this system call and you want ! 953: to use this name, ! 954: .Ds ! 955: #define GetHost ! 956: .De ! 957: .SH ! 958: \*MUtsName\fR ! 959: .PP ! 960: Some versions of UNIX, such as System V, provide the host name via ! 961: the \fIuname(2)\fR system call. If your system supports this call ! 962: and you want to use this name, ! 963: .Ds ! 964: #define UtsName ! 965: .De ! 966: .Ap "Appendix E \(em Sample Co-Expression Context Switch" ! 967: .sp 2 ! 968: .SH ! 969: \*Mrswitch.c\fR for the VAX under Berkeley UNIX: ! 970: .LP ! 971: .Ds ! 972: .ta 2.5i ! 973: coswitch(old_cs, new_cs, first) ! 974: int *old_cs, *new_cs; ! 975: int first; ! 976: .Dd ! 977: { ! 978: asm(" movl 4(ap),r0"); ! 979: asm(" movl 8(ap),r1"); ! 980: asm(" movl sp,0(r0)"); ! 981: asm(" movl fp,4(r0)"); ! 982: asm(" movl ap,8(r0)"); ! 983: asm(" movl r11,16(r0)"); ! 984: asm(" movl r10,20(r0)"); ! 985: asm(" movl r9,24(r0)"); ! 986: asm(" movl r8,28(r0)"); ! 987: asm(" movl r7,32(r0)"); ! 988: asm(" movl r6,36(r0)"); ! 989: .Dd ! 990: if (first == 0) { /* this is first activation */ ! 991: asm(" movl 0(r1),sp"); ! 992: asm(" clrl fp"); ! 993: asm(" clrl ap"); ! 994: interp(0, 0); ! 995: syserr("interp() returned in coswitch"); ! 996: } ! 997: .Dd ! 998: else { ! 999: asm(" movl 0(r1),sp"); ! 1000: asm(" movl 4(r1),fp"); ! 1001: asm(" movl 8(r1),ap"); ! 1002: asm(" movl 16(r1),r11"); ! 1003: asm(" movl 20(r1),r10"); ! 1004: asm(" movl 24(r1),r9"); ! 1005: asm(" movl 28(r1),r8"); ! 1006: asm(" movl 32(r1),r7"); ! 1007: asm(" movl 36(r1),r6"); ! 1008: } ! 1009: } ! 1010: .De ! 1011: .Ap "Appendix F \(em Sample Arithmetic Overflow Checking Routine" ! 1012: .sp 2 ! 1013: .SH ! 1014: \*Mrover.s\fR for the VAX under Berkeley UNIX: ! 1015: .Ds ! 1016: .globl _ckadd ! 1017: .globl _cksub ! 1018: .globl _ckmul ! 1019: ! 1020: .text ! 1021: .align 1 ! 1022: _ckadd: .word 0 ! 1023: addl3 4(ap),8(ap),r0 # Perform addition ! 1024: jvs oflow # Branch if overflow ! 1025: ret # Return result in r0 ! 1026: ! 1027: .align 1 ! 1028: _cksub: .word 0 ! 1029: subl3 8(ap),4(ap),r0 # Perform subtraction ! 1030: jvs oflow # Branch if overflow ! 1031: ret # Return result in r0 ! 1032: ! 1033: .align 1 ! 1034: _ckmul: .word 0 ! 1035: mull3 4(ap),8(ap),r0 # Perform multiplication ! 1036: jvs oflow # Branch if overflow ! 1037: ret # Return result in r0 ! 1038: ! 1039: oflow: # Got overflow on an operation ! 1040: pushl $0 ! 1041: pushl $203 ! 1042: calls $1,_runerr # runerr(203,0) ! 1043: .De
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.