Getting Started

This is a brief guide which should help those unfamiliar with installing and using DialogBlocks and wxWidgets on any of the major supported platforms. It's geared towards getting the tools up and running and doesn't cover detailed editor use: please see the DialogBlocks manual for further details.

Getting started on Windows

These are the basic steps you need to take:

Get and install DialogBlocks;
get and install wxWidgets (if not done in Step 1);
get and install a compiler (if not done in Step 1);
run DialogBlocks to compile wxWidgets and a sample project.

1. Installing DialogBlocks

If you don't already have a compiler and wxWidgets on your computer, you might like to download the DialogBlocks Developer Bundle, which has the usual version of DialogBlocks along with a recent version of wxWidgets and the net-based installer for the free MinGW compiler. This can make your installation experience smoother than finding and installing the bits and pieces separately.

Then run the DialogBlocks installation program. This will create a program group called Anthemion DialogBlocks x.y (or other name if you have chosen a different name). This folder can be accessed via the Start menu under Programs. The folder contains shortcuts to the program, help file, and Uninstall program. If you have installed the Developer Bundle, wxWidgets and/or MinGW will also be installed, and DialogBlocks will automatically be aware of these components.

You can uninstall DialogBlocks either by double-clicking the Uninstall DialogBlocks icon in the DialogBlocks group, or by invoking the Windows Control Panel, double-clicking on Add/Remove Programs, and then choosing the Anthemion DialogBlocks item.

2. Installing wxWidgets

If you already installed wxWidgets using the wxWidgets Developer Bundle, this may not be a separate step.

Install the latest official release from the wxWidgets web site (something like wxMSW-2.8.12-Setup.exe), and run the installer. Note that this doesn't build any libraries - it only installs the source, samples and manual. You'll build one or more libraries in Step 4.

3. Installing a compiler

DialogBlocks will work with a variety of compilers, and if you don't want to use MinGW (which is a somewhat slow compiler), you can use Microsoft's free Visual C++ Express, OpenWatcom C++, or Digital Mars C++. If installing VC++, don't forget to install the Platform SDK and set the DialogBlocks path for it. See Links for more on these options. For heavy-duty work, we would recommend using a Microsoft compiler but you don't need the most recent version - VC++ 6 is perfectly adequate.

Note that Visual C++ 2012 with the Windows 8 SDK cannot be used to create applications that run on Windows XP, so you may wish to use Visual C++ 2010 and the Windows 7 SDK. If your application requires the Active Template Library (ATL), for example if you're using Microsoft's SAPI, you can get ATL by installing the Windows 7 Device Driver Kit (DDK) since it's not installed with Visual C++ Express.

4. Running DialogBlocks

The first time you run DialogBlocks, it will take you through a Setup Wizard to gather some initial information about your wxWidgets distribution and compiler. DialogBlocks tries to guess locations and versions but check that these are correct.

Next, open the sample and using the drop-down list in the toolbar, select an appropriate build configuration for the compiler you're using, such as MinGW Debug or VC++ Debug. Press the green toolbar button or F8 to build the project - if the wxWidgets library suitable for this project doesn't already exist, DialogBlocks will ask you if you wish to build it. Answer Yes, and then once it's built, press F8 again to build the project. Click on the green toolbar button to run the application.

Getting started on Linux

These are the basic steps you need to take:

Get and install Linux and compilation tools;
get and install wxWidgets;
get and install DialogBlocks;
run DialogBlocks to compile wxWidgets and a sample project.

1. Installing Linux

First, you need to get and install a Linux distribution. There are many, but an increasingly popular and easy to install distribution is Ubuntu Linux. For those who don't like the Unity window manager in Ubuntu, there's always Linux Mint.

If you don't intend to use Linux as your main operating system, or you wish to try out several distributions, you will find it extremely helpful to use virtual machine software such as VMware Workstation. The Linux version of DialogBlocks is entirely developed and compiled on a Windows 8 laptop running various flavours of Linux, Solaris and FreeBSD via VMware. You can try out VMware using the free Player software, a cut-down version of VMware Workstation that only runs pre-packaged virtual machines, called 'appliances'. You can try out the Ubuntu appliance, saving you the bother of most of the initial installation steps.

