Building an executable file and dynamic libraries
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”.
How PowerBuilder builds the 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.
How PowerBuilder searches for objects
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.
Which
objects are copied to the executable file
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:1Open(w_continue) - If a menu item script refers to the global function f_calc, f_calc is
copied to the executable file:1f_calc(EnteredValue) - If a window uses a pop-up menu using the following
statements, m_new is copied to the
executable file:1m_new mymenu<br>mymenu = create m_new<br>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.
Which objects are not copied to the executable file
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:1dw_info.DataObject = "d_emp" - The bitmap files assigned dynamically in the following
script are not copied:1IF Balance < 0 THEN<br> p_logo.PictureName = "frown.bmp"<br>ELSE<br> p_logo.PictureName = "smile.bmp"<br>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:1window mywin<br>string winname = "w_go"<br>Open(mywin,winname)
Which objects are not copied to the dynamic libraries
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”.
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.
Table 34-3 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 |
Listing the objects in a project
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.
To list the objects in a project:
-
Build your project.
-
Select Design>List Objects from the menu
bar.