![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
|
|
|
|
 |
This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs. |
This chapter describes how to generate, organize, compile, and run the code for a PhAB application:
PhAB automatically generates everything that's required to turn your application into a working executable, including:
By doing all this, PhAB lets you get on with the job of writing the code that implements your application's main functionality.
 |
The way you build PhAB projects depends on whether you're running PhAB standalone or from the IDE. This chapter describes building and generating code using PhAB standalone, and indicates where there are differences when using the IDE. For more information on building and generating code in the IDE, see the "Building Projects" section in the Developing Programs chapter of the IDE User's Guide. |
For most code generation, you can use the Build menu. 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 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 menu, generate code from there, and then come back to write the function.
If you are using PhAB from the IDE, you can use PhAB's Build menu to generate the application's user interface code. All other build and run functions are handled by the IDE.
In standalone PhAB, the Build menu is the development center for building your applications. From this menu you can:
To build your application in standalone PhAB:
When you build your application, PhAB creates an executable that you can run on the target system.
If you haven't already added targets to your application, the Select New Platform dialog is displayed:
This dialog lets you select a target platform. For example, if you plan to run your application on an SH processor, you should select SH (Little Endian).
|
You can add more targets later using the Select New Platform dialog. To open this dialog, select Build-->Targets, then click Add target. See Managing targets below. |
Select your target and click Done.
If any errors or warnings are detected during the make process and it can determine which source file contains errors, PhAB enables the Edit button.
To edit the first file that contains errors, click Edit. After fixing the problems, click Restart to run make again.
To stop make at any time, click Cancel.
|
Depending on the state of the application, PhAB may skip some of the above steps. For instance, if you've already built your application, but just changed a resource for one of the widgets, PhAB may only save your application to update the changed widget and then rebind the widget files into your application; it will skip code generation, compilation, and linking. |
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.
|
When you use PhAB from the IDE, PhAB regenerates the application code every time you save the project. |
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 "Setting project properties" in the Working with Applications chapter, and "Global header file" in the Working with Code chapter. |
To generate your application code, select Generate UI from the Build menu. PhAB generates any required files any time you build your application.
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:
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):
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.
It's easier to save a PhAB application in CVS than RCS. Here are some things to keep in mind:
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.
PhAB generates function prototypes 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:
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 cause it some confusion, and an incorrect prototype is generated. Look for this kind 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. Or 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;
}
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.
At the top of the application's directory structure are the wgt and src directories. The wgt directory contains the application's widget files (files with extension .wgt* that PhAB uses to store information about your modules that are part of your application). The src directory contains header and source files needed to compile your application. At the same level as src and wgt are the platform directories (e.g. x86, mips, and arm). Their structure is the same as the structure generated by the addvariant command. The reports directory contains the files created when you choose the Generate Report command from the Project menu.
This directory structure is called the "Eclipse PhAB project" structure, because it is allows you to create an application in PhAB and then load it in Eclipse as an "Eclipse PhAB project". Conversely, an application created in Eclipse can be loaded in PhAB.
|
If you first generated your application with an earlier version of Photon, it might have been created as a single-platform application. In this case, the placement of files is slightly different, as described in the sections that follow. |
You can choose the target platforms on which to compile your application. You can edit your target configuration by choosing Targets from the Build menu.
Here's what each directory contains for a multiplatform application:
For detailed information on the files stored in this directory, see "What PhAB generates" in this 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. |
Here's what each directory contains for a single-platform application:
For detailed information on the files stored in this directory, see "What PhAB generates" in this 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. |
If you have a single-platform application built with an earlier version of Photon, it is converted to "Eclipse Project" format when you load it for the first time. When converting an application, PhAB moves any existing Makefile to src/default/Makefile.old.
If you have a multiplatform application built with an earlier version of Photon, it is loaded by PhAB as is. You can choose to convert it to Eclipse Project format by selecting Project-->Convert to Eclipse Project.
You can edit source files from an external editor, which you can configure in PhAB. If you're using PhAB from the IDE, you can use an editor in the IDE to work with source files as well.
You can open source files for editing within PhAB from the Browse Files palette. If the Browse Files palette isn't visible, select Window-->Show Project. The Browse Files palette looks like this:
Browse Files palette.
To edit, view, or delete source code from within PhAB:
You can also edit a file by double-clicking its name.
To choose which external editor or browser the Edit and View buttons invoke, see "Customizing your PhAB environment" in the PhAB's Environment chapter.
To create a new source-code module:
If you create any files, click Refresh to reread the application directory and refresh the list of files in the Browse Files palette.
To control which files are displayed in the Browse Files palette, use the following:
The Filter line at the bottom of the palette allows you to filter the list of the files the Browse Files palette displays. For instance *.[ch] displays subdirectories and filenames ending in .c and .h.
This section applies to standalone PhAB. For information about compiling and linking applications using the IDE, see the "Building projects" section in the Developing Programs chapter of the IDE User's Guide.
After generating the application code, you need to:
By default all PhAB applications link against libAp and libph. You can specify addtional libraries libraries for your application in the Link Libraries field of the Build and Debug Options dialog.
You can also specify how libraries are linked against your application:
The default is shared libraries. To specify how libraries are linked, use the -B option in the Link Libraries field of the Build and Debug Options dialog. For example, consider the following Link Libraries line: -Bstatic -lphexlib -Bdynamic -lmylib -Bstatic. This links against libphexlib.a, mylib.so, and since the default libraries are considered being after the end, libAp.a and libph.a.
You can also specify a list of library callback functions when you start PhAB. For more information, see appbuilder in the Utilities Reference.
Once you've chosen the library type, you're ready to compile and link.
The first time you generate your application, PhAB creates Makefile and common.mk files in the project 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 common.mk.
Once the common.mk is generated you can modify it, though you should only do so when there's no way to set options from within PhAB.
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 ensure 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:
To edit the first file that contains errors, click Edit. After fixing the problems, click Restart to run make again.
To stop make at any time, click Cancel.
The Done button is also enabled when you click Cancel.
By default, PhAB uses the installed make command to make your application. If you need to change this command in any way, click Build Preferences.
|
Any changes you make to Build Preferences settings are saved with the application itself rather than as a global preference. |
You can customize the build options on the Build and Debug Options tab on the Project Properties dialog. Open the Project Properties dialog by selecting Project-->Properties. For a description of this dialog, see Build and Debug options in the Working with Applications chapter.
When you use PhAB from the IDE, PhAB handles the code generation for the user interface, while the IDE manages the build process. Therefore, only items in this dialog that affect generation are available when you run PhAB from the IDE.
The first time you generate your application, PhAB creates a Makefile and a common.mk in the top level directory. Subsequent generations don't modify the file directly. You can customize your build process by changing or adding compile and link flags in common.mk.
Once the Makefile is generated you can modify it, though you should only do so when there's no way to set options from within PhAB.
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 ensure the external file reference method is still compatible.
For more information, see "Including non-PhAB files in your application," later in this chapter.
How you run an application developed in PhAB depends on whether you're running PhAB standalone or from the IDE. When running PhAB from the IDE, you set up launch configurations for targets through the IDE. For more information, see the Preparing Your Target chapter and "Running projects" section of the Developing C/C++ Programs chapter in the IDE User's Guide.
From standalone PhAB, once your application has been compiled and linked without errors, it's ready to run. Just follow these steps:
|
When your application runs, its working directory is the platform
directory
(i.e. the directory containing the executable).
If you check Do not show this dialog again, the Run Options dialog doesn't appear the next time you run the application. To reenable the dialog, check the Ask for run arguments option on the General tab of the AppBuilder Preferences Settings dialog. If you check Always use these settings, then the settings are saved and used any time you run this application. You can change the run arguments or language on the Run Options tab of the Project Properties 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 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.
|
If the target you chose to build your application for is not the same as the one you run PhAB on, you'll have to transfer your application's executable to your target in order to run it. |
You can run your application with a debugger, which can be handy if your application crashes or behaves incorrectly.
When running PhAB from the IDE, you use the debug features in the IDE. For more information, see the Debugging Programs chapter in the IDE User's Guide.
 |