When you have installed your Linux distribution, you will usually need to install further packages in order to compile wxWidgets application. In Ubuntu, open Synaptic Package Manager and get these packages:

g++
libgtk2.0-dev
libgnomeprintui-dev

Depending on what tools you wish to use, you may also wish to get emacs and subversion packages too.

You might also wish to make a ~/bin directory for your private commands (such as dialogblocks invocation script). Then you can edit your .bashrc file with emacs, vi or another editor and add this line at the end:

PATH=~/bin:.:$PATH

This will make sure that commands in your private bin directory and in the current directory will be found.

A note about wxGTK
The GTK+ port is the most highly developed of the Unix-based ports; there are also X11 and Motif ports, but they are not recommended for normal use. So, your wxWidgets applications will use the GTK+ widget set and will look best with the GNOME desktop, but will also work fine under KDE.

2. Installing wxWidgets

You'll probably want to get the latest official version, which at the time of writing is wxWidgets 2.8.12. It is highly recommended that you get the source version of wxWidgets, so that you have maximum flexibility in compiling the version you need, and the ability to fully debug your application.

You can get the wxGTK source archive only, or the whole wxWidgets source tree. (You can also get the latest source by CVS, but this is not as convenient and reliable as downloading an official release.)

Unarchive wxWidgets into a suitable directory, for example in your home area, using a command such as:

tar xvfz wxGTK-2.8.12.tar.gz

Later, DialogBlocks will help you compile suitable configurations. However, if you want to check immediately that wxWidgets compiles and builds, you can do something like this:

cd ~/wxWidgets-2.8.12
mkdir build
cd build
../configure
make
cd samples/minimal
make
./minimal

This will build configure and wxWidgets using default options, then building and running a sample. If something went wrong in the configuration process, you can look at build/config.log to see where it failed. It may indicate that you have forgotten to install the GTK+ development libraries, or g++, for example.

3. Installing DialogBlocks

If you use the .deb or .rpm distribution, this is very easy; just download the package and open it in your package manager. DialogBlocks should then turn up on the Development or Programming menu group.

To install using the tarball, download DialogBlocks-x.yz.tar.gz and in a terminal window, unarchive it to a suitable location in your filesystem. For example:

  cd ~
  mkdir tmp
  cd tmp
  tar xvfz ../Desktop/DialogBlocks-5.00-i386.tar.gz

This will produce two files - DialogBlocksData.tar.gz and installdb. Run installdb, following the instructions, and DialogBlocks and its run script 'dialogblocks' will be installed in your preferred directories. The script directory you are prompted for would typically be your ~/bin directory if doing a local install. The installation script will give you the choice of system-wide installation (requiring root access) or local installation (not requiring root access).

Now you can type 'dialogblocks' in a terminal window to run the application.

If you wish to maintain several DialogBlocks installations simultaneously, rename the original dialogblocks script before installing the updated version.

To uninstall DialogBlocks after using the tarball installation, run the uninstalldialogblocks-x.xx script created by the install.

4. Running DialogBlocks

When running DialogBlocks for the first time, the Setup Wizard invites you to enter the location of your wxWidgets distribution.

Then you can open the sample project and select a suitable build configuration in the toolbar drop-down control, such as GTK+ Debug. When you try to build your project (by clicking on the green arrow in the toolbar, or pressing F8, or choosing Build Project from the Build menu), you will initially get a message informing you that wxWidgets is not yet built for that configuration. Answer Yes to build wxWidgets, and then if this is successful, you can press F8 again to build the project, and/or the green button to build and run the sample.

Although it may seem a bit backwards to build wxWidgets after trying to build the project, this ensures that a correct configuration of wxWidgets will be present according to your project settings. If you add further configurations (for example, with Unicode switched on) then DialogBlocks will know to make a separate build of wxWidgets with matching settings. Further projects using the same settings will use the previously-built libraries.

By default, DialogBlocks places the various wxWidgets builds (objects and libraries) under your wxWidgets installation. For example, a GTK+ Release build will go in the GCCBuildReleaseGTK2 subdirectory. If there's a problem with configuring and building wxWidgets, look in these directories for the config.log file: it will provide heavy hints about configuration problems, for example missing libraries or a partially installed compiler.

