home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / languages / dice_443 / dice.lzh / doc / dcc.doc < prev    next >
Text File  |  1991-01-14  |  26KB  |  648 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.     REGISTERED VERSION OF DICE ONLY, this option is not enabled in
  203.     the freeware version, sorry! see REGISTER.DOC
  204.  
  205.     BEGINNERS NOTE:     either do not use these options or use only -mr
  206.  
  207.     These options control the automatic registerization of procedure
  208.     arguments.  Only those prototyped procedures declaring 4 or fewer
  209.     arguments will be registered.  Values are passed in D0/D1/A0/A1
  210.     according to the type of variable and availabilty of registers/
  211.  
  212.     -mr generates entry points for both the registered argument and
  213.         normal version of the function.  This option is ideal for
  214.         generating multi-model libraries.
  215.  
  216.     -mR generates only a single, registered entry point
  217.  
  218.     -mRR is similar to -mR but extends registerization to indirect
  219.         function calls (that are fully prototyped).  This is the
  220.         most dangerous option.
  221.  
  222.     Note that -mr and -mR assign the normal, nonregistered entry point
  223.     of a function to any indirect function pointers whether they are
  224.     fully prototyped or not (e.g. void (*func)() or void (*func)(int) )
  225.  
  226.     -mRR assigns either the registered or normal entry point to
  227.     function pointers depending on whether they are prototyped or not
  228.     (and any calls made through these function pointers will use the
  229.     registered args method).
  230.  
  231.     WARNING:    -mR CANNOT BE USED IF YOU MAKE C.LIB CALLS THAT TAKE
  232.     CALL-BACK FUNCTIONS AS ARGUMENTS.  -mr and -mRR *CAN* be used,
  233.     however with -mRR you must be careful to supply the registered
  234.     entry point.
  235.  
  236.     WARNING:    AMIGA.LIB ROUTINES THAT TAKE CALL-BACK FUNCTIONS AS
  237.     ARGUMENTS MUST BE GIVEN NON-REGISTERED ENTRY POINTS.  Thus if
  238.     you use -mRR you *must* qualify the procedure or function pointer
  239.     type specification with __stkargs to entire it has a normal
  240.     entry point.
  241.  
  242.     -mw <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  243.         AMIGA EXECUTABLES
  244.  
  245.     BEGINNER'S NOTE:    Do not use this option
  246.  
  247.     This option is another data model, called the ABSOLUTE-WORD data
  248.     model.    Source files compiled with this option generate
  249.     absolute-word data references to access data objects instead of
  250.     A4-relative or absolute-long.  The base of the data segment must be
  251.     specified as decimal, 0octal, or 0xHEX.
  252.  
  253.     Since absolute-word is used exclusive of A4-relative, the compiler
  254.     will now use A4 for register variables.  You may NOT mix -mw
  255.     modules with small-data models (do NOT use C.LIB, see ROMABLE.DOC)
  256.  
  257.     The ROMABLE program is usually run on the executable generated by
  258.     DLink to generate a ROM.
  259.  
  260.     -ma <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  261.         AMIGA EXECUTABLES
  262.  
  263.     BEGINNER'S NOTE:    Do not use this option
  264.  
  265.     This option specifies to the compiler and linker that the resulting
  266.     code is intended to be relocated to a permanent data address, that
  267.     specified by <addr> in decimal, 0octal, of 0xHEX.
  268.  
  269.     Unlike -mw, -ma assumes that the data segment can be placed
  270.     anywhere.  The ROMABLE program is usually run on the executable
  271.     generated by DLink to generate a ROM.
  272.  
  273.     You may still specify a data model, -md or -mD, to use with this
  274.     option.  Unlike -mw, -ma does NOT touch the A4 register and thus
  275.     may be mixed with the small-data model.  Again, see ROMABLE.DOC
  276.  
  277.     -rom    SET UP OPTIONS FOR GENERATING ROMABLE CODE
  278.  
  279.     BEGINNER'S NOTE:    Do not use this option
  280.  
  281.     Like -l0, -rom disables automatic inclusion of a startup file (you
  282.     must specify your own) and libraries.  However, x.o is still
  283.     included to sink any autoinit code.  Your startup code must handle
  284.     the appropriate model and call autoinit code before calling your
  285.     program main
  286.  
  287.     This option is used to support ROMed firmware, i.e. non-amiga
  288.     executables.  You should never link with C.LIB.  Instead, a new
  289.     library, ROM.LIB, is available.
  290.  
  291.     ROM.LIB contains no static or global references and thus works
  292.     with any data model, and only completely self-contained routines
  293.     are included.  The only data ROM.LIB uses is stack-based.  All
  294.     ROM.LIB routines are completely reentrant, including
  295.     [v]sprintf() !
  296.  
  297.     -proto    PROTOTYPE CHECKING AND OPTIMIZATIONS
  298.  
  299.     When this option is used, an ERROR message will be generated for
  300.     any call that is not prototyped.  This option is useful to ensure
  301.     that you have properly prototyped routines (when you use
  302.     prototypes), especially when floats and doubles are passed and
  303.     indirect function pointers are used (they must be prototyped as
  304.     well!).
  305.  
  306.     IN THE FUTURE THIS WILL ENABLE STACK-ARGUMENT OPTIMIZATION.
  307.     Currently, chars and shorts are extended to long's when pushed onto
  308.     the stack for a subroutine call.  In the future if the -proto
  309.     option is used these objects will be pushed as shorts and not
  310.     extended.
  311.  
  312.     -r        Make executable residentable with separate CODE & DATA hunks
  313.     -pr     Make executable residentable w/ no relocation hunks
  314.     -pi     Make executable NON-residentable w/ no relocation hunks
  315.  
  316.     BEGINNER'S NOTE:    Just use -r to get residentable executables and
  317.     do not worry about these other options.
  318.  
  319.     -pr/-pi generate 'position independant' code also useful for ROMed
  320.     applications.  NOTE that -pi and -pr force const items to be
  321.     referenced pc-relative as well, causing -ms and -mS to do the same
  322.     thing (when combined with -pr/-pi)
  323.  
  324.     CODE SIZE IS LIMITED TO 32KBYTES WHEN YOU USE -pr OR -pi
  325.  
  326.     Refer to the section below called 'RESIDENTABILITY' for a
  327.     discussion of these options
  328.  
  329.     NOTE ROPT1:    You may not make data references within const
  330.     declared objects when using the -r/-pr options.  This is because
  331.     the CODE hunk is shared between running instances of the program
  332.     and these address references would be different between the
  333.     instances.
  334.  
  335.     However, if you are using the -ms option, string constants will
  336.     be in the code section and thus no problem.
  337.  
  338.     -O outdir    Specify directory that is to contain output executable,
  339.         object, or assembly files (used when specifying multiple
  340.         source files)
  341.  
  342.     -O is useful to tell the compiler where to put the objects
  343.     when you use dcc to compile and link a whole bunch of files
  344.     at once.  In this case, the -o option can still be used to
  345.     specify where to put the final executable.
  346.  
  347.     NOTE:    The -O name is used as a prefix so if you are
  348.     specifying a directory be sure it has a ':' or '/' on
  349.     the end.
  350.  
  351.     -T tmpdir    Specify the temporary directory used to hold preprocessed
  352.         source files and temporary assembly files... files that
  353.         will be deleted after use.
  354.  
  355.     NOTE:    The -T name is used as a prefix so if you are
  356.     specifying a directory be sure it has a ':' or '/' on
  357.     the end.
  358.  
  359.     The default is T: .. this option is useful in low-memory situations
  360.     where you may decide to put intermediate files elsewhere.  Putting
  361.     intermediate files on your HD or floppy slows down compilation by
  362.     an order of magnitude, but if you are running on a system with
  363.     little memory you may not have a choice.
  364.  
  365.     -s        Include symbolic debugging information in the executable.
  366.         (dlink opion)
  367.  
  368.     This option includes the symbol table in the resulting executable
  369.     and is passed to dlink.  When using DOBJ to disassemble an
  370.     executable, DOBJ will use the symbol table to generate a more
  371.     symbolic dump.
  372.  
  373.     -S        ALTERNATE SECTION NAMING OP FOR LIBRARIES
  374.  
  375.     When making libraries: uses alternate section naming conventions so
  376.     that all initialized data in the module will be placed before any
  377.     initialized data in non -S modules (i.e. normal linked object
  378.     files).  Any library BSS will be placed before non-library BSS.
  379.     Thus, the final ordering in the final executable will be:
  380.  
  381.         [LIBDATA] [PROGRAMDATA] [LIBBSS] [PROGRAMBSS]
  382.  
  383.     Thus, if your program contains >64K Bytes of BSS you can still
  384.     link with a library that tries to reference its own BSS using
  385.     the small-data model.  If your library declares only initialized
  386.     data (i.e. int x = 0; ), then you can link with the library even
  387.     if your program declares >64KBytes of *initialized* data !
  388.  
  389.     -v        Display commands as DCC executes them.
  390.  
  391.     -new    Checks timestamps for source/destination and only
  392.         compiles/assembles if object is outdated or does not
  393.         exist.    Used to make DCC a standalone make.
  394.  
  395.     -f        FAST / ^C HANDLING FOR 1.3
  396.  
  397.         This option is used for 1.3 only.  You MUST be using the
  398.         commodore shell (NewShell) and if you make programs
  399.         resident you MUST use the commodore C:Resident command.
  400.  
  401.         This option will probably not work if you use WShell or
  402.         ARPShell under 1.3.  This option allows DICE to take
  403.         short cuts to run sub-programs and allows ^C to be
  404.         propogated to said programs.  This option is useful
  405.         to set permanently in your DCCOPTS ENV: variable if
  406.         you run under 1.3
  407.  
  408.         DICE under 2.0 has no such problems and will run sub
  409.         programs optimally, including propogation of ^C.
  410.  
  411.     -frag    FRAGment (linker option).
  412.  
  413.     Tell linker not to combine all code hunks together or combine all
  414.     data hunks together. Cannot be used if the -r or -mw options are
  415.     used. Generally only useful if the large-data model is used.  Not
  416.     entirely supported yet.
  417.  
  418.     -ffp    Set fp library for floats
  419.     BEGINNER'S NOTE:    When using single precision floating point
  420.     this option, use of the original ffp libraries, will make the
  421.     program portable across all amigas.  Otherwise only amigas that
  422.     have the commodore MathIeeeSing*.library libraries will be
  423.     able to run the program.
  424.  
  425.     If not specified, 'mathieeesingtrans.library' and
  426.     'mathieeesingbas.library' are used.  These are new 2.0 libraries
  427.     that may not exist on all machines yet.
  428.  
  429.     If specified, 'mathtrans.library' is used .. motorola's FFP float
  430.     library.
  431.  
  432.     NOTE:  IF -ffp is used, be warned that conversion from floats to
  433.     doubles and back again is not entirely reliable.
  434.  
  435.     -chip    CHIP force (linker option).
  436.  
  437.     Tell linker to force all hunks into CHIP memory.  You should
  438.     generally not use this option.    Instead, use the __chip
  439.     keyword (see EXTENSIONS.DOC) for those specific data items
  440.     that need to be in CHIP memory.
  441.  
  442.     NOTE:    CHIP data items are accessed using the large-data
  443.     model, thus you cannot create residentable executables that
  444.     contain __chip declarations UNLESS THEY ARE ALSO 'const'
  445.     objects -- read-only.
  446.  
  447.     -aztec    The front end attempts to run Aztec executables
  448.     -lattice    The front end attempts to run Lattice executables
  449.     -sas    same as -lattice
  450.  
  451.     These options allow one to write a single DMakefile able to handle
  452.     compilation under any compiler, assuming the source is compilable
  453.     under any compiler.
  454.  
  455.     These are very limited options and may not work across new
  456.     versions of Aztec or Sas/C
  457.  
  458.  
  459.     The ENV:DCCOPTS enviroment variable may contain additional options.
  460.  
  461.     ENV: must exist for DCC to run, even if you do not have a DCCOPTS
  462.     enviroment variable.  If you do not use ENV: then assign it to RAM:
  463.  
  464.  
  465.     Example #1.  Compile hello.c to executable.  The objects will be
  466.         left in T:
  467.  
  468.     1> dcc hello.c -o ram:hello
  469.     1> ram:hello
  470.  
  471.     Example #2.  Compile hello.c to executable and put the object file
  472.         in X:
  473.  
  474.     1> dcc hello.c -o ram:hello -TX:
  475.  
  476.     Example #3.  Compile hello.c into object into RAM: then link with symbols
  477.  
  478.     1> dcc -c hello.c -o ram:hello.o
  479.     1> dcc ram:hello.o -o ram:hello -s
  480.  
  481.     Example #4.  Compile foo.c and link with an already compiled object file
  482.          gar.o to produce an executable.  foo.o is placed in
  483.          T:
  484.  
  485.     1> dcc foo.c gar.o -o ram:foogar
  486.  
  487.                   PREPROCESSOR
  488.  
  489.     Predefined Symbols:
  490.  
  491.     __LINE__        current line number (integer constant)
  492.     __DATE__        current date (string)
  493.     __TIME__        current time (string)
  494.     __FILE__        current file (string)
  495.  
  496.     __BASE_FILE__        base source file (string), allows specification
  497.                 of the actual name of the source file from
  498.                 within an include file.
  499.  
  500.                 (-U undefines the below symbols)
  501.     __STDC__
  502.     mc68000
  503.     _DCC
  504.     AMIGA
  505.     _FFP_FLOAT        set if single prec. floats are in FFP format
  506.     _SP_FLOAT        set if single prec. floats are in IEEE-SING format
  507.                 (default)
  508.  
  509.     NOTE:  There are no limits to symbol and macro lengths.
  510.  
  511.                        MODELS
  512.  
  513.     DICE defaults to using the small-code and small-data models.  You can use
  514.     the small-code model even if your code is larger than 64K.    However, to
  515.     accomplish this DLINK uses one or more JUMP tables, and thus doing direct
  516.     comparisons of the address of a given procedure may yield a different
  517.     address depending on the module.  If this is a problem you must either
  518.     change the code or use the large-code model.
  519.  
  520.     The small-data model uses 16 bit A4-relative references to access
  521.     static and global data.  This has the advantage of making the executable
  522.     smaller for two reasons:
  523.  
  524.     (1) each reference requires only one word of extension instead of two.
  525.  
  526.     (2) The linker is able to completely resolve the relative offsets
  527.         and thus no relocation information is required in the final
  528.         executable for such references.
  529.  
  530.     The small-data model also makes code run a bit faster.  When you compile
  531.     with the large-data model, note that the library code (C.LIB) still uses
  532.     small-data references to access library based globals.  This is
  533.     normally not a problem since, due to the ordering of sections in the
  534.     startup module, all library data occurs before user data and is thus
  535.     within the A4 relative range.  However, there is one problem that you
  536.     might come up against... since BSS is always placed after initialized
  537.     DATA, if you have more than 64KBytes of initialized data the linker may
  538.     give up with an error due to library BSS being beyond the A4 relative
  539.     offset range.
  540.  
  541.                PUTTING CONST DATA INTO THE CODE SEGMENT
  542.  
  543.     Two options are available to handle the 'const' keyword: -ms and -mS.  If
  544.     neither are used 'const' is ignored.  The difference between the two
  545.     determines how external references (between modules) are handled.
  546.  
  547.     With -ms, all string constants "fubar" are placed into the code segment
  548.     and referenced according to the code model (pc-rel or absolute).  Any
  549.     variable declared const will also be put in the code segment and
  550.     referenced similary.  However, any EXTERN'd variables referenced but
  551.     not defined in this module (i.e. defined in another module) will be
  552.     accessed using ABSOLUTE references, since you cannot make a jump table
  553.     for data variables.
  554.  
  555.     The -mS option is much more dangerous.. it works the same as -ms except
  556.     that external references use pc-relative addressing as well. your final
  557.     executable must be LESS THAN 32KBytes TO ENSURE ALL CODE IS REACHABLE
  558.     VIA PC-RELATIVE ADDRESSING.  If you have a choice, please use -ms
  559.     instead of -mS .
  560.  
  561.     'const __chip' variables will also be placed in the code section, but
  562.     these always use absolute references since the code section is not
  563.     combined together with other code sections.  You may also override
  564.     default access method (pc-rel/absolute) by using the __near and __far
  565.     keywords, but this is not advised.
  566.  
  567.     The -ms option affects the main compiler DC1 and can be specified
  568.     independantly for each source module (i.e. some can have it while
  569.     others do not, though normally all will have it one way or the other)
  570.  
  571.     WHEN YOU USE -pr OR -pi, use of the -ms option is silently forced to
  572.     -mS
  573.  
  574.                 RESIDENTABILITY
  575.  
  576.     Two options are available to generate residentable executables and one
  577.     option is available to genreate a non-residentable executable with no
  578.     relocation information (loads quickly).
  579.  
  580.         RES?   RELOC?   DataLim CodeLim Alloc?  Hunks
  581.  
  582.     -md     no       yes        64K(1)  none    no      DATA, CODE
  583.     -mD     no       yes        none    none    no        DATA, CODE, optionally more
  584.     -r        yes    yes        64K     none    yes     DATA, CODE
  585.     -pr     yes    no        64K     32K     yes     CODE (combined DATA+CODE)
  586.     -pi     no       no        64K     32K     no        CODE (combined DATA+CODE)
  587.  
  588.     RES:    Can this program be made resident (dlink sets Pure bit)
  589.  
  590.     RELOC:    Will this executable contain 32-bit relocations?
  591.  
  592.     DATALIM:    The maximum amount of DATA+BSS that may be declared
  593.  
  594.     CODELIM:    The maximum size of the CODE
  595.  
  596.     ALLOC:    Does the startup code allocate a run time DATA+BSS segment?
  597.         (basically, resident programs must, non-resident programs
  598.         do not)
  599.  
  600.     HUNKS:    Number and type of hunks that may exist in the executable
  601.  
  602.  
  603.     -md     default
  604.  
  605.     -mD     used when final executable contains more than 64KBytes of data
  606.  
  607.     -r        most often used option
  608.  
  609.     -pr     used instead of -r if there is only a little initialized data
  610.  
  611.         Can be used with most programs but requires one large chunk of
  612.         memory instead of the two smaller chunks that -r allocates
  613.  
  614.         Also used in ROMable applications
  615.  
  616.     -pi     used instead of default when there is only a little INITIALIZED+BSS
  617.  
  618.         Can be used with many small programs that you do not intend to
  619.         make residentable, to make them load extremely fast (since there
  620.         is no relocation information).
  621.  
  622.         Also used in ROMable applications
  623.  
  624.     The __geta4 type qualifier will NOT work with residentable programs.
  625.  
  626.     You cannot use __far when accessing non-const (see -ms option) data
  627.     in residentable programs
  628.  
  629.     USING THE -ms OPTION can drastically reduce the amount of data that
  630.     needs to be allocated/copied when a resident program starts up by
  631.     moving string constants into the code section (only the data section is
  632.     duplicated), reducing overhead in both time and space for each
  633.     invocation of the RESIDENT'd program.
  634.  
  635.     To use one of the options -r, -pi, or -pr specify on the DCC line when
  636.     both compiling and linking your code.  The resulting executable will have
  637.     the pure bit set (for -r and -pr options) and be residentable.
  638.  
  639.     -r and -pr generate no BSS since the startup code is going to allocate
  640.     the DATA+BSS space.  -pi generates BSS space in the code segment just
  641.     after the initialized data.
  642.  
  643.     default    uses c.o
  644.     -r        uses c.o
  645.     -pi     uses c_pi.o
  646.     -pr     uses c_pr.o
  647.  
  648.