--- gcc/gcc.info-11 2018/04/24 18:18:44 1.1.1.7 +++ gcc/gcc.info-11 2018/04/24 18:42:13 1.1.1.10 @@ -1,13 +1,13 @@ -This is Info file gcc.info, produced by Makeinfo-1.55 from the input -file gcc.texi. +This is Info file gcc.info, produced by Makeinfo version 1.67 from the +input file gcc.texi. This file documents the use and the internals of the GNU compiler. - Published by the Free Software Foundation 675 Massachusetts Avenue -Cambridge, MA 02139 USA + Published by the Free Software Foundation 59 Temple Place - Suite 330 +Boston, MA 02111-1307 USA - Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, -Inc. + Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software +Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -30,799 +30,1115 @@ translations approved by the Free Softwa original English.  -File: gcc.info, Node: Bug Reporting, Next: Sending Patches, Prev: Bug Lists, Up: Bugs +File: gcc.info, Node: Installation Problems, Next: Cross-Compiler Problems, Prev: Actual Bugs, Up: Trouble -How to Report Bugs -================== +Installation Problems +===================== - The fundamental principle of reporting bugs usefully is this: -*report all the facts*. If you are not sure whether to state a fact or -leave it out, state it! - - Often people omit facts because they think they know what causes the -problem and they conclude that some details don't matter. Thus, you -might assume that the name of the variable you use in an example does -not matter. Well, probably it doesn't, but one cannot be sure. -Perhaps the bug is a stray memory reference which happens to fetch from -the location where that name is stored in memory; perhaps, if the name -were different, the contents of that location would fool the compiler -into doing the right thing despite the bug. Play it safe and give a -specific, complete example. That is the easiest thing for you to do, -and the most helpful. - - Keep in mind that the purpose of a bug report is to enable someone to -fix the bug if it is not known. It isn't very important what happens if -the bug is already known. Therefore, always write your bug reports on -the assumption that the bug is not known. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" This cannot help us fix a bug, so it is basically useless. We -respond by asking for enough details to enable us to investigate. You -might as well expedite matters by sending them to begin with. - - Try to make your bug report self-contained. If we have to ask you -for more information, it is best if you include all the previous -information in your response, as well as the information that was -missing. - - Please report each bug in a separate message. This makes it easier -for us to track which bugs have been fixed and to forward your bugs -reports to the appropriate maintainer. - - To enable someone to investigate the bug, you should include all -these things: - - * The version of GNU CC. You can get this by running it with the - `-v' option. - - Without this, we won't know whether there is any point in looking - for the bug in the current version of GNU CC. - - * A complete input file that will reproduce the bug. If the bug is - in the C preprocessor, send a source file and any header files - that it requires. If the bug is in the compiler proper (`cc1'), - run your source file through the C preprocessor by doing `gcc -E - SOURCEFILE > OUTFILE', then include the contents of OUTFILE in the - bug report. (When you do this, use the same `-I', `-D' or `-U' - options that you used in actual compilation.) - - A single statement is not enough of an example. In order to - compile it, it must be embedded in a complete file of compiler - input; and the bug might depend on the details of how this is done. - - Without a real example one can compile, all anyone can do about - your bug report is wish you luck. It would be futile to try to - guess how to provoke the bug. For example, bugs in register - allocation and reloading frequently depend on every little detail - of the function they happen in. - - Even if the input file that fails comes from a GNU program, you - should still send the complete test case. Don't ask the GNU CC - maintainers to do the extra work of obtaining the program in - question--they are all overworked as it is. Also, the problem may - depend on what is in the header files on your system; it is - unreliable for the GNU CC maintainers to try the problem with the - header files available to them. By sending CPP output, you can - eliminate this source of uncertainty and save us a certain - percentage of wild goose chases. - - * The command arguments you gave GNU CC or GNU C++ to compile that - example and observe the bug. For example, did you use `-O'? To - guarantee you won't omit something important, list all the options. - - If we were to try to guess the arguments, we would probably guess - wrong and then we would not encounter the bug. - - * The type of machine you are using, and the operating system name - and version number. - - * The operands you gave to the `configure' command when you installed - the compiler. - - * A complete list of any modifications you have made to the compiler - source. (We don't promise to investigate the bug unless it - happens in an unmodified compiler. But if you've made - modifications and don't tell us, then you are sending us on a wild - goose chase.) - - Be precise about these changes. A description in English is not - enough--send a context diff for them. - - Adding files of your own (such as a machine description for a - machine we don't support) is a modification of the compiler source. - - * Details of any other deviations from the standard procedure for - installing GNU CC. - - * A description of what behavior you observe that you believe is - incorrect. For example, "The compiler gets a fatal signal," or, - "The assembler instruction at line 208 in the output is incorrect." - - Of course, if the bug is that the compiler gets a fatal signal, - then one can't miss it. But if the bug is incorrect output, the - maintainer might not notice unless it is glaringly wrong. None of - us has time to study all the assembler code from a 50-line C - program just on the chance that one instruction might be wrong. - We need *you* to do this part! - - Even if the problem you experience is a fatal signal, you should - still say so explicitly. Suppose something strange is going on, - such as, your copy of the compiler is out of synch, or you have - encountered a bug in the C library on your system. (This has - happened!) Your copy might crash and the copy here would not. If - you said to expect a crash, then when the compiler here fails to - crash, we would know that the bug was not happening. If you don't - say to expect a crash, then we would not know whether the bug was - happening. We would not be able to draw any conclusion from our - observations. - - If the problem is a diagnostic when compiling GNU CC with some - other compiler, say whether it is a warning or an error. - - Often the observed symptom is incorrect output when your program - is run. Sad to say, this is not enough information unless the - program is short and simple. None of us has time to study a large - program to figure out how it would work if compiled correctly, - much less which line of it was compiled wrong. So you will have - to do that. Tell us which source line it is, and what incorrect - result happens when that line is executed. A person who - understands the program can find this as easily as finding a bug - in the program itself. - - * If you send examples of assembler code output from GNU CC or GNU - C++, please use `-g' when you make them. The debugging information - includes source line numbers which are essential for correlating - the output with the input. - - * If you wish to mention something in the GNU CC source, refer to it - by context, not by line number. - - The line numbers in the development sources don't match those in - your sources. Your line numbers would convey no useful - information to the maintainers. - - * Additional information from a debugger might enable someone to - find a problem on a machine which he does not have available. - However, you need to think when you collect this information if - you want it to have any chance of being useful. - - For example, many people send just a backtrace, but that is never - useful by itself. A simple backtrace with arguments conveys little - about GNU CC because the compiler is largely data-driven; the same - functions are called over and over for different RTL insns, doing - different things depending on the details of the insn. - - Most of the arguments listed in the backtrace are useless because - they are pointers to RTL list structure. The numeric values of the - pointers, which the debugger prints in the backtrace, have no - significance whatever; all that matters is the contents of the - objects they point to (and most of the contents are other such - pointers). - - In addition, most compiler passes consist of one or more loops that - scan the RTL insn sequence. The most vital piece of information - about such a loop--which insn it has reached--is usually in a - local variable, not in an argument. - - What you need to provide in addition to a backtrace are the values - of the local variables for several stack frames up. When a local - variable or an argument is an RTX, first print its value and then - use the GDB command `pr' to print the RTL expression that it points - to. (If GDB doesn't run on your machine, use your debugger to call - the function `debug_rtx' with the RTX as an argument.) In - general, whenever a variable is a pointer, its value is no use - without the data it points to. - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - Often people who encounter a bug spend a lot of time investigating - which changes to the input file will make the bug go away and which - changes will not affect it. - - This is often time consuming and not very useful, because the way - we will find the bug is by running a single example under the - debugger with breakpoints, not by pure deduction from a series of - examples. You might as well save your time for something else. - - Of course, if you can find a simpler example to report *instead* of - the original one, that is a convenience. Errors in the output - will be easier to spot, running under the debugger will take less - time, etc. Most GNU CC bugs involve just one function, so the - most straightforward way to simplify an example is to delete all - the function definitions except the one where the bug occurs. - Those earlier in the file may be replaced by external declarations - if the crucial function depends on them. (Exception: inline - functions may affect compilation of functions defined later in the - file.) - - However, simplification is not vital; if you don't want to do this, - report the bug anyway and send the entire test case you used. - - * In particular, some people insert conditionals `#ifdef BUG' around - a statement which, if removed, makes the bug not happen. These - are just clutter; we won't pay any attention to them anyway. - Besides, you should send us cpp output, and that can't have - conditionals. - - * A patch for the bug. - - A patch for the bug is useful if it is a good one. But don't omit - the necessary information, such as the test case, on the - assumption that a patch is all we need. We might see problems - with your patch and decide to fix the problem another way, or we - might not understand it at all. - - Sometimes with a program as complicated as GNU CC it is very hard - to construct an example that will make the program follow a - certain path through the code. If you don't send the example, we - won't be able to construct one, so we won't be able to verify that - the bug is fixed. - - And if we can't understand what bug you are trying to fix, or why - your patch should be an improvement, we won't install it. A test - case will help us to understand. - - *Note Sending Patches::, for guidelines on how to make it easy for - us to understand and install your patches. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even I can't guess right about - such things without first using the debugger to find the facts. - - * A core dump file. - - We have no way of examining a core dump for your type of machine - unless we have an identical system--and if we do have one, we - should be able to reproduce the crash ourselves. + This is a list of problems (and some apparent problems which don't +really mean anything is wrong) that show up during installation of GNU +CC. - -File: gcc.info, Node: Sending Patches, Prev: Bug Reporting, Up: Bugs + * On certain systems, defining certain environment variables such as + `CC' can interfere with the functioning of `make'. -Sending Patches for GNU CC -========================== + * If you encounter seemingly strange errors when trying to build the + compiler in a directory other than the source directory, it could + be because you have previously configured the compiler in the + source directory. Make sure you have done all the necessary + preparations. *Note Other Dir::. - If you would like to write bug fixes or improvements for the GNU C -compiler, that is very helpful. When you send your changes, please -follow these guidelines to avoid causing extra work for us in studying -the patches. - - If you don't follow these guidelines, your information might still be -useful, but using it will take extra work. Maintaining GNU C is a lot -of work in the best of circumstances, and we can't keep up unless you do -your best to help. - - * Send an explanation with your changes of what problem they fix or - what improvement they bring about. For a bug fix, just include a - copy of the bug report, and explain why the change fixes the bug. - - (Referring to a bug report is not as good as including it, because - then we will have to look it up, and we have probably already - deleted it if we've already fixed the bug.) - - * Always include a proper bug report for the problem you think you - have fixed. We need to convince ourselves that the change is - right before installing it. Even if it is right, we might have - trouble judging it if we don't have a way to reproduce the problem. - - * Include all the comments that are appropriate to help people - reading the source in the future understand why this change was - needed. - - * Don't mix together changes made for different reasons. Send them - *individually*. - - If you make two changes for separate reasons, then we might not - want to install them both. We might want to install just one. If - you send them all jumbled together in a single set of diffs, we - have to do extra work to disentangle them--to figure out which - parts of the change serve which purpose. If we don't have time - for this, we might have to ignore your changes entirely. - - If you send each change as soon as you have written it, with its - own explanation, then the two changes never get tangled up, and we - can consider each one properly without any extra work to - disentangle them. - - Ideally, each change you send should be impossible to subdivide - into parts that we might want to consider separately, because each - of its parts gets its motivation from the other parts. - - * Send each change as soon as that change is finished. Sometimes - people think they are helping us by accumulating many changes to - send them all together. As explained above, this is absolutely - the worst thing you could do. - - Since you should send each change separately, you might as well - send it right away. That gives us the option of installing it - immediately if it is important. - - * Use `diff -c' to make your diffs. Diffs without context are hard - for us to install reliably. More than that, they make it hard for - us to study the diffs to decide whether we want to install them. - Unidiff format is better than contextless diffs, but not as easy - to read as `-c' format. - - If you have GNU diff, use `diff -cp', which shows the name of the - function that each change occurs in. - - * Write the change log entries for your changes. We get lots of - changes, and we don't have time to do all the change log writing - ourselves. - - Read the `ChangeLog' file to see what sorts of information to put - in, and to learn the style that we use. The purpose of the change - log is to show people where to find what was changed. So you need - to be specific about what functions you changed; in large - functions, it's often helpful to indicate where within the - function the change was. - - On the other hand, once you have shown people where to find the - change, you need not explain its purpose. Thus, if you add a new - function, all you need to say about it is that it is new. If you - feel that the purpose needs explaining, it probably does--but the - explanation will be much more useful if you put it in comments in - the code. - - If you would like your name to appear in the header line for who - made the change, send us the header line. - - * When you write the fix, keep in mind that we can't install a - change that would break other systems. - - People often suggest fixing a problem by changing - machine-independent files such as `toplev.c' to do something - special that a particular system needs. Sometimes it is totally - obvious that such changes would break GNU CC for almost all users. - We can't possibly make a change like that. At best it might tell - us how to write another patch that would solve the problem - acceptably. - - Sometimes people send fixes that *might* be an improvement in - general--but it is hard to be sure of this. It's hard to install - such changes because we have to study them very carefully. Of - course, a good explanation of the reasoning by which you concluded - the change was correct can help convince us. - - The safest changes are changes to the configuration files for a - particular machine. These are safe because they can't create new - bugs on other machines. + * If you build GNU CC on a BSD system using a directory stored in a + System V file system, problems may occur in running `fixincludes' + if the System V file system doesn't support symbolic links. These + problems result in a failure to fix the declaration of `size_t' in + `sys/types.h'. If you find that `size_t' is a signed type and + that type mismatches occur, this could be the cause. - Please help us keep up with the workload by designing the patch in - a form that is good to install. + The solution is not to use such a directory for building GNU CC. - -File: gcc.info, Node: Service, Next: VMS, Prev: Bugs, Up: Top + * In previous versions of GNU CC, the `gcc' driver program looked for + `as' and `ld' in various places; for example, in files beginning + with `/usr/local/lib/gcc-'. GNU CC version 2 looks for them in + the directory `/usr/local/lib/gcc-lib/TARGET/VERSION'. + + Thus, to use a version of `as' or `ld' that is not the system + default, for example `gas' or GNU `ld', you must put them in that + directory (or make links to them from that directory). + + * Some commands executed when making the compiler may fail (return a + non-zero status) and be ignored by `make'. These failures, which + are often due to files that were not found, are expected, and can + safely be ignored. + + * It is normal to have warnings in compiling certain files about + unreachable code and about enumeration type clashes. These files' + names begin with `insn-'. Also, `real.c' may get some warnings + that you can ignore. + + * Sometimes `make' recompiles parts of the compiler when installing + the compiler. In one case, this was traced down to a bug in + `make'. Either ignore the problem or switch to GNU Make. + + * If you have installed a program known as purify, you may find that + it causes errors while linking `enquire', which is part of building + GNU CC. The fix is to get rid of the file `real-ld' which purify + installs--so that GNU CC won't try to use it. + + * On SLS 1.01, a Linux-based GNU system, there is a problem with + `libc.a': it does not contain the obstack functions. However, GNU + CC assumes that the obstack functions are in `libc.a' when it is + the GNU C library. To work around this problem, change the + `__GNU_LIBRARY__' conditional around line 31 to `#if 1'. + + * On some 386 systems, building the compiler never finishes because + `enquire' hangs due to a hardware problem in the motherboard--it + reports floating point exceptions to the kernel incorrectly. You + can install GNU CC except for `float.h' by patching out the + command to run `enquire'. You may also be able to fix the problem + for real by getting a replacement motherboard. This problem was + observed in Revision E of the Micronics motherboard, and is fixed + in Revision F. It has also been observed in the MYLEX MXA-33 + motherboard. + + If you encounter this problem, you may also want to consider + removing the FPU from the socket during the compilation. + Alternatively, if you are running SCO Unix, you can reboot and + force the FPU to be ignored. To do this, type `hd(40)unix auto + ignorefpu'. + + * On some 386 systems, GNU CC crashes trying to compile `enquire.c'. + This happens on machines that don't have a 387 FPU chip. On 386 + machines, the system kernel is supposed to emulate the 387 when you + don't have one. The crash is due to a bug in the emulator. + + One of these systems is the Unix from Interactive Systems: 386/ix. + On this system, an alternate emulator is provided, and it does + work. To use it, execute this command as super-user: + + ln /etc/emulator.rel1 /etc/emulator + + and then reboot the system. (The default emulator file remains + present under the name `emulator.dflt'.) + + Try using `/etc/emulator.att', if you have such a problem on the + SCO system. + + Another system which has this problem is Esix. We don't know + whether it has an alternate emulator that works. + + On NetBSD 0.8, a similar problem manifests itself as these error + messages: + + enquire.c: In function `fprop': + enquire.c:2328: floating overflow + + * On SCO systems, when compiling GNU CC with the system's compiler, + do not use `-O'. Some versions of the system's compiler miscompile + GNU CC with `-O'. + + * Sometimes on a Sun 4 you may observe a crash in the program + `genflags' or `genoutput' while building GNU CC. This is said to + be due to a bug in `sh'. You can probably get around it by running + `genflags' or `genoutput' manually and then retrying the `make'. + + * On Solaris 2, executables of GNU CC version 2.0.2 are commonly + available, but they have a bug that shows up when compiling current + versions of GNU CC: undefined symbol errors occur during assembly + if you use `-g'. + + The solution is to compile the current version of GNU CC without + `-g'. That makes a working compiler which you can use to recompile + with `-g'. + + * Solaris 2 comes with a number of optional OS packages. Some of + these packages are needed to use GNU CC fully. If you did not + install all optional packages when installing Solaris, you will + need to verify that the packages that GNU CC needs are installed. + + To check whether an optional package is installed, use the + `pkginfo' command. To add an optional package, use the `pkgadd' + command. For further details, see the Solaris documentation. + + For Solaris 2.0 and 2.1, GNU CC needs six packages: `SUNWarc', + `SUNWbtool', `SUNWesu', `SUNWhea', `SUNWlibm', and `SUNWtoo'. + + For Solaris 2.2, GNU CC needs an additional seventh package: + `SUNWsprot'. + + * On Solaris 2, trying to use the linker and other tools in + `/usr/ucb' to install GNU CC has been observed to cause trouble. + For example, the linker may hang indefinitely. The fix is to + remove `/usr/ucb' from your `PATH'. + + * If you use the 1.31 version of the MIPS assembler (such as was + shipped with Ultrix 3.1), you will need to use the + -fno-delayed-branch switch when optimizing floating point code. + Otherwise, the assembler will complain when the GCC compiler fills + a branch delay slot with a floating point instruction, such as + `add.d'. + + * If on a MIPS system you get an error message saying "does not have + gp sections for all it's [sic] sectons [sic]", don't worry about + it. This happens whenever you use GAS with the MIPS linker, but + there is not really anything wrong, and it is okay to use the + output file. You can stop such warnings by installing the GNU + linker. + + It would be nice to extend GAS to produce the gp tables, but they + are optional, and there should not be a warning about their + absence. + + * In Ultrix 4.0 on the MIPS machine, `stdio.h' does not work with GNU + CC at all unless it has been fixed with `fixincludes'. This causes + problems in building GNU CC. Once GNU CC is installed, the + problems go away. + + To work around this problem, when making the stage 1 compiler, + specify this option to Make: + + GCC_FOR_TARGET="./xgcc -B./ -I./include" + + When making stage 2 and stage 3, specify this option: + + CFLAGS="-g -I./include" + + * Users have reported some problems with version 2.0 of the MIPS + compiler tools that were shipped with Ultrix 4.1. Version 2.10 + which came with Ultrix 4.2 seems to work fine. + + Users have also reported some problems with version 2.20 of the + MIPS compiler tools that were shipped with RISC/os 4.x. The + earlier version 2.11 seems to work fine. + + * Some versions of the MIPS linker will issue an assertion failure + when linking code that uses `alloca' against shared libraries on + RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug in the + linker, that is supposed to be fixed in future revisions. To + protect against this, GNU CC passes `-non_shared' to the linker + unless you pass an explicit `-shared' or `-call_shared' switch. + + * On System V release 3, you may get this error message while + linking: + + ld fatal: failed to write symbol name SOMETHING + in strings table for file WHATEVER + + This probably indicates that the disk is full or your ULIMIT won't + allow the file to be as large as it needs to be. + + This problem can also result because the kernel parameter `MAXUMEM' + is too small. If so, you must regenerate the kernel and make the + value much larger. The default value is reported to be 1024; a + value of 32768 is said to work. Smaller values may also work. + + * On System V, if you get an error like this, + + /usr/local/lib/bison.simple: In function `yyparse': + /usr/local/lib/bison.simple:625: virtual memory exhausted + + that too indicates a problem with disk space, ULIMIT, or `MAXUMEM'. + + * Current GNU CC versions probably do not work on version 2 of the + NeXT operating system. + + * On NeXTStep 3.0, the Objective C compiler does not work, due, + apparently, to a kernel bug that it happens to trigger. This + problem does not happen on 3.1. + + * On the Tower models 4N0 and 6N0, by default a process is not + allowed to have more than one megabyte of memory. GNU CC cannot + compile itself (or many other programs) with `-O' in that much + memory. + + To solve this problem, reconfigure the kernel adding the following + line to the configuration file: + + MAXUMEM = 4096 -How To Get Help with GNU CC -*************************** + * On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a + bug in the assembler that must be fixed before GNU CC can be + built. This bug manifests itself during the first stage of + compilation, while building `libgcc2.a': - If you need help installing, using or changing GNU CC, there are two -ways to find it: + _floatdisf + cc1: warning: `-g' option not supported on this version of GCC + cc1: warning: `-g1' option not supported on this version of GCC + ./xgcc: Internal compiler error: program as got fatal signal 11 - * Send a message to a suitable network mailing list. First try - `bug-gcc@prep.ai.mit.edu', and if that brings no response, try - `help-gcc@prep.ai.mit.edu'. + A patched version of the assembler is available by anonymous ftp + from `altdorf.ai.mit.edu' as the file + `archive/cph/hpux-8.0-assembler'. If you have HP software support, + the patch can also be obtained directly from HP, as described in + the following note: - * Look in the service directory for someone who might help you for a - fee. The service directory is found in the file named `SERVICE' - in the GNU CC distribution. + This is the patched assembler, to patch SR#1653-010439, where + the assembler aborts on floating point constants. + + The bug is not really in the assembler, but in the shared + library version of the function "cvtnum(3c)". The bug on + "cvtnum(3c)" is SR#4701-078451. Anyway, the attached + assembler uses the archive library version of "cvtnum(3c)" + and thus does not exhibit the bug. + + This patch is also known as PHCO_4484. + + * On HP-UX version 8.05, but not on 8.07 or more recent versions, + the `fixproto' shell script triggers a bug in the system shell. + If you encounter this problem, upgrade your operating system or + use BASH (the GNU shell) to run `fixproto'. + + * Some versions of the Pyramid C compiler are reported to be unable + to compile GNU CC. You must use an older version of GNU CC for + bootstrapping. One indication of this problem is if you get a + crash when GNU CC compiles the function `muldi3' in file + `libgcc2.c'. + + You may be able to succeed by getting GNU CC version 1, installing + it, and using it to compile GNU CC version 2. The bug in the + Pyramid C compiler does not seem to affect GNU CC version 1. + + * There may be similar problems on System V Release 3.1 on 386 + systems. + + * On the Intel Paragon (an i860 machine), if you are using operating + system version 1.0, you will get warnings or errors about + redefinition of `va_arg' when you build GNU CC. + + If this happens, then you need to link most programs with the + library `iclib.a'. You must also modify `stdio.h' as follows: + before the lines + + #if defined(__i860__) && !defined(_VA_LIST) + #include + + insert the line + + #if __PGC__ + + and after the lines + + extern int vprintf(const char *, va_list ); + extern int vsprintf(char *, const char *, va_list ); + #endif + + insert the line + + #endif /* __PGC__ */ + + These problems don't exist in operating system version 1.1. + + * On the Altos 3068, programs compiled with GNU CC won't work unless + you fix a kernel bug. This happens using system versions V.2.2 + 1.0gT1 and V.2.2 1.0e and perhaps later versions as well. See the + file `README.ALTOS'. + + * You will get several sorts of compilation and linking errors on the + we32k if you don't follow the special instructions. *Note + Configurations::. + + * A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto + program to report an error of the form: + + ./fixproto: sh internal 1K buffer overflow + + To fix this, change the first line of the fixproto script to look + like: + + #!/bin/ksh  -File: gcc.info, Node: VMS, Next: Portability, Prev: Service, Up: Top +File: gcc.info, Node: Cross-Compiler Problems, Next: Interoperation, Prev: Installation Problems, Up: Trouble -Using GNU CC on VMS -******************* +Cross-Compiler Problems +======================= - Here is how to use GNU CC on VMS. + You may run into problems with cross compilation on certain machines, +for several reasons. -* Menu: + * Cross compilation can run into trouble for certain machines because + some target machines' assemblers require floating point numbers to + be written as *integer* constants in certain contexts. + + The compiler writes these integer constants by examining the + floating point value as an integer and printing that integer, + because this is simple to write and independent of the details of + the floating point representation. But this does not work if the + compiler is running on a different machine with an incompatible + floating point format, or even a different byte-ordering. + + In addition, correct constant folding of floating point values + requires representing them in the target machine's format. (The C + standard does not quite require this, but in practice it is the + only way to win.) + + It is now possible to overcome these problems by defining macros + such as `REAL_VALUE_TYPE'. But doing so is a substantial amount of + work for each target machine. *Note Cross-compilation::. + + * At present, the program `mips-tfile' which adds debug support to + object files on MIPS systems does not work in a cross compile + environment. + + +File: gcc.info, Node: Interoperation, Next: External Bugs, Prev: Cross-Compiler Problems, Up: Trouble + +Interoperation +============== -* Include Files and VMS:: Where the preprocessor looks for the include files. -* Global Declarations:: How to do globaldef, globalref and globalvalue with - GNU CC. -* VMS Misc:: Misc information. + This section lists various difficulties encountered in using GNU C or +GNU C++ together with other compilers or with the assemblers, linkers, +libraries and debuggers on certain systems. + + * Objective C does not work on the RS/6000. + + * GNU C++ does not do name mangling in the same way as other C++ + compilers. This means that object files compiled with one compiler + cannot be used with another. + + This effect is intentional, to protect you from more subtle + problems. Compilers differ as to many internal details of C++ + implementation, including: how class instances are laid out, how + multiple inheritance is implemented, and how virtual function + calls are handled. If the name encoding were made the same, your + programs would link against libraries provided from other + compilers--but the programs would then crash when run. + Incompatible libraries are then detected at link time, rather than + at run time. + + * Older GDB versions sometimes fail to read the output of GNU CC + version 2. If you have trouble, get GDB version 4.4 or later. + + * DBX rejects some files produced by GNU CC, though it accepts + similar constructs in output from PCC. Until someone can supply a + coherent description of what is valid DBX input and what is not, + there is nothing I can do about these problems. You are on your + own. + + * The GNU assembler (GAS) does not support PIC. To generate PIC + code, you must use some other assembler, such as `/bin/as'. + + * On some BSD systems, including some versions of Ultrix, use of + profiling causes static variable destructors (currently used only + in C++) not to be run. + + * Use of `-I/usr/include' may cause trouble. + + Many systems come with header files that won't work with GNU CC + unless corrected by `fixincludes'. The corrected header files go + in a new directory; GNU CC searches this directory before + `/usr/include'. If you use `-I/usr/include', this tells GNU CC to + search `/usr/include' earlier on, before the corrected headers. + The result is that you get the uncorrected header files. + + Instead, you should use these options (when compiling C programs): + + -I/usr/local/lib/gcc-lib/TARGET/VERSION/include -I/usr/include + + For C++ programs, GNU CC also uses a special directory that + defines C++ interfaces to standard C subroutines. This directory + is meant to be searched *before* other standard include + directories, so that it takes precedence. If you are compiling + C++ programs and specifying include directories explicitly, use + this option first, then the two options above: + + -I/usr/local/lib/g++-include + + * On some SGI systems, when you use `-lgl_s' as an option, it gets + translated magically to `-lgl_s -lX11_s -lc_s'. Naturally, this + does not happen when you use GNU CC. You must specify all three + options explicitly. + + * On a Sparc, GNU CC aligns all values of type `double' on an 8-byte + boundary, and it expects every `double' to be so aligned. The Sun + compiler usually gives `double' values 8-byte alignment, with one + exception: function arguments of type `double' may not be aligned. + + As a result, if a function compiled with Sun CC takes the address + of an argument of type `double' and passes this pointer of type + `double *' to a function compiled with GNU CC, dereferencing the + pointer may cause a fatal signal. + + One way to solve this problem is to compile your entire program + with GNU CC. Another solution is to modify the function that is + compiled with Sun CC to copy the argument into a local variable; + local variables are always properly aligned. A third solution is + to modify the function that uses the pointer to dereference it via + the following function `access_double' instead of directly with + `*': + + inline double + access_double (double *unaligned_ptr) + { + union d2i { double d; int i[2]; }; + + union d2i *p = (union d2i *) unaligned_ptr; + union d2i u; + + u.i[0] = p->i[0]; + u.i[1] = p->i[1]; + + return u.d; + } + + Storing into the pointer can be done likewise with the same union. + + * On Solaris, the `malloc' function in the `libmalloc.a' library may + allocate memory that is only 4 byte aligned. Since GNU CC on the + Sparc assumes that doubles are 8 byte aligned, this may result in a + fatal signal if doubles are stored in memory allocated by the + `libmalloc.a' library. + + The solution is to not use the `libmalloc.a' library. Use instead + `malloc' and related functions from `libc.a'; they do not have + this problem. + + * Sun forgot to include a static version of `libdl.a' with some + versions of SunOS (mainly 4.1). This results in undefined symbols + when linking static binaries (that is, if you use `-static'). If + you see undefined symbols `_dlclose', `_dlsym' or `_dlopen' when + linking, compile and link against the file `mit/util/misc/dlsym.c' + from the MIT version of X windows. + + * The 128-bit long double format that the Sparc port supports + currently works by using the architecturally defined quad-word + floating point instructions. Since there is no hardware that + supports these instructions they must be emulated by the operating + system. Long doubles do not work in Sun OS versions 4.0.3 and + earlier, because the kernel emulator uses an obsolete and + incompatible format. Long doubles do not work in Sun OS version + 4.1.1 due to a problem in a Sun library. Long doubles do work on + Sun OS versions 4.1.2 and higher, but GNU CC does not enable them + by default. Long doubles appear to work in Sun OS 5.x (Solaris + 2.x). + + * On HP-UX version 9.01 on the HP PA, the HP compiler `cc' does not + compile GNU CC correctly. We do not yet know why. However, GNU CC + compiled on earlier HP-UX versions works properly on HP-UX 9.01 + and can compile itself properly on 9.01. + + * On the HP PA machine, ADB sometimes fails to work on functions + compiled with GNU CC. Specifically, it fails to work on functions + that use `alloca' or variable-size arrays. This is because GNU CC + doesn't generate HP-UX unwind descriptors for such functions. It + may even be impossible to generate them. + + * Debugging (`-g') is not supported on the HP PA machine, unless you + use the preliminary GNU tools (*note Installation::.). + + * Taking the address of a label may generate errors from the HP-UX + PA assembler. GAS for the PA does not have this problem. + + * Using floating point parameters for indirect calls to static + functions will not work when using the HP assembler. There simply + is no way for GCC to specify what registers hold arguments for + static functions when using the HP assembler. GAS for the PA does + not have this problem. + + * In extremely rare cases involving some very large functions you may + receive errors from the HP linker complaining about an out of + bounds unconditional branch offset. This used to occur more often + in previous versions of GNU CC, but is now exceptionally rare. If + you should run into it, you can work around by making your + function smaller. + + * GNU CC compiled code sometimes emits warnings from the HP-UX + assembler of the form: + + (warning) Use of GR3 when + frame >= 8192 may cause conflict. + + These warnings are harmless and can be safely ignored. + + * The current version of the assembler (`/bin/as') for the RS/6000 + has certain problems that prevent the `-g' option in GCC from + working. Note that `Makefile.in' uses `-g' by default when + compiling `libgcc2.c'. + + IBM has produced a fixed version of the assembler. The upgraded + assembler unfortunately was not included in any of the AIX 3.2 + update PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 + should request PTF U403044 from IBM and users of AIX 3.2 should + request PTF U416277. See the file `README.RS6000' for more + details on these updates. + + You can test for the presense of a fixed assembler by using the + command + + as -u < /dev/null + + If the command exits normally, the assembler fix already is + installed. If the assembler complains that "-u" is an unknown + flag, you need to order the fix. + + * On the IBM RS/6000, compiling code of the form + + extern int foo; + + ... foo ... + + static int foo; + + will cause the linker to report an undefined symbol `foo'. + Although this behavior differs from most other systems, it is not a + bug because redefining an `extern' variable as `static' is + undefined in ANSI C. + + * AIX on the RS/6000 provides support (NLS) for environments outside + of the United States. Compilers and assemblers use NLS to support + locale-specific representations of various objects including + floating-point numbers ("." vs "," for separating decimal + fractions). There have been problems reported where the library + linked with GCC does not produce the same floating-point formats + that the assembler accepts. If you have this problem, set the + LANG environment variable to "C" or "En_US". + + * Even if you specify `-fdollars-in-identifiers', you cannot + successfully use `$' in identifiers on the RS/6000 due to a + restriction in the IBM assembler. GAS supports these identifiers. + + * On the RS/6000, XLC version 1.3.0.0 will miscompile `jump.c'. XLC + version 1.3.0.1 or later fixes this problem. You can obtain + XLC-1.3.0.2 by requesting PTF 421749 from IBM. + + * There is an assembler bug in versions of DG/UX prior to 5.4.2.01 + that occurs when the `fldcr' instruction is used. GNU CC uses + `fldcr' on the 88100 to serialize volatile memory references. Use + the option `-mno-serialize-volatile' if your version of the + assembler has this bug. + + * On VMS, GAS versions 1.38.1 and earlier may cause spurious warning + messages from the linker. These warning messages complain of + mismatched psect attributes. You can ignore them. *Note VMS + Install::. + + * On NewsOS version 3, if you include both of the files `stddef.h' + and `sys/types.h', you get an error because there are two typedefs + of `size_t'. You should change `sys/types.h' by adding these + lines around the definition of `size_t': + + #ifndef _SIZE_T + #define _SIZE_T + ACTUAL TYPEDEF HERE + #endif + + * On the Alliant, the system's own convention for returning + structures and unions is unusual, and is not compatible with GNU + CC no matter what options are used. + + * On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different + convention for structure and union returning. Use the option + `-mhc-struct-return' to tell GNU CC to use a convention compatible + with it. + + * On Ultrix, the Fortran compiler expects registers 2 through 5 to + be saved by function calls. However, the C compiler uses + conventions compatible with BSD Unix: registers 2 through 5 may be + clobbered by function calls. + + GNU CC uses the same convention as the Ultrix C compiler. You can + use these options to produce code compatible with the Fortran + compiler: + + -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5 + + * On the WE32k, you may find that programs compiled with GNU CC do + not work with the standard shared C library. You may need to link + with the ordinary C compiler. If you do so, you must specify the + following options: + + -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.7.1 -lgcc -lc_s + + The first specifies where to find the library `libgcc.a' specified + with the `-lgcc' option. + + GNU CC does linking by invoking `ld', just as `cc' does, and there + is no reason why it *should* matter which compilation program you + use to invoke `ld'. If someone tracks this problem down, it can + probably be fixed easily. + + * On the Alpha, you may get assembler errors about invalid syntax as + a result of floating point constants. This is due to a bug in the + C library functions `ecvt', `fcvt' and `gcvt'. Given valid + floating point numbers, they sometimes print `NaN'. + + * On Irix 4.0.5F (and perhaps in some other versions), an assembler + bug sometimes reorders instructions incorrectly when optimization + is turned on. If you think this may be happening to you, try + using the GNU assembler; GAS version 2.1 supports ECOFF on Irix. + + Or use the `-noasmopt' option when you compile GNU CC with itself, + and then again when you compile your program. (This is a temporary + kludge to turn off assembler optimization on Irix.) If this + proves to be what you need, edit the assembler spec in the file + `specs' so that it unconditionally passes `-O0' to the assembler, + and never passes `-O2' or `-O3'.  -File: gcc.info, Node: Include Files and VMS, Next: Global Declarations, Up: VMS +File: gcc.info, Node: External Bugs, Next: Incompatibilities, Prev: Interoperation, Up: Trouble -Include Files and VMS -===================== +Problems Compiling Certain Programs +=================================== + + Certain programs have problems compiling. + + * Parse errors may occur compiling X11 on a Decstation running + Ultrix 4.2 because of problems in DEC's versions of the X11 header + files `X11/Xlib.h' and `X11/Xutil.h'. People recommend adding + `-I/usr/include/mit' to use the MIT versions of the header files, + using the `-traditional' switch to turn off ANSI C, or fixing the + header files by adding this: + + #ifdef __STDC__ + #define NeedFunctionPrototypes 0 + #endif + + * If you have trouble compiling Perl on a SunOS 4 system, it may be + because Perl specifies `-I/usr/ucbinclude'. This accesses the + unfixed header files. Perl specifies the options + + -traditional -Dvolatile=__volatile__ + -I/usr/include/sun -I/usr/ucbinclude + -fpcc-struct-return + + most of which are unnecessary with GCC 2.4.5 and newer versions. + You can make a properly working Perl by setting `ccflags' to + `-fwritable-strings' (implied by the `-traditional' in the + original options) and `cppflags' to empty in `config.sh', then + typing `./doSH; make depend; make'. - Due to the differences between the filesystems of Unix and VMS, GNU -CC attempts to translate file names in `#include' into names that VMS -will understand. The basic strategy is to prepend a prefix to the -specification of the include file, convert the whole filename to a VMS -filename, and then try to open the file. GNU CC tries various prefixes -one by one until one of them succeeds: - - 1. The first prefix is the `GNU_CC_INCLUDE:' logical name: this is - where GNU C header files are traditionally stored. If you wish to - store header files in non-standard locations, then you can assign - the logical `GNU_CC_INCLUDE' to be a search list, where each - element of the list is suitable for use with a rooted logical. - - 2. The next prefix tried is `SYS$SYSROOT:[SYSLIB.]'. This is where - VAX-C header files are traditionally stored. - - 3. If the include file specification by itself is a valid VMS - filename, the preprocessor then uses this name with no prefix in - an attempt to open the include file. - - 4. If the file specification is not a valid VMS filename (i.e. does - not contain a device or a directory specifier, and contains a `/' - character), the preprocessor tries to convert it from Unix syntax - to VMS syntax. - - Conversion works like this: the first directory name becomes a - device, and the rest of the directories are converted into - VMS-format directory names. For example, the name `X11/foobar.h' - is translated to `X11:[000000]foobar.h' or `X11:foobar.h', - whichever one can be opened. This strategy allows you to assign a - logical name to point to the actual location of the header files. - - 5. If none of these strategies succeeds, the `#include' fails. - - Include directives of the form: - - #include foobar - -are a common source of incompatibility between VAX-C and GNU CC. VAX-C -treats this much like a standard `#include ' directive. That -is incompatible with the ANSI C behavior implemented by GNU CC: to -expand the name `foobar' as a macro. Macro expansion should eventually -yield one of the two standard formats for `#include': - - #include "FILE" - #include - - If you have this problem, the best solution is to modify the source -to convert the `#include' directives to one of the two standard forms. -That will work with either compiler. If you want a quick and dirty fix, -define the file names as macros with the proper expansion, like this: - - #define stdio - -This will work, as long as the name doesn't conflict with anything else -in the program. - - Another source of incompatibility is that VAX-C assumes that: - - #include "foobar" - -is actually asking for the file `foobar.h'. GNU CC does not make this -assumption, and instead takes what you ask for literally; it tries to -read the file `foobar'. The best way to avoid this problem is to -always specify the desired file extension in your include directives. - - GNU CC for VMS is distributed with a set of include files that is -sufficient to compile most general purpose programs. Even though the -GNU CC distribution does not contain header files to define constants -and structures for some VMS system-specific functions, there is no -reason why you cannot use GNU CC with any of these functions. You first -may have to generate or create header files, either by using the public -domain utility `UNSDL' (which can be found on a DECUS tape), or by -extracting the relevant modules from one of the system macro libraries, -and using an editor to construct a C header file. - - A `#include' file name cannot contain a DECNET node name. The -preprocessor reports an I/O error if you attempt to use a node name, -whether explicitly, or implicitly via a logical name. + * On various 386 Unix systems derived from System V, including SCO, + ISC, and ESIX, you may get error messages about running out of + virtual memory while compiling certain programs. + + You can prevent this problem by linking GNU CC with the GNU malloc + (which thus replaces the malloc that comes with the system). GNU + malloc is available as a separate package, and also in the file + `src/gmalloc.c' in the GNU Emacs 19 distribution. + + If you have installed GNU malloc as a separate library package, + use this option when you relink GNU CC: + + MALLOC=/usr/local/lib/libgmalloc.a + + Alternatively, if you have compiled `gmalloc.c' from Emacs 19, copy + the object file to `gmalloc.o' and use this option when you relink + GNU CC: + + MALLOC=gmalloc.o  -File: gcc.info, Node: Global Declarations, Next: VMS Misc, Prev: Include Files and VMS, Up: VMS +File: gcc.info, Node: Incompatibilities, Next: Fixed Headers, Prev: External Bugs, Up: Trouble -Global Declarations and VMS +Incompatibilities of GNU CC =========================== - GNU CC does not provide the `globalref', `globaldef' and -`globalvalue' keywords of VAX-C. You can get the same effect with an -obscure feature of GAS, the GNU assembler. (This requires GAS version -1.39 or later.) The following macros allow you to use this feature in -a fairly natural way: - - #ifdef __GNUC__ - #define GLOBALREF(TYPE,NAME) \ - TYPE NAME \ - asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) - #define GLOBALDEF(TYPE,NAME,VALUE) \ - TYPE NAME \ - asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ - = VALUE - #define GLOBALVALUEREF(TYPE,NAME) \ - const TYPE NAME[1] \ - asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) - #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ - const TYPE NAME[1] \ - asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ - = {VALUE} - #else - #define GLOBALREF(TYPE,NAME) \ - globalref TYPE NAME - #define GLOBALDEF(TYPE,NAME,VALUE) \ - globaldef TYPE NAME = VALUE - #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ - globalvalue TYPE NAME = VALUE - #define GLOBALVALUEREF(TYPE,NAME) \ - globalvalue TYPE NAME - #endif - -(The `_$$PsectAttributes_GLOBALSYMBOL' prefix at the start of the name -is removed by the assembler, after it has modified the attributes of -the symbol). These macros are provided in the VMS binaries -distribution in a header file `GNU_HACKS.H'. An example of the usage -is: - - GLOBALREF (int, ijk); - GLOBALDEF (int, jkl, 0); - - The macros `GLOBALREF' and `GLOBALDEF' cannot be used -straightforwardly for arrays, since there is no way to insert the array -dimension into the declaration at the right place. However, you can -declare an array with these macros if you first define a typedef for the -array type, like this: - - typedef int intvector[10]; - GLOBALREF (intvector, foo); - - Array and structure initializers will also break the macros; you can -define the initializer to be a macro of its own, or you can expand the -`GLOBALDEF' macro by hand. You may find a case where you wish to use -the `GLOBALDEF' macro with a large array, but you are not interested in -explicitly initializing each element of the array. In such cases you -can use an initializer like: `{0,}', which will initialize the entire -array to `0'. - - A shortcoming of this implementation is that a variable declared with -`GLOBALVALUEREF' or `GLOBALVALUEDEF' is always an array. For example, -the declaration: - - GLOBALVALUEREF(int, ijk); - -declares the variable `ijk' as an array of type `int [1]'. This is -done because a globalvalue is actually a constant; its "value" is what -the linker would normally consider an address. That is not how an -integer value works in C, but it is how an array works. So treating -the symbol as an array name gives consistent results--with the -exception that the value seems to have the wrong type. *Don't try to -access an element of the array.* It doesn't have any elements. The -array "address" may not be the address of actual storage. - - The fact that the symbol is an array may lead to warnings where the -variable is used. Insert type casts to avoid the warnings. Here is an -example; it takes advantage of the ANSI C feature allowing macros that -expand to use the same name as the macro itself. - - GLOBALVALUEREF (int, ss$_normal); - GLOBALVALUEDEF (int, xyzzy,123); - #ifdef __GNUC__ - #define ss$_normal ((int) ss$_normal) - #define xyzzy ((int) xyzzy) - #endif - - Don't use `globaldef' or `globalref' with a variable whose type is -an enumeration type; this is not implemented. Instead, make the -variable an integer, and use a `globalvaluedef' for each of the -enumeration values. An example of this would be: - - #ifdef __GNUC__ - GLOBALDEF (int, color, 0); - GLOBALVALUEDEF (int, RED, 0); - GLOBALVALUEDEF (int, BLUE, 1); - GLOBALVALUEDEF (int, GREEN, 3); - #else - enum globaldef color {RED, BLUE, GREEN = 3}; - #endif + There are several noteworthy incompatibilities between GNU C and most +existing (non-ANSI) versions of C. The `-traditional' option +eliminates many of these incompatibilities, *but not all*, by telling +GNU C to behave like the other C compilers. + + * GNU CC normally makes string constants read-only. If several + identical-looking string constants are used, GNU CC stores only one + copy of the string. + + One consequence is that you cannot call `mktemp' with a string + constant argument. The function `mktemp' always alters the string + its argument points to. + + Another consequence is that `sscanf' does not work on some systems + when passed a string constant as its format control string or + input. This is because `sscanf' incorrectly tries to write into + the string constant. Likewise `fscanf' and `scanf'. + + The best solution to these problems is to change the program to use + `char'-array variables with initialization strings for these + purposes instead of string constants. But if this is not possible, + you can use the `-fwritable-strings' flag, which directs GNU CC to + handle string constants the same way most C compilers do. + `-traditional' also has this effect, among others. + + * `-2147483648' is positive. + + This is because 2147483648 cannot fit in the type `int', so + (following the ANSI C rules) its data type is `unsigned long int'. + Negating this value yields 2147483648 again. + + * GNU CC does not substitute macro arguments when they appear inside + of string constants. For example, the following macro in GNU CC + + #define foo(a) "a" + + will produce output `"a"' regardless of what the argument A is. + + The `-traditional' option directs GNU CC to handle such cases + (among others) in the old-fashioned (non-ANSI) fashion. + + * When you use `setjmp' and `longjmp', the only automatic variables + guaranteed to remain valid are those declared `volatile'. This is + a consequence of automatic register allocation. Consider this + function: + + jmp_buf j; + + foo () + { + int a, b; + + a = fun1 (); + if (setjmp (j)) + return a; + + a = fun2 (); + /* `longjmp (j)' may occur in `fun3'. */ + return a + fun3 (); + } + + Here `a' may or may not be restored to its first value when the + `longjmp' occurs. If `a' is allocated in a register, then its + first value is restored; otherwise, it keeps the last value stored + in it. + + If you use the `-W' option with the `-O' option, you will get a + warning when GNU CC thinks such a problem might be possible. + + The `-traditional' option directs GNU C to put variables in the + stack by default, rather than in registers, in functions that call + `setjmp'. This results in the behavior found in traditional C + compilers. + + * Programs that use preprocessing directives in the middle of macro + arguments do not work with GNU CC. For example, a program like + this will not work: + + foobar ( + #define luser + hack) + + ANSI C does not permit such a construct. It would make sense to + support it when `-traditional' is used, but it is too much work to + implement. + + * Declarations of external variables and functions within a block + apply only to the block containing the declaration. In other + words, they have the same scope as any other declaration in the + same place. + + In some other C compilers, a `extern' declaration affects all the + rest of the file even if it happens within a block. + + The `-traditional' option directs GNU C to treat all `extern' + declarations as global, like traditional compilers. + + * In traditional C, you can combine `long', etc., with a typedef + name, as shown here: + + typedef int foo; + typedef long foo bar; + + In ANSI C, this is not allowed: `long' and other type modifiers + require an explicit `int'. Because this criterion is expressed by + Bison grammar rules rather than C code, the `-traditional' flag + cannot alter it. + + * PCC allows typedef names to be used as function parameters. The + difficulty described immediately above applies here too. + + * PCC allows whitespace in the middle of compound assignment + operators such as `+='. GNU CC, following the ANSI standard, does + not allow this. The difficulty described immediately above + applies here too. + + * GNU CC complains about unterminated character constants inside of + preprocessing conditionals that fail. Some programs have English + comments enclosed in conditionals that are guaranteed to fail; if + these comments contain apostrophes, GNU CC will probably report an + error. For example, this code would produce an error: + + #if 0 + You can't expect this to work. + #endif + + The best solution to such a problem is to put the text into an + actual C comment delimited by `/*...*/'. However, `-traditional' + suppresses these error messages. + + * Many user programs contain the declaration `long time ();'. In the + past, the system header files on many systems did not actually + declare `time', so it did not matter what type your program + declared it to return. But in systems with ANSI C headers, `time' + is declared to return `time_t', and if that is not the same as + `long', then `long time ();' is erroneous. + + The solution is to change your program to use `time_t' as the + return type of `time'. + + * When compiling functions that return `float', PCC converts it to a + double. GNU CC actually returns a `float'. If you are concerned + with PCC compatibility, you should declare your functions to return + `double'; you might as well say what you mean. + + * When compiling functions that return structures or unions, GNU CC + output code normally uses a method different from that used on most + versions of Unix. As a result, code compiled with GNU CC cannot + call a structure-returning function compiled with PCC, and vice + versa. + + The method used by GNU CC is as follows: a structure or union + which is 1, 2, 4 or 8 bytes long is returned like a scalar. A + structure or union with any other size is stored into an address + supplied by the caller (usually in a special, fixed register, but + on some machines it is passed on the stack). The + machine-description macros `STRUCT_VALUE' and + `STRUCT_INCOMING_VALUE' tell GNU CC where to pass this address. + + By contrast, PCC on most target machines returns structures and + unions of any size by copying the data into an area of static + storage, and then returning the address of that storage as if it + were a pointer value. The caller must copy the data from that + memory area to the place where the value is wanted. GNU CC does + not use this method because it is slower and nonreentrant. + + On some newer machines, PCC uses a reentrant convention for all + structure and union returning. GNU CC on most of these machines + uses a compatible convention when returning structures and unions + in memory, but still returns small structures and unions in + registers. + + You can tell GNU CC to use a compatible convention for all + structure and union returning with the option + `-fpcc-struct-return'. + + * GNU C complains about program fragments such as `0x74ae-0x4000' + which appear to be two hexadecimal constants separated by the minus + operator. Actually, this string is a single "preprocessing token". + Each such token must correspond to one token in C. Since this + does not, GNU C prints an error message. Although it may appear + obvious that what is meant is an operator and two values, the ANSI + C standard specifically requires that this be treated as erroneous. + + A "preprocessing token" is a "preprocessing number" if it begins + with a digit and is followed by letters, underscores, digits, + periods and `e+', `e-', `E+', or `E-' character sequences. + + To make the above program fragment valid, place whitespace in + front of the minus sign. This whitespace will end the + preprocessing number.  -File: gcc.info, Node: VMS Misc, Prev: Global Declarations, Up: VMS +File: gcc.info, Node: Fixed Headers, Next: Standard Libraries, Prev: Incompatibilities, Up: Trouble -Other VMS Issues -================ +Fixed Header Files +================== - GNU CC automatically arranges for `main' to return 1 by default if -you fail to specify an explicit return value. This will be interpreted -by VMS as a status code indicating a normal successful completion. -Version 1 of GNU CC did not provide this default. - - GNU CC on VMS works only with the GNU assembler, GAS. You need -version 1.37 or later of GAS in order to produce value debugging -information for the VMS debugger. Use the ordinary VMS linker with the -object files produced by GAS. - - Under previous versions of GNU CC, the generated code would -occasionally give strange results when linked to the sharable `VAXCRTL' -library. Now this should work. - - A caveat for use of `const' global variables: the `const' modifier -must be specified in every external declaration of the variable in all -of the source files that use that variable. Otherwise the linker will -issue warnings about conflicting attributes for the variable. Your -program will still work despite the warnings, but the variable will be -placed in writable storage. - - Although the VMS linker does distinguish between upper and lower case -letters in global symbols, most VMS compilers convert all such symbols -into upper case and most run-time library routines also have upper case -names. To be able to reliably call such routines, GNU CC (by means of -the assembler GAS) converts global symbols into upper case like other -VMS compilers. However, since the usual practice in C is to distinguish -case, GNU CC (via GAS) tries to preserve usual C behavior by augmenting -each name that is not all lower case. This means truncating the name -to at most 23 characters and then adding more characters at the end -which encode the case pattern of those 23. Names which contain at -least one dollar sign are an exception; they are converted directly into -upper case without augmentation. - - Name augmentation yields bad results for programs that use -precompiled libraries (such as Xlib) which were generated by another -compiler. You can use the compiler option `/NOCASE_HACK' to inhibit -augmentation; it makes external C functions and variables -case-independent as is usual on VMS. Alternatively, you could write -all references to the functions and variables in such libraries using -lower case; this will work on VMS, but is not portable to other -systems. The compiler option `/NAMES' also provides control over -global name handling. - - Function and variable names are handled somewhat differently with GNU -C++. The GNU C++ compiler performs "name mangling" on function names, -which means that it adds information to the function name to describe -the data types of the arguments that the function takes. One result of -this is that the name of a function can become very long. Since the -VMS linker only recognizes the first 31 characters in a name, special -action is taken to ensure that each function and variable has a unique -name that can be represented in 31 characters. - - If the name (plus a name augmentation, if required) is less than 32 -characters in length, then no special action is performed. If the name -is longer than 31 characters, the assembler (GAS) will generate a hash -string based upon the function name, truncate the function name to 23 -characters, and append the hash string to the truncated name. If the -`/VERBOSE' compiler option is used, the assembler will print both the -full and truncated names of each symbol that is truncated. - - The `/NOCASE_HACK' compiler option should not be used when you are -compiling programs that use libg++. libg++ has several instances of -objects (i.e. `Filebuf' and `filebuf') which become indistinguishable -in a case-insensitive environment. This leads to cases where you need -to inhibit augmentation selectively (if you were using libg++ and Xlib -in the same program, for example). There is no special feature for -doing this, but you can get the result by defining a macro for each -mixed case symbol for which you wish to inhibit augmentation. The -macro should expand into the lower case equivalent of itself. For -example: + GNU CC needs to install corrected versions of some system header +files. This is because most target systems have some header files that +won't work with GNU CC unless they are changed. Some have bugs, some +are incompatible with ANSI C, and some depend on special features of +other compilers. + + Installing GNU CC automatically creates and installs the fixed header +files, by running a program called `fixincludes' (or for certain +targets an alternative such as `fixinc.svr4'). Normally, you don't +need to pay attention to this. But there are cases where it doesn't do +the right thing automatically. + + * If you update the system's header files, such as by installing a + new system version, the fixed header files of GNU CC are not + automatically updated. The easiest way to update them is to + reinstall GNU CC. (If you want to be clever, look in the makefile + and you can find a shortcut.) + + * On some systems, in particular SunOS 4, header file directories + contain machine-specific symbolic links in certain places. This + makes it possible to share most of the header files among hosts + running the same version of SunOS 4 on different machine models. + + The programs that fix the header files do not understand this + special way of using symbolic links; therefore, the directory of + fixed header files is good only for the machine model used to + build it. + + In SunOS 4, only programs that look inside the kernel will notice + the difference between machine models. Therefore, for most + purposes, you need not be concerned about this. + + It is possible to make separate sets of fixed header files for the + different machine models, and arrange a structure of symbolic + links so as to use the proper set, but you'll have to do this by + hand. + + * On Lynxos, GNU CC by default does not fix the header files. This + is because bugs in the shell cause the `fixincludes' script to + fail. + + This means you will encounter problems due to bugs in the system + header files. It may be no comfort that they aren't GNU CC's + fault, but it does mean that there's nothing for us to do about + them. - #define StuDlyCapS studlycaps + +File: gcc.info, Node: Standard Libraries, Next: Disappointments, Prev: Fixed Headers, Up: Trouble + +Standard Libraries +================== + + GNU CC by itself attempts to be what the ISO/ANSI C standard calls a +"conforming freestanding implementation". This means all ANSI C +language features are available, as well as the contents of `float.h', +`limits.h', `stdarg.h', and `stddef.h'. The rest of the C library is +supplied by the vendor of the operating system. If that C library +doesn't conform to the C standards, then your programs might get +warnings (especially when using `-Wall') that you don't expect. + + For example, the `sprintf' function on SunOS 4.1.3 returns `char *' +while the C standard says that `sprintf' returns an `int'. The +`fixincludes' program could make the prototype for this function match +the Standard, but that would be wrong, since the function will still +return `char *'. + + If you need a Standard compliant library, then you need to find one, +as GNU CC does not provide one. The GNU C library (called `glibc') has +been ported to a number of operating systems, and provides ANSI/ISO, +POSIX, BSD and SystemV compatibility. You could also ask your operating +system vendor if newer libraries are available. + + +File: gcc.info, Node: Disappointments, Next: C++ Misunderstandings, Prev: Standard Libraries, Up: Trouble - These macro definitions can be placed in a header file to minimize -the number of changes to your source code. +Disappointments and Misunderstandings +===================================== + + These problems are perhaps regrettable, but we don't know any +practical way around them. + + * Certain local variables aren't recognized by debuggers when you + compile with optimization. + + This occurs because sometimes GNU CC optimizes the variable out of + existence. There is no way to tell the debugger how to compute the + value such a variable "would have had", and it is not clear that + would be desirable anyway. So GNU CC simply does not mention the + eliminated variable when it writes debugging information. + + You have to expect a certain amount of disagreement between the + executable and your source code, when you use optimization. + + * Users often think it is a bug when GNU CC reports an error for code + like this: + + int foo (struct mumble *); + + struct mumble { ... }; + + int foo (struct mumble *x) + { ... } + + This code really is erroneous, because the scope of `struct + mumble' in the prototype is limited to the argument list + containing it. It does not refer to the `struct mumble' defined + with file scope immediately below--they are two unrelated types + with similar names in different scopes. + + But in the definition of `foo', the file-scope type is used + because that is available to be inherited. Thus, the definition + and the prototype do not match, and you get an error. + + This behavior may seem silly, but it's what the ANSI standard + specifies. It is easy enough for you to make your code work by + moving the definition of `struct mumble' above the prototype. + It's not worth being incompatible with ANSI C just to avoid an + error for the example shown above. + + * Accesses to bitfields even in volatile objects works by accessing + larger objects, such as a byte or a word. You cannot rely on what + size of object is accessed in order to read or write the bitfield; + it may even vary for a given bitfield according to the precise + usage. + + If you care about controlling the amount of memory that is + accessed, use volatile but do not use bitfields. + + * GNU CC comes with shell scripts to fix certain known problems in + system header files. They install corrected copies of various + header files in a special directory where only GNU CC will + normally look for them. The scripts adapt to various systems by + searching all the system header files for the problem cases that + we know about. + + If new system header files are installed, nothing automatically + arranges to update the corrected header files. You will have to + reinstall GNU CC to fix the new header files. More specifically, + go to the build directory and delete the files `stmp-fixinc' and + `stmp-headers', and the subdirectory `include'; then do `make + install' again. + + * On 68000 systems, you can get paradoxical results if you test the + precise values of floating point numbers. For example, you can + find that a floating point value which is not a NaN is not equal + to itself. This results from the fact that the the floating point + registers hold a few more bits of precision than fit in a `double' + in memory. Compiled code moves values between memory and floating + point registers at its convenience, and moving them into memory + truncates them. + + You can partially avoid this problem by using the `-ffloat-store' + option (*note Optimize Options::.). + + * On the MIPS, variable argument functions using `varargs.h' cannot + have a floating point value for the first argument. The reason + for this is that in the absence of a prototype in scope, if the + first argument is a floating point, it is passed in a floating + point register, rather than an integer register. + + If the code is rewritten to use the ANSI standard `stdarg.h' + method of variable arguments, and the prototype is in scope at the + time of the call, everything will work fine.  -File: gcc.info, Node: Portability, Next: Interface, Prev: VMS, Up: Top +File: gcc.info, Node: C++ Misunderstandings, Next: Protoize Caveats, Prev: Disappointments, Up: Trouble + +Common Misunderstandings with GNU C++ +===================================== -GNU CC and Portability -********************** + C++ is a complex language and an evolving one, and its standard +definition (the ANSI C++ draft standard) is also evolving. As a result, +your C++ compiler may occasionally surprise you, even when its behavior +is correct. This section discusses some areas that frequently give +rise to questions of this sort. - The main goal of GNU CC was to make a good, fast compiler for -machines in the class that the GNU system aims to run on: 32-bit -machines that address 8-bit bytes and have several general registers. -Elegance, theoretical power and simplicity are only secondary. - - GNU CC gets most of the information about the target machine from a -machine description which gives an algebraic formula for each of the -machine's instructions. This is a very clean way to describe the -target. But when the compiler needs information that is difficult to -express in this fashion, I have not hesitated to define an ad-hoc -parameter to the machine description. The purpose of portability is to -reduce the total work needed on the compiler; it was not of interest -for its own sake. - - GNU CC does not contain machine dependent code, but it does contain -code that depends on machine parameters such as endianness (whether the -most significant byte has the highest or lowest address of the bytes in -a word) and the availability of autoincrement addressing. In the -RTL-generation pass, it is often necessary to have multiple strategies -for generating code for a particular kind of syntax tree, strategies -that are usable for different combinations of parameters. Often I have -not tried to address all possible cases, but only the common ones or -only the ones that I have encountered. As a result, a new target may -require additional strategies. You will know if this happens because -the compiler will call `abort'. Fortunately, the new strategies can be -added in a machine-independent fashion, and will affect only the target -machines that need them. +* Menu: + +* Static Definitions:: Static member declarations are not definitions +* Temporaries:: Temporaries may vanish before you expect  -File: gcc.info, Node: Interface, Next: Passes, Prev: Portability, Up: Top +File: gcc.info, Node: Static Definitions, Next: Temporaries, Up: C++ Misunderstandings -Interfacing to GNU CC Output -**************************** +Declare *and* Define Static Members +----------------------------------- - GNU CC is normally configured to use the same function calling -convention normally in use on the target system. This is done with the -machine-description macros described (*note Target Macros::.). - - However, returning of structure and union values is done differently -on some target machines. As a result, functions compiled with PCC -returning such types cannot be called from code compiled with GNU CC, -and vice versa. This does not cause trouble often because few Unix -library routines return structures or unions. - - GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes -long in the same registers used for `int' or `double' return values. -(GNU CC typically allocates variables of such types in registers also.) -Structures and unions of other sizes are returned by storing them into -an address passed by the caller (usually in a register). The -machine-description macros `STRUCT_VALUE' and `STRUCT_INCOMING_VALUE' -tell GNU CC where to pass this address. - - By contrast, PCC on most target machines returns structures and -unions of any size by copying the data into an area of static storage, -and then returning the address of that storage as if it were a pointer -value. The caller must copy the data from that memory area to the -place where the value is wanted. This is slower than the method used -by GNU CC, and fails to be reentrant. - - On some target machines, such as RISC machines and the 80386, the -standard system convention is to pass to the subroutine the address of -where to return the value. On these machines, GNU CC has been -configured to be compatible with the standard compiler, when this method -is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes. - - GNU CC uses the system's standard convention for passing arguments. -On some machines, the first few arguments are passed in registers; in -others, all are passed on the stack. It would be possible to use -registers for argument passing on any machine, and this would probably -result in a significant speedup. But the result would be complete -incompatibility with code that follows the standard convention. So this -change is practical only if you are switching to GNU CC as the sole C -compiler for the system. We may implement register argument passing on -certain machines once we have a complete GNU system so that we can -compile the libraries with GNU CC. - - On some machines (particularly the Sparc), certain types of arguments -are passed "by invisible reference". This means that the value is -stored in memory, and the address of the memory location is passed to -the subroutine. - - If you use `longjmp', beware of automatic variables. ANSI C says -that automatic variables that are not declared `volatile' have undefined -values after a `longjmp'. And this is all GNU CC promises to do, -because it is very difficult to restore register variables correctly, -and one of GNU CC's features is that it can put variables in registers -without your asking it to. - - If you want a variable to be unaltered by `longjmp', and you don't -want to write `volatile' because old C compilers don't accept it, just -take the address of the variable. If a variable's address is ever -taken, even if just to compute it and ignore it, then the variable -cannot go in a register: + When a class has static data members, it is not enough to *declare* +the static member; you must also *define* it. For example: + class Foo { - int careful; - &careful; ... - } - - Code compiled with GNU CC may call certain library routines. Most of -them handle arithmetic for which there are no instructions. This -includes multiply and divide on some machines, and floating point -operations on any machine for which floating point support is disabled -with `-msoft-float'. Some standard parts of the C library, such as -`bcopy' or `memcpy', are also called automatically. The usual function -call interface is used for calling the library routines. - - These library routines should be defined in the library `libgcc.a', -which GNU CC automatically searches whenever it links a program. On -machines that have multiply and divide instructions, if hardware -floating point is in use, normally `libgcc.a' is not needed, but it is -searched just in case. - - Each arithmetic function is defined in `libgcc1.c' to use the -corresponding C arithmetic operator. As long as the file is compiled -with another C compiler, which supports all the C arithmetic operators, -this file will work portably. However, `libgcc1.c' does not work if -compiled with GNU CC, because each arithmetic function would compile -into a call to itself! + void method(); + static int bar; + }; + + This declaration only establishes that the class `Foo' has an `int' +named `Foo::bar', and a member function named `Foo::method'. But you +still need to define *both* `method' and `bar' elsewhere. According to +the draft ANSI standard, you must supply an initializer in one (and +only one) source file, such as: + + int Foo::bar = 0; + + Other C++ compilers may not correctly implement the standard +behavior. As a result, when you switch to `g++' from one of these +compilers, you may discover that a program that appeared to work +correctly in fact does not conform to the standard: `g++' reports as +undefined symbols any static data members that lack definitions.