Maximizing your application's Linux compatibility
You will probably need to build your releases on a relatively old version of Linux known to be compatible with both old and new distributions. DialogBlocks is built using Ubuntu 8.04 for this reason. However, you can still use a more recent version of Linux for general development work, especially if you have a way of synchronizing your work with multiple environments, perhaps using a version control systems such as CVS.
Increasingly it's hard to provide a single distribution that works on all Linux variants, mainly because of the proliferation of different versions of libpng. So you may find yourself having to build multiple versions of your application for distributions that are not compatible with your main Linux build. Testing and building in several virtual machines is the best way to ensure compatibility.

Getting started on Mac OS X

This section assumes that you will compile using makefiles. DialogBlocks doesn't generate Xcode project files at present, but you can still use DialogBlocks and Xcode together if you create your project files yourself.

These are the basic steps you need to take:

Get and install the Apple developer tools;
Get and install wxWidgets;
get and install DialogBlocks;
run DialogBlocks to compile wxWidgets and a sample project.

1. Installing the Apple developer tools

You will need to go to the Apple Developer Connection site and sign up as an ADC member to download the Xcode developer kit for free. Follow Apple's instructions for downloading and installing the tools. Alternatively, you can install them from your Mac OS X DVD.

2. Installing wxWidgets

You'll probably want to get the latest official version, which at the time of writing is wxWidgets 2.8.x. It is highly recommended that you get the source version of wxWidgets, so that you have maximum flexibility in compiling the version you need, and the ability to fully debug your application.

You can get the wxMac source archive only, or the whole wxWidgets source tree. (You can also get the latest source by CVS, but this is not as convenient and reliable as downloading an official release.)

Unarchive wxWidgets into a suitable directory, for example in your home area, using a command such as:

tar xvfz wxMac-2.8.12.tar.gz

Later, DialogBlocks will help you compile suitable configurations. However, if you want to check immediately that wxWidgets compiles and builds, you can do something like this:

cd ~/wxWidgets-2.8.12
mkdir build
cd build
../configure
make
cd samples/minimal
make
./minimal

Important note: When building on Mac OS X 10.6 (Snow Leopard) and above, you will need to change configuration settings in order to compile applications that run on 10.3.9 and above, and you need to install the 10.4 SDK. From DialogBlocks 4.34, you can change the configuration as follows:

SDK path = /Developer/SDKs/MacOSX10.4u.sdk (or wherever your SDK is)
Libiconv path = /Developer/SDKs/MacOSX10.4u.sdk/usr (or similar)
Unicode mode = Unicode
Processor type = Mac Universal (to build universal binaries for Intel/PowerPC) or just 32-bit (for 32-bit only)
Minimum OS version = 10.3.9

If the minimum OS version is 10.3 or 10.4, DialogBlocks will set the C++ command, C command and linker command to g++-4.0 since it is necessary to use the older compiler for compatibility.

If you've already built wxWidgets, be sure to clean the wxWidgets and project builds before trying again after changing settings.

For more information on configuring wxWidgets for Mac, see the wxWidgets Wiki.

3. Installing DialogBlocks

Download DialogBlocks-x.yz.dmg: it should automatically open in a Finder window. Drag DialogBlocks to a suitable folder such as your Applications folder.

Now you can double-click on the DialogBlocks icon to run the application.

To uninstall DialogBlocks, simply remove the DialogBlocks folder.

4. Running DialogBlocks

When running DialogBlocks for the first time, the Setup Wizard invites you to enter the location of your wxWidgets distribution.

Then you can open the sample project and select a suitable build configuration in the toolbar drop-down control, such as GCC Debug Mac. When you try to build your project (by clicking on the green arrow in the toolbar, or pressing F8, or choosing Build Project from the Build menu), you will initially get a message informing you that wxWidgets is not yet built for that configuration. Answer Yes to build wxWidgets, and then if this is successful, you can press F8 again to build the project, and/or the green button to build and run the sample.

By default, DialogBlocks places the various wxWidgets builds (objects and libraries) under your wxWidgets installation. For example, a Mac Release build will go in the GCCBuildReleaseMac subdirectory. If there's a problem with configuring and building wxWidgets, look in these directories for the config.log file: it will provide heavy hints about configuration problems, for example missing libraries or a partially installed compiler.

