APPLE LOCAL file documentation This file describes Apple's version of GCC 3.x modified for Darwin / Mac OS X. Although Apple's stated policy is to contribute all of its GCC work to the FSF GCC mainstream, at any given moment there will be changes that are permanently unacceptable for FSF GCC, in need of rework before acceptance, or that we simply aren't ready to send in. This version of GCC contains all those changes. In keeping with provision 2a of the GPL, each Apple change is marked with a comment saying "APPLE LOCAL", followed by optional words "begin", "end", or "file", followed by a short phrase describing the change generally ("AltiVec" for instance, if the change is related to AltiVec support), followed by an optional date in the form yyyy-mm-dd, optionally followed by the initials or email address of the person making the change. The words "begin" and "end" indicate that the comments delimit a multi-line change, while the word "file" indicates that the entire file is an Apple addition. Additional explanatory comments should be in a separate comment. You may also isolate Apple's changes by diffing with the FSF mainline sources as of the date mentioned in gcc/version.c; this date is updated in the FSF repository daily, and is preserved when we import FSF sources into Apple's repository (the tag for the imported source is "fsf-cvs"). The primary purpose of this version of GCC is to be the main system compiler for Darwin and Mac OS X. However, since additions such as PFE precompiled headers and Objective-C++ are of interest on other platforms, we have generally conditionalized Mac-specific code so that the compiler will build and run elsewhere. You may however run into mistakes; please let us know about them and we will fix these if possible. NOTE! It's best to assume that this code has been updated from FSF development sources recently, and has received very little testing before being imported. There is a good chance that your favorite program will not compile or run when compiled with this program. The version of the compiler that ships with OS X is the standard for correctness; any time something works with that compiler but fails with this one is probably a bug, and should be reported to darwin-development@lists.apple.com. PREREQUISITES Presumably if you're reading this, you've figured out how to get the sources. :-) But just to be complete, these sources are available from the Darwin repository at opensource.apple.com, CVS module "gcc", branch "apple-ppc-branch". See http://www.opensource.apple.com/tools/cvs if this isn't enough info yet. If you want C++ exception handling to work, you will need a modified crt1.o. (crt1.o is the bit of code that sets up for execution and calls your program's main().) The modified crt1.o is standard in 10.2, but 10.1, you will need to set it up yourself. If you can't get a modified crt1.o from somebody else, you can patch a copy of the sources to the "Csu" project and build it yourself. The patch is included in this directory, as "csu-patch". The build is easy, just say "make" in the Csu directory, and then copy the crt1.o to /usr/lib/crt1.o (as usual, it's prudent to keep around a copy of the original crt1.o, just in case). You will need to have built the "cctools" project as well, in order to get the helper tool "indr" (which is expected to be installed as /usr/local/bin/indr). BUILDING, THE APPLE WAY To build things the Apple way, just say (in the source directory) mkdir -p build/obj build/dst build/sym gnumake install RC_OS=macos RC_ARCHS=ppc TARGETS=ppc \ SRCROOT=`pwd` OBJROOT=`pwd`/build/obj \ DSTROOT=`pwd`/build/dst SYMROOT=`pwd`/build/sym This will configure and then do a full bootstrap build, with all the results going into the subdirectory build/ that you created. The final results will be in the "dest root" directory build/dst, in the form of an image of the installed directory structure. The drivers and other user-visible tools have a "3" suffixed, so for instance the driver is /usr/bin/gcc3, and the demangler is /usr/bin/c++filt3. To install the results, become root and do ditto build/dst / Various knobs and switches are available, but even so, the Apple makefile machinery is mainly designed for mass builds of all the projects that make up Darwin and/or Mac OS X, and is thus not as flexible as the standard GCC build process. To build for i386 Darwin, set TARGETS=i386. To build fat, set RC_ARCHS='i386 ppc' TARGETS='i386 ppc'. Note that you must have a complete set of fat libraries and i386-targeting cctools for this all to work. You can set the four *ROOT variables to point anywhere, but they must always be absolute pathnames. This way of building may or may not work on non-Macs, and if it doesn't, you're on your own. BUILDING, THE FSF WAY In general, standard GCC procedures work for building this version. We recommend that you build in a separate objdir; create a sibling to the toplevel source dir, call it whatever you want, cd into it, and say "../gcc/configure". This way you can have more than one build using the same set of sources. If you insist on building in the source directory using "./configure", the GNUmakefile that supports the Apple build process (see above) will shadow your makefile, and you will need to override this behavior by saying "make -f Makefile" (or by moving GNUmakefile out of the way). For instance: mkdir darwin cd darwin ../configure --prefix=/tmp/testplace make bootstrap make install does a full build, plus two generations of self-compilation for GCC proper, then an install. To avoid building every language, use --enable-languages argument to configure. For instance, '--enable-languages=objc,c++,objc++' skips the Fortran and Java compilers. (The C compiler will always be built.) To build an x86 cross-compiler, add "--target=i386-darwin" to the configure line. The x86 compiler works, but to make it useful you will need libraries and such from x86 Darwin. There is a ProjectBuilder (PB) project also, but at the moment it's only useful for browsing. We expect to make it useful for building eventually. To keep it out of the way until then, it's in "pbproj/gcc3.pbproj". Tools built the FSF way are *not* usually going to be dropin replacements for already-installed tools built the Apple way, because search paths and other details will be different. TESTING This package includes a copy of the test framework of DejaGNU, for convenience in running GCC's testsuite. If you've done a make from the top, DejaGNU will have been built already; otherwise at the top of the objdir say "make all-dejagnu". Once the DejaGNU is available, you can cd into the gcc objdir and type "make check" to run all the tests. This will take several hours. You can do things like "make check-gcc" just to run C tests, or "make check-g77" for Fortran tests, which take less time. USING While this compiler can be used with 10.1, it is aimed at 10.2 (Jaguar) and later releases. Built correctly, using the "Apple way", it can be a dropin replacement for the 10.2 system compiler. * Compatibility Issues This section lists areas where this compiler behaves differently from other versions of GCC. Built-in functions are not automatically declared GCC knows about some functions, such as memcpy, so it can generate better code for them. However, 2.95.2 let C++ programs refer to them without ever declaring them. The current C++ compiler now does the right thing by requiring you to declare all functions. alloca is a built-in function Normally only __builtin_alloca is a built-in function, and user code #defines alloca as __builtin_alloca. This version of GCC also recognizes alloca as built-in, and compiles it into a single stack adjustment. va_arg cannot take chars, shorts, or floats You can no longer pass "char", "short", or "float" as the second argument to va_arg() when using varargs. #pragma once is silently accepted GCC handles #pragma once correctly, but the standard compiler warns that the pragma is obsolete. This version of GCC is silent by default. Use -Wpragma-once to see the warnings again. #import is silently accepted GCC handles #import correctly, but the standard compiler warns that the directive is obsolete. This version of GCC is silent by default. Use -Wimport to see the warnings again. Extra tokens after #endif and friends are silently accepted Standard GCC now warns about extra tokens after #endif and other preprocessor directives. This version of GCC is silent by default. Use -Wextra-tokens to see these warnings. Files with missing newlines are silently accepted Standard GCC warns about files that do not end with a newline. This seems to be common in Apple headers and sources, so this version does not warn. Use -Wnewline-eof to see these warnings. -fpermissive by default The C++ compiler is normally strict about adherence to the language standard, but the -fpermissive flag is available to convert many errors into warnings. Apple's compiler is set to be permissive by default. This is temporary as of 1/27/02. GNU stddef.h not installed If built the Apple way, GCC's stddef.h is installed as "gnu-stddef.h", and so by default you will get the /usr/include/stddef.h that comes with Darwin. libobjc not built Since GNU libobjc and its headers would mask the system library and headers, this version of GCC does not build or install them if targeting Darwin. Objective-C structure returns When using the NeXT runtime, methods returning structures will work, while they will fail when using FSF GCC. All assembly files are preprocessed FSF GCC only runs the C preprocessor on files with extension .S, and does not run it on files ending in .s. Apple GCC runs the preprocessor on .s files also. Bug reporting address different If the compiler gets an internal error, it will ask you to report the error to Apple, rather than to the FSF. * Extensions This section briefly describes Apple's extensions to GCC. Further details may be found in the GCC manual (usually). __APPLE_CC__ The preprocessor symbol __APPLE_CC__ identifies a specific "build number" of the compiler. These numbers are finer-grained than the generic GCC version numbers, and for gcc3 they range from 1000 up (2.95.2 versions are in the 900s). Framework includes Headers may be found by pathname in the usual way, or as part of "frameworks" which are assemblages of library/headers/resources. For instance, #include will be found as /System/Library/Frameworks/IOKit.framework/Headers/IOTypes.h. The -F adds as a place to search for frameworks; by default, the compiler will look in /System/Library/Frameworks, /Library/Frameworks, and /Local/Library/Frameworks. Frameworks may also have subframeworks, and the framework include machinery will find headers in subframeworks if the outer framework (known as an "umbrella framework) is being included. Objective-C++ Objective-C++ is C++ extended to understand Objective-C constructs. The two object models are separate and "mutually oblivious", so C++ code generally works unchanged, as well as Objective-C code that conforms to C++ restrictions (similar to the restrictions placed on plain C code by C++). Objective-C++ files must have the extension .mm or .M (but note that .M will conflict with .m files on HFS filesystems, so .mm is preferred). Pascal strings The flag -fpascal-strings enables the use of "\p" to designate a length byte, originally used for C-Pascal interoperation on Macs, but now mostly a human-appendix-like compatibility option. Macintosh alignment The options -malign-mac68k, -malign-power, and -malign-natural are available to control whether the alignment of structure fields follows 68K, PowerPC, or "natural" rules. These options are useful to applications which need to be binary-compatible with very old Mac applications, libraries, or resources. The "natural" alignment mode may be useful to applications whose performance is sensitive to misaligned data accesses. In addition, #pragma options align=