Creating an executable version of your application
The next few sections tell you more about the packaging process
and provide information to help you make choices about the resulting
application. You’ll read about:
- Compiler basics
- What can go in the package
- How to choose a packaging model
- How to implement your packaging model
- How to test the executable application you create
Compiler basics
When you plan an application, one of the fundamental topics
to think about is the compiler format in which you want that application
generated. PowerBuilder offers two alternatives: Pcode and machine
code.
Pcode
Pcode (short for pseudocode) is an interpreted language that’s
supported on all PowerBuilder platforms. It’s the same format
that PowerBuilder uses in libraries (PBL files) to store individual
objects in an executable state. Advantages of Pcode include its
convenience and its portability.
Machine code
PowerBuilder generates and compiles code to create a machine
code executable or dynamic library. The key advantage of machine
code is speed of execution.
On UNIX, PowerBuilder must have access to a
supported compiler to generate machine code. For information about
supported compilers, see the Installation Guide
or
the Release Notes.
Deciding which one to use
Here are some guidelines to help you decide whether Pcode
or machine code is right for your project:
- Speed If your primary goal is to optimize execution speed and your application
does intensive script processing, then choose machine code. It will
perform better than Pcode if your code makes heavy use of looping constructs,
floating point or integer arithmetic, and function calls.
Pcode does have one speed advantage–it is faster
to generate than machine code. That makes it especially handy when
you want to quickly create an executable version of their application
for testing. - Size The files generated for Pcode are smaller than those generated
for machine code. If your application is to be deployed on computers
where file size is a major issue, then you might decide to give
up the speed of machine code and choose Pcode instead. - Portability Pcode can be useful for cross-platform applications because it
is portable. You can deploy the same PBD on any Windows or UNIX platform.
However, you still need to generate the executable file on the target
platform, and performance is usually better if you also generate PBDs
on the target platform.
Machine code is, of course, platform-specific. That means
it requires you to generate and maintain complete versions of your
executable application on each platform. But you may still be willing
to do this to ensure the best performance.
Learning what can go in the package
No
matter which compiler format you pick, an application that you create
in PowerBuilder can consist of one or more of the following pieces:
- An executable file
- Dynamic libraries
- Resources
To decide which of these pieces are required for your particular
project, you need to know something about them.
About the executable file
If you are building a single- or two-tier application that
you will distribute to users as an executable file, rather than
as a server component or on the Internet, you will always create
an executable (EXE) file. If you are building a distributed PowerBuilder application,
you will create a client executable file and a server executable
file.
At minimum, the executable file contains code that enables
your application to run as a native application on its target platform.
That means, for example, when users want to start your application,
they can double-click the executable file’s icon on their
desktop.
What else can go in it Depending on the packaging model you choose for your application,
the executable file will also contain one or more of the following:
- Compiled
versions of objects
from your application’s
libraries
You can choose to put all of your objects in the executable
file (so that you have to deliver only this one file) or you can
choose to split your application into one executable file and one
or more dynamic libraries. More about that in just a moment. - An execution library list
that
the PowerBuilder execution system uses to find objects and resources
in any dynamic libraries you’ve packaged for the application - Resources
that your application
uses (such as bitmaps)
Size guidelines Try to keep an executable file smaller than 1.2 to 1.5 megabytes.
If it approaches that size, consider using dynamic libraries.
About dynamic libraries
As an alternative to putting your entire application in one
large executable file, you can deliver some (or even all) of its
objects in one or more dynamic libraries. The way PowerBuilder implements
dynamic libraries depends on the compiler format you choose:
| If you’re generating | Your dynamic libraries will be |
|---|---|
| Machine code | DLL files (dynamic link libraries) on Windows and shared (dynamic) libraries on UNIXMachine-code dynamic libraries are given the extension .dll. These dynamic libraries are like any other standard shared libraries in your operating environment. The only caveat is that they aren’t intended to be called from external programs |
| Pcode | PBD files (PowerBuilder dynamic libraries)These dynamic libraries are similar to DLLs in that they are linked to your application at execution time. But they are not interchangeable with DLLs, because they have a different internal formatYou can’t mix the two different kinds of dynamic libraries (DLLs and PBDs) in one application |
As with an executable file, only compiled
versions
of objects go into dynamic libraries (not their source):
What else can go in them Unlike your executable file, dynamic libraries don’t
include any startup code. That’s because they can’t
be executed independently. Instead, they are accessed as an application
executes when needed to provide objects the application requires
(if it can’t find those objects in the executable file).
But dynamic libraries can include resources (such as bitmaps).
In fact, you’ll often want to put any resources needed
by a dynamic library’s objects in that DLL or PBD file–this
makes the dynamic library a self-contained unit that can easily
be reused (although if performance is your main concern, you’ll
find that resources are loaded faster at execution time when they’re
in the executable file).
Why use them There are several reasons why you might want to use dynamic
libraries:
| Reason | Details |
|---|---|
| Modularity | They let you break up your application into smaller, more modular files that are easier to manage |
| Maintainability | They enable you to deliver your application components separately. That means when you need to provide users with an upgrade or bug fix, you don’t have to redistribute the entire application–you can just give them the particular dynamic library that was affected |
| Reusability | They make it possible for multiple applications to reuse the same components. That’s because dynamic libraries can be shared among applications as well as among users |
| Flexibility | They enable you to provide your application with objects that it references only dynamically at execution time (such as a window object referenced only through a string variable)You can’t put such objects in your executable file (unless they are DataWindow objects) |
| Efficiency | They can help a large application use memory efficiently because:
|
Organizing them Once you decide to use a dynamic library, you need to tell PowerBuilder which
library (PBL file) to create it from. PowerBuilder then places compiled
versions of all
objects from that PBL file
into the DLL or PBD file.
But suppose your application uses only some of those objects.
In that case, you may not want the dynamic library to include the
superfluous ones, since they’ll just serve to make the
file larger than it has to be. The solution is to:
- Create a
new PBL file
and copy just the objects you want into
it. - Use this new PBL file
as the
source of your dynamic library.
For further details on these steps, see the PowerBuilder User’s
Guide
.
About resources
In addition to PowerBuilder objects such as windows and menus,
applications also use various resources. Examples of resources include:
- Bitmaps
that
you might display in Picture or PictureButton controls - Custom pointers
that you might
assign to windows
When you use resources, you need to deliver them as part of
the application along with your PowerBuilder objects.
What kinds there are A PowerBuilder application can employ several different kinds
of resources. Here’s a list of them, organized by the specific objects
in which they might be needed:
| These objects | Can use these kinds of resources |
|---|---|
| Window objects and user objects | Icons (ICO files)Pictures (BMP, GIF, JPEG, RLE, and WMF files)Pointers (CUR files) |
| DataWindow objects | Pictures (BMP, GIF, JPEG, RLE, and WMF files) |
| Menu objects (when in an MDI application) | Pictures (BMP, GIF, JPEG, RLE, and WMF files) |
Delivering them When deciding how to package the resources that need to accompany
your application, you can choose from the following approaches:
- Include
them in the executable file
Whenever you create an executable file, PowerBuilder automatically examines
the objects it places in that file to see if they explicitly reference any
resources (icons, pictures, pointers). It then copies all such resources right
into the executable file.But PowerBuilder doesn’t automatically copy in resources
that are dynamically referenced (through string variables). To get
such resources into the executable file, you must use a resource
(PBR) file. This is simply a text file in which you
list existing ICO, BMP, GIF, JPEG, RLE, WMF, and CUR files.Once you have a PBR file, you can tell PowerBuilder to read
from it when creating the executable file to determine which additional
resources to copy in. (This might even include resources used by
the objects in your dynamic libraries, if you decide to put most
or all resources in the executable file for performance reasons.) - Include them in dynamic libraries
You will often want to include resources right in one or more
dynamic libraries. But PowerBuilder doesn’t automatically
copy any resources into a dynamic library that you ask to create
(even if they are explicitly referenced by objects in that file).
So you need to produce a PBR file that tells PowerBuilder which resources
you want in this particular DLL or PBD file.Use a different PBR file for each dynamic library in which
you want to include resources. (When appropriate, you can even use
this approach to generate a dynamic library that contains only resources
and no objects–simply start with an empty PBL file as the
source.) - Deliver them as separate files
This means that when you deploy the application, you’ll
give users various image files in addition to the application’s
executable file and any dynamic libraries. As long as you don’t
mind delivering a lot of files, this can be useful if you expect
to revise some of them in the future.But keep in mind that this is not the fastest approach at
execution time, because it requires more searching. Here’s
what happens. Whenever your application needs a resource, it first
searches the executable file. If the resource isn’t there,
it next searches the dynamic libraries. If the resource isn’t
there, it finally searches for a separate file.Make sure your application can find where these separate files
are stored. Otherwise it won’t display the corresponding
resources.
You can use one of these approaches or any combination of
them when packaging a particular application.
Using a PBR file to include a dynamically referenced
DataWindow object You may occasionally want to include a dynamically referenced
DataWindow object (one that your application knows about only through
a string variable) in the executable file you’re creating.
To do that, you must list its name in a PBR file (along with the
names of the resources you want PowerBuilder to copy into that executable
file).
You don’t
need to do this when
creating a dynamic library, because PowerBuilder will automatically
include every DataWindow object from the source library (PBL file)
in your new DLL or PBD file.
For more information on working with PBR files,
see the PowerBuilder User’s Guide
.
Choosing a packaging model
As you can see from reading the previous section, you have
a lot of options when it comes to packaging an executable version
of an application. To help you choose what’s best for your
project, here are several of the most common packaging models you
might consider.
A standalone executable file
In this model, you include everything (all objects and resources)
in the executable file. That means there’s just one file
to deliver.
Illustration Here’s a sample of what this model can look like:
Use This model is good for small, simple applications–especially
those you expect won’t need a lot of maintenance. For such
projects, it ensures the best performance and the easiest delivery.
An executable file and external resources
In this model, you include all objects and most resources
in the executable file. But you deliver separate files for particular
resources.
Illustration Here’s a sample of what this model can look like:
Use This model is also for small, simple applications. But it
differs from the preceding model in that it facilitates maintenance
of resources that are subject to change. In other words, it lets
you give users revised copies of specific resources without forcing
you to deliver a revised copy of the executable file.
You could also use this model to deal with resources that
must be shared by other applications or that are large and infrequently
needed.
An executable file and dynamic libraries
In this model, you split up your application into an executable
file and one or more dynamic library files (DLLs or PBDs). When
doing so, you can organize your objects and resources in various
ways, including these:
| To organize | You can |
|---|---|
| Objects | Place them all in dynamic libraries so that there are none in the executable file (which facilitates maintenance), or Place a few of the most frequently accessed ones in the executable file (to optimize access to them) and place all the rest in dynamic libraries |
| Resources | Place most or all of them in dynamic libraries along with the objects that use them (which facilitates reuse), or Place most or all of them in the executable file (to optimize access to them) |
Illustration Here’s a sample of what this model can look like:
Use This model is good for most substantial projects. That’s
because of the flexibility it gives you in organizing, delivering,
and maintaining your applications.
For instance, it enables you to make revisions to a particular
part of an application (in one dynamic library) and deliver that
revised dynamic library to users without disrupting the remainder
of the application. It also lets you deliver the same dynamic library
for use in multiple applications.
An executable file, dynamic libraries, and external
resources
This model is just like the preceding one except that you
deliver separate files for particular resources (instead of including
all of them in your executable file and dynamic libraries).
Illustration Here’s a sample of what this model can look like:
Use This model is good for substantial applications, particularly
those that call for flexibility in handling certain resources. Such
flexibility may be needed if a resource:
- Might have to be revised
- Must be shared by other applications
- Is large and infrequently used
Implementing your packaging model
When you have decided which is the appropriate packaging model
for your application, you can use the packaging facilities in PowerBuilder to
implement it. For the most part, this involves working in the Project
painter. You can use the Project painter
to build components, proxy libraries, and HTML files as well as
executable applications.
Using the Project painter for executable applications
The Project painter for executable applications orchestrates
all aspects of the packaging job by enabling you to:
- Specify the executable
file
to create - Specify any dynamic libraries
(DLL
or PBD files) to create - Specify the resources you want included
in
the executable file or in each particular dynamic library (by using
appropriate PBR files that indicate where to get those resources) - Choose machine code or Pcode
as
the compiler format to generate
With machine code, you can also specify a variety of code
generation options (such as optimization, trace information, and
error context information). - Choose build options
, including
whether you want the Project painter to do a full or incremental
rebuild of your application’s objects when generating the
executable application - Save all of these specifications as a project
object that you can use whenever necessary to rebuild
the whole package
For more information on using the Project
painter, see the PowerBuilder User’s Guide
.
Building individual dynamic libraries
When revising an existing application, you
might want to deliver only those portions that have been changed–such
as a particular dynamic library (DLL or PBD file). In these cases,
your project object may do more than what you need. So instead,
you can use the Library painter to rebuild dynamic libraries from
their library (PBL) files on an individual basis.
Testing the executable application
Once you create the executable version of your application,
test how it runs before proceeding with delivery. You may have already
executed the application many times within the PowerBuilder development
environment, but it’s still very important to run the executable
version as an independent
application–just
the way end users will.
To do this, you:
- Leave PowerBuilder and
go to your operating (windowing) environment. - Make sure that the PowerBuilder deployment libraries
are accessible to the application.
You can do this by verifying that the location of the PowerBuilder
virtual machine and other deployment files is in your PATH environment variable.
On Windows, you could also create a shortcut and set the Start In property
to the location of the deployment files or you could create a registry
entry for the application that specifies the path. - Run the application’s executable file as
you run any native application.
Tracing the application’s execution
To help you track down problems, PowerBuilder provides tracing
and profiling facilities that
you can use in the development environment and when running the
executable version of an application. Even if your application’s executable
is problem-free, you might consider using this facility to generate an
audit trail of its operation. For more information
on tracing execution, see the PowerBuilder User’s
Guide
.