---

Generating, Compiling, & Running Code

This chapter describes how to generate, organize, compile, and run the code for a PhAB application:

• Using the Build & Run dialog
• Generating application code
• How application files are organized
• Editing source
• Compiling & Linking
• Running the application
• Debugging
• Including non-PhAB files in your application

PhAB automatically generates everything that's required to turn your application into a working executable, including:

• code to handle the user-interface portion of your application
• stub C and/or C++ files for application-specific callbacks, module-setup functions, application-initialization functions, and so on
• all the files required to compile and link the application-Makefile, global header, main-line file, and prototype file.

By doing all this, PhAB lets you get on with the job of writing the code that implements your application's main functionality.

For most code generation, you use the Build & Run dialog. However, you can also generate some C and C++ stub files on the spot when using various dialogs to develop your application; use the icons that are located next to function or filename fields:

This means you're free to edit a callback function while still in the process of attaching it to the widget. You don't have to go into the Build & Run dialog, generate code from there, and then come back to write the function.

Using the Build & Run dialog

Think of the Build & Run dialog as the development center for building your applications. From this dialog, you can:

• generate the application code
• make (compile and link) your application
• debug your application
• edit code
• run your application

To open the Build & Run dialog, choose the Build & Run item from the Application menu or press F5.

---

If the Build & Run item is dimmed, your application hasn't been named yet. For more info, see "Saving an application" in the Working with Applications chapter.

---

PhAB automatically saves your application when you open the Build & Run dialog.

---

---

Sample Build & Run session.

The scrolling list displays the application source files that PhAB has generated, as well as any you've created by hand. This list may be empty if you're designing a new application and haven't yet generated any code.

Generating application code

When you make changes to your application, even within your own source files, you may need to generate the application code. Doing so ensures that the prototype header file, proto.h, is up to date. You can safely generate the code at any time - PhAB won't overwrite any code you've added to the stubs it generated earlier.

Before generating the code, PhAB saves your application if you've modified any modules. To minimize compile time, PhAB compiles only the files that have changed.

---

If you plan to use a global header in your application, you should set up the header before generating any code. For more information, see "Specifying application startup information" in the Working with Applications chapter, and "Global header file" in the Generating, Compiling, & Running Code chapter.

---

To generate your application code:

1. Click on the Generate button in the Build & Run dialog. Wait for the progress meter to reach 100%.
2. Click on Done in the progress dialog.

The file list now shows all the generated code files.

What PhAB generates

PhAB generates various files and stores them in the application's src directory.

---

Any filename that starts with ab is a PhAB file and shouldn't be modified at any time. If you try to edit an ab file, you could lose work (when PhAB overwrites the file) or experience incorrect behavior (when files get out of sync).

---

You can modify any other files that PhAB generates, with few conditions. These conditions are described in the following sections.

Here are the files that PhAB generates:

Makefile

Used to compile and link the application

Usemsg

A usage message for the application

abHfiles
abOfiles
abSfiles

External PhAB references in the Makefile

abdefine.h

Contains all the PhAB-generated manifests. PhAB includes this header in all C files.

abevents.h

Contains all the application's callbacks

abimport.h

The extern reference header that's included in all C files. See "Function prototypes", below.

ablinks.h

Contains all the application's module definitions

abmain.c

The application's main-line C file. This file starts with ab, so don't modify it. If you need to control the main-line processing, specify a mainloop function in the Application Startup Information dialog, as described in the Working with Applications chapter.

abmain.cc

If PhAB detects any C++ functions in your application, it generates abmain.cc instead of abmain.c. This file also starts with ab, so don't modify it.

abplatform

Contains a list of the platform directories for the application

abvars.h

Contains all the PhAB-generated global variables

abwidgets.h

Contains all the PhAB data references

proto.h

Contains the application's prototypes - see "Function prototypes", below. Don't rename this file.

Version control

Here are the files you need to save if you're using version-control software (PhAB can generate some of them, but it's a good idea to save them all):

abapp.dfn

Callbacks and other information - this is a binary file.

wgt/*

Widget resources - these might look like text, but they're binary.

src/*.{c,cc,cpp,C,h}

Source files and headers.

src/*files

Files that list non-PhAB source files. Be sure to save the non-PhAB source, too.

src/Makefile, src/*/Makefile

