Once you have completed development and defined your project, you build the project to create the executable files and all specified dynamic libraries. You can build your project whenever you have made changes to the objects and want to test or deploy another version of your application.
This section describes building a single project in the Project painter. You can build all the targets in your workspace at any time using buttons on the PowerBar, pop-up menus in the System Tree, or a command line. For more information, see Building workspaces.
To build the application:
-
Open the project you built in the Project painter.
-
Click the Build button in the PainterBar, or select Design>Build Project.
If the target's library list has changed
When you click Build, PowerBuilder checks your target's library list. If it has changed since you defined your project, PowerBuilder updates the Project painter workspace with the new library list. Make whatever changes you need in the workspace, then click Build again.
PowerBuilder builds the executable and all specified dynamic libraries.
The next two sections describe in detail how PowerBuilder builds the project and finds the objects used in the target.
When PowerBuilder has built the target, you can check which objects are included in the target. See Listing the objects in a project.
When PowerBuilder builds your application project:
-
If you selected Rebuild: Full, PowerBuilder regenerates all the objects in the libraries.
-
If you selected Prompt for Overwrite, PowerBuilder displays a message box asking for confirmation before overwriting the executable file and each dynamic library.
To create the executable file you specified, PowerBuilder searches through your target and copies into the executable file the compiled versions of referenced objects from the libraries in the target's library search path that are not specified as dynamic libraries. For more details, see How PowerBuilder searches for objects.
PowerBuilder creates a dynamic library for each of the libraries you specified for the target and maintains a list of these library files. PowerBuilder maintains the unqualified file names of the dynamic library files; it does not save the path name.
PowerBuilder does not copy objects that are not referenced in the application to the executable file, nor does it copy objects to the executable file from libraries you declared to be dynamic libraries. These objects are linked to the target at runtime and are not stored in the executable file.
What happens at runtime
When an object such as a window is referenced in the application, PowerBuilder first looks in the executable file for the object. If it does not find it there, it looks in the dynamic library files that are defined for the target. For example, if you specified that a dynamic library should be generated from test.pbl, PowerBuilder looks for test.pbd or test.dll at runtime. The dynamic library files must be in the search path. If PowerBuilder cannot find the object in any of the dynamic library files, it reports a runtime error.
When searching through the target, PowerBuilder does not find all the objects that are used in your target and copy them to the executable file. This section describes which objects it finds and copies and which it does not.
PowerBuilder finds and copies the following objects to the executable file.
Objects that are directly referenced in scripts
PowerBuilder copies objects directly referenced in scripts to the executable file. For example:
-
If a window script contains the following statement, w_continue is copied to the executable file:
Open(w_continue)
-
If a menu item script refers to the global function f_calc, f_calc is copied to the executable file:
f_calc(EnteredValue)
-
If a window uses a pop-up menu using the following statements, m_new is copied to the executable file:
m_new mymenu mymenu = create m_new mymenu.m_file.PopMenu(PointerX(), PointerY())
Objects that are referenced in painters
PowerBuilder copies objects referenced in painters to the executable file. For example:
-
If a menu is associated with a window in the Window painter, the menu is copied to the executable file.
-
If a DataWindow object is associated with a DataWindow control in the Window painter, the DataWindow object is copied to the executable file.
-
If a window contains a custom user object that includes another user object, both user objects are copied.
-
If a resource is assigned in a painter, it is copied to the executable file. For example, when you place a Picture control in a window in the Window painter, the bitmap file you associate with it is copied.
When creating the executable file, PowerBuilder can identify the associations you made in the painter, because those references are saved with the object's definition in the library, and direct references in scripts, because the compiler saves this information.
However, it cannot identify objects that are referenced dynamically through string variables. To do so, it would have to read through all the scripts and process all assignment statements to uncover all the referenced objects. The following examples show objects that are not copied to the executable file:
-
If the DataWindow object d_emp is associated with a DataWindow control dynamically using the following statement, d_emp is not copied:
dw_info.DataObject = "d_emp"
-
The bitmap files assigned dynamically in the following script are not copied:
IF Balance < 0 THEN p_logo.PictureName = "frown.bmp" ELSE p_logo.PictureName = "smile.bmp" END IF
-
The reference to window w_go in a string variable in the following window script is not found by PowerBuilder when building the executable file, so w_go is not copied to the executable file:
window mywin string winname = "w_go" Open(mywin,winname)
When building a dynamic library, PowerBuilder does not inspect the objects; it simply copies the compiled form of the objects. Therefore, the DataWindow objects and resources (pictures, icons, and pointers) used by any of the objects in the library—either specified in a painter or assigned dynamically in a script—are not copied into the dynamic library.
For example, suppose test_dw.pbl contains DataWindow objects and test_w.pbl contains window objects that reference them, either statically or dynamically. If you build a dynamic library from test_w.pbl, you must either include the DataWindow objects in a PowerBuilder resource file that is referenced by test_w.pbl, or build a dynamic library from test_dw.pbl, as described in How to include the objects that were not found.
If you did not use any of the types of references described in the preceding sections, you do not need to do anything else to ensure that all objects get distributed: they are all built into the executable file. Otherwise, you have the following choices for how to include the objects that were not found.
Distributing graphic objects
For graphic objects such as icons and bitmaps, you have two choices:
-
Distribute them separately
-
Include them in a PowerBuilder resource file (PBR), then build an executable file or dynamic PowerBuilder library that uses the resource file
Distributing DataWindow objects
For DataWindow objects, you have two choices:
-
Include them in a PBR, then build an executable file or dynamic PowerBuilder library that uses the resource file
-
Build and distribute a dynamic library from the PBL that contains the DataWindow objects
Distributing other objects
All other objects, such as windows referenced only in string variables, must be included directly in a dynamic library.
The following table summarizes resource distribution possibilities.
|
Distribution method |
Graphic objects |
DataWindow objects |
Other objects |
|---|---|---|---|
|
As a separate file |
Yes |
No |
No |
|
In an executable or dynamic library that references a PBR |
Yes |
Yes |
No |
|
Directly in a dynamic library |
No |
Yes |
Yes |
After you have built your project, you can display a list of objects in the project in a grid DataWindow object with three columns showing:
-
The source library that contains the object
-
The name of the object
-
The type of the object
The report lists the objects that PowerBuilder placed in the executable file and the dynamic libraries it created when it built the project.
Because the report is a grid DataWindow object, you can resize and reorder columns just as you can in other grid DataWindow objects. You can also sort the rows and print the report using the Sort and Print buttons.
