home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / GAMES / infocom_src.lha / compile.txt next >
Text File  |  1993-03-03  |  16KB  |  624 lines
  1. The InfoTaskForce Infocom Interpreter Compilation Guide
  2. =======================================================
  3. Copyright (c) 1992 InfoTaskForce
  4.  
  5.  
  6. System-specific Compilation
  7. ---------------------------
  8.  
  9. The makefile distributed with the interpreter sources contains entries 
  10. for the following compilers:
  11.  
  12. turboc        Compile the interpreter using either Turbo C, Turbo C++ 
  13.         or Borland C++ on an IBM PC or compatable computer.
  14.  
  15. qc        Compile the interpreter using Microsoft C on an IBM PC 
  16.         or compatable computer. This version excludes all 
  17.         optimisation and invokes the "quick compile" option.
  18.  
  19. msc        Compile the interpreter using Microsoft C on an IBM PC 
  20.         or compatable computer. This version invokes full 
  21.         optimisation.
  22.  
  23. bsd_ansi    Compile the interpreter using the native C compiler on a 
  24.         computer running BSD UNIX. This version uses ANSI 
  25.         escape sequences to format screen output.
  26.  
  27. bsd_ansic    Compile the interpreter using the native C compiler on a 
  28.         computer running BSD UNIX. This version uses ANSI 
  29.         escape sequences to format screen output and for colour.
  30.  
  31. bsd_curses    Compile the interpreter using the native C compiler on a 
  32.         computer running BSD UNIX. This version uses the UNIX 
  33.         CURSES package to format screen output.
  34.  
  35. bsd        Compile the interpreter using the native C compiler on a 
  36.         computer running BSD UNIX. This version uses the UNIX 
  37.         TERMCAP package to format screen output.
  38.  
  39. sysv_ansi    Compile the interpreter using the native C compiler on a 
  40.         computer running UNIX System V. This version uses ANSI 
  41.         escape sequences to format screen output.
  42.  
  43. sysv_ansic    Compile the interpreter using the native C compiler on a 
  44.         computer running UNIX System V. This version uses ANSI 
  45.         escape sequences to format screen output and for colour.
  46.  
  47. sysv_curses    Compile the interpreter using the native C compiler on a 
  48.         computer running UNIX System V. This version uses the 
  49.         UNIX CURSES package to format screen output.
  50.  
  51. sysv_cursesc    Compile the interpreter using the native C compiler on a 
  52.         computer running UNIX System V. This version uses the 
  53.         UNIX CURSES package to format screen output and for colour.
  54.  
  55. sysv_termcap    Compile the interpreter using the native C compiler on a 
  56.         computer running UNIX System V. This version uses the 
  57.         UNIX TERMCAP package to format screen output.
  58.  
  59. sysv        Compile the interpreter using the native C compiler on a 
  60.         computer running UNIX System V. This version uses the 
  61.         UNIX TERMINFO package to format screen output.
  62.  
  63. Note that if the CURSES, TERMCAP or TERMINFO options are used, the terminal 
  64. database on your system MUST contain the correct sequences for your 
  65. terminal if the interpreter is to operate correctly. We have found many 
  66. TERMCAP databases to be inaccurate or incomplete on many UNIX 
  67. systems.
  68.  
  69.  
  70.  
  71. User-defined Compilation
  72. ------------------------
  73.  
  74. If none of the above options suit your system, you can roll your own 
  75. makefile entry. The interpreter sources currently recognise the 
  76. following compile time options (all in UPPERCASE) which can be 
  77. invoked using the -D<macro> option of most C compilers. See the 
  78. distribution makefile for examples of how they can be used.
  79.  
  80. ANSI_ESCAPE    Compile a version that uses ANSI ESCAPE 
  81.         sequences for terminal output.
  82.  
  83. ANSI_COLOR    Compile a version that uses ANSI ESCAPE 
  84.         sequences for coloured terminal output.
  85.  
  86. BSD        Compile on a BSD UNIX machine. (This also defines 
  87.         "UNIX")
  88.  
  89. CHEAT        Include the routines for spying on Object movement.
  90.  
  91. CURSES        Compile a version that uses curses features for terminal 
  92.         output. You may also have to include a curses library as 
  93.         well.
  94.  
  95. CURSES_COLOR    Compile a version that uses curses features including colours
  96.         for terminal output. You may also have to include a curses
  97.         library as well. This only works for some SYSV versions of
  98.         curses.
  99.  
  100. DEBUG        Compile a debug version of the interpreter. Compare 
  101.         output produced with this option against a working debug 
  102.         version when you suspect problems in the virtual machine 
  103.         [this commonly produces error 21].
  104.  
  105. LSC        Compile on a Macintosh using LightSpeed C Version 2.01.
  106.  
  107. MSC        Compile on an MS-DOS machine using Microsoft C.
  108.  
  109. MSDOS        Compile on an MS-DOS machine.
  110.  
  111. SYS_V        Compile on a UNIX System V machine. (This also defines 
  112.         "UNIX")
  113.  
  114. TERMCAP        Compile a version that uses termcap features for terminal 
  115.         output. You may also have to include a termcap library as 
  116.         well.
  117.  
  118. TERMINFO    Compile a version that uses terminfo features for terminal 
  119.         output. You may also have to include a terminfo library as 
  120.         well.
  121.  
  122. THINKC        Compile on a Macintosh using THINK C Version 4.0.
  123.  
  124. TURBOC        Compile on an MS-DOS machine using Borland C or Turbo C.
  125.  
  126. UNIX        Compile on a UNIX machine.
  127.  
  128.  
  129.  
  130. Advanced user-specified Compilation
  131. -----------------------------------
  132.  
  133. If none of the above options suit your system's setup, the interpreter 
  134. can be customised as described in this section.
  135.  
  136. The interpreter has been deliberately written in a way that makes 
  137. it easy to customise to a particular operating environment. There are 
  138. only three files which make assumptions about the compiler through 
  139. which these sources are run.
  140.  
  141. Firstly, the file infocom.h makes the following assumptions:
  142.  
  143. *    A variable of type char occupies exactly one byte.
  144. *    A variable of type short occupies exactly two bytes.
  145. *    A variable of type long occupies exactly four bytes.
  146. *    The compiler supports the signed and unsigned qualifiers for 
  147.     each of the above types.
  148. *    Unsigned char elements of structures are aligned on byte 
  149.     boundaries ( not on word or long word boundaries ).
  150.  
  151. If any of these assumptions are false, the infocom.h file may 
  152. require modification to the type definitions of "byte", "word", 
  153. "longword", "object" and "header". We do not anticipate that such 
  154. modifications will be required to this file.
  155.  
  156. The other two files are machine.h and io.c - these files contain 
  157. all the interface macros and functions required by the C compiler. 
  158. These are the only two files (apart from perhaps the makefile) which 
  159. should be modified by the user.
  160.  
  161. The interpreter performs all interface functions via macros which 
  162. are defined in machine.h. Depending on which machine the interpreter 
  163. is being compiled for, these macros contain the name of a machine 
  164. specific routine in io.c to perform that task for a given environment. 
  165. For example, the interpreter performs all printing to stdout using the 
  166. PUT_CHAR () macro. If we then compile the interpreter for Microsoft C 
  167. on a PC, the makefile #defines MSC which, in turn #defines PUT_CHAR 
  168. to the msc_putchar routine in io.c. On the otherhand, if we compile for 
  169. Turbo C on the PC, the makefile #defines TURBOC which, in turn 
  170. #defines PUT_CHAR to the tc_putchar routine in io.c.
  171.  
  172. The following is a list of the compiler customisation variables 
  173. defined in machine.h:
  174.  
  175. INTERPRETER    Interpreter Number - indicates the type of the target 
  176.         machine. By default, this is set to APPLE_2E. See 
  177.         infocom.h for other possibilities, although it doesn't 
  178.         make much difference (except in Beyond Zork, where 
  179.         this value is used to determine whether or not an 
  180.         alternative graphics character set is avaliable for 
  181.         drawing the map - the APPLE_2E has no such 
  182.         character set).
  183.  
  184. MODE_BITS    The bits to set in the "mode_bits" byte of the game 
  185.         file header to indicate target system capabilities. If 
  186.         underlining is available, this should be set to 
  187.         UNDERLINE, otherwise it should be set to 0.
  188.  
  189. SCREEN_WIDTH    Default number of Characters per Screen Line. This 
  190.         is used if the screen line width cannot be determined 
  191.         dynamically at run time.
  192.  
  193. SCREEN_HEIGHT    Default number of Screen Lines. This is used if the 
  194.         number of screen lines cannot be determined 
  195.         dynamically at run time.
  196.  
  197. READ_STRING    String used by fopen to open a file in read binary 
  198.         mode - usually "r" or "rb".
  199.  
  200. WRITE_STRING    String used by fopen to open a file in write binary 
  201.         mode - usually "w" or "wb".
  202.  
  203. APPEND_STRING    String used by fopen to open a file in append text 
  204.         mode - usually "a".
  205.  
  206. Void        Defines the "void" type. If a pre-ANSI compiler is 
  207.         being used which does not know about the void type, 
  208.         use the int type instead.
  209.  
  210. HUGE        Used in the type definition of pointers. This is 
  211.         included for MSDOS and other Intel 80x86 C Compilers 
  212.         with segment based memory models. Omit it for 
  213.         "normal" machines.
  214.  
  215. MALLOC(s)    Macro to invoke the memory allocation routine. Note 
  216.         that this macro may be used to allocate more than 64 
  217.         Kbytes of memory and hence takes an unsigned long 
  218.         as an arguement and returns a pointer to the 
  219.         allocated block of memory. For example, in UNIX,
  220.  
  221.             #define    MALLOC(s)    malloc(s)
  222.  
  223.         See machine.h for more complex examples. If your 
  224.         compiler only has a malloc routine which takes an 
  225.         unsigned int as an argument, this macro should 
  226.         contain the name of your own malloc function which 
  227.         should be placed in io.c - care must be taken if you 
  228.         write your own malloc since the interpreter assumes 
  229.         that the memory block it asks for is contiguous, so if 
  230.         you allocate a number of smaller blocks to get a 
  231.         larger one you MUST check that all the blocks are 
  232.         contiguous, otherwise malloc should fail with a null 
  233.         pointer.
  234.  
  235. FREE(p)        Macro to invoke the memory deallocation routine, 
  236.         where "p" is the pointer returned by the MALLOC(s) 
  237.         macro. This macro returns a void. For example,
  238.  
  239.             #define    FREE(p)    free((void *)p)
  240.  
  241. main        Name of the initial C procedure (LSC only - omit it 
  242.         for all other machines).
  243.  
  244. TIME_FUNCTION    Macro to invoke the standard library time function 
  245.         which is used to seed the random number generator. 
  246.         This macro itself takes no arguements and assumes 
  247.         that the returned value is a long. Thus if your 
  248.         standard time function requires arguements, these 
  249.         must also be included in the macro. For example,
  250.  
  251.             #define    TIME_FUNCTION    time((long *)0)
  252.  
  253.         If such a function is not available, the following will 
  254.         suffice:
  255.             #define    TIME_FUNCTION    -1L
  256.  
  257. ONE_SECOND    The value used by "TIME_FUNCTION" to indicate the 
  258.         passing of one second of real time.
  259.  
  260. INIT_SIGNAL    Routine to perform any special initialisation for signal 
  261.         trapping routines.
  262.  
  263. SIGNAL_QUIT    Routine to perform any signal cleanup and/or 
  264.         handling. An integer is passed to this routine to 
  265.         specify  the action required.
  266.  
  267. INIT_IO        Routine to perform any special initialisation for the 
  268.         I/O routines.
  269.  
  270. EXIT_IO        Routine to restore any I/O modes when the program 
  271.         exits.
  272.  
  273. PUT_CHAR    Routine to send a character to "stdout".
  274.  
  275. GOTO_XY        Routine to move the cursor to a given screen 
  276.         position.
  277.  
  278. GET_X        Routine to get the cursor's x-coordinate.
  279.  
  280. GET_Y        Routine to get the cursor's y-coordinate.
  281.  
  282. USE_WINDOW    Routine used to set a screen window's scroll region.
  283.  
  284. GET_CH        Routine to get a character from "stdin" without echo.
  285.  
  286. KBD_HIT        Routine to detect whether there is a character 
  287.         waiting to be read from "stdin".
  288.  
  289. ERASE_TO_EOLN    Routine to Erase the current Screen Line.
  290.  
  291. ERASE_WINDOW    Routine to Erase several consecutive Screen Lines.
  292.  
  293. SAVE_CURSOR    Routine to Save the Current Cursor Position.
  294.  
  295. RESTORE_CURSOR    Routine to Restore the Current Cursor Position.
  296.  
  297. RCFILE        String containing name of initialization file.
  298.  
  299.  
  300. In summary, to install a custom set of interface routines, insert 
  301. something like the following into machine.h:
  302.  
  303. #ifdef    MY_OPERATING_SYSTEM
  304.  
  305. #include    <my.h>
  306.  
  307. #define    INTERPRETER    APPLE_2E
  308. #define    MODE_BITS    UNDERLINE
  309. #define    SCREEN_WIDTH    80
  310. #define    SCREEN_HEIGHT    24
  311. #define    READ_STRING    "rb"
  312. #define    WRITE_STRING    "wb"
  313. #define    APPEND_STRING    "a"
  314.  
  315. #define    TIME_FUNCTION    my_time((long *)0)
  316. #define    ONE_SECOND    1
  317. #define    INIT_SIGNAL    my_signal_init
  318. #define    SIGNAL_QUIT    my_signal_quit
  319.  
  320. extern int    my_get_x () ;
  321. extern int    my_get_y () ;
  322.  
  323. #define    Void        void
  324. #define    HUGE
  325. #define    MALLOC(s)    malloc(s)
  326. #define    FREE(p)        free((void *)p)
  327.  
  328. #define    INIT_IO        my_init_io
  329. #define    EXIT_IO        my_exit_io
  330. #define    PUT_CHAR    my_putchar
  331. #define    GOTO_XY        my_goto_xy
  332. #define    GET_X        my_get_x
  333. #define    GET_Y        my_get_y
  334. #define    USE_WINDOW    my_use_window
  335. #define    GET_CH        my_getch
  336. #define    KBD_HIT        my_kbd_hit
  337. #define    ERASE_TO_EOLN    my_erase_to_eoln
  338. #define    ERASE_WINDOW    my_erase_window
  339. #define    SAVE_CURSOR    my_save_cursor
  340. #define    RESTORE_CURSOR    my_restore_cursor
  341. #define    RCFILE        "infocom.rc"
  342.  
  343. #endif    /* MY_OPERATING_SYSTEM */
  344.  
  345. With a corresponding entries in io.c:
  346.  
  347. #ifdef    MY_OPERATING_SYSTEM
  348.  
  349. /*
  350. **    My Signal Trapping Routine.
  351. */
  352.  
  353. Void
  354. my_signal_init ( sig_action )
  355. int        sig_action ;
  356. {
  357.     /*
  358.     **    Initialise signals ...
  359.     */
  360. }
  361.  
  362. Void
  363. my_signal_quit ( sig_action )
  364. int        sig_action ;
  365. {
  366.     switch ( sig_action )
  367.     {
  368.         case SOMETHING:
  369.         default:
  370.             /*
  371.             **    Handle signal ...
  372.             */
  373.     }
  374. }
  375.  
  376. /*
  377. **    My I/O Routines.
  378. */
  379.  
  380. Void
  381. my_init_io ()
  382. {
  383.     extern int    screen_height ;
  384.         
  385.     /*
  386.     **    Initialise my I/O variables ...
  387.     */
  388.  
  389.     GOTO_XY ( 0,screen_height - 1 ) ;
  390. }
  391.  
  392. Void
  393. my_exit_io ()
  394. {
  395.     /*
  396.     **    Clean up the I/O before quitting ...
  397.     */
  398. }
  399.  
  400. Void
  401. my_putchar ( c )
  402. char    c ;
  403. {
  404.     extern boolean    enable_screen ;
  405.  
  406.     switch ( c )
  407.     {
  408.         case 1:
  409.             /*
  410.             **    Set Normal Text Mode.
  411.             */
  412.  
  413.             break ;
  414.         case 2:
  415.             /*
  416.             **    Set Inverse Text Mode.
  417.             */
  418.  
  419.             break ;
  420.         case 3:
  421.             /*
  422.             **    Set Bold Text Mode.
  423.             */
  424.  
  425.             break ;
  426.         case 4:
  427.             /*
  428.             **    Unused.
  429.             */
  430.  
  431.             break ;
  432.         case 5:
  433.             /*
  434.             **    Set Underline Text Mode.
  435.             */
  436.  
  437.             break ;
  438.         case 0:
  439.             c = ' ' ;
  440.  
  441.             /*
  442.             **    Fall Through ...
  443.             */
  444.  
  445.         default:
  446.             if ( enable_screen )
  447.                 putchar ( c ) ;
  448.             break ;
  449.     }
  450. }
  451.  
  452. Void
  453. my_goto_xy ( x,y )
  454. int        x,y ;
  455. {
  456.     /*
  457.     **    Move the cursor to (x,y) ...
  458.     **    The top-left corner of the screen has coordinates (0,0).
  459.     */
  460. }
  461.  
  462. int
  463. my_get_x ()
  464. {
  465.     /*
  466.     **    The left-most character position is position 0.
  467.     */
  468.  
  469.     return ( cursor's_current_x_position ) ;
  470. }
  471.  
  472. int
  473. my_get_y ()
  474. {
  475.     /*
  476.     **    The top screen line is 0.
  477.     */
  478.  
  479.     return ( cursor's_current_y_position ) ;
  480. }
  481.  
  482. /*
  483. **    The Enhanced Windowing Default I/O Functions.
  484. */
  485.  
  486. Void
  487. my_use_window ( the_window )
  488. word    the_window ;
  489. {
  490.     switch ( the_window )
  491.     {
  492.         case WINDOW_0:
  493.             /*
  494.             ** Use the Lower Window ...
  495.             */
  496.  
  497.             break ;
  498.         case WINDOW_1:
  499.             /*
  500.             ** Use the Upper Window ...
  501.             */
  502.  
  503.             break ;
  504.         case FULL_SCREEN:
  505.             /*
  506.             ** Use the entire screen ...
  507.             */
  508.  
  509.             break ;
  510.     }
  511. }
  512.  
  513. Void
  514. my_erase_window ( top_of_window,bottom_of_window )
  515. word    top_of_window ;
  516. word    bottom_of_window ;
  517. {
  518.     extern int        screen_width ;
  519.     extern word        top_screen_line ;
  520.  
  521.     /*
  522.     **    Erase Screen from the line specified by "top_of_window"
  523.     **    to the line ABOVE that specified by "bottom_of_window".
  524.     **    Leave Cursor at the top, left-hand corner of the erased window.
  525.     **    The top screen line is line 0.
  526.     */
  527.  
  528.     word    i ;
  529.  
  530.     for ( i = bottom_of_window ; i > top_of_window ; i-- )
  531.     {
  532.         GOTO_XY ( 0,i-1 ) ;
  533.         my_erase_to_eoln () ;
  534.     }
  535. }
  536.  
  537. int        saved_cursor_x ;
  538. int        saved_cursor_y ;
  539.  
  540. Void
  541. my_save_cursor ()
  542. {
  543.     extern int    saved_cursor_x ;
  544.     extern int    saved_cursor_y ;
  545.  
  546.     saved_cursor_x = GET_X () ;
  547.     saved_cursor_y = GET_Y () ;
  548. }
  549.  
  550. Void
  551. my_restore_cursor ()
  552. {
  553.     extern int    saved_cursor_x ;
  554.     extern int    saved_cursor_y ;
  555.  
  556.     GOTO_XY ( saved_cursor_x,saved_cursor_y ) ;
  557. }
  558.  
  559. /*
  560. **    The PLUS Series Default I/O Functions.
  561. */
  562.  
  563. Void
  564. my_erase_to_eoln ()
  565. {
  566.     /*
  567.     **    The characters at the cursor and to the right are erased.
  568.     **    The cursor itself is not moved.
  569.     */
  570.  
  571.     extern int    screen_width ;
  572.     int            saved_x_posn ;
  573.     int            saved_y_posn ;
  574.     int            i ;
  575.  
  576.     saved_x_posn = GET_X () ;
  577.     saved_y_posn = GET_Y () ;
  578.     for ( i = saved_x_posn ; i < screen_width ; i++ )
  579.         out_char ( ' ' ) ;
  580.     GOTO_XY ( saved_x_posn,saved_y_posn ) ;
  581. }
  582.  
  583. int
  584. my_kbd_hit ()
  585. {
  586.     if ( a_key_is_being_pressed )
  587.         return ( TRUE ) ;
  588.     else
  589.         return ( FALSE ) ;
  590. }
  591.  
  592. int
  593. my_getch ()
  594. {
  595.     if ( a_key_is_being_pressed )
  596.         return ( the_ascii_value_of_the_key ) ;
  597.     else
  598.         return ( EOF ) ;
  599. }
  600.  
  601. #endif    /* MY_OPERATING_SYSTEM */
  602.  
  603.  
  604. Notes.
  605. ------
  606.  
  607. MS-DOS
  608.  
  609. The object room tree option uses recursive code, and hence is stack-intensive.
  610. If compiling for MS-DOS then the memory allocated for stack must be increased
  611. to 8k or more (the standard stack of 2K is adequate for normal game execution
  612. and all other options).
  613.  
  614. Termcap
  615.  
  616. We have found that TERMCAP emulation on many TERMINFO systems is seriously
  617. deficient, escape sequences that are supported in TERMINFO simply are
  618. not supported for TERMCAP. When compiling for a TERMINFO system use the
  619. TERMINFO option rather than TERMCAP. The TERMCAP option does actually seems
  620. to work OK if all required terminal features are available. And finally, if
  621. you are compiling for MS-DOS then Microsoft C will produce a slightly more
  622. functional executable than Borland C (video paging has not been implemented
  623. for Borland C).
  624.