Using wxWidgets with Borland CPP Builder 5
From WxWiki
---
Written by Tim Griesser, October 23, 2002 rev. 1.0
Updated by Tim Griesser, November 5, 2002 rev. 1.1
Added troubleshooting tips, and advice to disable memory debugging.
Updated by Chris Elliott, Jan 30, 2003 rev 1.2 (comments in brackets)
Updated by Tim Griesser, December 17, 2004 rev 1.3 for version 2.5.3
---
These instructions describe how to use wxWidgets
with the Borland C++ Builder IDE on Microsoft Windows.
The instructions were tested with
- wxWidgets 2.5.3
- Borland C++ Builder Professional Version 5 (Build 12.34)
- Microsoft Windows XP Home Edition Version 5.1 (Build 2600)
Hopefully these instructions will help you scale the learning
curve of getting started.
- Install Borland C++ Builder 5, in a directory without spaces.
The default directory is "c:\Program Files\Borland\CBuilder5"
but don't use that default. Change it to something without
spaces such as c:\bcb5. Also, be sure to use either
the custom install or the full install to get the Microsoft
help files for the Windows SDK. These are very useful
files but are not installed unless you ask for them.
- If you already installed Borland C++ Builder 5 with the
default directory, then you may be able to use the 8.3
format of the name: c:\progra~1\borland\cbuilder5
- Go to http://www.wxwidgets.org and download wxMSW-2.5.3-setup.zip
or a newer version if you like.
- Unpack wxMSW-2.5.3-setup.zip. On modern versions of Windows
you can do this by just clicking on the *.zip file. A new
directory will be created called wxMSW-2.5.3-setup.
- Go to this new directory and run the installation program setup.exe.
The default installation directory is c:\wxWidgets-2.5.3.
You can accept this name or pick another one but be sure to
use a name without spaces. For example, over time you might use other
versions of wxWidgets so you could keep all of these versions
in a single wx directory using a name structure like
this: c:\wx\v253. You can pick any directory names without
spaces that appeal to you, however the rest of these instructions
will assume you picked the default name of c:\wxWidgets-2.5.3
- Start a "Command Prompt Window" (also known as a DOS window.)
- Go to the wxWidgets source directory and compile the library:
cd c:\wxWidgets-2.5.3\build\msw
make -f makefile.bcc
The compile will run for several minutes and will create a debug
version of the wxWidgets library. This will allow you to use
your debugger to debug your own code plus the wxWidgets code.
The compile will create many new files. The most important
files are these:
In c:\wxWidgets-2.5.3\lib\bcc_lib,
the files *d.lib are the debug libraries which you will link to your code
In c:\wxWidgets-2.5.3\lib\bcc_lib\mswd\wx
the file setup.h describes your wxWidgets configuration.
In your projects you must always have the directory
c:\wx\v253\lib\bcc_lib\mswd first in your include path
so the compiler can find "wx\setup.h"
In c:\wxWidgets-2.5.3\include\wx
the files *.h and msw\*.h will be used when compiling your
projects. Therefore in your projects you must always have the
directory c:\wxWidgets-2.5.3 in your include path
so the compiler can find "wx\*.h" and "wx\msw\*.h" files
- Go to the wxWidgets source directory and compile the library
again, but this time not as a debug version
cd c:\wxWidgets-2.5.3\build\msw
make -f makefile.bcc BUILD=release
The compile will run for several minutes and will create a release
version of the wxWidgets library. This will allow you to use
your debugger to debug your own code if you wish, but you will not
be able to step through the wxWidgets code. This makes it easier
for you to debug your own code without getting lost in the
wxWidgets code. The compile will create many new files. The most
important files are these
In c:\wxWidgets-2.5.3\lib\bcc_lib,
the files *.lib which do not end if *d.lib are the release libraries
which you will link to your code if you don't need to debug
wxWidgets.
In c:\wxWidgets-2.5.3\lib\bcc_lib\msw\wx
the file setup.h describes your wxWidgets configuration.
If you are using the release libraries, then in
your projects you must always have the directory
c:\wx\v253\lib\bcc_lib\msw first in your include path
so the compiler can find "wx\setup.h"
In c:\wxWidgets-2.5.3\include\wx
the files *.h and msw\*.h will be used when compiling your projects.
Therefore in your projects you must always have the
directory c:\wxWidgets-2.5.3 in your include path
so the compiler can find "wx\*.h" and "wx\msw\*.h" files
- Try to compile and run a sample file such as the "widgets" sample.
cd c:\wxWidgets-2.5.3\samples\widgets
make -f makefile.bcc
The executable is in the debug directory bcc_mswd. Run it by typing:
bcc_mswd\widgets.exe
Alternatively you can run it by clicking on the icon for
c:\wxWidgets-2.5.3\samples\widgets\bcc_mswd\widgets.exe
This is a good example of many widgets which can be created
with wxWidgets. Experiment with it for a while.
- Now repeat those same steps but for a release build.
Try to compile and run a sample file such as the "widgets" sample.
cd c:\wxWidgets-2.5.3\samples\widgets
make -f makefile.bcc BUILD=release
The executable is in the release directory bcc_msw. Run it by typing:
bcc_msw\widgets.exe
Alternatively you can run it by clicking on the icon for
c:\wxWidgets-2.5.3\samples\widgets\bcc_msw\widgets.exe
You won't actually see any difference in the sample unless you try
to run it in the debugger.
- Try to repeat the same steps above for one of the demos such as
c:\wxWidgets-2.5.3\demos\bombs or c:\wxWidgets-2.5.3\demos\life.
Experiment with these demos.
- Compile some of the other samples and demos and then run them to
see the look-and-feel of wxWidgets. There are many great
examples which you can learn from. A complete list of the
samples and demos is found at this link which you can
open in your browser: c:\wxWidgets-2.5.3\docs\html\index.htm
- If everything above worked, you are ready to try to compile
with the Borland IDE by using the steps below.
- You will be configuring the Borland IDE to use the same compiler
settings as makefile.bcc. The directions below use the
sample project "controls" to get you started. Then you
can repeat these same steps for your own creations.
- Create a new empty directory in which to do your work. Copy these
files from c:\wxWidgets-2.5.3\samples\controls to your new directory.
Do not move them; just copy them.
- controls.cpp
- controls.rc
- mondrian.ico
- test2.bmp
- the entire icons directory
- The instructions below will help you to use the debug libraries
so you can step through the wxWidgets code in the debugger.
Where applicable, the instructions will also tell you the changes
you'll need if you prefer to use the release libraries. When you
use the release libraries, you will not be able to step through
wxWidgets code. This might make it easier to debug your own code
because you won't get lost in wxWidgets code.
- Start Borland C++ Builder
- Choose "File, New..., Console Wizard, OK"
- In the Console Wizard to the following:
In Source Type, choose C++. Remove the checkmarks next
to "Use VCL", "Multithreaded", and "Console Application".
Set a checkmark on "Specify project source".
Press the "..." button and click on "controls.cpp" from
your new directory. Click Open. Click OK.
- Choose "File, Save Project As..," and save it as "controls.bpr"
in your new directory.
- Click Project, Options, Directories/Conditionals.
In the "Include Path" line, click the "..." button.
In the Directories Window, click the "..." button.
Select the directory C:\wxWidgets-2.5.3\lib\bcc_lib\mswd
Click OK, Click Add
Click the "..." button again.
Select the directory C:\wxWidgets-2.5.3\include
Click OK, Click Add
The list of include directories should now be:
$(BCB)\include
$(BCB)\include\vcl
C:\wxWidgets-2.5.3\lib\bcc_lib\mswd
C:\wxWidgets-2.5.3\include
Click OK
(If you prefer to use the release libraries,
simply replace
C:\wxWidgets-2.5.3\lib\bcc_lib\mswd
with
C:\wxWidgets-2.5.3\lib\bcc_lib\msw
above)
In the "Library Path" line, click the "..." button.
In the Directories Window, click the "..." button.
Select the directory C:\wxWidgets-2.5.3\lib\bcc_lib\mswd
Click OK, Click Add
The list of library directories should now be:
$(BCB)\lib\obj
$(BCB)\lib
C:\wxWidgets-2.5.3\lib\bcc_lib\mswd
Click OK
(If you prefer to use the release libraries,
simply replace
C:\wxWidgets-2.5.3\lib\bcc_lib\mswd
with
C:\wxWidgets-2.5.3\lib\bcc_lib\msw
above)
In the "Debug source path" line, click the "..." button.
In the Directories Window, click the ..." button.
Select the directory C:\wxWidgets-2.5.3\src\common
Click OK, Click Add
Click the "..." button again.
Select the directory C:\wxWidgets-2.5.3\src\msw
Click OK, Click Add
Click the "..." button again.
Select the directory C:\wxWidgets-2.5.3\include\wx
Click OK, Click Add
The list of paths should now be:
$(BCB)\source\vcl
C:\wxWidgets-2.5.3\src\common
C:\wxWidgets-2.5.3\src\msw
C:\wxWidgets-2.5.3\include\wx
Click OK
In the "Conditional Defines", use this line:
_DEBUG;__WXMSW__;__WXDEBUG__
(If you prefer to use the release libraries,
simply replace
_DEBUG;__WXMSW__;__WXDEBUG__
with
__WXMSW__
above)
Click OK to close the Project Options dialog box.
- Click Project, Options, Compiler, Warnings,
Check "W8057 Parameter is never used", OK, OK
(Actually the makefiles turn this warning off, but
my own personal preference is to have it on.
You can decide if you want this warning for your own
work or not.)
- Click Project, Options, Compiler,
Check "Treat enum types as ints"
Click OK
- Click Project, Options, Advanced Compiler,
Data Alignment = Quad Word
Register variables = Automatic
Click OK
- Click Project, Options, C++
Uncheck zero length empty base classes
Uncheck zero length empty class members
Click OK
- Click Project, Add to Project, Files of Type: Library (*.lib)
Navigate to c:\wxWidgets-2.5.3\lib\bcc_lib
Select these three files
wxmsw25d_core.lib
wxbase25d.lib
wxpngd.lib
wxzlibd.lib
Click "Open"
In your own projects, you may need more or fewer libraries.
This project "controls" just needs these four. If you need
more, the linker will let you know by giving you errors
about "unresolved symbols"
(If you prefer to use the release libraries,
simply replace
wxmsw25d_core.lib, wxbase25d.lib, wxpngd.lib, wxzlibd.lib
with
wxmsw25_core.lib, wxbase25.lib, wxpng.lib, wxzlib.lib
above)
- Click Project, Add to Project, Files of Type: Resource (*.rc)
Select "controls.rc" from your working directory. Click Open.
- Save your work by clicking "File, Save All"
- Click "Project, Build controls".
This forces a new compile of all files with your new
project settings. You must remember to use "Build"
to recompile everything again anytime you make
changes to project options.
If you just make changes to source code, then you can
just click "Run" instead of "Build". Choosing "Run"
will compile only the files which have changed rather than
compiling everything.
There may be warnings in your first compile. You should read
through them, but you can probably ignore them for now. Don't
ignore warnings forever though because they are likely going
to cause you trouble someday if you ignore them too long.
- Click "Run, Run" or click on the green triangle or hit F9 to run.
At this point the "controls" example should be running
correctly. If not, see below for troubleshooting tips.
- Now we'll try to use the debugger.
- To use the debugger, you'll first need to set a breakpoint on
an interesting line in a callback routine.
Click "View, Project Manager"
Click the "+" next to "control.exe"
Double-click on "controls.cpp"
Find the line with "void MyPanel::OnChoiceButtons( wxCommandEvent &event )"
Click on the left column next to this line.
The line should change color to indicate you have set a breakpoint
- Hit F9 to run the program
- Now in the "controls" program,
click on the "wxChoice" tab
click on the "Select #2" button
This should hit the breakpoint you set in the debugger, so
the debugger should reappear at that line.
- Your choices in the debugger are:
click F8 to step to the next line
click F7 to trace into the current line
click F9 to continue running the program until the next breakpoint
click "Run, Program Reset" to abort the program
Experiment with those choices.
Notice that if you used the debug libraries you can use F7 to
step through the wxWidgets code. However, if you used the
release libraries, you cannot step through the wxWidgets code
except the inline functions and macros appearing in *.h files.
- Hopefully these instructions have gotten you up and running
in a short time. Now you should read the wxWidgets manual
and the wxWidgets samples and demos to learn how to program
in wxWidgets.
---------------------------------------------------------------------
Troubleshooting tips for compile-time errors:
- Click "View, Project Manager" and verify that your project
has an rc file such as myfile.rc which contains this line:
#include "wx/msw/wx.rc"
- Do not use "Project, Add to project" to add "wx/msw/wx.rc"
to your project. If you do this, Borland C++ Builder
will add "include/wx/msw" to your include path which will
break your compiles.
- Click "Project, Options, Directories" and examine the "Include Path"
to verify that "C:\wxWidgets-2.5.3\include\wx\msw" is not listed in
your include path.
---------------------------------------------------------------------
Troubleshooting tips for run-time errors:
- If the program complains that you have mismatched debug
and non-debug versions of the libraries, then verify that you
have done one or the other of these two choices:
a) You have used only *d.lib libraries and you have
set the define __WXDEBUG__
b) You have used no *d.lib libraries and you have not
set the define __WXDEBUG__ or _DEBUG
- Be sure you have selected "Data Alignment = Quad Word" and
"Register variables = Automatic" under Project, Options, Advanced Compiler.
- If your "controls" program still crashes when compiled from the IDE, but
works fine when compiled from c:\wxWidgets-2.5.3\samples\controls\makefile.bcc,
it means that your compiler settings in the IDE do not match the
compiler settings you used when you compiled the wxWidgets library.
You must verify every compiler setting by doing the following:
- From the Borland IDE, click "Help, C++ Builder Help, Find"
and then search for "compiler options (alphabetical listing)"
This is an alphabetical listing of the C++ compiler options
such as -A, -B, -C, etc. Print it.
- From the Borland IDE, click "Help, C++ Builder Help, Find"
and then search for "linker options (alphabetical listing)"
This is an alphabetical listing of the liker options.
Print it.
- In a DOS window, go to c:\wxWidgets-2.5.3\samples\controls and run
the following command which forces a complete rebuild, writes
the output to a log file, and doesn't delete any temporary files.
make -B -K -f makefile.bcc > log.txt
If you examine log.txt, you will see the actual compile
options plus the use of a temporary file such as make0000.@@@
- From the Borland IDE, click "Project, Edit Option Source".
This will make a new file "controls.bpr.xml".
- Compare log.txt and make0000.@@@ from the makefile.bcc build
to controls.bpr.xml from the IDE to determine which compiler or
linker options are incorrectly set. There will be many differences
but most of them are unimportant. So your task will be to find
the important setting which is incorrect using the documentation
which you printed.
- Find the incorrect setting in the IDE and change it to the
setting which matches c:\wxWidgets-2.5.3\samples\controls\makefile.bcc
and then everything should work properly.
---------------------------------------------------------------------
The steps and troubleshooting tips described above should get the
IDE version of "controls" to work just as well as the version which
you compiled using "c:\wxWidgets-2.5.3\samples\controls\makefile.bcc".
The same steps and troubleshooting tips will get your own
projects working under the Borland C++ Builder IDE.
Good Luck!!
