From: David Elliott Date: Sun, 27 Mar 2005 09:28:39 +0000 (+0000) Subject: Added documentation for using MW compilers with configure. X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/6ecd355e0f33df405101184ace4f3b2c6866d0bf Added documentation for using MW compilers with configure. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@33089 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/metrowerks/configure_howto.txt b/docs/metrowerks/configure_howto.txt new file mode 100644 index 0000000000..dbe908529e --- /dev/null +++ b/docs/metrowerks/configure_howto.txt @@ -0,0 +1,242 @@ +Title: Metrowerks w/ configure HOWTO +Author: David Elliott +Id: $Id$ + +=== Introduction to Metrowerks command line tools === + +Since CodeWarrior version 8, Metrowerks has provided command-line compilers +hosted on OS X. There are three available targets. + +1) Mac OS X/PPC +Compiler: mwcc +Linker: mwld +-- File formats -- +Executable: Mach-O +Shared Library: Mach-O (bundle, dylib, etc.) +Static Library: CodeWarrior +Object: CodeWarrior + +2) Mach-O/PPC +Compiler: mwccppc +Linker: mwldppc +-- File formats -- +Executable: Mach-O +Shared Library: Mach-O (bundle, dylib, etc.) +Static Library: Archived (ar) Mach-O (.a files) +Object: Mach-O .o files + +3) Mac/PPC +Compiler: mwpefcc +Linker: mwpefld +-- File formats -- +Executable: PEF +Shared Library: PEF ("code fragments") +Static Library: CodeWarrior +Object: CodeWarrior + +As you can see, only one of these targets produces Mach-O .o files that +normal ar and ranlib could hope to handle. It's no matter though, +really all that ar and ranlib do is create a static library (.a) from a +collection of .o files. This can be emulated by a shell script which +calls the appropriate mwld. I've provided one called mwar which does this. +For ranlib simply use true since mwar does all of the work. + +=== Metrowerks Environment Variables === + +In order for any of these programs to work some environment variables +must be set. The compiler must know where to look for headers (CIncludes). +The linker needs to know where to look for libraries (Libraries) such as +those specified on the commandline with -l as well as crt1.o (or sometimes +mwcrt1.o) for OS X. The linker also needs to know if any additional +libraries should be linked into executables (LibraryFiles). Finally, +on OS X the linker needs to know where to look for Frameworks (FrameworkPaths). +These are controlled by the following environment variables: + +1) Mac OS X/PPC +CIncludes: MWCMacOSXPPCIncludes +Libraries: MWMacOSXPPCLibraries +LibraryFiles: MWMacOSXPPCLibraryFiles +FrameworkPaths: MWFrameworkPaths + +2) Mach-O/PPC +CIncludes: MWCMachPPCIncludes +Libraries: MWMachPPCLibraries +LibraryFiles: MWMachPPCLibraryFiles +FrameworkPaths: MWFrameworkPaths + +3) Mac/PPC +CIncludes: MWPEFCIncludes +Libraries: MWPEFLibraries +LibraryFiles: MWPEFLibraryFiles +FrameworkPaths: (N/A) +Notes (mwldppc 3.0.3 build 343): +The environment variables (including MWPEFLibraries) aren't read until after +the command line options have been parsed! The command line option parser +actually tries to do the linking from within the parser and thus -l options +which don't have a -L specifying where to look for the library do not work. +Yes, this means that MWPEFLibraries is essentially useless AFAICT. + +I have provided an example mwvars.sh. It's what I use with CW 8.3. YMMV. + +=== Compiling wxWidgets targetting Mac OS X with Metrowerks === + +With recent wxWidgets (2.5.5) it is possible to compile using the +Metrowerks tools with minimal effort. You may use either mwcc/mwld +or mwccppc/mwldppc. Ideally you will have the tools on your path +on your path as well as the mwar script I've provided. You will also +have had to source mwvars.sh (either yourself or by sourcing it from +your .profile or .bash_profile). + +Before beginning I strongly recommend you write a simple C++ hello world +program. I recommend #include and cout << "Hello World" << endl;. +This will ensure your C++ standard library is working. Note that +you can compile this using mwcc hello.cpp. You will find a hello.cpp.o +file as well as an a.out file if the compiler and linker were successful. +Assuming your compiler can produce a.out you're ready to begin. + +As per usual, I recommend building outside the source tree. +From the source tree (workingDirectory$ is the prompt) + +wxWidgets$ mkdir ../BUILD_MACd_CW8 +wxWidgets$ cd ../BUILD_MACd_CW8 +BUILD_MACd_CW8$ ../wxWidgets/configure --enable-debug --disable-shared CC=mwcc CXX=mwcc LD=mwld AR=mwar RANLIB=true +[ configure hopefully succeeds ] +BUILD_MACd_CW8$ make +[ make hopefully succeeds ] +BUILD_MACd_CW8$ make -C samples/minimal +[ minimal make succeeds ] +BUILD_MACd_CW8$ ./samples/minimal/minimal.app/Contents/MacOS/minimal +[ minimal runs and your prompt will return when you Quit the app ] + +The important options are CC=mwcc CXX=mwcc LD=mwld AR=mwar RANLIB=true +Right now you also need --disable-shared. Eventually I hope to add the +ability to created shared libraries. + +If you wish to use the Mach-O compilers instead of the Mac OS X compilers +then use CC=mwccppc CXX=mwccppc LD=mwldppc. You don't need a special +AR or RANLIB with this compiler. + +At the moment, precompiled headers aren't supported though you don't need +to pass --disable-precomp-headers since the Makefiles know they can't do PCH. +I hope to add this soon. + +As you can see, this is not wildly different from compiling using any +other compiler (for instance GCC). The same files that would be compiled +by gcc are now compiled by mwcc. The same files that would be linked +by the combination of ar and ranlib are now linked using the mwar shell +script that calls mwld to do the work and using true in place of ranlib. +The same files that would be linked using ld (i.e. the executable sample) +are linked using mwld. + + +=== Compiling wxWidgets targetting Mac OS (Carbon) with Metrowerks === + +Compiling for Mac OS PEF Carbon is not really more or less difficult +than compiling for OS X. However, there is still some work left to do. + +In particular, the -lCarbonLib and -lQuickTimeLib options to the linker don't +work because of the aforementioned bug in mwpefld. To fix this you can add +-L/path/to/Universal/Libraries/StubLibraries to LDFLAGS. Unfortunately +because autoconf (2.59) doesn't always use eval appropriately you cannot +have spaces in the path. What I recommend is to make a symlink from +/Applications/Metrowerks CodeWarrior 8.0/Metrowerks CodeWarrior/MacOS Support to some path which can be accessed without using spaces. +Something like this: +~$ ln -snf "/Applications/Metrowerks CodeWarrior 8.0/Metrowerks CodeWarrior/MacOS Support" MW_MacOS + +There is also a problem with the samples Makefiles. Currently they clear +the resource fork of the executable rather than append to it. This +can be remedied by adding the -a option to Rez before making in that +sample's directory. I hope to fix this soon. + +Assuming you work around these it's pretty straightforward: + +wxWidgets$ mkdir ../BUILD_MACCARBONd_CW8 +wxWidgets$ cd ../BUILD_MACCARBONd_CW8 +BUILD_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 +[ configure hopefully succeeds ] +BUILD_MACd_CW8$ make +[ make hopefully succeeds ] +BUILD_MACd_CW8$ make -C samples/minimal +[ minimal make succeeds ] +BUILD_MACd_CW8$ /System/Library/Frameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp ./samples/minimal/minimal +[ minimal runs and your prompt will return when you Quit the app ] + +Unlike the OS X case not many people compile wxMac Carbon PEF using configure. +From time to time there may be minor problems. Please report these using +the sourceforge bug tracker. + +=== Other Metrowerks notes === +--- Object file extension --- +By default, the mw compilers when used with the -c option will append .o +to the source filename (following symlinks even). This is in contrast to +normal compilers which replace the files extension with .o. To get the +normal behavior you must add -ext o to the compiler options. The wxWidgets +configure script does this and the macros to check for this are part of +Bakefile (bakefile.sourceforge.net). + +--- Static library extension --- +The CodeWarrior IDE typically uses the .lib extension for CodeWarrior static +libraries and .a for Mach-O static libraries (ar/ranlib archives). The +wxWidgets makefiles always use .a. This isn't really a problem just be +aware that the .a files aren't really ar/ranlib archives and aren't useable +by anything other than CodeWarrior itself. + +--- IDE --- +As far as I know it should be possible to use libraries created by +the command line tools from the IDE. For instance, you could compile +wxWidgets using this method but continue to use the IDE for your application. +Personally, I prefer sticking with the command line so I haven't tried this. + +--- OS X SDKs --- +Before CodeWarrior 9.3 the usage of SDKs (those in /Developer/SDKs) is +impossible. You might think that it would work simply be prefacing any +/System or /usr paths with the SDK path when setting the environment variables. +Unfortunately, the libraries and frameworks inside these SDKs contain absolute +paths to libraries and frameworks which they depend on. Thus, the linker +attempts to load the non-SDK version to satisfy the dependency. + +To ensure an app will work correctly on previous versions of the OS you +can use Apple's availability macros. + +--- CodeWarrior 8.3 and Panther --- +CodeWarrior 8.3 has some problems running on Panther. When using the IDE +version it is typical to change the OS X directory to the 10.2 SDK. +Unfortunately, this is impossible with the command line compiler due to +the aforementioned bug. Thus, the only solution is to allow CodeWarrior +8.3 to work with Panther's headers. Fortunately, this isn't as hard +as some people (particularly those at Metrowerks) would make you think. + +First of all, there are issues with Apple's headers declaring conflicting +types. Particularly with respect to wchar_t. Now, I'm sure you're +aware of the "(wchar_t Support fix)" directory. What you need to do +is create another one called "(wchar_t Support Panther fix)" using the +provided machine/ansi.h file which contains some minor changes from +the Metrowerks version. + +Secondly, there is an issue with crt1.o. Apple's position is that +/usr/lib/crt1.o is intended to be used only with Apple's GCC. +Metrowerks does provide an mwcrt1.o and when you're using the IDE you +can perfectly well use it instead of Apple's crt1.o. Unfortunately, +when you are using mwld it has crt1.o hardcoded. Very fortunately, it +has only the filename encoded and it searches the libraries path! +What I do is symlink "Mac OS X Support/Libraries/Startup/mwcrt1.o" to +crt1.o in the same directory. + +--- MSL on OS X --- +In mwvar.sh for the Mac OS X/PPC toolchain I've used MSL C++ with the +BSD CRT. To do this I used the .a files. Earlier I used the .lib files +but these also require the MSL C .lib. AFAIK using this would cause +the MSL CRT to be used and I think I don't want that unless I'm using +the MSL CRT headers. It did work although I never tested it with +anything too complex. I suspect it would have failed although I'm +wondering how it works with the CW projects because I think they do +link with the MSL_C libs. This is probably very wrong. + +If you do decide to use the MSL_C libs you'll need to add +"MSL/MSL_C/MSL_MacOS/Src/console_OS_X.c". Unfortunately, +mwld is a linker and doesn't understand C source code. Thus you must +compile this file and use the compiled version. + +What I did was simply run mwcc -c console_OS_X.c to generate a +console_OS_X.c.o object file. This file must be in MWMacOSXPPCLibraryFiles. + diff --git a/docs/metrowerks/mwar b/docs/metrowerks/mwar new file mode 100755 index 0000000000..2479920f34 --- /dev/null +++ b/docs/metrowerks/mwar @@ -0,0 +1,17 @@ +#! /bin/sh +if test "x$1" '!=' "xrcu"; then + echo "$0: this isn't really ar. Only rcu is supported" >&2 + exit 1 +fi +if test "x$2" == "x"; then + echo "$0: no archive file specified" >&2 + exit 1 +fi +if test "x$3" == "x"; then + echo "$0: no archive members specified" >&2 + exit 1 +fi +outputfile="$2" +shift +shift +/Users/dfe/bin/mw8.3/realmw/mwld -xm l -o "$outputfile" "$@" diff --git a/docs/metrowerks/mwpefar b/docs/metrowerks/mwpefar new file mode 100755 index 0000000000..b12faaa49b --- /dev/null +++ b/docs/metrowerks/mwpefar @@ -0,0 +1,17 @@ +#! /bin/sh +if test "x$1" '!=' "xrcu"; then + echo "$0: this isn't really ar. Only rcu is supported" >&2 + exit 1 +fi +if test "x$2" == "x"; then + echo "$0: no archive file specified" >&2 + exit 1 +fi +if test "x$3" == "x"; then + echo "$0: no archive members specified" >&2 + exit 1 +fi +outputfile="$2" +shift +shift +/Users/dfe/bin/mw8.3/realmw/mwpefld -xm l -o "$outputfile" "$@" diff --git a/docs/metrowerks/mwvars.sh b/docs/metrowerks/mwvars.sh new file mode 100644 index 0000000000..88c96378be --- /dev/null +++ b/docs/metrowerks/mwvars.sh @@ -0,0 +1,147 @@ +# File: mwvars.sh +# Author: David Elliott +# Id: $Id$ +CWINSTALL="/Applications/Metrowerks CodeWarrior 8.0/Metrowerks CodeWarrior" +if ! test -d "$CWINSTALL"; then + CWINSTALL="$HOME/Applications/Metrowerks CodeWarrior 8.0/Metrowerks CodeWarrior" +fi +if ! test -d "$CWINSTALL"; then + echo "WARNING: Could not find CodeWarrior" 1>&2 +fi + +# NOTE: Do not use this with CW < 9.3 +# If you do have CW 9.3, please read the documentation.before +# attempting this as I don't have it so haven't tested it. +#CW_NEXT_ROOT="/Developer/SDKs/MacOSX10.2.8.sdk" +CW_NEXT_ROOT="" + +# Turn this on to use MW's CRT instead of BSD CRT.w/ mwcc/mwld +CW_MWCC_USE_MW_CRT=no +# NOTE: When you turn this on you MUST define _MSL_USING_MW_C_HEADERS +# You probably also want to define _MSL_NEEDS_EXTRAS (for strcasecmp) +# Furthermore, you can't use UNIXy stuff like popen when you use these! +# That is why it is off by default. + +########################################################################### +## Metrowerks Mac OS X and Mach-O + +##### MWCMachPPCIncludes ##### +# Path containing machine/ansi.h fixed to work with Panther headers +# standard /usr/include directory +# MSL C++ headers +# MSL C headers (MSL C++ needs this for mslGlobals.h in particular) +# MW compiler specific headers +export MWCMachPPCIncludes=\ +"$CWINSTALL/MacOS X Support/Headers/(wchar_t Support Panther fix):"\ +"$CW_NEXT_ROOT/usr/include:"\ +"$CWINSTALL/MSL/MSL_C++/MSL_Common/Include:"\ +"$CWINSTALL/MSL/MSL_C/MSL_MacOS/Include:"\ +"$CWINSTALL/MSL/MSL_C/MSL_Common/Include:"\ +"$CWINSTALL/MacOS X Support/Headers/PPC Specific:"\ + #end MWCMachPPCIncludes + +##### MWCMacOSXPPCIncludes ##### +# If using BSD CRT then our includes are like those for the Mach-O compiler. +export MWCMacOSXPPCIncludes="$MWCMachPPCIncludes" +if test "x$CW_MWCC_USE_MW_CRT" = "xyes"; then +# Path containing machine/ansi.h fixed to work with Panther headers +# MSL C++ and C headers +# standard /usr/include directory +# MSL Extra headers (extras.h defines strcasecmp!) +# MW compiler specific headers +#NOTE: MSL Extras must be included after /usr/include so mode_t +# doesn't get redefined incorrectly for OS X. + export MWCMacOSXPPCIncludes=\ +"$CWINSTALL/MacOS X Support/Headers/(wchar_t Support Panther fix):"\ +"$CWINSTALL/MSL/MSL_C++/MSL_Common/Include:"\ +"$CWINSTALL/MSL/MSL_C/MSL_MacOS/Include:"\ +"$CWINSTALL/MSL/MSL_C/MSL_Common/Include:"\ +"$CW_NEXT_ROOT/usr/include:"\ +"$CWINSTALL/MSL/MSL_Extras/MSL_Common/Include:"\ +"$CWINSTALL/MacOS X Support/Headers/PPC Specific" + #end MWCMacOSXPPCIncludes +fi + +##### MWMacOSXPPCLibraries ##### +# First we must have the path containing mwcrt1.o (see note) +# Then we have the normal /usr/lib. +# +# NOTE: For CW 8.3 users using Panther you must link mwcrt1.o to crt1.o +# so that the crt1.o from /usr/lib does not get used. +export MWMacOSXPPCLibraries=\ +"$CWINSTALL/MacOS X Support/Libraries/Startup:"\ +"$CW_NEXT_ROOT/usr/lib" + #end MWMacOSXPPCLibraries + +##### MWMachPPCLibraries ##### +# Mach-O/PPC linker uses the same system library path as Mac OS X/PPC +export MWMachPPCLibraries="$MWMacOSXPPCLibraries" + +##### MWMachPPCLibraryFiles ##### +# First we need the MSL Runtime for basic C++ support. +# Second we need the MSL C++ library. +# There doesn't appear to be any MSL C for this configuration. +export MWMachPPCLibraryFiles=\ +"$CWINSTALL/MacOS X Support/Libraries/Runtime/Libs/MSL_Runtime_Mach-O.a:"\ +"$CWINSTALL/MSL/MSL_C++/MSL_MacOS/Lib/Mach-O/MSL_C++_Mach-O.a:"\ + #end MWMachPPCLibraryFiles + + +##### MWMacOSXPPCLibraryFiles ##### +export MWMacOSXPPCLibraryFiles="$MWMachPPCLibraryFiles" +if test "x$CW_MWCC_USE_MW_CRT" = "xyes"; then +# First of all we need the MSL Runtime which appears to implement +# the very basic C++ functions like operator new/delete as well +# as Metrowerks C++ standard RTTI. +# Second we need the MSL C++ library. +# Since we're using MSL C++ library we also need the C library. +# Finally, we need the console_OS_X.c file which you'll need to compile +# for this to work (a normal project would have console_OS_X.c in it) + export MWMacOSXPPCLibraryFiles=\ +"$CWINSTALL/MacOS X Support/Libraries/Runtime/Libs/MSL_Runtime_Mach-O.lib:"\ +"$CWINSTALL/MSL/MSL_C++/MSL_MacOS/Lib/Mach-O/MSL_C++_Mach-O.lib:"\ +"$CWINSTALL/MSL/MSL_C/MSL_MacOS/Lib/Mach-O/MSL_C_Mach-O.lib:"\ +"$CWINSTALL/MSL/MSL_C/MSL_MacOS/Src/console_OS_X.c.o:"\ + #end MWMacOSXPPCLibraryFiles +fi + +##### MWFrameworkPaths ##### +# We need /System/Library/Frameworks for the OS X stuff +export MWFrameworkPaths=\ +"$CW_NEXT_ROOT/System/Library/Frameworks" + #end MWFrameworkPaths + + +########################################################################### +## PEF +export MWPEFCIncludes=\ +"$CWINSTALL/MSL/MSL_C++/MSL_Common/Include:"\ +"$CWINSTALL/MSL/MSL_C/MSL_MacOS/Include:"\ +"$CWINSTALL/MSL/MSL_C/MSL_Common/Include:"\ +"$CWINSTALL/MSL/MSL_Extras/MSL_Common/Include:"\ +"$CWINSTALL/MSL/MSL_Extras/MSL_MacOS/Include:"\ +"$CWINSTALL/MacOS Support/Headers/PPC Specific:"\ +"$CWINSTALL/MacOS Support/Universal/Interfaces/CIncludes:"\ +"$CWINSTALL/MacOS Support/MetroNub Utilities/:"\ + #end MWPEFCIncludes + +export MWPEFLibraries=\ +"$CWINSTALL"/MacOS\ Support/Universal/Libraries/StubLibraries:\ +"$CWINSTALL"/MacOS\ Support/Libraries/Runtime/Libs:\ +"$CWINSTALL"/MSL/MSL_C/MSL_MacOS/Lib/PPC:\ +"$CWINSTALL"/MSL/MSL_C++/MSL_MacOS/Lib/PPC + #end MWPEFLibraries + +export MWPEFLibraryFiles=\ +"$CWINSTALL/MacOS Support/Libraries/Runtime/Libs/MSL_All_Carbon.Lib:"\ +"$CWINSTALL/MSL/MSL_C/MSL_MacOS/Src/console.stubs.o:"\ +"$CWINSTALL/MacOS Support/MetroNub Utilities/MNU Carbon.Lib:"\ +"CarbonLib:"\ +"CarbonFrameworkLib:"\ + #end MWPEFLibraryFiles +# I don't need the following but here they are for reference: +#"$CWINSTALL/MacOS Support/Libraries/Runtime/Libs/MSL_StdCRuntime_PPC.lib:"\ +#"$CWINSTALL/MacOS Support/Libraries/Runtime/Libs/MSL_Runtime_PPC.lib:"\ +#"$CWINSTALL/MSL/MSL_C++/MSL_MacOS/Lib/PPC/MSL_C++_PPC.lib:"\ +#"$CWINSTALL/MSL/MSL_C/MSL_MacOS/Lib/PPC/MSL_C_PPC.lib:"\ + diff --git a/docs/metrowerks/wchar_t_panther_fix/machine/ansi.h b/docs/metrowerks/wchar_t_panther_fix/machine/ansi.h new file mode 100644 index 0000000000..153485f6cb --- /dev/null +++ b/docs/metrowerks/wchar_t_panther_fix/machine/ansi.h @@ -0,0 +1,58 @@ +/* + * File: ansi.h + * ©2000-2002 Metrowerks Corporation. All rights reserved. + * + * Content: wchar_t overrides for OS X + * + */ + + +#ifndef _MW_ANSI_H_ +#define _MW_ANSI_H_ + +#if defined (__ppc__) + #include +#elif defined (__i386__) + #include +#else + #error architecture not supported +#endif + +#ifndef _BSD_WCHAR_T_DEFINED_ + #define _BSD_WCHAR_T_DEFINED_ + + #if !__cplusplus || !__option(wchar_type) + typedef int wchar_t; + #undef __WCHAR_TYPE__ + #define __WCHAR_TYPE__ int + #else + #undef __WCHAR_TYPE__ + #define __WCHAR_TYPE__ wchar_t + #endif + + #undef _BSD_WCHAR_T_ + #define _BSD_WCHAR_T_ __WCHAR_TYPE__ /* wchar_t */ + + #undef _BSD_RUNE_T_ + #define _BSD_RUNE_T_ __WCHAR_TYPE__ /* rune_t */ + +#ifndef WCHAR_MIN + #define WCHAR_MIN ((wchar_t) 0x80000000U) + #define WCHAR_MAX ((wchar_t) 0x7FFFFFFFU) +#endif + + typedef wchar_t wint_t; + typedef wchar_t wctype_t; +#if 0 // 10.3 headers declare mbstate_t as union + typedef int mbstate_t; +#endif + typedef wchar_t Wint_t; +#endif + + +#ifndef _ANSI_SOURCE + typedef _BSD_WCHAR_T_ rune_t; +#endif + + +#endif /* _MW_ANSI_H_ */