All the make files.

application_name.ldb

Your application's language database. Save any translation files as well.

You'll need to keep a matched set of all the files that PhAB generates; save the same version of the abapp.dfn, src/ab*, and wgt/*.wgt? files.

Tips on using CVS

It's easier to save a PhAB application in CVS than RCS. Here are some things to keep in mind:

• Flag the *.wgt? and abapp.dfn files as binary (-kb).
• Since binary files can't be merged, try to prevent multiple people from modifying the binary files at the same time. CVS doesn't support locking; the closest you can get is to set a "watch" on abapp.dfn (cvs watch on abapp.dfn).

  This way, if you just check out an application, your copy of abapp.dfn is read-only and PhAB doesn't let you load the application. If you do want to modify the application, you have to run cvs edit abapp.dfn, which makes the file writable. Even though this doesn't prevent other people from doing the same, it at least adds you to a list of "editors" on the CVS server that other people can query.

Function prototypes

PhAB generates function prototypes that are used by the compiler to check that your functions are called correctly. These prototypes are placed in abimport.h and optionally in proto.h. Here's how these files compare:

proto.h	abimport.h
Generated by parsing your source code.	Generated by looking at your application's settings.
Prototypes for all functions are generated.	Only prototypes known to PhAB (callbacks, setup functions, pointer-to-function resources) are generated.
You can have problems with preprocessor directives (see "Potential problems with generating proto.h"), unusual C constructs, syntax errors, and C++ code.	Prototypes don't depend on the source code.
Doesn't work with C++.	Contains the appropriate #ifdefs and extern "C" declarations required by C++.
Prototypes match what the functions look like.	Prototypes match what the functions are supposed to look like-if the source code is different, the compiler can detect it.

To suppress the generation of prototypes in proto.h:

1. Press F2 or from the Application menu, choose Startup Info/Modules to open the Application Startup Information dialog.
2. Click on the Generate empty "proto.h" file button.

Potential problems with generating proto.h

In the interests of speed, the program that scans your source files for function prototypes ignores preprocessor directives. This can cause some problems in proto.h.

For example, say we have the following code:

