The stand alone compiler was first introduced in PowerBuilder 2017. It's primarily of interest for shops who perform routine (perhaps daily) builds of their PowerBuilder based applications, usually in order to perform manual and/or automated testing in order to capture bugs as soon as possible after they are introduced into the code base.
While you could perform command line compiles using the PowerBuilder IDE (and still can) it does require an additional license for the IDE, and it has a few drawbacks (e.g., stopping and displaying a messagebox nobody can see on some error rather than exiting with an error code).
One issue with the initial version of the command line compiler introduced in PowerBuilder 2017 is that it didn't support every option available in the PowerBuilder project painter. Therefore, if there was some particular feature that use used in the project painter (e.g., generating an external manifest or no manifest at all) it wasn't possible to use the stand alone compiler and get the results you needed.
The stand alone compiler enhancements in PowerBuilder 2017 R2 adds support for the vast majority of the remaining options in the project painter. There are a few that still aren't covered, and likely will never be. In that case, if you need to take advantage of those options you may need to use the command line compile option of the PowerBuilder IDE or PowerGen.
So let's take a look at the project painter and determine what options are now supported. We'll start with the General tab.
General
As you can see, PowerBuilder 2017 R2 adds support for every option on the General tab that wasn't previously supported, with the exception of "Prompt for overwrite" which wouldn't make sense for a command line compiler. One note with regard to the /i and /f options. Those were available in the initial release, but they weren't included in the documentation that came with the compiler (the PBC170.PDF file). In fact, they aren't documented in the R2 version of that file either. It does show up in the "PBC runtime parameters" when you toggle the option though, so if you were using that to get the arguments to provide to the compiler you were getting what you needed. They are also documented in the command line help you get if you run the compiler with the /h option. This documentation laspse has been reported to Appeon and should be addressed in a later update.
Next we'll turn to the Libraries tab.
Libraries
This is the one area where neither the initial release or the R2 release provide any support. One option here allow you to provide a separate PBR file for each PBL file. Given that you can provide a PBR file for the entire application this doesn't appear to be an issue. The other thing you can specify here is, on a PBL by PBL basis, whether the objects in that PBL should be included in the main EXE or in a separate PBD/DLL. When you use the command line compiler, you will always get the EXE and one PBD/DLL for every PBL in the library list. Some people prefer to create just a single executable, or to create a single executable with a subset of the PBLs in the library list. Those people will need to decide whether they want to use the command line compiler and adjust to how it operates, or whether they want to continue to use the IDE or PowerGen to compiler their applications.
Note that there is a mistake at one point in the R2 version of the documentation (PBC170.PDF) where it indicates that "You can either deploy all or none of the PBLs to PBD/DLL files.". The command line compiler does not give you that choice. Instead it will always deploy all of them. This documentation error has been reported to Appeon and should be corrected in a later update.
We're going to skip over the Version tab for a moment and come back to it later, for reasons that will make sense when we get there.
The tab after that is the Security tab.
Security
The initial version of the command line compiler didn't provide any support here, and the R2 version supports every option.
Next comes the Run tab:
Run
Neither the initial version or the R2 version of the command line compiler support any option in this tab. However, that's appropriate. Like the "Prompt for overwrite" option in the General tab, none of these options make sense for a command line compiler.
Finally, let's go back to the Version tab.
Version
The initial release of the command line compiler supported all of the options on the Version tab with the exception of the "Product Version" in the "Executable version used by installer" section. It also used the value provided with the /fv argument for the "File Version" for both the "Properties display for executable" and "Executable version used by installer" sections. The R2 version didn't change anything there. However, there are some issues with that initial implementation that we're going to look at in some depth here (which is why I saved this tab for last).
To understand the issue, we need to take a look at the VERSIONINFO structure from the Windows API which is used to store the information about Windows EXE and DLLs, including the information that we're setting through this tab.
There are two primary areas of interest to us in that structure. The first is the 'fixed-info' section which includes a number numeric values, including the FILEVERSION and PRODUCTVERSION. Both of those are a series of four 16 bit integers. These are the values in the PowerBuilder project painter in the "Executable version used by installer" section.
The second area of interest is the 'string-name' section, which includes a number of string values, including the ProductVersion and FileVersion. These are the values in the PowerBuilder project painter in the "Properties display for executable" section.
So, let's see what the command line compiler does when we use the /v and /fv options. I'm going to pass '2.2.2.2' for /v and '3.3.3.3' for /fv. I'm then going to use a great little utility called Resource Tuner to look at the version information that gets included in the executable. I'm also going to look at what Windows Explorer shows for Product Version and File Version. The result is this:
We can see the following:
- The stand alone compiler has used the /v value to set the ProductVersion in the 'string-name' section.
- The stand alone compiler has used the /fv value to set FileVersion in the 'string-name' section and the FILEVERSION in the 'fixed-info' section.
- When using the stand alone compiler the PRODUCTVERSION in the 'fixed-info' section is left at the default value of '1.0.0.1'
- Windows Explorer shows the ProductVersion from the 'string-name' section and the FILEVERSION from the 'fixed-info' section.
And that brings up the following issues:
- Using the command line compiler, it's currently not possible to set the PRODUCTVERSION in the 'fixed-info' section.
- Using the command line compiler, it's currently not possible to set the FileVersion in the 'string-name' section to a non numeric string value. Because the stand alone compiler uses the /fv argument to populate both the string and numeric file version values, it will throw an error when generating the executable if the value passed for that argument cannot be parsed into a numeric value.
It's actually a common practice to set the ProductVersion and FileVersion string values to string representations of the PRODUCTVERSION and FILEVERSION numeric values. If that's what you do, then that second issue really isn't of concern. However, the Windows installer uses the PRODUCTVERSION in the 'fixed-info' section, so it can be important to be able to set that. These issues have been reported to Appeon and are under consideration to be addressed in a later release. Until then, if you want to use the command line compiler but the way it handles version information is an issue for you, you might consider the Version Edit utility from E Crane. It's a command line tool that properly handles the version stamping PowerBuilder executables.
Summary
With the exception of those issues and the documentation items noted above, the stand alone compiler is essentially complete as of R2. It does pretty much everything you can do through the PowerBuilder project painter. The exception is being able to specify on a PBL by PBL basis whether the code should be included in the EXE or in a PBD/DLL, and I don't anticipate that feature ever being introduced in a command line argument driven utility. In particular, it is possible to do compiles using OrcaScript as well, which used a script file rather than command line arguments. However, the difficulty in getting the pbdflags option set correctly, particular when there are 100+ PBLs as is in the case of many typical PowerBuilder apps, shows how difficult getting that particular feature implemented in a command line utility would be.