To debug your application in standalone PhAB, choose Build & Debug from the Build menu. This launches the application in your preferred debugger. |
|
In order to debug an application, you have to compile a debug-build version. To do this, select Build & Debug from the Build menu. |
To switch between the debugger and the application, use the Window Manager's taskbar.
You can add or delete target platforms using the Manage Targets dialog. To open this dialog, select Build-->Targets.
Manage Targets dialog.
To add a target, click Add target. Note that if the target is already added to your application, the Makefile in the target directory is overwritten.
To delete a target, select it and click Delete target.
Only the targets selected in this dialog are built.
Here's a description of all the items in the Build menu:
* For these commands, "all your selected targets" means the building process will take place only for selected targets. To change the currently selected targets simply choose Targets from the Build menu and change the selection in the target list. You can also select targets from the Build and Debug Options tab of the Project Properties dialog.
Your application can include files that aren't created with PhAB, but you need to tell PhAB how to find them.
To add non-PhAB source files to an application, place them in the project's src directory.
PhAB generates empty lists in the following files in the src directory, and you can edit them:
MYHDR = ../header1.h ../header2.h
MYOBJ = file1.o file2.o
MYSRC = file1.c file2.c
|
Remember to specify the filenames relative to where the Makefile
s are
found. For a multiplatform application, that's relative to the platform
directory:
|
A single-platform application from an earlier version of Photon doesn'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. |
If your application uses a library that isn't included by default in the Makefile, you can add it with the Link Libraries line on the Build and Debug Options tab of the Project Properties dialog. Open this dialog by selecting Project-->Properties.
For instance, if you want to link against the socket library, put the following in the Link Libraries line:
-l socket.
You can also add it by editing the LDFLAGS variable in common.mk:
You can make a PhAB application into a DLL, but there isn't a PhAB option that will do it for you. PhAB doesn't know anything about building DLLs; it's the PhAB library that lets you turn a PhAB application into a DLL.
|
The application that loads your DLL must be a PhAB application
so that the PhAB library is properly initialized.
Even though PhAB lets you set up an initialization function and windows to open at startup, they're ignored when your application is a DLL. That's because this regular PhAB startup is done by main(), and the main() function of a DLL isn't called. (Don't attempt to call it from your own code, either.) |
In general, you can turn any application (whether created by PhAB or not) into a DLL by adding -shared to the compiler and linker flags (and most likely adding a dll extension to the filename). You should also give the -Bsymbolic option to the linker to make sure that locally defined symbols that your DLL uses aren't overridden by any symbols in the executable with the same name.
To make these changes for a PhAB application, run the addvariant command at the top level directory for the application. For example:
addvariant x86 dll
For more information, see addvariant in the Utilities Reference and the Conventions for Makefiles and Directories chapter of the Neutrino Programmer's Guide.
Typically, a DLL defines an initialization function that an application calls after it calls dlopen() to load the DLL. Your DLL's initialization function needs the full path to the DLL.
Before calling any PhAB code, the initialization function must call ApAddContext(), like this:
ApAddContext( &AbContext, fullpath );
The arguments are:
|
This structure has the same name in every PhAB application or DLL, so you must link your DLL with the -Bsymbolic option mentioned above. |
You can call ApAddContext() more than once, but you need to keep track of how many times you called it.
ApAddContext() returns zero on success, or -1 on failure. Don't call any Ap* functions if ApAddContext() fails.
AbContext holds, among other things, the location of the executable or DLL that it's contained in, and the language translation files currently loaded for that file. At any time, one of the registered contexts may be "current"; a few libAp functions implicitly refer to the current context, and some require a current context when you call them. At program startup, the program's context is made current. You can unset it or change it to a different context by calling ApSetContext():
ApContext_t *ApSetContext( ApContext_t *context );
This makes the given context current, and returns the previous current context. Both can be NULL; but if you pass a non-NULL pointer, it must point to a registered context.
When an application is about to unload a DLL, it typically calls a cleanup function in the DLL. In your DLL's cleanup function, you must:
or
ApRemoveContext( &AbContext );
You must call ApRemoveContext() the number of times that you successfully called ApAddContext(). After you've called ApRemoveContext(), your DLL must not call any PhAB functions.
|
|
|
|