home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / c / gnu_c / docs / _readme next >
Encoding:
Text File  |  1996-03-09  |  10.8 KB  |  305 lines
  1.                      The GNU C compiler
  2.  
  3.  
  4. 0.      Introduction
  5.  
  6. This file (sort of) documents the Nick Burrett port of
  7. GNU C version 2.7.2 (RISC OS backend 1.0.5) for RISC OS versions 2 or 3.
  8. For copyright details and sources see !Intro, COPYING and COPYINGLIB.
  9.  
  10. GCC (as the compiler is generally known) requires approximately 3 Mb
  11. of free RAM and a hard disc. !Virtual is compatible with GCC and so large
  12. C sources can be compiled on small machines.
  13.  
  14. This is a binary distribution only and consists of the following packages :
  15.  
  16. !GCC - Non-specific files, documentation, etc.
  17.   !Intro          General help and copy-right
  18.   !ReadMe         This file.
  19.   !Boot
  20.   !Run
  21.   !Sprites
  22.   docs.gcc-faq      The RISC OS GCC FAQ document
  23.   docs.gccuser    The GNU C/C++ users manual - MakeInfo version
  24.   
  25.  
  26. GCC - GNU C compiler
  27.   bin.gcc         Front end to the C compiler.
  28.   bin.cpp         C preprocessor.
  29.   bin.cc1         C compiler.
  30.   gcc.o.libgcc    GCC runtime library routines.
  31.   gcc.h           GCC runtime library headers
  32.  
  33. Compiler support files
  34.   as             Assembler.
  35.   ld             Front end to link
  36.  
  37. The compiler sources (about 27Mb) can be obtained from the sites listed at
  38. the end of !Intro.
  39.  
  40. 1.      Installation
  41.  
  42. To install GCC onto a hard disc, just merge all the archives together.
  43. Running !gcc will setup Run$Path to automatically search for the compiler
  44. tools.
  45.  
  46. If you wish to separate the distribution, the files in !gcc.bin should be
  47. copied so that they are in your run path, while GCC$Path and GPP$Path should
  48. point to where the GCC and GPP directories are respectively.
  49.  
  50. Note, there is no linker or run-time library supplied, but DRLink and
  51. Unixlib 3.6e, available at various servers (HENSA, etc) are useable with
  52. GCC. This completes installation, and GCC may be used simply by typing
  53. 'gcc' at the CLI prompt.
  54.  
  55. 2.      Using GCC
  56.  
  57. GCC uses the same assumptions as Norcroft C, with C sources held in the
  58. '.c' subdirectory and header files held in the '.h' subdirectory. By
  59. default, GCC will compile assemble and link the named sources.
  60.  
  61. For most of the details for using GCC see the file Docs.gccuser.
  62.  
  63. 2.1     RISC-OS specific features.
  64.  
  65. *       AMU
  66.  
  67. This version of GCC supports the dynamic dependencies feature in the version
  68. of AMU supplied with desktop C. To automatically update the dependencies
  69. during compilation, include the '-mamu' switch in the command line. This
  70. will generate the !Depend file that AMU uses.
  71.  
  72. *       Norcroft Stubs / ANSILib
  73.  
  74. By default, GCC uses the the UnixLib header and library files supplied,
  75. though the Norcroft files can be used. To do this you need the following
  76. command lines options :
  77.  
  78.         -nostdinc       Do not use the UnixLib headers.
  79.         -nostdlib       Do not link again Unixlib / gcc
  80.         -IGCC:          Get GCC specific include files.
  81.         -IC:            Get header files from the C: path
  82.         -lC:o.stubs     Link against Stubs - you can also use -lC:o.AnsiLib
  83.                         to link with AnsiLib.
  84.         -lGCC:o.gcc     Link against gcc
  85.  
  86. If you wish to link against the Shared C Library, the switch -mstubs will
  87. perform the above sequence.
  88.  
  89.  
  90. *       LD
  91.  
  92. LD is a front end to Link, which converts the LD as generated by gcc to the
  93. Acorn Link format. LD only recognises a few options, the rest are passed
  94. directly through to Link. LD also attempts to convert Unix format names to
  95. RISC OS format. The options that LD recognises are :
  96.  
  97. -L <dir>
  98.         This specifies a directory / path that LD is to use when searching
  99.         for libraries. <dir> must be either a path (i.e gcc:, etc), or it
  100.         must be a valid Unix / RISC OS directory name, ending in either '/'
  101.         or '.'. Directories are searched in the order that they are
  102.         specified.
  103.  
  104. -l <file>
  105.         This specifies the name of a library file which LD will search the
  106.         library directories for. This may either be a complete filename (i.e
  107.         C:o.stubs) or just the leaf name, in which case, LD will search
  108.         though the specified library directories for the file o.<file>.
  109.  
  110. The sequence '-Lgcc: -LC: -lgcc -lstubs' will cause LD to look for the files
  111. gcc:o.gcc, c:o.gcc, gcc:o.stubs and c:o.stubs, taking the first gcc and
  112. stubs files that it finds.
  113.  
  114. LD does not recognise any other unix commands, therefore the other LD
  115. options documented in invoke_tex should not be used. Acorn link options can
  116. be passed from GCC to link using -Wl and -XLinker options.
  117.  
  118. LD requires that the linker be named 'link', even if you are using DRLink.
  119. The linker must be in the default run-path, as LD does not handle the -B
  120. command.
  121.  
  122. *       Interworking with Norcroft cc
  123.  
  124. Code compiled with GCC can be linked with code produced by the Norcroft CC
  125. compiler, and probably other APCS-R conformant compilers, with no problems.
  126.  
  127. Experience has showed that there are minor incompatibilities between
  128. Norcroft C and GCC in the way structures are implemented. However, these
  129. incompatibilities are very minor and should not affect the general user.
  130.  
  131. *       Predefines
  132.  
  133. The following preprocessor constants are defined for GCC:
  134.         'arm', '__arm', '__arm__', 'riscos', '__riscos,' '__riscos__' and
  135.         '__GNUC__'.
  136.  
  137. *       RISC OS specific switches
  138.  
  139. The following RISC OS specific switches are recognised
  140.  
  141.   * -mapcs, -mapcs-frame
  142.    target for ARM Procedure Call Standard stack frames.
  143.   * -mpoke-function-name
  144.    place the name of the current function before the start of the function
  145.    to allow the post mortem debugger to print a readable backtrace.
  146.    Using it's opposite will reduce code size by about 3.5%.
  147.   * -mfpe
  148.    prevents instruction scheduling of floating point instructions since it
  149.    increases compile time and the benefits acheived make no difference through
  150.    the FPE.
  151.   * -mapcs-32
  152.    target the APCS-32 bit standard. Condition flags are assumed to be corrupted
  153.    by function calls in this mode.
  154.   * -mapcs-stack-check
  155.    provide explicit stack checking on entry to each function which allocates
  156.    temporary variables on the stack.
  157.   * -mapcs-strict
  158.    make the compiler conform strictly to the APCS even in the cases where
  159.    stack frames do not need to be set up.
  160.   * -msoft-float
  161.    cause the compile to assume all floating point instructions are missing
  162.    (and there is no emulator either), therefore generating function calls
  163.    instead.
  164.   * -mhard-float
  165.    the opposite of -msoft-float
  166.   * -mshort-load-bytes, -mno-short-load-words
  167.    if the MMU traps unaligned word accesses, shorts must be loaded
  168.    byte-at-a-time so this flag should be set.
  169.  
  170.   RISC OS specific options
  171.  
  172.   * -munique-areas
  173.    generate each function in its own individual code area giving the linker
  174.    extra chance to remove unused functions from the resulting binary.
  175.   * -mthrowback
  176.    send errors to a text editor capable of receiving 'throwbacks'.
  177.   * -mstubs
  178.    compiles to target SharedCLibrary and tells the linker to link with
  179.    stubs instead of UnixLib.
  180.   * -munixlib
  181.    tell the linker to target UnixLib instead of the SharedCLibrary
  182.   * -mdepend
  183.    Generate the file !Depend which contains a list of all the source
  184.    files that the produced object depend on. This is intended for use
  185.    with amu, which edit the makefile to include these after the
  186.    '# Dynamic Dependencies' line.
  187.  
  188. *       Search paths
  189.  
  190. The default search paths for GCC are as follows and searched in the
  191. specified order.
  192.         GCC$Path        GCC specific include files.
  193.         Unix$Path       Unixlib header files.
  194.  
  195. *       <varargs.h>, <assert.h>, <stdarg.h>
  196.  
  197. GCC supplies it's own versions of these header files since they are not
  198. compatible with the headers supplied with Norcroft C and UnixLib.  However,
  199. this feature is invisible to the user.
  200.  
  201. *       Wimpslot
  202.  
  203. Due to the structure of the stack under UnixLib, GCC is not able to extend
  204. its wimpslot, and therefore you will have to set it to the required size
  205. from the start (around 2.7 - 3.4 Mb is usually enough).
  206.  
  207. 2.2     Feature not yet implemented
  208.  
  209. *       debugging data
  210.  
  211. There is, as yet, no debugging data generated by gcc. Therefore, DDT can
  212. only be used for object level debugging, not source level. Note, this is
  213. very difficult to implement so don't expect anything special in the near
  214. and most probably distant future.
  215.  
  216. *       Throwback
  217.  
  218. Throwback is supported, but only by the compilers. The C preprocessor does
  219. not support it because I didn't really see the point.
  220.  
  221.  
  222. 3       Implementation details
  223.  
  224. *       compilers
  225.  
  226. The supplied C compiler is a stage 3 compiler (as it should be).
  227.  
  228. *       Stack checking
  229.  
  230. This version of GCC fully supports APCS-R stack checking, therefore there is
  231. no need to set the size of the stack chunk when using Stubs / ANSILib.
  232.  
  233. *       Libraries
  234.  
  235. When separately linking C++ executables with global constructors, the gcc
  236. library requires some routines from the main run-time library. Therefore,
  237. the gcc library must be placed before the main run-time library in the
  238. command line or, if using DRLink, the -rescan command should be given..
  239.  
  240.  
  241. 4.      Known bugs / Problems
  242.  
  243. This is a list of all the known (by me) bugs and problems in
  244. GCC 2.7.2 (ARM/RISCOS v1.0.5)
  245.  
  246. Bug 1:
  247. Sometimes when memory is tight, the machine will completely freeze i.e. caps
  248. lock light doesn't work.
  249.  
  250. Preventative actions:
  251. Try and allocate some more memory or use Virtual Memory.
  252.  
  253. Nick B: I believe this bug to now be fixed but have not been able to prove
  254. it by time of release.
  255.  
  256. ================================================================================
  257.  
  258. Bug 2:
  259. Statements of the form #include "dir.file.h" do not work correctly - Unixlib
  260. does not convert this to dir.h.file
  261.  
  262. Reported by:    Simon Callan
  263.  
  264. Preventative actions:
  265. Use "dir/file.h" instead. This is more portable, anyway, and should not
  266. cause major problems.
  267.  
  268. ================================================================================
  269.  
  270. 5.      Acknowledgements, sources and other bits
  271.  
  272. *       Acknowledgements
  273.  
  274. As with all large programs, thanks go to various people for the help and
  275. assistance that they have given me. These are :
  276.  
  277.   Simon Callan
  278.      For the changes to gcc to enable it's use with an AOF assembler instead
  279.      of an 'a.out' format one.  Basically, a lot of other help for which this
  280.      port would never have been realised.
  281.  
  282.   Richard Earnshaw
  283.      For the small, but quite significant, help and advice provided with
  284.      the RISC OS port.
  285.  
  286.   Peter Burwood
  287.      Generally commenting on my code; spotting some difficult bugs; optimising
  288.      code I couldn't be botherd to optimise; suggesting improvements; testing
  289.      my changes; the work he helped provide on solving dynamic allocation
  290.      and lots of other stuff too numerous to mention. Responsible for moving
  291.      forward the GCC release date by a few months.
  292.  
  293.   Niklas Röjemo
  294.      For writing the backend assembler 'as' and allowing me to contain it
  295.      within this distribution.
  296.  
  297.   Jochen Scharrlach
  298.      Provided the GCC-FAQ, supplied with this distribution and available
  299.      elsewhere.
  300.  
  301. *       Sources
  302.  
  303. The location of the relevant sources are described at the end of the !Intro
  304. file.
  305.