APDL Public Domain 1

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

/ APDL Public Domain 1 / APDL_PD1A.iso / program / c / gnu_c / riscos / RiscOS / Readme_RB < prev

Wrap

Text File | 1993-08-04 | 23.5 KB | 706 lines

GCC for RISC OS --------------- -3. Contents -------- -3. Contents -2. For readers of German language only -1. Something general 0. Installation 1. Prefixes in filenames 2. (Options for) GCC 3. Include files 3.1 How to use standard C header files 3.2 Changes to standard header files 4. Linker 5. AOFConvert 6. Assembler 7. Libraries 7.1 Stubs / RISC_OSlib 7.2 Your own libraries 7.3 Converting libraries from ALF (Acorn Library Format) to MUPROS format 7.4 The wimpclass library 7.5 The libg-- library 8. Objective C 9. "Support" 10. Source code 11. Floating point arithmetic 12. Memory 13. Debugger 14. AOF 15. Stack 16. Constructors/Destructors -2. For readers of German language only ----------------------------------- Nun ja, ich habe mich also entschieden, die Textfiles nur noch in Englisch zu fuehren. Ich denke, so verstehen mich mehr Leute, als wenn ich in Deutsch schreiben wuerde. Ich hoffe, alle deutschsprachigen Leser verzeihen mir! -1. Something general ----------------- Though this distribution is called 'gcc-2.3.3' it is NOT the official gcc for RISC-OS release - it is my private one. I have to add that it is NOT AT ALL free of bugs. So when using this version of gcc you should always keep in mind that there may be (a) bugs that could make it useless for your specific purpose. I think that there are not too many bugs as with the help of some of you I was able to discover and eliminate some. There are some people (around Michael Ben Gershon and Simon Callan) working on an official GCC for RISC-OS release. This will be a more reliable one that this one is. Both version will converge (is this an Englisch word?) in future so that you will not have to completely change your conception of gcc as soon as the official version is available. 0. Installation ------------ The installation consists of: 1. RUN$Path must be extended with the directory name, which contains the GNU C executables. You can also copy them to your library directory. 2. Set the variable CPATH. This variable should contain the directories, which contain the header files. For instance: Set CPATH IDEFS::IDEDisc4.$.DesktopC.Clib CPATH can contain more than one directory name by using ';' seperators. For instance: If your header files are in $.clib.1.h and $.clib.2.h, CPATH must be set as follows: Set CPATH $.clib.1;$.clib.2 You may also want to set the variables: C_INCLUDE_PATH CPLUS_INCLUDE_PATH OBJC_INCLUDE_PATH OBJCPLUS_INLCUDE_PATH CPLUS_INCLUDE_PATH and OBJCPLUS_INCLUDE_PATH will be only used during compiling c++ sources, objective c sources resp. do not forget the header files in risclib.inc.h! 3. You must set the variable mulib$Path to the FULL directory name where the risclib libraries can be found (e.g. stubsmu and oslib_mu). For instance: Set mulib$path IDEFS::IDEDisc4.$.Temp.GNU-CC.gcc2-3-3.risclib. The libraries can be found by calling Libraries mulib:stubsmu and mulib:oslib_mu set the variable clib$Path to the directory name where the original libraries (in AOF-format) can be found. For instance: Set clib$path adfs::4.$.c-compiler.clib. 4. You may have to convert Stubs und RISC_OSlib (use makelibs in the risclib directory). Makelibs does also compile the wimpclass library (MUPROS format). You should run makelibs even if you have already a running version of gcc installed - there are some changes. 5. compile the wimpclass library (for people who'd like to use AOF format object files) by amu-ing the makeAOF file in the risclib directory. It will build the wimpclass and gccext libraries in the clib:o directory. 6. The documentation can be found in the 'doc' directory. 7. Have a look at the !sbconfig application. It is a good sample on how to use wimpclass library - and it includes make files for both mupros and AOF compiling/linking 1. Prefixes in filenames --------------------- Unix expects, in contrary to RISC OS, that files types such as .c .o .cc are used as extension to the filename (e.g. myfile.c). GCC uses also file names in this format. In order to behave correctly under RISC OS, GCC moves the file type extension to the start of the filename. For instance 'GCC sample.c' will be 'GCC c.sample'. Note: 'irgend.sample.c' will be 'c.irgend.sample'. GCC uses these extensions in order to find out the file type. Remember: all unrecognized files are treated like object files. The extensions have the following meaning: .c C Source .cc, .cxx, .C C++ Source (Note: only .cc can be used with RISC OS) .m objective-C Source (not yet supported) .o object file .h header file .i pre-processed file (cpp output) .ii pre-processed C++ file .s assembler source .S assembler source (needs pre-processing) 2. (Options for) GCC ----------------- Since revision A GCC is able to automatically invoke the linker. With Revision B it invokes either mulink or link (Acorn's linker) depending on wether the -aof switch is off or on. There are no libraries automatically linked. An exact explanation of the compiler options are given in the file 'invoke' in the doc directory. Most options are just like with other C compilers. You must not forget to use the -O or -O2 (optimizing) option. Without these options you will get less efficient code. Machine dependent options: -mno-apsc use the C-call convention for functions. -mcoproc Coprocessor is available (due to code optimizing, works also without one) -mpoke-function-name function names for post mortem debugger in code -aof use AOF instead of mupros object file format (new) you can not mix AOF and mupros! -+ (passed to the linker) match C++ function calls to C function names. with that switch on you can call C functions from a C++ program without declaring it as extern "C" (does not work with AOF) -just-show (obsolete) just print the commands gcc would invoke to treat the given files. See the included sample application !sbconfig for sample make files for both MUPROS and AOF style compiling/linking 3. Include files ------------- For the include files is also the prefix-notation for file typen used. In the source code can the suffix-notation be used. The pre-processor converts these file names to prefix notation and recognizes the Unix directory paths. For instance /usr/include/sys/times.h becomes $.usr.include.sys.h.times, ../my-header.h becomes ^.h.my-header. The compiler recognizes only the file extensions .h und .c. Search order for include files: 1. current directory or the directories, which have been entered using the -I option 2. the directories, which are given by CPATH. 3. the directories given by C_INCLUDE_PATH (Standard C), CPLUS_INCLUDE_PATH (C++), OBJC_INCLUDE_PATH (Objective C) or OBJCPLUS_INLCUDE_PATH (Objective C++) The 'environment variables' may contain more directories (by using the ';' character as seperator). The Unix notation may also be used. However, different from RISC OS, the '.' or '/' character may not be the last character in direcory name (the Pre-Processor will do this for you). Also the '.h' must not be used in the path name. 3.1 How to use standard C header files ---------------------------------- If you include standard C headers into a C++ I propose to do it as the example shows: extern "C" { #include "stdlib.h" #include "stdio.h" ... } This makes the -+ option unnecessary and therefore does work with AOF too. 3.2 Changes to standard header files -------------------------------- If you use the standard string.h file, you should change memcpy, memcmp and strlen to extern int memcmp(const void * /*s1*/, const void * /*s2*/, long unsigned int /*n*/); extern void *memcpy(void * /*s1*/, const void * /*s2*/, long unsigned int /*n*/); extern long unsigned int strlen(const char * /*s*/); You should also replace in the file 'template.h' 'template' in typedef struct ... template through e.g. 'template_t'; don't forget to change it all over the file 4. Linker ------ In order to get 'absolute' code the linker must be called as follows: mulink -F -a32768 -osample -C o.sample1 o.sample2 mulib:stubsmu settype sample absolute Explanation: mulib$path contains the directory name where 'stubsmu' can be found. -F first object file must always be linked (only , when referenced). If stubsmu is linked, this option is not particulary necessary, because stubsmu has set the Obligatory-Link-Flag (will always be linked) and contains a reference to 'main'. -a32768 Absolute code with execution address &8000. -osample sample will be the output file -C only the code, without header, publics, relocs. If the -a and -C options are not used, an object-file will be produced. Further options: -x a list of symbols, moduls and their addresses (e.g. offsets) will be given. -+ link C++ - code. The linker will search for symbol names in a C++ fashion and if they could not be found, they are converted into standard-C name. For instance: printf( "%d", 10 ) generates in C++ a assembler call: ... bl printf__FPci If a symbol printf__FPci exists, the linker will generate a call to this symbol. Otherwise (with the -+ option) the name printf will be used (without __F...). -$<suffix> the characters, which in C++ symbol names is used between the 'normal' name of the function and the type. Default: __F. -u do not print a liste of undefined externals -=<name>=<value> create a symbol named <name> with the absolute value <value> All other options are ignored by RISC OS version (have no meaning). Stubs MUST be linked before the RISC_OSlib is linked. The file which contains the function main MUST be linked first (obsolete - does not matter if AIF header is linked. As it is contained in stubsmu it will be linked). In other cases the order of the object files doesn't matter. Objects which are referenced by none of the other object files are simply ignored. For instance: mulink -F o.sample1 o.sample2 mulib:stubsmu o.sample2 will not be linked, if neither in mulib:stubsmu nor in o.sample1 a function or variable from o.sample1 is referenced. If Stubs are linked, the following message could be printed: unresolved external(s) '__root_stack_size' in module 'Stub$$Code' '__RelocCode' in module 'Stub$$Code' Both references are in AOF-files as 'weak binding' defined and don't have to be declared. Applications will be linked correctly. Fomer versions of mulink used to print the following message is printed: warning: double defined public variable(s): 'C$$Code' in module 'C$$Code' This was due to an error in AOFconvert and should not appear any more (if you use newly converted libraries). If you get such a message please report to me which libraries you used. 5. AOFConvert ---------- AOFConvert is a utility which converts object files in AOF-Format into the MUPROS format. You have to use it as follows: AOFConvert -l -osample o.sample The option -l suppresses all warnings (which are not interesting). During some circumstances you will also have to use the -O option. Then will the converted object ALWAYS be linked (if it is used somewhere in conjunction with MULINK, even if no reference is fullfilled). 6. Assembler --------- If you like to use the assembler, you are referred to the tex file (in the doc directory) and the RISC OS PRM's. The assembler is called by using: as -o o.sample s.sample A object file in MUPROS format will be generated. Note: assembler instructions must be lower case. Register names may be upper case or lower case. ARM/MUPROS/AOF specific command line options: -d create a debug area. any source level debugging data will only be included in the object file if this option is found on the command line. -A output an AOF object file rather than a MUPROS object file ARM/MUPROS specific pseudo-instructions: .objname <name> the just assembled object will be called <name> (Default: Dateiname) .segid <name> the segment ID becomes <name> (Default: 'code') .segattr <'RO'|'RW'> Read-only or Read-Write Segment (Default: 'RW') .init <symbol> insert a constructor into init area (init area is scanned by _init_globals()/_kill_globals()) .kill <symbol> insert a destructor into init area .file <filename> specifies the source file name (-> source level debugging) .line <linenumber> specifies the source file number (dto.) .frag begin new line info fragment (should not be used) .obligatory to make the currently assembled area an 'obligatory link area' (does not work with AOF) .optionally to make the currently assembled area an 'optionally link area' (does not work with AOF) .ignoreline ignore .line directives .resumeline self explaining At the moment the assembler does not support separate code, data and null initialised segments (.text, .data, .bss), these will be assembled in different files. An example of a assembler source code is risclib.s.div-fast. More examples can be generated using GCC -O -S ... A full list of the assembler instructions (from the source code): /* format of the assembler string : %<bitfield>r print as an ARM register %<bitfield>f print a floating point constant if >7 else an fp register %c print condition code (always bits 28-31) %P print floating point precision in arithmetic insn %Q print floating point precision in ldf/stf insn %R print floating point rounding mode %<bitnum>'c print specified char iff bit is one %<bitnum>-<len>'c print specified char iff bit is one and length of command after c is at least len %<bitnum>`c print specified char iff bit is zero %<bitnum>?ab print a if bit is one else print b %p print 'p' iff bits 12-15 are 15 %o print operand2 (immediate or register + shift) %a print address for ldr/str instruction %b print branch destination %A print address for ldc/stc/ldf/stf instruction %m print register mask for ldm/stm instruction %s print bits 0-23 as swi number/name %L print ldm type (fd, ea and the like ...) %S print stm type %r print adr operand /* ARM instructions */ "mul%c%20's %16-19r,%0-3r,%8-11r", "mla%c%20's %16-19r,%0-3r,%8-11r,%12-15r", "and%c%20's %12-15r,%16-19r,%o", "eor%c%20's %12-15r,%16-19r,%o", "sub%c%20's %12-15r,%16-19r,%o", "rsb%c%20's %12-15r,%16-19r,%o", "add%c%20's %12-15r,%16-19r,%o", "adr%c%20's %12-15r,%r", "adc%c%20's %12-15r,%16-19r,%o", "sbc%c%20's %12-15r,%16-19r,%o", "rsc%c%20's %12-15r,%16-19r,%o", "tst%c%p %16-19r,%o", "teq%c%p %16-19r,%o", "cmp%c%p %16-19r,%o", "cmn%c%p %16-19r,%o", "orr%c%20's %12-15r,%16-19r,%o", "mov%c%20's %12-15r,%o", "bic%c%20's %12-15r,%16-19r,%o", "mvn%c%20's %12-15r,%o", "str%c%22'b %12-15r,%a", "ldr%c%22'b %12-15r,%a", "stm%c%S %16-19r%21'!,%m", "ldm%c%L %16-19r%21'!,%m%22'^", "b%24-2'l%c%24'l %b", "swi%c %s", /* Floating point coprocessor instructions */ "adf%c%P%R %12-14f,%16-18f,%0-3f", "muf%c%P%R %12-14f,%16-18f,%0-3f", "suf%c%P%R %12-14f,%16-18f,%0-3f", "rsf%c%P%R %12-14f,%16-18f,%0-3f", "dvf%c%P%R %12-14f,%16-18f,%0-3f", "rdf%c%P%R %12-14f,%16-18f,%0-3f", "pow%c%P%R %12-14f,%16-18f,%0-3f", "rpw%c%P%R %12-14f,%16-18f,%0-3f", "rmf%c%P%R %12-14f,%16-18f,%0-3f", "fml%c%P%R %12-14f,%16-18f,%0-3f", "fdv%c%P%R %12-14f,%16-18f,%0-3f", "frd%c%P%R %12-14f,%16-18f,%0-3f", "pol%c%P%R %12-14f,%16-18f,%0-3f", "mvf%c%P%R %12-14f,%0-3f", "mnf%c%P%R %12-14f,%0-3f", "abs%c%P%R %12-14f,%0-3f", "rnd%c%P%R %12-14f,%0-3f", "sqt%c%P%R %12-14f,%0-3f", "log%c%P%R %12-14f,%0-3f", "lgn%c%P%R %12-14f,%0-3f", "exp%c%P%R %12-14f,%0-3f", "sin%c%P%R %12-14f,%0-3f", "cos%c%P%R %12-14f,%0-3f", "tan%c%P%R %12-14f,%0-3f", "asn%c%P%R %12-14f,%0-3f", "acs%c%P%R %12-14f,%0-3f", "atn%c%P%R %12-14f,%0-3f", "flt%c%P%R %16-18f,%12-15r", "fix%c%P%R %12-15r,%0-2f", "wfs%c %12-15r", "rfs%c %12-15r", "wfc%c %12-15r", "rfc%c %12-15r", "cmf%c %16-18f,%0-3f", "cnf%c %16-18f,%0-3f", "cmfe%c %16-18f,%0-3f", "cnfe%c %16-18f,%0-3f", "stf%c%Q %12-14f,%A", "ldf%c%Q %12-14f,%A", 7. Libraries --------- 7.1 Stubs / RISC_OSlib ------------------ With the GNU C/C++ compiler, you should have also the converted versions of Stubs and RISC_OSlib (stubsmu and oslib_mu in the directory risclib). If this is not the case, you can generate these libraries by executing the Obey file risclib.makelibs. Again: link Stubs always before RISC_OSlib. Until Revision B gcc had its own division routines (thought to be faster). From now on the routines included with stubs are used. 7.2 Your own libraries ------------------ Libraries are constructed as follows (for MUPROS format only): 1. compile single modules 2. put the objects in one file (e.g. using fappend) BTW: mulink .... o.sample1 o.sample2 is exactly the same as: fappend o.sample1 o.sample2 mulink .... o.sample1 Note: if someone has written a number of functions or classes, which are very interesting: PLEASE let also other people use them. If this is the case, contact me. I will try to distribute them. I hope, other people will respond. 7.3 Converting libraries from ALF (Acorn Library Format) to MUPROS format --------------------------------------------------------------------- You have to follow this procedure to convert libraries: 1. extract all the object files from the library using libfile -e <library> * 2. convert each object file with AOFconvert (see above) 3. fappend the object files you wish to be included in your converted library That's it. 7.4 The wimpclass library --------------------- With revision A/B of GCC there came the so called wimpclass library. This is a kind of pre-alpha-Release. I included it to motivate people creating classes for wimp rather than distribute a useful wimp library. Try out !sbconfig to see what is implemented yet. 7.5 The libg-- library ----------------- Ferdinand Oeinck succeeded in porting the iostream part of the libg++ library. The compiled versions can be found in mulib:libg--/mulib:libg--AOF resp. The headers needed for application of this library are in mulib:inc.h. You find all the sources and Ferdinand's comments in the directory mulib:libg231. In libg-- there is also a string class. Have a look at its header file (str.h) to see what it is for. NOTE: you should link libg-- together with UnixLib 3.6 (available from e.g. Newcastle server). Only parts of it do work with Stubs. 8. Objective C ----------- The current RISC OS version of GNU C/C++ does not support objective C. If you have a need for this, please contact me. 9. "Support" --------- In many mailboxes you will find discussions about GNU C/C++. If you have access to Internet, for instance UUCP-News, you can read the newsgroup gnu.g++... or comp.sys.acorn For RISC OS specific problems I can be contacted at: Thomas Aeby Graeffet 406 1735 Giffers Schweiz Tel. 037 38 16 00 EMail aeby@uropax.contrib.de Please do report any bugs to this address. Thank you! There was a mail list setup for GCC for RISCOS purposes. Please send a mail to riscos-g++-request@visionware.co.uk to get registered as a gcc user (this is not a machine - please be polite). You will then get all the announcements from me and other users. This 'registration' does not mean that you are registered in any legal way - it is just a mail list. Mail sent to riscos-g++@visionware.co.uk will redistributed to all the registered users. 10. Source code ----------- All source code of the compiler and the assembler are available from the address above and from JLACS/JLACD Archimedes Clubs (Switzerland, Germany). 11. Floating point arithmetic ------------------------- Floating point arithmetic can be used and SHOULD work. However, it is still not very well tested. You can't rely on it. 12. Memory ------ In order to compile C++ programs, you will need more than 2Mb free memory (task slot). Standard C uses less memory, but you will still need about 1-1.2 Mb. Error messages like 'virtual memory exhausted' mean lack of memory. NOTE: gcc does now work under !Virtual but you need a version >0.23 of !Virtual. Some messages ...SWI ... Allow(Yn) may occur. Answer them with 'Y'. 13. Debugger -------- Until now only one source level debugging feature is implemented (use -g option with gcc): source file and line information. So you can at least trace through programs with ASD (do not use the step in command), set breakpoints, see source lines. Information about Procedures, Variables, ... is not available yet (in progress). NOTE: You can not use !DDT with GCC! Though Acorn says in its manuals that !DDT should use the same format for debugging info it apparently does not. Does any one know the difference (Then please write to me!)? 14. AOF --- Since revision B you can create/link AOF style object files with gcc. To use this feature you have to apply the -aof (gcc) or the -A (as) option. You have to link not only the stubs library but the library called 'gccext' too. This library contains some functions gcc expects to be in the standard library. You can create this library by invoking amu with the makeAOF file contained in the risclib directory. MakeAOF will put the library 'gccext' and the AOF version of the 'wimpclass' library into clib:o The sample application !sbconfig contains both makefiles for AOF style and MUPROS style compiling. Have a look on it! 15. Stack ----- GCC does still not produce any stack checking code. It assumes a infinite continuous descending stack. So you have to take care that the stack is large enough. If you use stubs you can use the variable __root_stack_size for this purpose. E.g. if you define int __root_stack_size = 16384; in one of the source files stubs will allocate 16kBytes for stack on startup (default is 4k). Note that a stack overflow will not cause an immediate failure in every case. It may cause very subtle errors. 16. Constructors/Destructors ------------------------ Constructors/Destructors of global objects are collected in the so-called init area but they are not automatically called at program startup/exit. To do this gccext provides two functions, one for constructor calls, one for destructor calls. They are called _init_globals() (calls each global constructor) _kill_globals() (calls each global destructor) These functions should be called at program startup/exit if there are any global objects. Of course they may be called if there are no global objects too. Thomas Aeby Graeffet 406 1735 Giffers Tel.: 037 38 16 00 EMail: aeby@uropax.contrib.de thanks to L.L. Frederiks who translated the original version of this readme file from German (I added the mistakes)