1Title: Metrowerks w/ configure HOWTO 2Author: David Elliott 3Id: $Id: configure_howto.txt 33089 2005-03-27 09:28:39Z DE $ 4 5=== Introduction to Metrowerks command line tools === 6 7Since CodeWarrior version 8, Metrowerks has provided command-line compilers 8hosted on OS X. There are three available targets. 9 101) Mac OS X/PPC 11Compiler: mwcc 12Linker: mwld 13-- File formats -- 14Executable: Mach-O 15Shared Library: Mach-O (bundle, dylib, etc.) 16Static Library: CodeWarrior 17Object: CodeWarrior 18 192) Mach-O/PPC 20Compiler: mwccppc 21Linker: mwldppc 22-- File formats -- 23Executable: Mach-O 24Shared Library: Mach-O (bundle, dylib, etc.) 25Static Library: Archived (ar) Mach-O (.a files) 26Object: Mach-O .o files 27 283) Mac/PPC 29Compiler: mwpefcc 30Linker: mwpefld 31-- File formats -- 32Executable: PEF 33Shared Library: PEF ("code fragments") 34Static Library: CodeWarrior 35Object: CodeWarrior 36 37As you can see, only one of these targets produces Mach-O .o files that 38normal ar and ranlib could hope to handle. It's no matter though, 39really all that ar and ranlib do is create a static library (.a) from a 40collection of .o files. This can be emulated by a shell script which 41calls the appropriate mwld. I've provided one called mwar which does this. 42For ranlib simply use true since mwar does all of the work. 43 44=== Metrowerks Environment Variables === 45 46In order for any of these programs to work some environment variables 47must be set. The compiler must know where to look for headers (CIncludes). 48The linker needs to know where to look for libraries (Libraries) such as 49those specified on the commandline with -l as well as crt1.o (or sometimes 50mwcrt1.o) for OS X. The linker also needs to know if any additional 51libraries should be linked into executables (LibraryFiles). Finally, 52on OS X the linker needs to know where to look for Frameworks (FrameworkPaths). 53These are controlled by the following environment variables: 54 551) Mac OS X/PPC 56CIncludes: MWCMacOSXPPCIncludes 57Libraries: MWMacOSXPPCLibraries 58LibraryFiles: MWMacOSXPPCLibraryFiles 59FrameworkPaths: MWFrameworkPaths 60 612) Mach-O/PPC 62CIncludes: MWCMachPPCIncludes 63Libraries: MWMachPPCLibraries 64LibraryFiles: MWMachPPCLibraryFiles 65FrameworkPaths: MWFrameworkPaths 66 673) Mac/PPC 68CIncludes: MWPEFCIncludes 69Libraries: MWPEFLibraries 70LibraryFiles: MWPEFLibraryFiles 71FrameworkPaths: (N/A) 72Notes (mwldppc 3.0.3 build 343): 73The environment variables (including MWPEFLibraries) aren't read until after 74the command line options have been parsed! The command line option parser 75actually tries to do the linking from within the parser and thus -l options 76which don't have a -L specifying where to look for the library do not work. 77Yes, this means that MWPEFLibraries is essentially useless AFAICT. 78 79I have provided an example mwvars.sh. It's what I use with CW 8.3. YMMV. 80 81=== Compiling wxWidgets targetting Mac OS X with Metrowerks === 82 83With recent wxWidgets (2.5.5) it is possible to compile using the 84Metrowerks tools with minimal effort. You may use either mwcc/mwld 85or mwccppc/mwldppc. Ideally you will have the tools on your path 86on your path as well as the mwar script I've provided. You will also 87have had to source mwvars.sh (either yourself or by sourcing it from 88your .profile or .bash_profile). 89 90Before beginning I strongly recommend you write a simple C++ hello world 91program. I recommend #include <iostream> and cout << "Hello World" << endl;. 92This will ensure your C++ standard library is working. Note that 93you can compile this using mwcc hello.cpp. You will find a hello.cpp.o 94file as well as an a.out file if the compiler and linker were successful. 95Assuming your compiler can produce a.out you're ready to begin. 96 97As per usual, I recommend building outside the source tree. 98From the source tree (workingDirectory$ is the prompt) 99 100wxWidgets$ mkdir ../BUILD_MACd_CW8 101wxWidgets$ cd ../BUILD_MACd_CW8 102BUILD_MACd_CW8$ ../wxWidgets/configure --enable-debug --disable-shared CC=mwcc CXX=mwcc LD=mwld AR=mwar RANLIB=true 103[ configure hopefully succeeds ] 104BUILD_MACd_CW8$ make 105[ make hopefully succeeds ] 106BUILD_MACd_CW8$ make -C samples/minimal 107[ minimal make succeeds ] 108BUILD_MACd_CW8$ ./samples/minimal/minimal.app/Contents/MacOS/minimal 109[ minimal runs and your prompt will return when you Quit the app ] 110 111The important options are CC=mwcc CXX=mwcc LD=mwld AR=mwar RANLIB=true 112Right now you also need --disable-shared. Eventually I hope to add the 113ability to created shared libraries. 114 115If you wish to use the Mach-O compilers instead of the Mac OS X compilers 116then use CC=mwccppc CXX=mwccppc LD=mwldppc. You don't need a special 117AR or RANLIB with this compiler. 118 119At the moment, precompiled headers aren't supported though you don't need 120to pass --disable-precomp-headers since the Makefiles know they can't do PCH. 121I hope to add this soon. 122 123As you can see, this is not wildly different from compiling using any 124other compiler (for instance GCC). The same files that would be compiled 125by gcc are now compiled by mwcc. The same files that would be linked 126by the combination of ar and ranlib are now linked using the mwar shell 127script that calls mwld to do the work and using true in place of ranlib. 128The same files that would be linked using ld (i.e. the executable sample) 129are linked using mwld. 130 131 132=== Compiling wxWidgets targetting Mac OS (Carbon) with Metrowerks === 133 134Compiling for Mac OS PEF Carbon is not really more or less difficult 135than compiling for OS X. However, there is still some work left to do. 136 137In particular, the -lCarbonLib and -lQuickTimeLib options to the linker don't 138work because of the aforementioned bug in mwpefld. To fix this you can add 139-L/path/to/Universal/Libraries/StubLibraries to LDFLAGS. Unfortunately 140because autoconf (2.59) doesn't always use eval appropriately you cannot 141have spaces in the path. What I recommend is to make a symlink from 142/Applications/Metrowerks CodeWarrior 8.0/Metrowerks CodeWarrior/MacOS Support to some path which can be accessed without using spaces. 143Something like this: 144~$ ln -snf "/Applications/Metrowerks CodeWarrior 8.0/Metrowerks CodeWarrior/MacOS Support" MW_MacOS 145 146There is also a problem with the samples Makefiles. Currently they clear 147the resource fork of the executable rather than append to it. This 148can be remedied by adding the -a option to Rez before making in that 149sample's directory. I hope to fix this soon. 150 151Assuming you work around these it's pretty straightforward: 152 153wxWidgets$ mkdir ../BUILD_MACCARBONd_CW8 154wxWidgets$ cd ../BUILD_MACCARBONd_CW8 155BUILD_MACCARBONd_CW8$ ../wxWidgets/configure --host=powerpc-apple-macos --enable-debug --disable-shared CC=mwpefcc CXX=mwpefcc LD=mwpefld AR=mwpefar RANLIB=true LDFLAGS=-L/Users/yourname/MW_MacOS/Universal/Libraries/StubLibraries 156[ configure hopefully succeeds ] 157BUILD_MACd_CW8$ make 158[ make hopefully succeeds ] 159BUILD_MACd_CW8$ make -C samples/minimal 160[ minimal make succeeds ] 161BUILD_MACd_CW8$ /System/Library/Frameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp ./samples/minimal/minimal 162[ minimal runs and your prompt will return when you Quit the app ] 163 164Unlike the OS X case not many people compile wxMac Carbon PEF using configure. 165From time to time there may be minor problems. Please report these using 166the sourceforge bug tracker. 167 168=== Other Metrowerks notes === 169--- Object file extension --- 170By default, the mw compilers when used with the -c option will append .o 171to the source filename (following symlinks even). This is in contrast to 172normal compilers which replace the files extension with .o. To get the 173normal behavior you must add -ext o to the compiler options. The wxWidgets 174configure script does this and the macros to check for this are part of 175Bakefile (bakefile.sourceforge.net). 176 177--- Static library extension --- 178The CodeWarrior IDE typically uses the .lib extension for CodeWarrior static 179libraries and .a for Mach-O static libraries (ar/ranlib archives). The 180wxWidgets makefiles always use .a. This isn't really a problem just be 181aware that the .a files aren't really ar/ranlib archives and aren't useable 182by anything other than CodeWarrior itself. 183 184--- IDE --- 185As far as I know it should be possible to use libraries created by 186the command line tools from the IDE. For instance, you could compile 187wxWidgets using this method but continue to use the IDE for your application. 188Personally, I prefer sticking with the command line so I haven't tried this. 189 190--- OS X SDKs --- 191Before CodeWarrior 9.3 the usage of SDKs (those in /Developer/SDKs) is 192impossible. You might think that it would work simply be prefacing any 193/System or /usr paths with the SDK path when setting the environment variables. 194Unfortunately, the libraries and frameworks inside these SDKs contain absolute 195paths to libraries and frameworks which they depend on. Thus, the linker 196attempts to load the non-SDK version to satisfy the dependency. 197 198To ensure an app will work correctly on previous versions of the OS you 199can use Apple's availability macros. 200 201--- CodeWarrior 8.3 and Panther --- 202CodeWarrior 8.3 has some problems running on Panther. When using the IDE 203version it is typical to change the OS X directory to the 10.2 SDK. 204Unfortunately, this is impossible with the command line compiler due to 205the aforementioned bug. Thus, the only solution is to allow CodeWarrior 2068.3 to work with Panther's headers. Fortunately, this isn't as hard 207as some people (particularly those at Metrowerks) would make you think. 208 209First of all, there are issues with Apple's headers declaring conflicting 210types. Particularly with respect to wchar_t. Now, I'm sure you're 211aware of the "(wchar_t Support fix)" directory. What you need to do 212is create another one called "(wchar_t Support Panther fix)" using the 213provided machine/ansi.h file which contains some minor changes from 214the Metrowerks version. 215 216Secondly, there is an issue with crt1.o. Apple's position is that 217/usr/lib/crt1.o is intended to be used only with Apple's GCC. 218Metrowerks does provide an mwcrt1.o and when you're using the IDE you 219can perfectly well use it instead of Apple's crt1.o. Unfortunately, 220when you are using mwld it has crt1.o hardcoded. Very fortunately, it 221has only the filename encoded and it searches the libraries path! 222What I do is symlink "Mac OS X Support/Libraries/Startup/mwcrt1.o" to 223crt1.o in the same directory. 224 225--- MSL on OS X --- 226In mwvar.sh for the Mac OS X/PPC toolchain I've used MSL C++ with the 227BSD CRT. To do this I used the .a files. Earlier I used the .lib files 228but these also require the MSL C .lib. AFAIK using this would cause 229the MSL CRT to be used and I think I don't want that unless I'm using 230the MSL CRT headers. It did work although I never tested it with 231anything too complex. I suspect it would have failed although I'm 232wondering how it works with the CW projects because I think they do 233link with the MSL_C libs. This is probably very wrong. 234 235If you do decide to use the MSL_C libs you'll need to add 236"MSL/MSL_C/MSL_MacOS/Src/console_OS_X.c". Unfortunately, 237mwld is a linker and doesn't understand C source code. Thus you must 238compile this file and use the compiled version. 239 240What I did was simply run mwcc -c console_OS_X.c to generate a 241console_OS_X.c.o object file. This file must be in MWMacOSXPPCLibraryFiles. 242 243