Getting started on other platforms

DialogBlocks and wxWidgets also support Solaris x86 and FreeBSD; the process of installing and using wxWidgets and DialogBlocks is similar to that for Linux. The additional notes below on compiling applications on Solaris with gcc may be helpful.

Note that you can also use DialogBlocks to write applications that will run on platforms that DialogBlocks does not currently support, by using DialogBlocks on one platform and compiling the generating sources on another.

GCC on Solaris

GCC and other required GNU tools may not initially be found when you try compiling applications. You need to do the following:

Edit the .profile file in your root directory and Add /usr/sfw/bin to the front of your $PATH so that gcc is found.
Do an ln -s gmake make in /usr/sfw/bin.
Do an ln -s gar ar in /usr/sfw/bin.
Do an ln -s granlib ranlib in /usr/sfw/bin.

Working methods

You will probably have your own idea of how you'll use DialogBlocks (and wxWidgets), but an example of one method of development may be helpful. This is how Anthemion Software's applications are developed - not necessarily the best method, just one possibility.

The bulk of Anthemion's application development happens on Windows XP. DialogBlocks is used to generate its own dialogs (!) and those of our other applications (HelpBlocks and Writer's Cafe). The IDE of choice is good old Visual C++ 6, which has a good compiler and executable speed, and excellent debugging abilities. Some editing is done within DialogBlocks, and some within the VC++ editor, but confusion is minimized since each tool will reload files changed by an external tool. In our case, DialogBlocks isn't used to maintain all application files, only the dialog-related ones, and we use a hand-tweaked VC++ project. Two configurations are used: Unicode Debug, and Unicode Release. Having a debug configuration on all platforms is essential.

When a new release is to be made, source changes are committed to CVS and this source synchronized with virtual machines (on the same laptop) for Linux, FreeBSD and Solaris. The source is also synchronized with a MacBook Pro; so only two physical computers are involved. It's possible to run Mac OS X on the PC and reduce this to only one machine, but this would not be legal. Alternatively, you can legally run Windows, Linux, FreeBSD and Solaris using VMware or Parallels on a Mac, and thereby use only one machine for compiling all Intel and PowerPC-based distributions.

The applications are built on the non-Windows platforms using a standard makefile, driven by a script that can do the building as well as the tarring up and copying to the web site (via curl). So, on the non-Windows platforms, there is very little interaction required besides testing and occasional debugging using gdb running within emacs.

If your favourite working environment is Linux, you can of course run Windows in a VM. Although in theory you could cross-compile for Windows on Linux, in reality it's tricky to set up and you're going to have to test it on a real copy of Windows anyway, so it's probably not worth the hassle.

To avoid trouble with dynamic libraries, Anthemion's applications are linked statically where possible; they are fully statically linked on Windows, and linked statically to the wxWidgets library only on Unix and Mac. On Linux, the underlying GTK+ toolkit is always dynamically linked to applications - trying to statically link will not work. On Mac, universal binaries are used which means that they will run on both Intel and PPC machines.

Note that while wxWidgets attempts to exhibit the same behaviour across all platforms, there are some small differences and you should not assume that your application will work on platform B if you have tested it on platform A. Some small changes may be needed (for example to accomodate large control decorations on Mac OS X or to accomodate button layout differences), and sometimes 'wrong' code might work on one platform, but fail on another. So factor in testing on all supported platforms. When you're familiar with wxWidgets on all platforms, there will be fewer and fewer surprises and the need for extensive testing and debugging equally on all platforms with every source change will diminish.

Where next?

We haven't mentioned debugging in detail in this section: DialogBlocks has a simple built-in way of driving the GNU debugger gdb, but for serious work you need to find out more about the debugger that comes with your compiler. The simplest option on Linux and Mac is to use gdb, either standalone or using another tool to drive it such as emacs. For more details on gdb commands, see the gdb manual in the DialogBlocks Reference tab.

The How To... section of the DialogBlocks manual has information on how to work with configurations, compile your projects and so on.

You can subscribe to the Anthemion Developer Tools mailing list for discussion and information about new releases.

There are also the mailing lists and forum at the wxWidgets web site, and last but not least, the wxWidgets book to help speed up your wxWidgets development.

Back to the DialogBlocks home page