Mac OS X And Xcode 1.1 Setup Guide
From WxWiki
Contents |
[edit] Using wxWidgets with the Xcode IDE for Mac OS X
[edit] NOTE: These directions are obsolete.
[edit] They have been superseded by http://wiki.wxwidgets.org/wiki.pl?Mac_OS_X_And_Xcode_For_Beginners
[edit] Please use that newer page instead.
---
Written by Tim Griesser, February 28, 2004 for wxWidgets 2.4.2
Updated by Tim Griesser, June 18, 2004 for wxWidgets 2.5.2 and CVS HEAD
---
These instructions describe how to use wxWidgets with the Xcode IDE
for Mac OS X. The Xcode IDE is included free with Mac OS X 10.3.
Mac OS X 10.3 is also known as Panther.
The Xcode IDE is not preinstalled but it does come on the CDs or DVD
included with any Macintosh. You just need to install it yourself.
Alternatively, you can get the latest version of Xcode IDE from
Apple's website for a nominal shipping charge.
These instructions were tested with
- Mac OS X 10.3
- Xcode 1.1
- Three versions of wxWidgets:
- wxWidgets 2.4.2
- wxWidgets 2.5.2
- CVS HEAD as of June 18, 2004
Hopefully these instructions will help you even if you are working
on newer versions. However, Xcode will not work on earlier
versions of Mac OS X.
- If you are new to the Macintosh, you'll probably want to buy a
book. Two good books for newcomers are
Mastering Mac OS X, Third Edition, 10.3 Panther, Todd Stauffer
Mac OS X, Panther Edition, The Missing Manual, David Pogue
- You need to have two accounts on your Macintosh computer.
One must be an admin account. One should be a user account.
Do all of your work in your user account, and just use the
admin account to install software such as Xcode and wxWidgets.
- You will not need a superuser or root account in these instructions.
Apple ships Mac OS X with the root account disabled for security.
You can enable it if you want, but you never really need to
because you can use the admin account with "sudo" to do all of
your necessary system tasks. So I don't use a root account in
these instructions.
- Login to your admin account and install Xcode.
- Log out of your admin account.
- Login to your user account.
- Xcode is typically installed into the /Developer directory. The
documentation is then in /Developer/Documentation/index.html.
You should add this page to your hotlist or bookmarks in your
browser (Safari or Mozilla) because you will refer to this
documentation often. You will use the documentation for learning
about Carbon, CVS, gcc, Xcode, etc.
- Go to www.wxwidgets.org and download the Mac distribution. You can
choose from the following choices as of June 18, 2004:
Version 2.4.2 = the current released version: old but stable
Version 2.5.2 = the development snapshot: newer but less stable
Branch CVS HEAD = the development branch: very new and may be unstable
If you are new to wxWidgets, then pick Version 2.5.2
If you chose CVS HEAD, then skip the next few steps about
2.4.2 and 2.5.2.
In you chose 2.4.2, then follow these steps:
--------------------------------------------
Download these three files from wxWidgets.org
wxMac-2.4.2.tar.gz
wxWindows-2.4.2-HTML.tar.gz
wxWindows-2.4.2-PDF.tar.gz
To unpack these .tar.gz files, Mac OS X uses the free program
StuffIt Expander which is already preinstalled in Mac OS X.
From Finder, double click on each of the .tar.gz files above,
and unpack them. This will create three new directories:
wxMac-2.4.2, wxWindows-2.4.2, and wxWindows-2.4.2.1
You will only keep the wxMac-2.4.2 directory but you'll need the
documentation from the other two directories. Therefore you
should
a) rename wxMac-2.4.2/docs/html to 'html.old'
b) move wxWindows-2.4.2/docs/html to wxMac-2.4.2/docs/html
c) rename wxMac-2.4.2/docs/pdf to 'pdf.old'
d) move wxWindows-2.4.2.1/docs/pdf to wxMac-2.4.2/docs/pdf
e) delete the empty directories wxWindows-2.4.2 and wxWindows-2.4.2.1
You can now delete the three *.tar.gz files if you want. Or you
can archive the *.tar.gz files somewhere in case you want to reinstall
the libraries later.
In you chose 2.5.2, then follow these steps:
--------------------------------------------
Download these three files from wxWidgets.org
wxMac-2.5.2.tar.gz
wxWidgets-2.5.2-HTML.tar.gz
wxWidgets-2.5.2-PDF.tar.gz
To unpack these .tar.gz files, Mac OS X uses the free program
StuffIt Expander which is already preinstalled in Mac OS X.
From Finder, double click on each of the .tar.gz files above,
and unpack them. This will create three new directories:
wxMac-2.5.2, wxWidgets-2.5.2, and wxWidgets-2.5.2.1
You will only keep the wxMac-2.5.2 directory but you'll need the
documentation from the other two directories. Therefore you
should
a) rename wxMac-2.5.2/docs/html to 'html.old'
b) move wxWidgets-2.5.2/docs/html to wxMac-2.5.2/docs/html
c) move wxWidgets-2.5.2.1/docs/pdf to wxMac-2.5.2/docs/pdf
e) delete the two directories wxWidgets-2.5.2 and wxWidgets-2.5.2.1
You can now delete the three *.tar.gz files if you want. Or you
can archive the *.tar.gz files somewhere in case you want to reinstall
the libraries later.
In you chose CVS HEAD, then follow these steps:
-----------------------------------------------
In Finder, click on Applications, then click on Utilities. You will
see the Terminal program. Click on the Terminal program.
First make an empty directory for the wx source code. (In these
commands, the ~ means your user directory, usually /Users/yourname)
mkdir ~/wx
cd ~/wx
Check out the wx source code:
cvs -d :pserver:anoncvs@cvs.wxwidgets.org:/pack/cvsroots/wxwidgets login
CVS password: anoncvs
cvs -d :pserver:anoncvs@cvs.wxwidgets.org:/pack/cvsroots/wxwidgets co -r HEAD wxWidgets
You should now have a directory ~/wx/wxWidgets with all of the source code.
If you ever want to update the CVS source, just do this:
cd ~/wx/wxWidgets
cvs update
Now that you have the source code, follow these steps:
------------------------------------------------------
- Next you need to pick a place to put all of the source code.
One choice is to create directories using the following structure:
~/wx/v242 for the wxMac-2.4.2 files
~/wx/v252 for the wxMac-2.5.2 files
~/wx/wxWidgets for the CVS HEAD files.
You can use any names you like. For the rest of these
instructions, I'm going to assume you picked the name
"/Users/yourname/wx/ver" as the location of your files.
- For 2.4.2, create the new directory you picked above and move the files
from wxMac-2.4.2 to this new directory.
For 2.5.2, create the new directory you picked above and move the files
from wxMac-2.5.2 to this new directory.
For CVS HEAD, your files are already in the correct place. But you
must configure the makefiles. To do this from the terminal window,
type:
autoconf
- For 2.4.2 or 2.5.2, but not for CVS HEAD:
Now you should add links to the wxWidgets documentation from your
hotlist or bookmarks in your browser (Safari or Mozilla). You will be
using the documentation often. Here are two good links to add:
/Users/yourname/wx/ver/docs/html/index.htm
/Users/yourname/wx/ver/docs/html/wx/wx.htm
- For 2.4.2 or 2.5.2, but not for CVS HEAD:
If you are new to wxWidgets, you may want printed documentation.
I recommend taking /Users/yourname/wx/ver/docs/pdf/wx.pdf (1769 pages)
and /Users/yourname/wx/ver/docs/pdf/wxTutorial.pdf (117 pages) to your
local copy shop for printing. Ask them to print both documents double
sided and then bind them into four books of roughly 300 sheets per book.
It is great reference material and well worth the price of printing and
binding.
- In Finder, click on Applications, then click on Utilities. You will
see the Terminal program. Drag Terminal to the Dock. You will be
using Terminal often, so it is handy to have it on the Dock.
- Open a Terminal window by clicking on the Terminal icon in the Dock.
- In the Terminal window, configure the wxWidgets code as follows:
cd ~/wx/ver
./configure --disable-shared
This takes about 30 seconds on a dual 1.8 GHz Power Mac.
- In the Terminal window, compile the wxWidgets code by typing:
cd ~/wx/ver
make
The build takes about 10 minutes on a dual 1.8 GHz Power Mac.
Note for 2.4.2 only:
You may get an error in src/mac/dc.cpp. If you do, then
simply edit src/mac/dc.cpp using Xcode or vi and comment out
the two offending functions: IntToFixed and FixedToInt.
This is a naming conflict which is fixed in 2.5.2
Restart the build by typing
cd ~/wx/ver
make
If you have any other compile problems, check the troubleshooting
tips below.
- Now try to build the demos from the Terminal window
For 2.4.2, you can build all of the demos like this:
cd ~/wx/ver/demos
make
For 2.5.2 and CVS HEAD, the dbbrowse demo will not compile so
you'll need to build the demos individually like this:
cd ~/wx/ver/demos
cd life; make; cd ..
cd bombs; make; cd ..
cd forty; make; cd ..
If you have any compile problems, check the troubleshooting
tips below.
- Now try to run the demos from the Terminal window.
Sometimes the demo might start underneath your Terminal window,
so you need to move the Terminal window to find it. Also you'll
need to exit the demo before you'll be able to use the Terminal
window again.
Try the demo of the Game of Life:
cd life
./life
Try the demo of Bombs:
cd ..
cd bombs
./bombs
Try the demo of Forty Thieves:
cd ..
cd forty
./forty
- You can also run the demos from Finder.
Using Finder, go to ~/wx/ver/demos/forty and click on the
icon which shows three squares colored red, blue and yellow.
- Now try to build some samples from the Terminal window.
Not all samples work because some require platform specific
features of Microsoft Windows. But most work. Here are a few
to try, and all of these should work:
cd ~/wx/ver/samples/image
make
./image
cd ~/wx/ver/samples/notebook
make
./notebook
cd ~/wx/ver/samples/layout
make
./layout
cd ~/wx/ver/samples/wizard
make
./wizard
on the menu for wizard, click "File, Run wizard..."
cd ~/wx/ver/samples/splitter
make
./splitter
- If everything above worked, you are ready to try the Xcode IDE.
- Continue to look through ~/wx/ver/samples until you find
one that closely matches the program you'd like to write.
I'll pick ~/wx/ver/samples/notebook, and use the files from
"notebook" in the rest of this document. But you can pick
whichever sample you want.
- Make a new directory for your own work such as ~/test/notebook
and copy all of the files from ~/wx/ver/samples/notebook
to that directory. Be sure to leave ~/wx/ver/samples/notebook
unchanged so you can compare it to your test directory if
things are not working.
- In ~/test/notebook, make a subdirectory called 'obsolete'. Move
the following files to this 'obsolete' directory because you
won't be using them with Xcode:
Makefile
makefile.*
Makefile.*
*.o
notebook
notebook.app
- Start Xcode.
- Click "File, New Project ..., Empty Project"
Set the Project Name to "notebook"
Set the Project Directory to "~/test/notebook/"
Click Finish
- Click "Project, New Target..., Carbon Application"
Set the Target Name to "notebook"
Click Finish
- Click "Project, Add Files... "
Select notebook.cpp, Add, Add.
- For 2.4.2
Click "Projects, Add Frameworks..."
Choose "~/wx/ver/lib/libwx_mac-2.4.a
Click "Add"
For 2.5.2
Click "Projects, Add Frameworks..."
Choose "~/wx/ver/lib/libwx_mac_core-2.5.a
Click "Add"
Click "Projects, Add Frameworks..."
Choose "~/wx/ver/lib/libwx_base_carbon-2.5.a
Click "Add"
For CVS HEAD
Click "Projects, Add Frameworks..."
Choose "~/wx/ver/lib/libwx_mac_core-2.5.a
Click "Add"
Click "Projects, Add Frameworks..."
Choose "~/wx/ver/lib/libwx_base_carbon-2.5.a
Click "Add"
- In the left column of the main window, click on "Targets, notebook"
Click on "Project, Get Info..."
Click on the "Build" tab.
A side drawer will pop out.
Find each of the following settings in the side drawer and change them.
Most of these are in the "Language" or "Common Settings" groups.
For 2.4.2, Other C Flags =
-D_FILE_OFFSET_BITS=64 -D_LARGE_FILES -D__WXMAC__ -DWXMAKINGDLL
For 2.5.2, Other C Flags =
-D_FILE_OFFSET_BITS=64 -D_LARGE_FILES -D__WXMAC__ -DNO_GCC_PRAGMA
For CVS HEAD, Other C Flags =
-D_FILE_OFFSET_BITS=64 -D_LARGE_FILES -D__WXMAC__ -DNO_GCC_PRAGMA
Other Linker Flags =
-framework Carbon -framework System -liconv
Product Name = notebook
Generate Debug Symbols = checked
Unstripped Product = checked
Optimization Level = None
(You can set it higher later after you get used to the debugger.)
For 2.4.2, Header Search Path =
/Users/yourname/wx/ver/include
For 2.5.2, Header Search Path =
/Users/yourname/wx/ver/lib/wx/include/mac-2.5 /Users/yourname/wx/ver/include
For CVS HEAD, Header Search Path =
/Users/yourname/wx/ver/lib/wx/include/mac-2.5 /Users/yourname/wx/ver/include
(When you start writing your own code, you will also add your
own header file directories in the Header Search Path as needed.)
Close the settings window.
- Click "Build, Show Detailed Build Results"
- Click "Build, Build and Run"
Verify there are no errors in the "Build Results" window.
Fix any errors you see.
Repeat until the program works.
You can also read the troubleshooting notes below.
---------------------------------------------------------------------
Troubleshooting tips for compile-time errors:
- If Xcode can't find a header *.h file, go back and check your
'Header Search Path' under the Build Settings window. Make
sure the header file is in the wx subdirectory of the directory
in the Header Search Path.
- Sometimes Xcode gives the error "Undefined symbols", but it doesn't
tell you which symbols are undefined. This is quite frustrating
because you can't define the undefined symbols if you don't know
which symbols are undefined. I've submitted this as a bug to Apple.
In the meantime, here is the workaround: use xcodebuild from
the command line and it will tell you which symbols are undefined.
Here are the steps:
Exit Xcode.
Your project will be saved as notebook.xcode for example.
Run Terminal
In Terminal, cd to your working directory
Type "xcodebuild -buildstyle Development"
Now you will see the complete error messages including the names
of the undefined symbols. You need to fix them by adding the missing
source code or libraries to the project. After you have fixed
the Undefined Symbols, you can go back to work in Xcode again.
There is actually a button to show you the results of the linking step, including any
undefined symbols: In the Build window, below the toolbar, at the far right of the line
that says "Build failed (XX error, XX warning". The icon looks like a small paragraph of
text on a white background. Alternatively, you can drag the handle on the bottom of
Build window up to reveal the linking results. This works in Xcode 1.2. -- Adrian
<pre>
- Sometimes your build settings are incorrect. Open two Terminal
windows. In the first one, compile a working sample: cd ~/wx/ver/samples/notebook make clean make In the second one, build with xcodebuild which uses your project settings: cd ~/test/notebook xcodebuild clean xcodebuild -buildstyle Development Compare the output of the two builds. Many things will appear different but actually there will be just one or two wrong settings. You'll have to be a detective to determine which settings are wrong.
- Sometimes you are missing some header files. If the compiler
complains about an error for a symbol, check that you #include a header file that defines the symbol. If the compiler can't find the header file, you'll need to add the path under "Header Search Path" in the build settings.
Troubleshooting tips for run-time errors:
- If your program crashes when compiled from Xcode,
but does not crash when compiled from the "samples" makefile, then it means that your compiler settings in Xcode do not match the compiler settings you used when you compiled the wxWidgets library. You can verify the compiler settings using xcodebuild as described above under "Troubleshooting tips for compile-time errors"
- To use the debugger, choose "Debug, Show Debugger".
Open a *.cpp file and click in the left column to set breakpoints. Click "Build and Debug" When you stop on a breakpoint, you can choose to "Step Over", "Step Into", "Step Out", "Continue", etc. You can click "Debug, Expressions..." to examine variables.
- If you want to debug beyond your code and into the wxWidgets code,
you need to do three things: (1) build a debug version of the wxWidgets library, (2) add this debug library to your Xcode project and (3) add the __WXDEBUG__ compile flag to your project. Here are the three steps in detail: (1) Go to a Terminal Window cd ~/wx/ver make clean ./configure --enable-debug --disable-shared make (2) Go to Xcode Choose "Build, Clean" Make a list of the *.a frameworks in the project Highlight each framework *.a file and press "delete" Click "Projects, Add Frameworks..." Add back the same frameworks with a "d" in the name for 'debug'. (3) In the left column of Xcode, click on "Targets, notebook" Click on "Project, Get Info..." Click on the "Build" tab. Add this additional entry to "Other C Flags": -D__WXDEBUG__ Click "Build, Build and Debug"
Use of 'make install'
In many places in the wxWidgets instructions, you're told to do this sequence:
make make install
The 'make install' is usually not needed with Xcode and therefore it was not used above. It fact, it has some disadvantages which should be noted:
1) It takes longer to do both 'make' and 'make install' especially since
you have to switch to an administrator account to do the
'make install' part.
2) You will have two copies of headers and libraries, and it is easy for
them to get out of sync and cause compile errors.
3) If you ever switch to a new version of wxWidgets, you usually have
to remember to remove the old version from /usr/local or you might
get confusing errors during the compile
If you want to do 'make install' anyway, then here are some tips:
- If wxWidgets doesn't compile, it may be because you have a conflict
with a previously installed version. You should remove any prior
versions of wxWidgets and try compiling again. DANGER AHEAD:
You will need to remove the following files and directories using
an administrator account and using "sudo rm" to remove the files:
- The folder /usr/local/lib/wx
- The folder /usr/local/include/wx
- The folder /usr/local/share/wx
- Any files starting with wx in /usr/local/bin
- Any files starting with libwx in /usr/local/lib
BE CAREFUL. It is vital that you don't delete the wrong system
files here. Don't forget to exit your administrator account as
soon as you are done with this task. Then return to your wx
directory and try 'make clean' and make' again.
- The installation files for wxWidgets will be put in a directory
called /usr/local/lib but these files aren't normally visible from
Finder. As a developer, you will occasionally need to go there
with Finder. Therefore you must do these amazing steps in Finder:
Go to the Finder.
Click "Go, Go to folder..."
Enter "/usr"
Click "Go"
Observe that "usr" appears in the title bar with a folder icon to the left.
Drag the folder icon of "usr" to the left column of the Finder
so that you can now get to "usr" from Finder. You will need this often.
- To actually run 'make install' you must be in an administrator account.
You can use these steps:
In the Terminal window, type these commands, replacing "yourAdminAcct"
with the name of your admin account:
su yourAdminAccount
{enter admin password}
sudo make install
{enter admin password}
exit
Doublecheck that you typed 'exit' above or you will be in the
wrong account. Type 'whoami' to verify you are back to your
user account.
- If you choose to use 'make install' then you'll have to remember
to do it every time you compile the wxWidgets library. Otherwise you won't be able to see the effect of any changes you made.
</pre>
The steps and troubleshooting tips described above should get you started with Xcode. And you can start writing your own software as soon as possible.
By the way, I'm actually amazed at how good wxWidgets looks on Mac OS X. Thanks to everyone who worked on the port to Mac OS X.
Good Luck!!
[edit] Using darwinports
I used darwinports to install wxWidgets and found one hiccup. You need to add the include path for the wx/setup.h file in addition to the include path for the other wx include files.
On my system all of my ports are installed in /usr/local/ports so I had to also include the directory /usr/local/ports/lib/wx/include/mac-2.4.
- John Mehringer (john@mehringer.com)
[edit] add to Header Search Path
I could not get it to build from within xcode until I added the following to the Header Search Path:
/usr/local/lib/wx/include/mac-2.4
- Paul Heller (comodeler@earthlink.net)
[edit] Using wx-config
To get the correct defines and paths, it's a good idea to run wx-config from the command line and just copy the relevant output to the Xcode settings (instead of copying from the text above).
- Fredrik Roubert (roubert@df.lth.se)
