RISCWORLD 7

home *** CD-ROM | disk | FTP | other *** search

/ RISCWORLD 7 / RISCWORLD_VOL7.iso / Software / Issue2 / SDL.ARC / !gcc / docs / Intro < prev next >

Wrap

Text File | 2004-10-05 | 17.8 KB | 483 lines

Introduction to GCC 3.4 for RISC OS =================================== This is a short introduction to GCC, the GNU Compiler Collection or RISC OS. This document does not provide an introduction to programming, for that you will have to get a text book on the language you are interested in. IMPORTANT NOTE 1: The GCC compiler binaries are at least 3000K, so you must ensure that a large enough Wimpslot has been allocated. Please refer to the `Troubleshooting' section later in this document, if you are getting `Address exception' and `No writeable memory at this address' errors. IMPORTANT NOTE 2: If ypu have received this copy of GCC from a CD, then it is likely there is a more up-to-date version obtainable from elsewhere. IMPORTANT NOTE 3: GCC requires a minimum of 16MB RAM. The RISC OS GNU Compiler Collection consists of a generic front end program `gcc' that provides a consistent interface to the compilers themselves. Currently compilers are supported for the languages C, C++ and Fortran. GCC is covered by the FSF General Public License (see the files docs.COPYING and docs.COPYINGLIB for details). This port of GCC is Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001 Nick Burrett Copyright (c) 2002, 2003, 2004 GCCSDK Development Team As with all GNU programs, THERE IS NO WARRANTY OF ANY SORT The standard RISC OS distribution contains GCC and supporting binaries allowing you to start developing applications straight away. So you get a C compiler, a C++ compiler, an AOF linker, an AOF assembler, the UnixLib C runtime library and headers and stubs for the SharedCLibrary (as found in the RISC OS ROMS). Installation ------------ To install GCC, copy the contents of this archive onto your hard disc. Other compilers can be installed by copying the contents of their archives into the same directory as where you install GCC - RISC OS will automatically combine the !gcc directories together. Running !gcc will setup Run$Path to automatically search for the compiler tools. As compilers are installed, sub-directories named according to the language they support will be placed within !gcc.docs. These sub-directories will contain specific information for the language compiler, including its usage and environment requirements. GCC uses a linker front end, LD. This will search for both drlink and link on the current Run$Path and in that order. This completes installation, and GCC may be used simply by typing 'gcc' at the CLI prompt. Simple compilations ------------------- This assumes you have actually installed a compiler and are using UnixLib as the run-time library. Please note that the instructions below are generic and the ideas presented can be applied to all GNU compilers. The usage of C source files is merely for example purposes. Source files are stored in the standard ASCII text format and kept in a directory that is relevant for the language of your program. For example, C programs are stored in directory 'c' and C++ programs are stored in 'cc'. For simple use, all that is needed is to set up a command line prompt and ensure there is enough free memory to run the compiler (details of memory requirements vary between compilers and can be found in the specific compiler documentation). To compile a C program just type: *gcc hellow.c This will compile, assemble and link the source 'c.hellow' to produce an executable called '!RunImage', which can be run immediately. Adding the switch '-o' to the command line, it's possible to specify a place to store the resultant file: *gcc hellow.c -o hellow This will comple, assemble and link the source 'hellow.c' to produce an executable called 'hellow', which can be run immediately. It is possible to compile several sources at one go, mixing C sources in the same program, using a command line of: *gcc file1.c file2.c file3.c file4.c Again, this will compile, assemble and link all the sources to produce the '!RunImage' executable. To compile to the object form, use the -c switch. i.e. gcc -c file.c will compile and assemble 'file.c' to 'file.o'. To compile the same files but using the SharedCLibrary as the target run-time library instead of UnixLib, add the switch '-mlibscl' to the command line. For example: gcc hellow.c -mlibscl will compile and link the hellow.c source file, using header files from the SharedCLibrary, and linking against the library C:o.stubs. The output file will still be called '!RunImage' and can be run in the same way. Support has been provided for both RISC OS and UNIX format filenames. GCC will translate any UNIX filenames into their RISC OS equivalent. For example: ../include/stdio.h is translated to ^.include.h.stdio /work/gcc/hello.c is translated to $.work.gcc.c.hello stdlib.h is translated to h.stdlib but tree.def is translated to tree/def For further examples of compilation procedures, please look at `Examples' in !gcc.files. The full GCC manual can be referred to at !gcc.docs.gcc. Switches -------- This is a list of the simpler, standard switches for GCC. Full details can be obtained from the !gcc.docs.gcc manual. Please see below for the ARM specific switches since these have altered from the original gcc version. The switches described below are useable with any GNU compiler. -c compile and assemble the source to the object file -S compile the source to assembler code -E preprocess the source file -o <file> put the resulting output into <file> -O apply some optimisations to the output -O2 apply full optimisation. -O3 full optimisation and inline small functions as well. There are some additional ARM specific switches. -mapcs, -mapcs-frame target for ARM Procedure Call Standard stack frames. -mpoke-function-name place the name of the current function before the start of the function to allow the post mortem debugger to print a readable backtrace. This option is disabled by default. Turing this option on can increase code size by about 3.5% for C programs and as much as 10% for C++. However, it should be noted that the performance of the generated application will not be slower. It is useful to turn this option on when developing applications as it can lead to a clear indication of where a program is failing. -mapcs-stack-check provide explicit stack checking on entry to each function which allocates temporary variables on the stack. This option is enabled by default. Disabling this option will reduce the function prologue overhead by 3-5 instructions. -mfpe=2 Target the Floating Point architecture version 2. Notably the function prologues and epilogues use the STFE instruction to preserve floating-point registers rathern than the much faster and more accurate SFM instruction of the version 3 (default) architecture. RISC OS specific options -mthrowback send errors to a text editor capable of receiving 'throwbacks'. Error throwbacks will only occur when the DDEUtils module has previously been loaded. -mlibscl build and link source code against the SharedCLibrary headers and library files. -munixlib build and link source code against the UnixLib headers and library files. -mlibscl and -munixlib are mutually exclusive. -munixlib is the default. -mamu Generate the file !Depend which contains a list of all the source files that the produced object depends on. This is intended for use with Acorn's Make Utility (AMU), which edits the makefile to include these after the '# Dynamic Dependencies' line. LD -- LD is a front end program that converts the linker command line as generated by gcc to a format recognised by Drlink and Link. LD also attempts to convert Unix format names to RISC OS format. The option recognised are: -L<dir> This specifies a directory/path that LD is to use when searching for libraries. <dir> must be either a path (i.e gcc:, etc), or it must be a valid Unix/RISC OS directory name, ending in either '/' or '.'. Directories are searched in the order that they are specified. -l<file> This specifies the name of a library file which LD will search the library directories for. This may either be a complete filename (i.e C:o.stubs) or just the leaf name, in which case, LD will search though the specified library directories for the file o.lib<file> and o.<file> if the former isn't found. -o <file> This specifies the filename to which the resultant executable will be stored. -via <file> <file> contains a list of object files to be included in the link process. -version Print the version number of 'ld'. -help Display a brief summary of LD and its command line arguments. The following Drlink linker commands are recognised: -acornmap, -area[map] <file>, -aif, -aof, -bin, -case, -leave[weak], -map, -no[unused], -output, -res[can], -throwback, -via <file>, -verbose The following Acorn Link linker commands are recognised: -aif, -aof, -bin, -map, -via <file>, -nounused[areas], -verbose Unrecognised commands are flagged as an error and LD will not perform the link process. Characters with square brackets are optional. The sequence '-Lgcc: -LC: -lgcc -lstubs' will cause LD to look for the files gcc:o.libgcc, gcc:o.gcc, c:o.libgcc, c:o.gcc, gcc:o.libstubs, gcc:o.stubs, c:o.libstubs and c:o.stubs, taking the first gcc and stubs files that it finds. Linker options can be passed from GCC to link using -Wl and -XLinker options. The linker must be in the default Run$Path, as LD does not handle the -B command. Please note that it is best to define GCC$Linker in the !gcc.!run file to point to the linker you want to use. e.g. Set GCC$Linker "link" will make LD use the program 'link' for linking. Predefines ---------- The following preprocessor constants are defined by GCC: '__arm', '__arm__', '__riscos', '__riscos__', '__aof__' '__GNUC__', '__GNUC_MAJOR__', '__JMP_BUF_SIZE' To implement dynamic allocations within a function, it is necessary to add an extra field to jmpbuf. Fortunately the setjmp.h header files recognise __JMP_BUF_SIZE and can alter their jmpbuf array appropriately. When targetting the SharedCLibrary (i.e. -mlibscl switch is supplied on gcc command line) then an additional preprocessor constant is defined, namely `__TARGET_SCL__'. GCC and Virtual Memory ---------------------- GNU compilers use a lot of memory and nothing can be done about that. For the Risc PC, UnixLib has been modified to make use of dynamic areas. So users with small memory machines can use Clares' Virtualise to provide a working virtual memory envionment for them. See the section *Dynamic Areas* below. Users of older machines, the Archimedes and A5000, with less than 8MB RAM will not be able to use this software. Dynamic areas ------------- The following information is deprecated, as recent versions of UnixLib can extend their own Wimpslot, but it is included for reference. UnixLib has a facility to use Dynamic Areas, found in RISC OS 3.5 and above, for the program's heap. The heap is another name for the malloc area. The advantages of using a dynamic area for the program's heap include : * the Wimpslot of the program can be limited to the code and stack requirements of the program. This helps alleviate the cost of RISC OS task switching which slows down dramatically as the Wimpslot grows in size. * Dynamic Areas provide a means of Virtual Memory when used with a product such as Virtualise[1]. Virtual Memory allows programs to use more data space than is available with just physical memory. Basically, use *Set GCC$Heap "" to enable dynamic areas for the compiler and *UnSet GCC$Heap to disable dynamic areas for the compiler. Before running a program set the wimpslot in the normal way, but it only needs to be large enough to hold the sum of the largest executables that can be run concurrently. e.g., with gcc, use the unsqueezed size of gcc plus cc1. When running from a command line amu remember to allow additional space for the amu executable and amu's workspace (though this is tricky to estimate!). If other programs that form part of a compiler are run directly from the command line, e.g., gnatmake, then separate environment variables must be set to allow these programs to use dynamic areas for the program's heap. So, with gnatmake, *Set gnatmake$heap "" As a user, you should not really need to worry about these details as the !gcc.!run file already contains the relevant lines. Please read the !run file if you are a Risc PC user, since some lines will need to be uncommented. [1] Virtualise is a commercial product available from Clares. Peter Burwood has no connection with Clares or the Virtualise product other than being a user of Virtualise. If other similar products become available then UnixLib should work transparently since the UnixLib startup code does not use any Virtualise features. Troubleshooting --------------- Here are described some common problems users have with gcc and the GNU compilers. Possible solutions are provided for the known problems. 1. The compiler fails to compile anything but no error message is reported. This is usually caused by a lack of memory. To see how far through compilation a file has gone, try compiling with the '-v' flag. '-v' gives verbose output and will show the programs gcc is executing. A lack of memory will be shown up by an almost instantaneous return from any program executed. If this happens, try increasing the wimpslot, using *wimpslot -min nnnK, where nnn is as follows: 4000K or more for GNU C, Objective-C, C++, Fortran and Pascal. 6000K or more for GNAT Ada. When the compiler runs out of memory during compilation, an error 'virtual memory exhausted' is usually reported. 2. Abort on data transfer errors are displayed during compilation Insufficient memory has been allocated to the program. Increase the wimpslot. 3. The error 'No writable memory at this address' is returned. This is caused by insufficient memory memory and can be fixed by increasing the wimpslot to similar values as above. 4. ld fatal error: drlink returned exit status 12 This is caused by insufficient memory during the linking stage. Increase the wimpslot to fix this. 5. A source file is correctly compiled and linked. The resultant executable 'hellow' is placed in the current directory. However, when I try and run the file I get the error 'No such file or directory'. This and many other obsure errors are caused by linking source files against run-time libraries that are incompatible with the StrongARM processor. An example would be UnixLib 3.7a. StrongARM compatibility wasn't introduced to UnixLib until version 3.7b. AOF files, Libraries, Linkers etc. ---------------------------------- The following is a brief introduction to the world of compiling source code, object files and linking. Taking the C compiler as an example. Language C source files are stored within a directory called 'c'. Typing *gcc -c hello.c -o hello.o will tell gcc to run the C compiler on the source file c.hello. The resultant output will be stored in the directory 'o' as hello. Files in 'o' are called Acorn Object Format (AOF) files. During multistage compilation (i.e. where a program is made up from several source files), the compiler will compile one file at a time and this will produce several AOF files. Each source file might contain references to variables and functions that are not defined within its own scope. For an executable to be created, these references must be resolved and that is the purpose of the Linker. The Linker takes AOF files and attempts to resolve references between them. Not all references are defined within AOF files, some (like printf) are defined within libraries - called Acorn Library Format (ALF) files. So the Linker will also look at ALF files to match unresolved symbols. For example, below is a list of C source files that will be compiled to make the program called Harry. Along with each source file is a list of the symbols that are defined within that source, and a list of symbols that are not defined (i.e. referenced) by that source. C source: fred.c Symbols defined: foo, bar, pint Symbols referenced: printf, puts, food C source: bob.c Symbols defined: fags, beer, food Symbols referenced: bar, pint C source: harry.c Symbols defined: main Symbols referenced: foo Using gcc to compile fred.c, bob.c, harry.c will produce three AOF files, fred.o, bob.o and harry.o. harry.c contains a reference to 'foo' which is defined within c.fred. So the Linker must combine harry.o and fred.c to resolve a reference. fred.c contains a reference to 'printf', 'puts' and 'food'. 'food' is defined by bob.c so bob.o will also be combined with harry.o and fred.o to resolve further references. 'printf' and 'puts' are defined by the C library, therefore the linker will need to combine the ALF file with harry.o, fred.o and bob.o to finally generate an executable. Obtaining compilers ------------------- As said earlier, GCC is a compiler front end. The compilers themselves can be found at http://gccsdk.riscos.info/ Distribution patches -------------------- From time to time bugs might be fixed in the GCC distribution. To save download time involved in uploading/fetching new binaries, patch archives will become available from the address: http://gccsdk.riscos.info/ Announcements will be posted to comp.sys.acorn.announce whenever new patch archives are uploaded. Contacting the author ---------------------- A mailing list has been setup for discussions on GCC, including development work. To join it, send mail to majordomo@gccsdk.riscos.info and put `subscribe gcc' as the only item of text in the message body. Location of the main GCC sources -------------------------------- The official GCC website is http://gcc.gnu.org The official GNU website is http://www.gnu.org