home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / c / rconfig.lha / RConfig_v1.1 / RConfig.doc < prev    next >
Text File  |  1992-09-20  |  7KB  |  191 lines
  1.      _________
  2.     /         \                 Omni Communications Products
  3.    |   |       |      Presents the Latest Addition to the RoboWare Line
  4.    |.---------.|
  5.    [|#########|]                        RCONFIG v1.1
  6.     |---------|
  7.      \   ~   /                Copyright 1992 by Anthon S T Pang
  8.       \  -  /
  9. _:_1__|`==='|__1_:_                Freely Redistributable
  10.      \\_____//
  11.  
  12.  
  13. Introduction
  14. ~~~~~~~~~~~~
  15.     RConfig is a 2.0 utility for >>> Manx Aztec C 5.2a <<< users for
  16.     configuring a replacement linker library (rlib.lib).  This library
  17.     is simply linked with your code, before c.lib, cl.lib, c16.lib, or
  18.     cl16.lib.
  19.  
  20.     The replacement functions available are:
  21.  
  22.         stkchk()    -     An improved low stack condition test, which
  23.                           takes into account the size of a procedure's
  24.                           local stack frame; optional dynamic stack code
  25.  
  26.         main()      -     Choose from 3 variations of the startup code:
  27.                           normal, detaching, residentable
  28.  
  29.         setjmp()    -     Adds support for free()'ing DynaStack extension
  30.                           stack blocks and alloca()'d blocks
  31.  
  32.     In addition, an alloca() function is provided.  This doesn't replace
  33.     any similarly named function in clib, but I much prefer it over the
  34.     GNU alloca.c code.
  35.  
  36.     Lastly, you can choose additional compiler options in generating the
  37.     library, size of the data model (large or small), integer size (32 vs
  38.     16 bits), and various parameters for stkchk().
  39.  
  40.  
  41. Using RConfig
  42. ~~~~~~~~~~~~~
  43.     RConfig should be run from the CLI.  It takes no parameters.
  44.  
  45.     RConfig looks for the source files in RLIB: first and then in
  46.     Aztec:RLib/.  If neither of these paths exist, you will not
  47.     get the desired effect.
  48.  
  49.     The check boxes determine whether a function is replaced or not.
  50.  
  51.     Click on the "Generate Library" button to generate source.  The
  52.     file "rlib.o" will be created in the current directory by
  53.     default.  You can change the output directory by selecting the
  54.     menu item "Change Directory...".  If you haven't redirected
  55.     RConfig's output, you'll be able to see the command string used
  56.     to compile the replacement library.
  57.  
  58.     Click on the "Optimizations..." button to go to the CC options
  59.     selection window.  RConfig will use these options in compiling
  60.     the replacement, temporarily overriding the CCOPTS environment
  61.     variable.  Click on the "Done" button or the close gadget to
  62.     return to the main RConfig window.
  63.  
  64.     To quit, you can do one of the following: click on the "Cancel"
  65.     button, click the close gadget, select the menu option for
  66.     "Quit", or press right-Amiga Q.
  67.  
  68.  
  69. Using the Replacement Library
  70. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  71.     Copy the files "include/alloca.h" and "include/rsetjmp.h" to
  72.     your Aztec:Includes/ directory or to a directory listed in
  73.     your INCLUDE environment variable setting.
  74.  
  75.     After generating the replacement library, #include "rlib.h"
  76.     in your code.  "rlib.h" in turn makes the appropriate #defines
  77.     and #includes.
  78.  
  79.     If you're using the improved stkchk() code, process the
  80.     intermediate assembly source (Compile with -at or -a options.)
  81.     with "stkchker".
  82.  
  83.     If you're using the detach startup code, declare the following
  84.     variables:
  85.  
  86.         long _stack        = 0L;    /* Stack size, 0 means use default */
  87.         long _priority     = 0L;    /* Priority (normally 0)           */
  88.         long _BackGroundIO = 1L;    /* If !=0, keep CLI for output     */
  89.         char *_procname    = "tst"; /* Just a name for reference       */
  90.  
  91.     If you're using the resident startup code, remember to compile
  92.     in small (near) data mode.
  93.  
  94.     Link rlib.lib before c.lib, c16.lib, cl.lib, or cl16.lib.  Example:
  95.  
  96.         ln test1.o rlib.lib -lc 
  97.  
  98.     Please refer to the docs/ directory for more technical information
  99.     regarding alloca(), stkchk(), and resstart.  Documentation for
  100.     the detach code can be found in "detach.man" and "detach.readme"
  101.     contained on your 5.2a disks.
  102.  
  103.  
  104. Common Errors
  105. ~~~~~~~~~~~~~
  106.     1)  Skipped file processing with stkchk().
  107.  
  108.         You must run "stkchker" on the intermediate assembly
  109.         files when using the 'better' or 'dynastack' versions
  110.         of stkchk().
  111.  
  112.     2)  Linking with the wrong version of the replacement library.
  113.  
  114.         Check the comment header of "rlib.h" to determine the
  115.         version of rlib.lib created.
  116.  
  117.     3)  Missing #defines with setjmp()/longjmp().
  118.  
  119.         Forgot to #include "rlib.h".  "rlib.h" contains #defines
  120.         which will ensure the jmp_buf structure used in <rsetjmp.h>
  121.         is the appropriate size.
  122.  
  123.     4)  Missing #define with alloca().
  124.  
  125.         Forgot to #include "rlib.h".  "rlib.h" contains a #define
  126.         which determines whether the safe or risky version of
  127.         alloca() is used.  Be careful not to mix usage of alloca()
  128.         within the same project.  Please see alloca.doc for more
  129.         information.  A Makefile with explicit dependencies on
  130.         "rlib.h" can also help to avoid mixing versions.
  131.  
  132.  
  133. Manifest
  134. ~~~~~~~~
  135.     The following files should be in this archive:
  136.  
  137.         rconfig.doc             - this file
  138.         rconfig                 - executable
  139.         stkchker                - conversion utility for new stkchk()
  140.         ToDo                    - my "to do" list
  141.         docs/alloca.doc         - documentation for alloca() function
  142.         docs/stkchk.doc         - documentation for stkchk() function
  143.         docs/resstart.doc       - documentation for residentable startup code
  144.         include/alloca.h        - header files for your code
  145.         include/rsetjmp.h
  146.         rlib/rlib.c             - replacment library source
  147.         rlib/crt0.a68
  148.         rlib/_main.c
  149.         rlib/_exit.c
  150.         rlib/rlib_alloca.c
  151.         rlib/rlib_setjmp.c
  152.         rlib/rlib_stkchk.c
  153.         src/Makefile
  154.         src/rc2.g               - GadToolsBox project
  155.         src/rconfig.c           - rconfig source
  156.         src/busyptrimg.c
  157.         src/genlib.c
  158.         src/gtbsup.c
  159.         src/rccopts.c
  160.         src/rconfig_rev.h
  161.         src/rc2.h               - generated GTB source
  162.         src/rc2.c               - generated GTB source w/mods
  163.         src/stkchker.c          - source for conversion utility
  164.         tests/TESTS.README      - description for tests/examples
  165.         tests/1/TEST            - AmigaDOS test script (Execute me)
  166.         tests/1/test.c          - test program
  167.         tests/2/TEST      tests/4b/TEST      \
  168.         tests/2/test.c    tests/4b/test.c     \
  169.         tests/3a/TEST     tests/5/TEST         \
  170.         tests/3a/test.c   tests/5/test.c        \ more scripts & programs
  171.         tests/3b/TEST     tests/6/TEST          /
  172.         tests/3b/test.c   tests/6/test.c       /
  173.         tests/4a/TEST     tests/7/TEST        /
  174.         tests/4a/test.c   tests/7/test.c     /
  175.  
  176.     Please do not distribute incomplete or augmented (ie adding BBS ads)
  177.     versions of this archive.
  178.  
  179.  
  180. Contacting the Author
  181. ~~~~~~~~~~~~~~~~~~~~~
  182.     Send questions, bug reports, suggestions, donations, etc to:
  183.  
  184.     Omni Communications Products        UUCP: apang@mindlink.bc.ca
  185.     Attn: Anthon Pang                   BIX: apang
  186.     P.O. BOX 35266
  187.     Vancouver, BC  V6M 4G4
  188.     Canada
  189.  
  190.                                 - - - EOF - - -
  191.