From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001
From: upstream source tree <ports@midipix.org>
Date: Sun, 15 Mar 2015 20:14:05 -0400
Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified
gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream
tarball.
downloading a git-generated archive based on the 'upstream' tag
should provide you with a source tree that is binary identical
to the one extracted from the above tarball.
if you have obtained the source via the command 'git clone',
however, do note that line-endings of files in your working
directory might differ from line-endings of the respective
files in the upstream repository.
---
gcc/README.Portability | 197 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 197 insertions(+)
create mode 100644 gcc/README.Portability
(limited to 'gcc/README.Portability')
diff --git a/gcc/README.Portability b/gcc/README.Portability
new file mode 100644
index 000000000..32a33e27b
--- /dev/null
+++ b/gcc/README.Portability
@@ -0,0 +1,197 @@
+Copyright (C) 2000, 2003 Free Software Foundation, Inc.
+
+This file is intended to contain a few notes about writing C code
+within GCC so that it compiles without error on the full range of
+compilers GCC needs to be able to compile on.
+
+The problem is that many ISO-standard constructs are not accepted by
+either old or buggy compilers, and we keep getting bitten by them.
+This knowledge until know has been sparsely spread around, so I
+thought I'd collect it in one useful place. Please add and correct
+any problems as you come across them.
+
+I'm going to start from a base of the ISO C90 standard, since that is
+probably what most people code to naturally. Obviously using
+constructs introduced after that is not a good idea.
+
+For the complete coding style conventions used in GCC, please read
+http://gcc.gnu.org/codingconventions.html
+
+
+String literals
+---------------
+
+Irix6 "cc -n32" and OSF4 "cc" have problems with constant string
+initializers with parens around it, e.g.
+
+const char string[] = ("A string");
+
+This is unfortunate since this is what the GNU gettext macro N_
+produces. You need to find a different way to code it.
+
+Some compilers like MSVC++ have fairly low limits on the maximum
+length of a string literal; 509 is the lowest we've come across. You
+may need to break up a long printf statement into many smaller ones.
+
+
+Empty macro arguments
+---------------------
+
+ISO C (6.8.3 in the 1990 standard) specifies the following:
+
+If (before argument substitution) any argument consists of no
+preprocessing tokens, the behavior is undefined.
+
+This was relaxed by ISO C99, but some older compilers emit an error,
+so code like
+
+#define foo(x, y) x y
+foo (bar, )
+
+needs to be coded in some other way.
+
+
+free and realloc
+----------------
+
+Some implementations crash upon attempts to free or realloc the null
+pointer. Thus if mem might be null, you need to write
+
+ if (mem)
+ free (mem);
+
+
+Trigraphs
+---------
+
+You weren't going to use them anyway, but some otherwise ISO C
+compliant compilers do not accept trigraphs.
+
+
+Suffixes on Integer Constants
+-----------------------------
+
+You should never use a 'l' suffix on integer constants ('L' is fine),
+since it can easily be confused with the number '1'.
+
+
+ Common Coding Pitfalls
+ ======================
+
+errno
+-----
+
+errno might be declared as a macro.
+
+
+Implicit int
+------------
+
+In C, the 'int' keyword can often be omitted from type declarations.
+For instance, you can write
+
+ unsigned variable;
+
+as shorthand for
+
+ unsigned int variable;
+
+There are several places where this can cause trouble. First, suppose
+'variable' is a long; then you might think
+
+ (unsigned) variable
+
+would convert it to unsigned long. It does not. It converts to
+unsigned int. This mostly causes problems on 64-bit platforms, where
+long and int are not the same size.
+
+Second, if you write a function definition with no return type at
+all:
+
+ operate (int a, int b)
+ {
+ ...
+ }
+
+that function is expected to return int, *not* void. GCC will warn
+about this.
+
+Implicit function declarations always have return type int. So if you
+correct the above definition to
+
+ void
+ operate (int a, int b)
+ ...
+
+but operate() is called above its definition, you will get an error
+about a "type mismatch with previous implicit declaration". The cure
+is to prototype all functions at the top of the file, or in an
+appropriate header.
+
+Char vs unsigned char vs int
+----------------------------
+
+In C, unqualified 'char' may be either signed or unsigned; it is the
+implementation's choice. When you are processing 7-bit ASCII, it does
+not matter. But when your program must handle arbitrary binary data,
+or fully 8-bit character sets, you have a problem. The most obvious
+issue is if you have a look-up table indexed by characters.
+
+For instance, the character '\341' in ISO Latin 1 is SMALL LETTER A
+WITH ACUTE ACCENT. In the proper locale, isalpha('\341') will be
+true. But if you read '\341' from a file and store it in a plain
+char, isalpha(c) may look up character 225, or it may look up
+character -31. And the ctype table has no entry at offset -31, so
+your program will crash. (If you're lucky.)
+
+It is wise to use unsigned char everywhere you possibly can. This
+avoids all these problems. Unfortunately, the routines in <string.h>
+take plain char arguments, so you have to remember to cast them back
+and forth - or avoid the use of strxxx() functions, which is probably
+a good idea anyway.
+
+Another common mistake is to use either char or unsigned char to
+receive the result of getc() or related stdio functions. They may
+return EOF, which is outside the range of values representable by
+char. If you use char, some legal character value may be confused
+with EOF, such as '\377' (SMALL LETTER Y WITH UMLAUT, in Latin-1).
+The correct choice is int.
+
+A more subtle version of the same mistake might look like this:
+
+ unsigned char pushback[NPUSHBACK];
+ int pbidx;
+ #define unget(c) (assert(pbidx < NPUSHBACK), pushback[pbidx++] = (c))
+ #define get(c) (pbidx ? pushback[--pbidx] : getchar())
+ ...
+ unget(EOF);
+
+which will mysteriously turn a pushed-back EOF into a SMALL LETTER Y
+WITH UMLAUT.
+
+
+Other common pitfalls
+---------------------
+
+o Expecting 'plain' char to be either sign or unsigned extending.
+
+o Shifting an item by a negative amount or by greater than or equal to
+ the number of bits in a type (expecting shifts by 32 to be sensible
+ has caused quite a number of bugs at least in the early days).
+
+o Expecting ints shifted right to be sign extended.
+
+o Modifying the same value twice within one sequence point.
+
+o Host vs. target floating point representation, including emitting NaNs
+ and Infinities in a form that the assembler handles.
+
+o qsort being an unstable sort function (unstable in the sense that
+ multiple items that sort the same may be sorted in different orders
+ by different qsort functions).
+
+o Passing incorrect types to fprintf and friends.
+
+o Adding a function declaration for a module declared in another file to
+ a .c file instead of to a .h file.
+
--
cgit v1.2.3