home *** CD-ROM | disk | FTP | other *** search
/ AMIGA PD 1 / AMIGA-PD-1.iso / Programme_zum_Heft / Programmieren / Kurztests / DiceC / doc / dcc.doc < prev    next >
Text File  |  1994-02-01  |  32KB  |  819 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.     -l lib    When linking include this library. (space is optional)
  98.  
  99.         Generally -l is used to include the math library (-lm)
  100.         when formatted floating point *printf()s are required.
  101.  
  102.         Refer to the section 'MODELS AND LIBRARIES' and 'CREATING
  103.         YOUR OWN LIBRARIES' below for more information on linking
  104.         in custom libraries.
  105.  
  106.     -2.0    Default amiga.lib is    dlib:amigas20.lib
  107.         Default amiga include path is dinclude:amiga20/
  108.  
  109.         -2.x where 'x' is the second digit replacing the '0' in the
  110.         above example.    This option is useful when compiling for
  111.         different versions of the operating system.
  112.  
  113.     -1.3    Like -2.0, but using dlib:amigas13.lib and dinclude:amiga13/
  114.  
  115.         Again, -1.x may be specified.
  116.  
  117.     -L0     remove default library search path, including all explicitly
  118.         specified (-L dir) directories up to this point.
  119.  
  120.     -L dir    add the specified directory to the library search path.  If
  121.         the object module or library can not be found in the
  122.         current directory, directories specified with -L are
  123.         searched.  -L directories are searched before the default
  124.         library directory (DLIB:), assuming it was not removed
  125.         with -L0 .
  126.  
  127.         Note that the directory path specified by -L is used to
  128.         search for libraries AND object modules.
  129.  
  130.         A trailing '/' is optional
  131.  
  132.     -I0     remove default include path from search list.  The default
  133.         include path is dinclude: and dinclude:amiga/ (unless
  134.         modified by -1.x and -2.x options)
  135.  
  136.     -I dir    When compiling scan this include directory (space is
  137.         optional) The specified path takes precedence over defaults
  138.         but defaults are NOT removed.
  139.  
  140.     -D define[=value]
  141.         Pre-define a symbol
  142.  
  143.     -U        undefine __STDC__, mc68000, _DCC, and AMIGA.
  144.  
  145.     BEGINNER'S NOTE:    Do not use any of these options
  146.  
  147.     -H<outfile>=<hdrfile>
  148.  
  149.     This option enables precompiled header file generation and
  150.     operation. You may specify any number of -H options.  Example
  151.     usage:
  152.  
  153.     -Ht:defs.m=defs.h
  154.  
  155.     When DICE encounters an #include <defs.h> this will cause it to
  156.     first check for the existance of T:DEFS.M ... if T:DEFS.M does
  157.     not exist DICE will generate it from <defs.h>.    if T:DEFS.M
  158.     does exist then DICE will use it directly and ignore <defs.h>
  159.  
  160.     You must specify the -H option both to have DICE create the
  161.     precompiled header file and to have DICE use the precompiled
  162.     header file.  Normally one makes operation as transparent as
  163.     possible so as not depend on the option existing when porting
  164.     to other enviroments.
  165.  
  166.     WARNING WARNING WILL ROBINSON!    A precompiled header file contains
  167.     the preprocessed header and preprocessor macros.  These are set in
  168.     stone!    If you modify a #define that would normally effect
  169.     preprocessing of a header file which is precompiled THE EFFECT WILL
  170.     NOT OCCUR.  It is strongly suggested you use precompiled headers
  171.     ONLY with includes that are pretty much unchanging.  For example,
  172.     the commodore includes or otherwise have an appropriate dependancy
  173.     in your DMakefile or make script to delete the precompiled header
  174.     file whenever any of your headers are modified.
  175.  
  176.     Normally one has a single -H option that enables precompiling of a
  177.     local header file, say DEFS.H, which contains #include's of all
  178.     other header files.  Source modules would then #include <defs.h>
  179.  
  180.     BEGINNERS'S NOTE:   Do not use this option
  181.  
  182.     -o file    Specify output executable, object, or assembly file name
  183.         depending on what you are producing.  The space is optional
  184.  
  185.     -020    generate code for the 68020 and later microprocessors
  186.     -030    generate code for the 68030 and later microprocessors
  187.     -881    generate inline FFP code for the 68881
  188.     -882    generate inline FFP code for the 68882
  189.  
  190.     BEGINNER'S NOTE:    Do not use any of these options
  191.  
  192.     These options exist to produce 020 and 030 opcodes, and 881/882
  193.     inline assembly for floating point operations.    They are not
  194.     necessarily implemented yet.  The intent is to implement them
  195.     by V2.06 .
  196.  
  197.     -md     small data model (default)      uses A4-relative
  198.     -mD     large data model        uses absolute-long
  199.     -mc     small code model (default)      uses PC-relative
  200.     -mC     large code model        uses absolute-long
  201.  
  202.     BEGINNER'S NOTE:    Use only -mD if you declare more than
  203.     64KBytes of data.
  204.  
  205.     These options specify the default data and code model to use.
  206.     The model may be overriden by use of the __near and __far
  207.     type qualifiers (see EXTENSIONS.DOC) on a variable by variable
  208.     basis.
  209.  
  210.     DICE defaults to the small data and small code model, and is able
  211.     to generate >32KBytes of code using the small code model so you
  212.     should never have to use -mC.  Note that the DICE libraries have
  213.     all been compiled with the small-data model, and certain
  214.     applications may disrupt the base register, A4... in this case
  215.     use of the __geta4 type qualifier should be of use.  If worse
  216.     comes to worse you can recompile a large-data model C.LIB, but
  217.     I suggest you try other solutions first.
  218.  
  219.     -ms0    (default), only const objects are put into a CODE hunk
  220.     -ms     string constants are put into the read-only code hunk
  221.     -mS     string constants are put into the read-only code hunk AND
  222.         all external const references use NEAR addressing
  223.     BEGINNER'S NOTE:    Use only -ms
  224.  
  225.     -ms0 turns off -ms/-mS in case you have it in your DCCOPTS enviroment
  226.     variable and want to turn it off.
  227.  
  228.     Default operation (no -ms or -mS) puts 'const' items into a
  229.     read-only CODE hunk.  Locally declared objects are referenced
  230.     using PC-REL while external objects (declared in some other
  231.     module) are referenced using 32-BIT ABSOLUTE addressing.
  232.  
  233.     -ms will additionally make all string constants, such as "fubar",
  234.     const and referenced via PC-REL.  -ms is an extremely useful
  235.     option when you will never modify any of your string constants
  236.     because the strings are not copied for multiple running instances
  237.     of the program (if resident).
  238.  
  239.     -mS works like -ms, but in addition forces all external const
  240.     references to use PC-REL addressing INSTEAD of 32-bit absolute
  241.     addressing.  THIS IS A VERY DANGEROUS OPTION, DO NOT USE UNLESS
  242.     THE FINAL CODE SIZE IS LESS THAN 32 KBytes.
  243.  
  244.     Using -ms along with -r can result in huge savings of memory due to
  245.     the string constants being moved out of the data segment (which
  246.     must be duplicated for each running instance of the program).
  247.  
  248.     WARNING WARNING.  In all cases if you declare an object as 'const'
  249.     it must be extern'd as 'const' in other modules or incorrect code
  250.     will be generated.  This is true whether you use -ms/S or not.
  251.  
  252.     -mr     registered arguments, light
  253.     -mR     registered arguments, medium
  254.     -mRR    registered arguments, strict
  255.  
  256.     BEGINNERS NOTE:     either do not use these options or use only -mr
  257.     BEGINNERS NOTE:     see REGARGS.DOC
  258.  
  259.     These options control the automatic registerization of procedure
  260.     arguments.  Only those prototyped procedures declaring 4 or fewer
  261.     arguments will be registered.  Values are passed in D0/D1/A0/A1
  262.     according to the type of variable and availabilty of registers/
  263.  
  264.     -mr generates entry points for both the registered argument and
  265.         normal version of the function.  This option is ideal for
  266.         generating multi-model libraries.
  267.  
  268.     -mR generates only a single, registered entry point
  269.  
  270.     -mRR is similar to -mR but extends registerization to indirect
  271.         function calls (that are fully prototyped).  This is the
  272.         most dangerous option.
  273.  
  274.     Note that -mr and -mR assign the normal, nonregistered entry point
  275.     of a function to any indirect function pointers whether they are
  276.     fully prototyped or not (e.g. void (*func)() or void (*func)(int) )
  277.  
  278.     -mRR assigns either the registered or normal entry point to
  279.     function pointers depending on whether they are prototyped or not
  280.     (and any calls made through these function pointers will use the
  281.     registered args method).
  282.  
  283.     WARNING:    -mR CANNOT BE USED IF YOU MAKE C.LIB CALLS THAT TAKE
  284.     CALL-BACK FUNCTIONS AS ARGUMENTS.  -mr and -mRR *CAN* be used,
  285.     however with -mRR you must be careful to supply the registered
  286.     entry point.
  287.  
  288.     WARNING:    AMIGA.LIB ROUTINES THAT TAKE CALL-BACK FUNCTIONS AS
  289.     ARGUMENTS MUST BE GIVEN NON-REGISTERED ENTRY POINTS.  Thus if
  290.     you use -mRR you *must* qualify the procedure or function pointer
  291.     type specification with __stkargs to entire it has a normal
  292.     entry point.
  293.  
  294.     -mw <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  295.         AMIGA EXECUTABLES
  296.  
  297.     BEGINNER'S NOTE:    Do not use this option
  298.  
  299.     This option is another data model, called the ABSOLUTE-WORD data
  300.     model.    Source files compiled with this option generate
  301.     absolute-word data references to access data objects instead of
  302.     A4-relative or absolute-long.  The base of the data segment must be
  303.     specified as decimal, 0octal, or 0xHEX.
  304.  
  305.     Since absolute-word is used exclusive of A4-relative, the compiler
  306.     will now use A4 for register variables.  You may NOT mix -mw
  307.     modules with small-data models (do NOT use C.LIB, see ROMABLE.DOC)
  308.  
  309.     The ROMABLE program is usually run on the executable generated by
  310.     DLink to generate a ROM.
  311.  
  312.     -ma <addr>    USED FOR MAKING ROMABLE EXECUTABLES, DO NOT USE TO CREATE
  313.         AMIGA EXECUTABLES
  314.  
  315.     BEGINNER'S NOTE:    Do not use this option
  316.  
  317.     This option specifies to the compiler and linker that the resulting
  318.     code is intended to be relocated to a permanent data address, that
  319.     specified by <addr> in decimal, 0octal, of 0xHEX.
  320.  
  321.     Unlike -mw, -ma assumes that the data segment can be placed
  322.     anywhere.  The ROMABLE program is usually run on the executable
  323.     generated by DLink to generate a ROM.
  324.  
  325.     You may still specify a data model, -md or -mD, to use with this
  326.     option.  Unlike -mw, -ma does NOT touch the A4 register and thus
  327.     may be mixed with the small-data model.  Again, see ROMABLE.DOC
  328.  
  329.     -rom    SET UP OPTIONS FOR GENERATING ROMABLE CODE
  330.  
  331.     BEGINNER'S NOTE:    Do not use this option
  332.  
  333.     Like -l0, -rom disables automatic inclusion of a startup file (you
  334.     must specify your own) and libraries.  However, x.o is still
  335.     included to sink any autoinit code.  Your startup code must handle
  336.     the appropriate model and call autoinit code before calling your
  337.     program main
  338.  
  339.     This option is used to support ROMed firmware, i.e. non-amiga
  340.     executables.  You should never link with C.LIB.  Instead, a new
  341.     library, ROM.LIB, is available.
  342.  
  343.     ROM.LIB contains no static or global references and thus works
  344.     with any data model, and only completely self-contained routines
  345.     are included.  The only data ROM.LIB uses is stack-based.  All
  346.     ROM.LIB routines are completely reentrant, including
  347.     [v]sprintf() !
  348.  
  349.     -proto    PROTOTYPE CHECKING AND OPTIMIZATIONS
  350.  
  351.     When this option is used, an ERROR message will be generated for
  352.     any call that is not prototyped.  This option is useful to ensure
  353.     that you have properly prototyped routines (when you use
  354.     prototypes), especially when floats and doubles are passed and
  355.     indirect function pointers are used (they must be prototyped as
  356.     well!).
  357.  
  358.     IN THE FUTURE THIS WILL ENABLE STACK-ARGUMENT OPTIMIZATION.
  359.     Currently, chars and shorts are extended to long's when pushed onto
  360.     the stack for a subroutine call.  In the future if the -proto
  361.     option is used these objects will be pushed as shorts and not
  362.     extended.
  363.  
  364.     -prof    enable profiling for source modules
  365.     -prof1    same as -prof
  366.     -prof2    enable profiling for source modules and c*p.lib
  367.     -prof3    enable profiling for source mods, c*p.lib, and amiga*p.lib
  368.  
  369.     Enable profiling.  You may compile some or all your source modules
  370.     with profiling enabled.  Any -prof* option will enable profiling
  371.     for compiled source modules.  -prof2 will cause DCC to link
  372.     with a profiled c*p.lib while -prof3 will cause DCC to link
  373.     with a profiled c*p.lib AND amiga*p.lib (the ultimate).
  374.  
  375.     To profile c*.lib and/or amiga*.lib functions the equivalent
  376.     c*p.lib and amiga*p.lib must exist.  These libraries are most
  377.     likely lharc'd in DCC2:dlib/ or DCC3:dlib/ but if not, registered
  378.     users may create any link library from the library source.
  379.  
  380.     -r        Make executable residentable with separate CODE & DATA hunks
  381.     -pr     Make executable residentable w/ no relocation hunks
  382.     -pi     Make executable NON-residentable w/ no relocation hunks
  383.  
  384.     BEGINNER'S NOTE:    Just use -r to get residentable executables and
  385.     do not worry about these other options.
  386.  
  387.     -pr/-pi generate 'position independant' code also useful for ROMed
  388.     applications.  NOTE that -pi and -pr force const items to be
  389.     referenced pc-relative as well, causing -ms and -mS to do the same
  390.     thing (when combined with -pr/-pi)
  391.  
  392.     CODE SIZE IS LIMITED TO 32KBYTES WHEN YOU USE -pr OR -pi
  393.  
  394.     Refer to the section below called 'RESIDENTABILITY' for a
  395.     discussion of these options
  396.  
  397.     NOTE ROPT1:    You may not make data references within const
  398.     declared objects when using the -r/-pr options.  This is because
  399.     the CODE hunk is shared between running instances of the program
  400.     and these address references would be different between the
  401.     instances.
  402.  
  403.     However, if you are using the -ms option, string constants will
  404.     be in the code section and thus no problem.
  405.  
  406.     -O outdir    Specify directory that is to contain output executable,
  407.         object, or assembly files (used when specifying multiple
  408.         source files)
  409.  
  410.     -O is useful to tell the compiler where to put the objects
  411.     when you use dcc to compile and link a whole bunch of files
  412.     at once.  In this case, the -o option can still be used to
  413.     specify where to put the final executable.
  414.  
  415.     NOTE:    The -O name is used as a prefix so if you are
  416.     specifying a directory be sure it has a ':' or '/' on
  417.     the end.
  418.  
  419.     -T tmpdir    Specify the temporary directory used to hold preprocessed
  420.         source files and temporary assembly files... files that
  421.         will be deleted after use.
  422.  
  423.     NOTE:    The -T name is used as a prefix so if you are
  424.     specifying a directory be sure it has a ':' or '/' on
  425.     the end.
  426.  
  427.     The default is T: .. this option is useful in low-memory situations
  428.     where you may decide to put intermediate files elsewhere.  Putting
  429.     intermediate files on your HD or floppy slows down compilation by
  430.     an order of magnitude, but if you are running on a system with
  431.     little memory you may not have a choice.
  432.  
  433.     -s        Include symbolic debugging information in the executable.
  434.         (dlink opion)
  435.  
  436.     This option includes the symbol table in the resulting executable
  437.     and is passed to dlink.  When using DOBJ to disassemble an
  438.     executable, DOBJ will use the symbol table to generate a more
  439.     symbolic dump.
  440.  
  441.     -S        ALTERNATE SECTION NAMING OP FOR LIBRARIES
  442.  
  443.     When making libraries: uses alternate section naming conventions so
  444.     that all initialized data in the module will be placed before any
  445.     initialized data in non -S modules (i.e. normal linked object
  446.     files).  Any library BSS will be placed before non-library BSS.
  447.     Thus, the final ordering in the final executable will be:
  448.  
  449.         [LIBDATA] [PROGRAMDATA] [LIBBSS] [PROGRAMBSS]
  450.  
  451.     Thus, if your program contains >64K Bytes of BSS you can still
  452.     link with a library that tries to reference its own BSS using
  453.     the small-data model.  If your library declares only initialized
  454.     data (i.e. int x = 0; ), then you can link with the library even
  455.     if your program declares >64KBytes of *initialized* data !
  456.  
  457.     -v        Display commands as DCC executes them.
  458.  
  459.     -new    Checks timestamps for source/destination and only
  460.         compiles/assembles if object is outdated or does not
  461.         exist.    Used to make DCC a standalone make.
  462.  
  463.     -f        FAST / ^C HANDLING FOR 1.3
  464.  
  465.         This option is used for 1.3 only.  You MUST be using the
  466.         commodore shell (NewShell) and if you make programs
  467.         resident you MUST use the commodore C:Resident command.
  468.  
  469.         This option will probably not work if you use WShell or
  470.         ARPShell under 1.3.  This option allows DICE to take
  471.         short cuts to run sub-programs and allows ^C to be
  472.         propogated to said programs.  This option is useful
  473.         to set permanently in your DCCOPTS ENV: variable if
  474.         you run under 1.3
  475.  
  476.         DICE under 2.0 has no such problems and will run sub
  477.         programs optimally, including propogation of ^C.
  478.  
  479.     -frag    FRAGment (linker option).
  480.  
  481.     Tell linker not to combine all code hunks together or combine all
  482.     data hunks together. Cannot be used if the -r or -mw options are
  483.     used. Generally only useful if the large-data model is used.  Not
  484.     entirely supported yet.
  485.  
  486.     -ffp    Set fp library for floats
  487.     BEGINNER'S NOTE:    When using single precision floating point
  488.     this option, use of the original ffp libraries, will make the
  489.     program portable across all amigas.  Otherwise only amigas that
  490.     have the commodore MathIeeeSing*.library libraries will be
  491.     able to run the program.
  492.  
  493.     If not specified, 'mathieeesingtrans.library' and
  494.     'mathieeesingbas.library' are used.  These are new 2.0 libraries
  495.     that may not exist on all machines yet.
  496.  
  497.     If specified, 'mathtrans.library' is used .. motorola's FFP float
  498.     library.
  499.  
  500.     NOTE:  IF -ffp is used, be warned that conversion from floats to
  501.     doubles and back again is not entirely reliable.
  502.  
  503.     -d#     Set debugging level (# = a number), used for compiler
  504.         diagnostics only.
  505.  
  506.     -d<opts>    Specify any combination of debugging options.  These options
  507.         may be combined in one -d option.
  508.  
  509.         Currently no options are defined.
  510.  
  511.     -gs     Generate Dynamic Stack Code.  This generates code on every
  512.         subroutine call to check available stack.  If available
  513.         stack falls below 2K a new stack frame is allocated which
  514.         will be deallocated when the subroutine returns.
  515.  
  516.         If the allocation fails, stack_abort() is called.  If this
  517.         routine is not defined by you, the library stack_abort()
  518.         will call abort().  REFER TO DOC/EXTENSIONS.DOC FOR
  519.         MORE INFO.cd src
  520.  
  521.  
  522.         This option is extremely useful when compiling UNIX code
  523.         that expects infinite stack.
  524.  
  525.     -chip    CHIP force (linker option).
  526.  
  527.     Tell linker to force all hunks into CHIP memory.  You should
  528.     generally not use this option.    Instead, use the __chip
  529.     keyword (see EXTENSIONS.DOC) for those specific data items
  530.     that need to be in CHIP memory.
  531.  
  532.     NOTE:    CHIP data items are accessed using the large-data
  533.     model, thus you cannot create residentable executables that
  534.     contain __chip declarations UNLESS THEY ARE ALSO 'const'
  535.     objects -- read-only.
  536.  
  537.     -aztec    The front end attempts to run Aztec executables
  538.     -lattice    The front end attempts to run Lattice executables
  539.     -sas    same as -lattice
  540.  
  541.     These options allow one to write a single DMakefile able to handle
  542.     compilation under any compiler, assuming the source is compilable
  543.     under any compiler.
  544.  
  545.     These are very limited options and may not work across new
  546.     versions of Aztec or Sas/C
  547.  
  548.     -//
  549.     This option enables C++ style // comments.  This form of commenting
  550.     begins with a // causing it and the remainder of the line to be
  551.     considered a comment.
  552.  
  553.     -no-env
  554.     This option disables DCCOPTS.  DCC will not process options in
  555.     the DCCOPTS enviroment variable.
  556.  
  557.  
  558.     The ENV:DCCOPTS enviroment variable may contain additional options.
  559.  
  560.     ENV: must exist for DCC to run, even if you do not have a DCCOPTS
  561.     enviroment variable.  If you do not use ENV: then assign it to RAM:
  562.  
  563.  
  564.     Example #1.  Compile hello.c to executable.  The objects will be
  565.         left in T:
  566.  
  567.     1> dcc hello.c -o ram:hello
  568.     1> ram:hello
  569.  
  570.     Example #2.  Compile hello.c to executable and put the object file
  571.         in X:
  572.  
  573.     1> dcc hello.c -o ram:hello -TX:
  574.  
  575.     Example #3.  Compile hello.c into object into RAM: then link with symbols
  576.  
  577.     1> dcc -c hello.c -o ram:hello.o
  578.     1> dcc ram:hello.o -o ram:hello -s
  579.  
  580.     Example #4.  Compile foo.c and link with an already compiled object file
  581.          gar.o to produce an executable.  foo.o is placed in
  582.          T:
  583.  
  584.     1> dcc foo.c gar.o -o ram:foogar
  585.  
  586.                   PREPROCESSOR
  587.  
  588.     Predefined Symbols:
  589.  
  590.     __LINE__        current line number (integer constant)
  591.     __DATE__        current date (string)
  592.     __TIME__        current time (string)
  593.     __FILE__        current file (string)
  594.  
  595.     __BASE_FILE__        base source file (string), allows specification
  596.                 of the actual name of the source file from
  597.                 within an include file.
  598.  
  599.                 (-U undefines the below symbols)
  600.     __STDC__
  601.     mc68000
  602.     _DCC
  603.     AMIGA
  604.     _FFP_FLOAT        set if single prec. floats are in FFP format
  605.     _SP_FLOAT        set if single prec. floats are in IEEE-SING format
  606.                 (default)
  607.  
  608.     NOTE:  There are no limits to symbol and macro lengths.
  609.  
  610.                    MODELS AND LIBRARIES
  611.  
  612.     DICE supports various memory models and this is closely coupled with
  613.     the link libraries it picks.  There are two major memory models that
  614.     effect the link library selection:
  615.  
  616.     -mRR        registerized procedure calls
  617.     -md/-mD     small data / large data
  618.     -prof1        profiled user code
  619.     -prof2        profiled c.lib
  620.     -prof3        profiled c.lib and amiga.lib
  621.  
  622.    Library naming convention works as follows:
  623.  
  624.     <libraryname>[srpl].lib
  625.  
  626.     l - large data model    \ one of these two will always be specified
  627.     s - small data model    /
  628.     r - registered arguments, else stack arguments
  629.     p - profiled link library, else not profiled
  630.  
  631.     Keeping that in mind, these are the libraries that come with the
  632.     registered version of DICE:
  633.  
  634.     cs.lib        small data
  635.     csr.lib     small data + registered args
  636.     csp.lib     small data + profiled
  637.     csrp.lib    small data + registered args + profiled
  638.  
  639.     ms.lib        small data
  640.     msr.lib     small data + registered args
  641.     msp.lib     small data + profiled
  642.     msrp.lib    small data + registered args + profiled
  643.  
  644.     amigal13.lib    large data amiga.lib for 1.3 (commodore 1.3 amiga.lib)
  645.     amigas13.lib    small data amiga.lib for 1.3
  646.     amigasp13.lib    small data profiled amiga.lib for 1.3
  647.  
  648.     amigal20.lib    large data amiga.lib for 2.0 (commodore 2.0 amiga.lib)
  649.     amigas20.lib    small data amiga.lib for 2.0
  650.     amigasp20.lib    small data profiled amiga.lib for 2.0
  651.     amigasr20.lib    small data registered-args amiga.lib for 2.0
  652.     amigasrp20.lib    small data registered-args + profiled amiga.lib for 2.0
  653.  
  654.     Registered users can generate any combination of models they wish by
  655.     compiling the library source code.
  656.  
  657.     DICE defaults to the small data model ('s' libraries).  Generally you
  658.     will never use the large-data model so these are not included in the
  659.     distribution (i.e. they have to be made).  Since there are a huge
  660.     number of model combinations possible the distribution itself contains
  661.     only those that are likely to be used --- to whit, small data model
  662.     libraries.    DICE has enough features in it that you should never have
  663.     to use the large-data model.
  664.  
  665.     The large-data model suffix 'l' is new.  This was added to ensure that
  666.     all combinations of models generate at least a one character suffix.
  667.     This allows DICE to give the linker hints about where to find user
  668.     libraries --- if the linker cannot find a library name unadorned it
  669.     will append the suffix and try again.  Previously, the large-data model
  670.     had no suffic so this method would not work (the large data model
  671.     library would be found even though the small-data model library is what
  672.     we wanted).
  673.  
  674.               CREATING YOUR OWN LIBRARIES
  675.  
  676.     It is extremely easy to write your own link library.  There are two
  677.     ways to do it.  First, simply compile various source modules into
  678.     objects and JOIN them together into a .lib.  Second, use the LIBMAKE
  679.     utility (see LIBMAKE.DOC).  You should name the library according to
  680.     the data model, registered args, and profiling capability you
  681.     compiled the source code for.
  682.  
  683.     For example, if you have compiled your library modules small-data
  684.     without registered arguments and no profiling and want to call your
  685.     library 'foo', you should append an 's' suffix to the library name
  686.     so the actual library file would be called 'foos.lib'.
  687.  
  688.     If you compiled the library modules small-data with registered args it
  689.     would be called 'foosr.lib'.  If you compiled it small-data with normal
  690.     args and profiling it would be called 'foosp.lib', etc... the ordering
  691.     of suffix characters is always reverse alphabetical.
  692.  
  693.     When you finally specify your library linking some program with DCC you
  694.     have two choices:    (1) you can specify the full library name such as
  695.     '-lfoosr', or (2) you can specify only the base name and let DICE pick
  696.     the suffixes for you: '-lfoo'.  The latter is the most portable, DICE
  697.     will choose the suffixes according to the various options you give DCC
  698.     when linking.
  699.  
  700.     WARNING: option (2), just specifying the base name, assumes that you do
  701.     not have a library called 'foo.lib' .. i.e. all your foo libraries have
  702.     at least one suffix character.
  703.  
  704.  
  705.  
  706.  
  707.  
  708.                PUTTING CONST DATA INTO THE CODE SEGMENT
  709.  
  710.     Two options are available to handle the 'const' keyword: -ms and -mS.  If
  711.     neither are used 'const' is ignored.  The difference between the two
  712.     determines how external references (between modules) are handled.
  713.  
  714.     With -ms, all string constants "fubar" are placed into the code segment
  715.     and referenced according to the code model (pc-rel or absolute).  Any
  716.     variable declared const will also be put in the code segment and
  717.     referenced similary.  However, any EXTERN'd variables referenced but
  718.     not defined in this module (i.e. defined in another module) will be
  719.     accessed using ABSOLUTE references, since you cannot make a jump table
  720.     for data variables.
  721.  
  722.     The -mS option is much more dangerous.. it works the same as -ms except
  723.     that external references use pc-relative addressing as well. your final
  724.     executable must be LESS THAN 32KBytes TO ENSURE ALL CODE IS REACHABLE
  725.     VIA PC-RELATIVE ADDRESSING.  If you have a choice, please use -ms
  726.     instead of -mS .
  727.  
  728.     'const __chip' variables will also be placed in the code section, but
  729.     these always use absolute references since the code section is not
  730.     combined together with other code sections.  You may also override
  731.     default access method (pc-rel/absolute) by using the __near and __far
  732.     keywords, but this is not advised.
  733.  
  734.     The -ms option affects the main compiler DC1 and can be specified
  735.     independantly for each source module (i.e. some can have it while
  736.     others do not, though normally all will have it one way or the other)
  737.  
  738.     WHEN YOU USE -pr OR -pi, use of the -ms option is silently forced to
  739.     -mS
  740.  
  741.                 RESIDENTABILITY
  742.  
  743.     Two options are available to generate residentable executables and one
  744.     option is available to genreate a non-residentable executable with no
  745.     relocation information (loads quickly).
  746.  
  747.         RES?   RELOC?   DataLim CodeLim Alloc?  Hunks
  748.  
  749.     -md     no       yes        64K(1)  none    no      DATA, CODE
  750.     -mD     no       yes        none    none    no        DATA, CODE, optionally more
  751.     -r        yes    yes        64K     none    yes     DATA, CODE
  752.     -pr     yes    no        64K     32K     yes     CODE (combined DATA+CODE)
  753.     -pi     no       no        64K     32K     no        CODE (combined DATA+CODE)
  754.  
  755.     RES:    Can this program be made resident (dlink sets Pure bit)
  756.  
  757.     RELOC:    Will this executable contain 32-bit relocations?
  758.  
  759.     DATALIM:    The maximum amount of DATA+BSS that may be declared
  760.  
  761.         (1) it is possible to declare more then 64KB worth of
  762.         data when using the small-data model by selectively
  763.         making large declarations __far.
  764.  
  765.     CODELIM:    The maximum size of the CODE
  766.  
  767.     ALLOC:    Does the startup code allocate a run time DATA+BSS segment?
  768.         (basically, resident programs must, non-resident programs
  769.         do not)
  770.  
  771.     HUNKS:    Number and type of hunks that may exist in the executable
  772.  
  773.  
  774.     -md     default
  775.  
  776.     -mD     used when final executable contains more than 64KBytes of data
  777.  
  778.     -r        most often used option
  779.  
  780.     -pr     used instead of -r if there is only a little initialized data
  781.  
  782.         Can be used with most programs but requires one large chunk of
  783.         memory instead of the two smaller chunks that -r allocates
  784.  
  785.         Also used in ROMable applications
  786.  
  787.     -pi     used instead of default when there is only a little INITIALIZED+BSS
  788.  
  789.         Can be used with many small programs that you do not intend to
  790.         make residentable, to make them load extremely fast (since there
  791.         is no relocation information).
  792.  
  793.         Also used in ROMable applications
  794.  
  795.     The __geta4 type qualifier will NOT work with residentable programs.
  796.  
  797.     You cannot use __far when accessing non-const (see -ms option) data
  798.     in residentable programs
  799.  
  800.     USING THE -ms OPTION can drastically reduce the amount of data that
  801.     needs to be allocated/copied when a resident program starts up by
  802.     moving string constants into the code section (only the data section is
  803.     duplicated), reducing overhead in both time and space for each
  804.     invocation of the RESIDENT'd program.
  805.  
  806.     To use one of the options -r, -pi, or -pr specify on the DCC line when
  807.     both compiling and linking your code.  The resulting executable will have
  808.     the pure bit set (for -r and -pr options) and be residentable.
  809.  
  810.     -r and -pr generate no BSS since the startup code is going to allocate
  811.     the DATA+BSS space.  -pi generates BSS space in the code segment just
  812.     after the initialized data.
  813.  
  814.     default    uses c.o
  815.     -r        uses c.o
  816.     -pi     uses c_pi.o
  817.     -pr     uses c_pr.o
  818.  
  819.