home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / disks / disk466.lzh / Dice / dice206b.lzh / netdcc / doc / dcc.doc < prev    next >
Text File  |  1991-01-13  |  26KB  |  646 lines
  1.  
  2. dcc/dcc                                 dcc/dcc
  3.  
  4.                 DCC.DOC
  5.  
  6.                   Matthew Dillon
  7.                   891 Regal Rd.
  8.                   Berkeley, Ca. 94708
  9.                   USA
  10.  
  11.                   dillon@overload.Berkeley.CA.US        --or--
  12.                   uunet.uu.net!overload!dillon
  13.  
  14.                   BIX: mdillon
  15.  
  16.     DCC <options and files>
  17.  
  18.     NOTE:   new this version, use of single precision IEEE libraries for
  19.     floating point.   Please read the note under the option '-ffp' for
  20.     more information.
  21.  
  22.     DCC is similar to the UNIX 'cc' command and is the frontend for the
  23.     DICE compiler.  For best performance I strongly suggest that you make
  24.     DCC, DC1, DCPP, DAS, and DLINK resident.  If you do not have enough
  25.     memory to do so you at least want to leave the largest programs, DC1
  26.     and DAS resident.    It is suggested that your machine have at least 1MB
  27.     of memory.    A compile or link can take as much as 400K of run-time
  28.     memory.
  29.  
  30.     Options may occur anywhere on the command line but MUST occur singly.
  31.     That is, -c -a instead of -ca.  file arguments to options may occur
  32.     with or without an intervening space.  -oFILE and -o FILE are both legal.
  33.  
  34.     Files ending in .a[sm] are assumed to be assembly files.  Files ending
  35.     in .l[ib] are assumed to be library files.    Files ending in .o[bj] are
  36.     assumed to be object files.  All other files are assumed to be C source
  37.     files.
  38.  
  39.     Normally DCC compiles all C source files, assembles all .a[sm] files,
  40.     and links the resulting object files with any specified .o files
  41.     together to produce an executable.    The output file may optionally be
  42.     specified with the -o option.  If not specified, a default output
  43.     filename based on the name of the input file is generated.    This
  44.     general action is modified by two options:
  45.  
  46.     -c    DCC does NOT link, -o specifies the output object file
  47.  
  48.     -a    DCC does NOT assemble (i.e. leaves the .a file resulting from
  49.         a compile).  -o specifies the output assembly file
  50.  
  51.     If neither option is given -o specifies the name of the resulting
  52.     executable.
  53.  
  54.     The default object directory is T: and may be changed with the -O option.
  55.     The default temporary directory is also T: and may be changed with the -T
  56.     option.  IF YOU HAVE LIMITED MEMORY you may have to specify that
  57.     temporary files not be placed in T: either by re-assigning T: or using
  58.     the -T option.  DICE goes much slower if temporary files must be written
  59.     to a floppy or even a hard disk.
  60.  
  61.     WARNING: .a[sm] files are assembled with DAS, read DAS.DOC if you
  62.     intend to assemble non-DC1 generated assembly.
  63.  
  64.         ------------------- OPTIONS ------------------
  65.  
  66.     file    File to compile, assemble (.a), and/or link (.o, .lib)
  67.  
  68.     @file    File containing further list of files, one per line.
  69.         (blank lines and lines beginning with ';' or '#' are
  70.         ignored.  File may NOT contain further options).
  71.  
  72.     -E file    specify stderr file, any errors are appended to the file
  73.         instead of to stdout.  Useful for batch compiles
  74.  
  75.     -c        Compile C source files and assemble into OBJECT files
  76.         only (do not link).
  77.  
  78.     -a        Compile C source files into ASSEMBLY files (do not assemble
  79.         or link).
  80.  
  81.         Keep in mind the DAS will do further optimizations on the
  82.         assembly file that you see.
  83.  
  84.     -l0     Do not link default libraries (dlib:c.lib dlib:amigas.lib
  85.         dlib:auto.lib), or standard startup (dlib:c.o and
  86.         dlib:x.o).
  87.  
  88.         BEGINNER'S NOTE:    Do not use this option
  89.  
  90.         This option is used in special circumstances, such as when
  91.         generating .libraries or .devices.
  92.  
  93.         WARNING: DICE is much more dependant on its startup code
  94.         (c.o and x.o) than other compilers, do not link without
  95.         the startup unless you know what you are doing.
  96.  
  97.     -2.0    Default amiga.lib is    dlib:amigas20.lib
  98.         Default amiga include path is dinclude:amiga20/
  99.  
  100.         -2.x where 'x' is the second digit replacing the '0' in the
  101.         above example.    This option is useful when compiling for
  102.         different versions of the operating system.
  103.  
  104.     -1.4    Like -2.0, but using dlib:amigas14.lib and dinclude:amiga14/
  105.  
  106.         Again, -1.x may be specified.
  107.  
  108.     -l lib    When linking include this library. (space is optional)
  109.  
  110.         Generally -l is used to include the math library (-lm)
  111.         when formatted floating point *printf()s are required.
  112.  
  113.     -I0     remove default include path from search list.  The default
  114.         include path is dinclude: and dinclude:amiga/ (unless
  115.         modified by -1.x and -2.x options)
  116.  
  117.     -I dir    When compiling scan this include directory (space is
  118.         optional) The specified path takes precedence over defaults
  119.         but defaults are NOT removed.
  120.  
  121.     -D define[=value]
  122.         Pre-define a symbol
  123.  
  124.     -U        undefine __STDC__, mc68000, _DCC, and AMIGA.
  125.  
  126.     BEGINNER'S NOTE:    Do not use any of these options
  127.  
  128.     -o file    Specify output executable, object, or assembly file name
  129.         depending on what you are producing.  The space is optional
  130.  
  131.     -020    generate code for the 68020 and later microprocessors
  132.     -030    generate code for the 68030 and later microprocessors
  133.     -881    generate inline FFP code for the 68881
  134.     -882    generate inline FFP code for the 68882
  135.  
  136.     BEGINNER'S NOTE:    Do not use any of these options
  137.  
  138.     These options exist to produce 020 and 030 opcodes, and 881/882
  139.     inline assembly for floating point operations.    They are not
  140.     necessarily implemented yet.  The intent is to implement them
  141.     by V2.06 .
  142.  
  143.     -md     small data model (default)      uses A4-relative
  144.     -mD     large data model        uses absolute-long
  145.     -mc     small code model (default)      uses PC-relative
  146.     -mC     large code model        uses absolute-long
  147.  
  148.     BEGINNER'S NOTE:    Use only -mD if you declare more than
  149.     64KBytes of data.
  150.  
  151.     These options specify the default data and code model to use.
  152.     The model may be overriden by use of the __near and __far
  153.     type qualifiers (see EXTENSIONS.DOC) on a variable by variable
  154.     basis.
  155.  
  156.     DICE defaults to the small data and small code model, and is able
  157.     to generate >32KBytes of code using the small code model so you
  158.     should never have to use -mC.  Note that the DICE libraries have
  159.     all been compiled with the small-data model, and certain
  160.     applications may disrupt the base register, A4... in this case
  161.     use of the __geta4 type qualifier should be of use.  If worse
  162.     comes to worse you can recompile a large-data model C.LIB, but
  163.     I suggest you try other solutions first.
  164.  
  165.     -ms0    (default), only const objects are put into a CODE hunk
  166.     -ms     string constants are put into the read-only code hunk
  167.     -mS     string constants are put into the read-only code hunk AND
  168.         all external const references use NEAR addressing
  169.     BEGINNER'S NOTE:    Use only -ms
  170.  
  171.     -ms0 turns off -ms/-mS in case you have it in your DCCOPTS enviroment
  172.     variable and want to turn it off.
  173.  
  174.     Default operation (no -ms or -mS) puts 'const' items into a
  175.     read-only CODE hunk.  Locally declared objects are referenced
  176.     using PC-REL while external objects (declared in some other
  177.     module) are referenced using 32-BIT ABSOLUTE addressing.
  178.  
  179.     -ms will additionally make all string constants, such as "fubar",
  180.     const and referenced via PC-REL.  -ms is an extremely useful
  181.     option when you will never modify any of your string constants
  182.     because the strings are not copied for multiple running instances
  183.     of the program (if resident).
  184.  
  185.     -mS works like -ms, but in addition forces all external const
  186.     references to use PC-REL addressing INSTEAD of 32-bit absolute
  187.     addressing.  THIS IS A VERY DANGEROUS OPTION, DO NOT USE UNLESS
  188.     THE FINAL CODE SIZE IS LESS THAN 32 KBytes.
  189.  
  190.     Using -ms along with -r can result in huge savings of memory due to
  191.     the string constants being moved out of the data segment (which
  192.     must be duplicated for each running instance of the program).
  193.  
  194.     WARNING WARNING.  In all cases if you declare an object as 'const'
  195.     it must be extern'd as 'const' in other modules or incorrect code
  196.     will be generated.  This is true whether you use -ms/S or not.
  197.  
  198.     -mr     registered arguments, light
  199.     -mR     registered arguments, medium
  200.     -mRR    registered arguments, strict
  201.  
  202.     BEGINNERS NOTE:     either do not use these options or use only -mr
  203.     BEGINNERS NOTE:     see REGARGS.DOC
  204.  
  205.     These options control the automatic registerization of procedure
  206.     arguments.  Only those prototyped procedures declaring 4 or fewer
  207.     arguments will be registered.  Values are passed in D0/D1/A0/A1
  208.     according to the type of variable and availabilty of registers/
  209.  
  210.     -mr generates entry points for both the registered argument and
  211.         normal version of the function.  This option is ideal for
  212.         generating multi-model libraries.
  213.  
  214.     -mR generates only a single, registered entry point
  215.  
  216.     -mRR is similar to -mR but extends registerization to indirect
  217.         function calls (that are fully prototyped).  This is the
  218.         most dangerous option.
  219.  
  220.     Note that -mr and -mR assign the normal, nonregistered entry point
  221.     of a function to any indirect function pointers whether they are
  222.     fully prototyped or not (e.g. void (*func)() or void (*func)(int) )
  223.  
  224.     -mRR assigns either the registered or normal entry point to
  225.     function pointers depending on whether they are prototyped or not
  226.     (and any calls made through these function pointers will use the
  227.     registered args method).
  228.  
  229.     WARNING:    -mR CANNOT BE USED IF YOU MAKE C.LIB CALLS THAT TAKE
  230.     CALL-BACK FUNCTIONS AS ARGUMENTS.  -mr and -mRR *CAN* be used,
  231.     however with -mRR you must be careful to supply the registered
  232.     entry point.
  233.  
  234.     WARNING:    AMIGA.LIB ROUTINES THAT TAKE CALL-BACK FUNCTIONS AS
  235.     ARGUMENTS MUST BE GIVEN NON-REGISTERED ENTRY POINTS.  Thus if
  236.     you use -mRR you *must* qualify the procedure or function pointer
  237.     type specification with __stkargs to entire it has a normal
  238.     entry point.
  239.  
  240.     -mw <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  241.         AMIGA EXECUTABLES
  242.  
  243.     BEGINNER'S NOTE:    Do not use this option
  244.  
  245.     This option is another data model, called the ABSOLUTE-WORD data
  246.     model.    Source files compiled with this option generate
  247.     absolute-word data references to access data objects instead of
  248.     A4-relative or absolute-long.  The base of the data segment must be
  249.     specified as decimal, 0octal, or 0xHEX.
  250.  
  251.     Since absolute-word is used exclusive of A4-relative, the compiler
  252.     will now use A4 for register variables.  You may NOT mix -mw
  253.     modules with small-data models (do NOT use C.LIB, see ROMABLE.DOC)
  254.  
  255.     The ROMABLE program is usually run on the executable generated by
  256.     DLink to generate a ROM.
  257.  
  258.     -ma <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  259.         AMIGA EXECUTABLES
  260.  
  261.     BEGINNER'S NOTE:    Do not use this option
  262.  
  263.     This option specifies to the compiler and linker that the resulting
  264.     code is intended to be relocated to a permanent data address, that
  265.     specified by <addr> in decimal, 0octal, of 0xHEX.
  266.  
  267.     Unlike -mw, -ma assumes that the data segment can be placed
  268.     anywhere.  The ROMABLE program is usually run on the executable
  269.     generated by DLink to generate a ROM.
  270.  
  271.     You may still specify a data model, -md or -mD, to use with this
  272.     option.  Unlike -mw, -ma does NOT touch the A4 register and thus
  273.     may be mixed with the small-data model.  Again, see ROMABLE.DOC
  274.  
  275.     -rom    SET UP OPTIONS FOR GENERATING ROMABLE CODE
  276.  
  277.     BEGINNER'S NOTE:    Do not use this option
  278.  
  279.     Like -l0, -rom disables automatic inclusion of a startup file (you
  280.     must specify your own) and libraries.  However, x.o is still
  281.     included to sink any autoinit code.  Your startup code must handle
  282.     the appropriate model and call autoinit code before calling your
  283.     program main
  284.  
  285.     This option is used to support ROMed firmware, i.e. non-amiga
  286.     executables.  You should never link with C.LIB.  Instead, a new
  287.     library, ROM.LIB, is available.
  288.  
  289.     ROM.LIB contains no static or global references and thus works
  290.     with any data model, and only completely self-contained routines
  291.     are included.  The only data ROM.LIB uses is stack-based.  All
  292.     ROM.LIB routines are completely reentrant, including
  293.     [v]sprintf() !
  294.  
  295.     -proto    PROTOTYPE CHECKING AND OPTIMIZATIONS
  296.  
  297.     When this option is used, an ERROR message will be generated for
  298.     any call that is not prototyped.  This option is useful to ensure
  299.     that you have properly prototyped routines (when you use
  300.     prototypes), especially when floats and doubles are passed and
  301.     indirect function pointers are used (they must be prototyped as
  302.     well!).
  303.  
  304.     IN THE FUTURE THIS WILL ENABLE STACK-ARGUMENT OPTIMIZATION.
  305.     Currently, chars and shorts are extended to long's when pushed onto
  306.     the stack for a subroutine call.  In the future if the -proto
  307.     option is used these objects will be pushed as shorts and not
  308.     extended.
  309.  
  310.     -r        Make executable residentable with separate CODE & DATA hunks
  311.     -pr     Make executable residentable w/ no relocation hunks
  312.     -pi     Make executable NON-residentable w/ no relocation hunks
  313.  
  314.     BEGINNER'S NOTE:    Just use -r to get residentable executables and
  315.     do not worry about these other options.
  316.  
  317.     -pr/-pi generate 'position independant' code also useful for ROMed
  318.     applications.  NOTE that -pi and -pr force const items to be
  319.     referenced pc-relative as well, causing -ms and -mS to do the same
  320.     thing (when combined with -pr/-pi)
  321.  
  322.     CODE SIZE IS LIMITED TO 32KBYTES WHEN YOU USE -pr OR -pi
  323.  
  324.     Refer to the section below called 'RESIDENTABILITY' for a
  325.     discussion of these options
  326.  
  327.     NOTE ROPT1:    You may not make data references within const
  328.     declared objects when using the -r/-pr options.  This is because
  329.     the CODE hunk is shared between running instances of the program
  330.     and these address references would be different between the
  331.     instances.
  332.  
  333.     However, if you are using the -ms option, string constants will
  334.     be in the code section and thus no problem.
  335.  
  336.     -O outdir    Specify directory that is to contain output executable,
  337.         object, or assembly files (used when specifying multiple
  338.         source files)
  339.  
  340.     -O is useful to tell the compiler where to put the objects
  341.     when you use dcc to compile and link a whole bunch of files
  342.     at once.  In this case, the -o option can still be used to
  343.     specify where to put the final executable.
  344.  
  345.     NOTE:    The -O name is used as a prefix so if you are
  346.     specifying a directory be sure it has a ':' or '/' on
  347.     the end.
  348.  
  349.     -T tmpdir    Specify the temporary directory used to hold preprocessed
  350.         source files and temporary assembly files... files that
  351.         will be deleted after use.
  352.  
  353.     NOTE:    The -T name is used as a prefix so if you are
  354.     specifying a directory be sure it has a ':' or '/' on
  355.     the end.
  356.  
  357.     The default is T: .. this option is useful in low-memory situations
  358.     where you may decide to put intermediate files elsewhere.  Putting
  359.     intermediate files on your HD or floppy slows down compilation by
  360.     an order of magnitude, but if you are running on a system with
  361.     little memory you may not have a choice.
  362.  
  363.     -s        Include symbolic debugging information in the executable.
  364.         (dlink opion)
  365.  
  366.     This option includes the symbol table in the resulting executable
  367.     and is passed to dlink.  When using DOBJ to disassemble an
  368.     executable, DOBJ will use the symbol table to generate a more
  369.     symbolic dump.
  370.  
  371.     -S        ALTERNATE SECTION NAMING OP FOR LIBRARIES
  372.  
  373.     When making libraries: uses alternate section naming conventions so
  374.     that all initialized data in the module will be placed before any
  375.     initialized data in non -S modules (i.e. normal linked object
  376.     files).  Any library BSS will be placed before non-library BSS.
  377.     Thus, the final ordering in the final executable will be:
  378.  
  379.         [LIBDATA] [PROGRAMDATA] [LIBBSS] [PROGRAMBSS]
  380.  
  381.     Thus, if your program contains >64K Bytes of BSS you can still
  382.     link with a library that tries to reference its own BSS using
  383.     the small-data model.  If your library declares only initialized
  384.     data (i.e. int x = 0; ), then you can link with the library even
  385.     if your program declares >64KBytes of *initialized* data !
  386.  
  387.     -v        Display commands as DCC executes them.
  388.  
  389.     -new    Checks timestamps for source/destination and only
  390.         compiles/assembles if object is outdated or does not
  391.         exist.    Used to make DCC a standalone make.
  392.  
  393.     -f        FAST / ^C HANDLING FOR 1.3
  394.  
  395.         This option is used for 1.3 only.  You MUST be using the
  396.         commodore shell (NewShell) and if you make programs
  397.         resident you MUST use the commodore C:Resident command.
  398.  
  399.         This option will probably not work if you use WShell or
  400.         ARPShell under 1.3.  This option allows DICE to take
  401.         short cuts to run sub-programs and allows ^C to be
  402.         propogated to said programs.  This option is useful
  403.         to set permanently in your DCCOPTS ENV: variable if
  404.         you run under 1.3
  405.  
  406.         DICE under 2.0 has no such problems and will run sub
  407.         programs optimally, including propogation of ^C.
  408.  
  409.     -frag    FRAGment (linker option).
  410.  
  411.     Tell linker not to combine all code hunks together or combine all
  412.     data hunks together. Cannot be used if the -r or -mw options are
  413.     used. Generally only useful if the large-data model is used.  Not
  414.     entirely supported yet.
  415.  
  416.     -ffp    Set fp library for floats
  417.     BEGINNER'S NOTE:    When using single precision floating point
  418.     this option, use of the original ffp libraries, will make the
  419.     program portable across all amigas.  Otherwise only amigas that
  420.     have the commodore MathIeeeSing*.library libraries will be
  421.     able to run the program.
  422.  
  423.     If not specified, 'mathieeesingtrans.library' and
  424.     'mathieeesingbas.library' are used.  These are new 2.0 libraries
  425.     that may not exist on all machines yet.
  426.  
  427.     If specified, 'mathtrans.library' is used .. motorola's FFP float
  428.     library.
  429.  
  430.     NOTE:  IF -ffp is used, be warned that conversion from floats to
  431.     doubles and back again is not entirely reliable.
  432.  
  433.     -chip    CHIP force (linker option).
  434.  
  435.     Tell linker to force all hunks into CHIP memory.  You should
  436.     generally not use this option.    Instead, use the __chip
  437.     keyword (see EXTENSIONS.DOC) for those specific data items
  438.     that need to be in CHIP memory.
  439.  
  440.     NOTE:    CHIP data items are accessed using the large-data
  441.     model, thus you cannot create residentable executables that
  442.     contain __chip declarations UNLESS THEY ARE ALSO 'const'
  443.     objects -- read-only.
  444.  
  445.     -aztec    The front end attempts to run Aztec executables
  446.     -lattice    The front end attempts to run Lattice executables
  447.     -sas    same as -lattice
  448.  
  449.     These options allow one to write a single DMakefile able to handle
  450.     compilation under any compiler, assuming the source is compilable
  451.     under any compiler.
  452.  
  453.     These are very limited options and may not work across new
  454.     versions of Aztec or Sas/C
  455.  
  456.  
  457.     The ENV:DCCOPTS enviroment variable may contain additional options.
  458.  
  459.     ENV: must exist for DCC to run, even if you do not have a DCCOPTS
  460.     enviroment variable.  If you do not use ENV: then assign it to RAM:
  461.  
  462.  
  463.     Example #1.  Compile hello.c to executable.  The objects will be
  464.         left in T:
  465.  
  466.     1> dcc hello.c -o ram:hello
  467.     1> ram:hello
  468.  
  469.     Example #2.  Compile hello.c to executable and put the object file
  470.         in X:
  471.  
  472.     1> dcc hello.c -o ram:hello -TX:
  473.  
  474.     Example #3.  Compile hello.c into object into RAM: then link with symbols
  475.  
  476.     1> dcc -c hello.c -o ram:hello.o
  477.     1> dcc ram:hello.o -o ram:hello -s
  478.  
  479.     Example #4.  Compile foo.c and link with an already compiled object file
  480.          gar.o to produce an executable.  foo.o is placed in
  481.          T:
  482.  
  483.     1> dcc foo.c gar.o -o ram:foogar
  484.  
  485.                   PREPROCESSOR
  486.  
  487.     Predefined Symbols:
  488.  
  489.     __LINE__        current line number (integer constant)
  490.     __DATE__        current date (string)
  491.     __TIME__        current time (string)
  492.     __FILE__        current file (string)
  493.  
  494.     __BASE_FILE__        base source file (string), allows specification
  495.                 of the actual name of the source file from
  496.                 within an include file.
  497.  
  498.                 (-U undefines the below symbols)
  499.     __STDC__
  500.     mc68000
  501.     _DCC
  502.     AMIGA
  503.     _FFP_FLOAT        set if single prec. floats are in FFP format
  504.     _SP_FLOAT        set if single prec. floats are in IEEE-SING format
  505.                 (default)
  506.  
  507.     NOTE:  There are no limits to symbol and macro lengths.
  508.  
  509.                        MODELS
  510.  
  511.     DICE defaults to using the small-code and small-data models.  You can use
  512.     the small-code model even if your code is larger than 64K.    However, to
  513.     accomplish this DLINK uses one or more JUMP tables, and thus doing direct
  514.     comparisons of the address of a given procedure may yield a different
  515.     address depending on the module.  If this is a problem you must either
  516.     change the code or use the large-code model.
  517.  
  518.     The small-data model uses 16 bit A4-relative references to access
  519.     static and global data.  This has the advantage of making the executable
  520.     smaller for two reasons:
  521.  
  522.     (1) each reference requires only one word of extension instead of two.
  523.  
  524.     (2) The linker is able to completely resolve the relative offsets
  525.         and thus no relocation information is required in the final
  526.         executable for such references.
  527.  
  528.     The small-data model also makes code run a bit faster.  When you compile
  529.     with the large-data model, note that the library code (C.LIB) still uses
  530.     small-data references to access library based globals.  This is
  531.     normally not a problem since, due to the ordering of sections in the
  532.     startup module, all library data occurs before user data and is thus
  533.     within the A4 relative range.  However, there is one problem that you
  534.     might come up against... since BSS is always placed after initialized
  535.     DATA, if you have more than 64KBytes of initialized data the linker may
  536.     give up with an error due to library BSS being beyond the A4 relative
  537.     offset range.
  538.  
  539.                PUTTING CONST DATA INTO THE CODE SEGMENT
  540.  
  541.     Two options are available to handle the 'const' keyword: -ms and -mS.  If
  542.     neither are used 'const' is ignored.  The difference between the two
  543.     determines how external references (between modules) are handled.
  544.  
  545.     With -ms, all string constants "fubar" are placed into the code segment
  546.     and referenced according to the code model (pc-rel or absolute).  Any
  547.     variable declared const will also be put in the code segment and
  548.     referenced similary.  However, any EXTERN'd variables referenced but
  549.     not defined in this module (i.e. defined in another module) will be
  550.     accessed using ABSOLUTE references, since you cannot make a jump table
  551.     for data variables.
  552.  
  553.     The -mS option is much more dangerous.. it works the same as -ms except
  554.     that external references use pc-relative addressing as well. your final
  555.     executable must be LESS THAN 32KBytes TO ENSURE ALL CODE IS REACHABLE
  556.     VIA PC-RELATIVE ADDRESSING.  If you have a choice, please use -ms
  557.     instead of -mS .
  558.  
  559.     'const __chip' variables will also be placed in the code section, but
  560.     these always use absolute references since the code section is not
  561.     combined together with other code sections.  You may also override
  562.     default access method (pc-rel/absolute) by using the __near and __far
  563.     keywords, but this is not advised.
  564.  
  565.     The -ms option affects the main compiler DC1 and can be specified
  566.     independantly for each source module (i.e. some can have it while
  567.     others do not, though normally all will have it one way or the other)
  568.  
  569.     WHEN YOU USE -pr OR -pi, use of the -ms option is silently forced to
  570.     -mS
  571.  
  572.                 RESIDENTABILITY
  573.  
  574.     Two options are available to generate residentable executables and one
  575.     option is available to genreate a non-residentable executable with no
  576.     relocation information (loads quickly).
  577.  
  578.         RES?   RELOC?   DataLim CodeLim Alloc?  Hunks
  579.  
  580.     -md     no       yes        64K(1)  none    no      DATA, CODE
  581.     -mD     no       yes        none    none    no        DATA, CODE, optionally more
  582.     -r        yes    yes        64K     none    yes     DATA, CODE
  583.     -pr     yes    no        64K     32K     yes     CODE (combined DATA+CODE)
  584.     -pi     no       no        64K     32K     no        CODE (combined DATA+CODE)
  585.  
  586.     RES:    Can this program be made resident (dlink sets Pure bit)
  587.  
  588.     RELOC:    Will this executable contain 32-bit relocations?
  589.  
  590.     DATALIM:    The maximum amount of DATA+BSS that may be declared
  591.  
  592.     CODELIM:    The maximum size of the CODE
  593.  
  594.     ALLOC:    Does the startup code allocate a run time DATA+BSS segment?
  595.         (basically, resident programs must, non-resident programs
  596.         do not)
  597.  
  598.     HUNKS:    Number and type of hunks that may exist in the executable
  599.  
  600.  
  601.     -md     default
  602.  
  603.     -mD     used when final executable contains more than 64KBytes of data
  604.  
  605.     -r        most often used option
  606.  
  607.     -pr     used instead of -r if there is only a little initialized data
  608.  
  609.         Can be used with most programs but requires one large chunk of
  610.         memory instead of the two smaller chunks that -r allocates
  611.  
  612.         Also used in ROMable applications
  613.  
  614.     -pi     used instead of default when there is only a little INITIALIZED+BSS
  615.  
  616.         Can be used with many small programs that you do not intend to
  617.         make residentable, to make them load extremely fast (since there
  618.         is no relocation information).
  619.  
  620.         Also used in ROMable applications
  621.  
  622.     The __geta4 type qualifier will NOT work with residentable programs.
  623.  
  624.     You cannot use __far when accessing non-const (see -ms option) data
  625.     in residentable programs
  626.  
  627.     USING THE -ms OPTION can drastically reduce the amount of data that
  628.     needs to be allocated/copied when a resident program starts up by
  629.     moving string constants into the code section (only the data section is
  630.     duplicated), reducing overhead in both time and space for each
  631.     invocation of the RESIDENT'd program.
  632.  
  633.     To use one of the options -r, -pi, or -pr specify on the DCC line when
  634.     both compiling and linking your code.  The resulting executable will have
  635.     the pure bit set (for -r and -pr options) and be residentable.
  636.  
  637.     -r and -pr generate no BSS since the startup code is going to allocate
  638.     the DATA+BSS space.  -pi generates BSS space in the code segment just
  639.     after the initialized data.
  640.  
  641.     default    uses c.o
  642.     -r        uses c.o
  643.     -pi     uses c_pi.o
  644.     -pr     uses c_pr.o
  645.  
  646.