#ifdef DOUBLE
    for (i = 0; i < 18; i++, i++) {
#else
    for (i = 0; i < 18; i++) {
#endif
        x += 2 * (i + x);
        y += x;
    }

Since preprocessor directives are ignored, the prototype generator sees:

    for (i = 0; i < 18; i++, i++) {
    for (i = 0; i < 18; i++) {
        x += 2 * (i + x);
        y += x;
    }

The two opening braces will cause it some confusion, and an incorrect prototype will be generated. Look for this type of thing if the prototype generator is creating incorrect prototypes.

To fix the example above, we could remove the opening braces and put an opening brace on the line after the #endif. Alternatively, we could do the following:

#ifdef DOUBLE
#define ADDAMOUNT   2
#else
#define ADDAMOUNT   1
#endif

    for (i = 0; i < 18; i += ADDAMOUNT) {
        x += 2 * (i + x);
        y += x;
    }

How application files are organized

PhAB stores each application as a directory structure. This structure consists of a main directory that holds the application-definition file, two subdirectories that store the module files and application source code, and, potentially, directories for different development platforms:

---

---

Directories for a PhAB application.

The platforms directories are created if you generate your application for the first time after having installed Watcom C version 10.6 or later. You can choose the platforms on which to compile your application.

---

You should choose default as the platform unless you specifically need a different one. If you choose default, new versions of the compiler will be used automatically when they're installed.

---

Multiplatform applications

Here's what each directory contains if you generate your application for the first time after installing Watcom 10.6 or later:

appl

The name of this directory is the same as your application. It contains the application-definition file, abapp.dfn. Because this file is proprietary to PhAB, you shouldn't try to modify it.

appl/src

The src directory contains the source code, headers, and a Makefile generated by PhAB, as well as any code you create yourself. The Build & Run dialog initially displays the contents of this directory.

For detailed information on the files stored in this directory, see "What PhAB generates" in this chapter.

appl/src/platforms

These directories contain the Makefile, object files and executables for the chosen platforms. The Makefile in the src directory runs those in the platform directories.

appl/wgt

The wgt directory contains your application modules. Because each type of module has a different file extension, it's fairly easy to recognize the exact modules you want when importing modules from another application. For more info, see the handy tables in the "Module types" section in the Working with Modules chapter.

---

Always use PhAB to edit the module files in the wgt directory. Don't try to edit these binary files with another editor. Never modify any files prefixed by ab.

---

Single-platform applications

Here's what each directory contains if you first generate your application before installing Watcom 10.6 or later:

appl

The name of this directory is the same as your application. It contains the application-definition file, abdefn.app. Because this file is proprietary to PhAB, you shouldn't try to modify it. After you've compiled and linked the application, the executable is also placed in this directory.

appl/src

The src directory contains the source code, headers, object files, and Makefile generated by PhAB, as well as any code you create yourself. The Build & Run dialog initially displays the contents of this directory.

For detailed information on the files stored in this directory, see "What PhAB generates" in this chapter.

appl/wgt

The wgt directory contains your application modules. Because each type of module has a different file extension, it's fairly easy to recognize the exact modules you want when importing modules from another application. For more info, see the handy tables in the "Module types" section in the Working with Modules chapter.

---

Always use PhAB to edit the module files in the wgt directory. Don't try to edit these binary files with another editor. Never modify any files prefixed by ab.

---

Converting to multiplatforms

You can convert your application to multiple platforms after installing Watcom 10.6 or later, but it isn't necessary; PhAB works with both types of application.

To convert to multiple platforms, choose Convert to Multiplatform from the Application menu. PhAB moves any existing Makefile to src/default/Makefile.old. Use the Generate command in the Build & Run dialog to generate a new Makefile for the desired platforms, and then edit them to propagate any required changes from the old Makefile to the new.

Editing source

Once you've generated your application code, you'll see the C and/or C++ source code modules displayed in Build & Run's file list. Next to the file list, you'll see several buttons to perform various actions on the files.

To edit, view, or delete source code:

1. Click on the source-code file.
2. Click on the appropriate action button (Edit, View, Delete, ...).

   You can also edit a file by double-clicking on its name.

Choosing an editor or browser

To choose which editor or browser the Edit and View buttons will invoke, see "Customizing your PhAB environment" in the chapter on PhAB's Environment.

Creating a source module

To create a new source-code module:

1. Click on the Create button to open the Create File dialog, then type the name of the new file.
2. If you wish to create the file using a template (for a header file or widget callback), select a format from the Template combobox.
3. Click on Create. You'll see a terminal window that displays either an empty file or a file that contains the template.

If you create any files, click on the Refresh button to reread the application directory and refresh the list of files on the left side of the Build & Run dialog,

Changing the file display

To control which files are displayed in the Build & Run dialog, use the following:

• Refresh-forces a reread of the application source directory to ensure that your file list is current
• File Spec-lets you specify a filename pattern

Compiling & linking

After generating the application code, you need to:

1. Choose the libraries your application will use.
2. Use Make to compile and link your application.

Choosing the libraries

PhAB lets you use the following libraries with your application:

• Static Lib-Link the Photon and PhAB libraries into the application executable. The application will be larger than if you used the shared library, but will run without the shared libraries. This might be useful in an embedded environment.
• Shared Lib-Don't include the libraries in the application. The application will be much smaller, but requires the Photon shared libraries to run.

The default is shared libraries.

Running make

Once you've chosen the library type, you're ready to compile and link.

The first time you generate your application, PhAB creates a Makefile in the src directory (plus a Makefile for each platform selected for multiplatform development) so you can make the application. Subsequent generations don't modify the file directly; instead, they update external files referenced in the Makefile.

Once the Makefile is generated you're free to modify it, with a few conditions:

• PhAB places external file references in the Makefile for the object, source, and header files it generates and uses. Don't remove these references.
• PhAB also uses three target-name references called app, shr, and proto. Don't rename these make targets.

  The app and shr targets are used to compile and link the application with static or shared libraries. The proto target is used to generate the application prototype file, proto.h; see "Generating function prototypes" later in this chapter.

By default, the Makefile is compatible with the installed make command. You can convert the file to a format that suits the make command you prefer-just make sure the external file reference method is still compatible.

For more information, see "Including non-PhAB files in your application," later in this chapter.

To make your application:

1. Click on the Make button to open the Make Application dialog and start the make process.
2. If any errors or warnings are detected during the make process, PhAB enables the Edit and Restart buttons.

   To edit the first file that contains errors, click on Edit. After fixing the problems, click on Restart to run make again.

   To stop make at any time, click on Abort.

3. Once the application has been compiled and linked, PhAB will enable the Make dialog's Done button. Click on Done to close the dialog.

   The Done button is also enabled when you click on Abort.

Modifying the make command

By default, PhAB uses the installed make command to make your application. If you need to change this command in any way, click on the Build Preferences button.

---

Any changes you make to Build Preferences settings are saved with the application itself rather than as a global preference.

---

Running the application

Once your application has been compiled and linked without errors, it's ready to run. Just follow these steps:

1. If you've used PhAB to create a multilingual application, you can choose the language in the Build & Run dialog before running your application. For more information, see the International Language Support chapter.
2. If your application needs command-line arguments, type them into the Run Arguments box.
3. Click on Run Appl.

---

When your application runs, its working directory is the one that's displayed in the Build & Run dialog.

---

If you use functions such as printf() in your application, the output goes to your console if you run your application from PhAB. To see this output:

• Open a pterm window and use the ditto utility to view the console (ditto is described in the QNX Utilities Reference).

  Or

• Open a pterm and run the application from there instead of from PhAB.

PhAB is still active while your application is running. To switch between the two, use the Window Manager's taskbar.

Debugging

PhAB lets you run your application with a debugger such as wd, which can be handy if your application crashes or behaves incorrectly.

To run your application from inside a debugger, click on the Debug Application button. The debugger will start up in a terminal window. Your application will display once you run it from the debugger.

To switch between the debugger and the application, use the Window Manager's taskbar.

Modifying the debugger command

The default debugger is wd. If you need to change this command in any way, click on the Build Preferences button and edit the debugger command. For example, if you're using Watcom 9.5x, change the command to wvideo.

If you're using printf() calls to debug your program, the easiest way to see the output is to change the default debugger to:

pterm -z

When you click on Debug Application in the Build & Run dialog, PhAB creates a pterm, which runs your application. The program's output appears in the pterm window. The -z option makes the pterm window remain open until explicitly closed. For more information on pterm, see the Photon Installation & Configuration guide.

You can even use printf() and wd together by setting the default debugger to:

pterm wd

When you click on Debug Application in the Build & Run dialog, PhAB starts pterm, which starts wd, which starts your application. You can then use wd and see the program's printed output.

---

Any changes you make to Build Preferences settings are saved with the application itself rather than as a global preference.

---

Including non-PhAB files in your application

Your application can include files that aren't created with PhAB, but you need to tell PhAB how to find them.

Multiplatform applications

PhAB generates empty lists in the following files in the src directory, and you can edit them:

indHfiles

Non-PhAB header files. For example:

    MYHDR = ../header1.h ../header2.h
      

indOfiles

Non-PhAB object files. For example:

    MYOBJ = file1.o file2.o
      

indSfiles

Non-PhAB source files. For example:

    MYSRC = ../file1.c ../file2.c
      

---

Remember to specify the filenames relative to where the Makefiles are found. For a multiplatform application, that's relative to the platform directory: header files and source files are usually in the parent directory, src, so their names start with ../ object files are usually in the same directories as the Makefiles

---

Single-platform applications

If you generated your application for the first time before installing Watcom 10.6, you won't have the indHfiles, indOfiles and indSfiles files. Instead, you'll find MYHDR, MYOBJ and MYSRC in your Makefile, and you can specify filenames there.

---

Remember to specify the filenames relative to where the Makefile is found. For a single-platform application, that's relative to the src directory.

---

Adding libraries

If your application uses a library that isn't included by default in the Makefile, you can add it by editing the following variables:

• LDFLAGS - used when linking against static Photon libraries.
• SDFLAGS - used when linking against shared Photon libraries.

---