ARTICLE - The Road to Release
By Brad Moore (bjaz.moore@verizon.net)

Home

Window Placement Techniques
Listview Report by Brent Thorn
Enhancing Liberty Basic [Array Handling]
The Road to Release
Formatted ListBox

 

There is no doubt that LB is powerful, even powerful enough to produce commercial quality applications. If you need proof, just mosey on out to http://members.tripod.com/~eaglesoar/eagle.html and take a look at birthday keeper published by EagleSoar Software. It has earned numerous awards and is a top rated shareware download. Not bad for an application developed in Liberty Basic.

Truth is, any one can do it. Given enough practice and patience, production and release of a polished, professional software product is well within the scope of a Liberty Basic programmer. But there are several steps between "finishing" that great game and having a commercially acceptable software product. The aim of this article is to take the average Liberty Basic developer from the "I think I am done" stage to the ready for distribution stage. So hop aboard for a really swell ride on the "Road to Release"The Journey Begins

Our first stop is at the application itself. There are several really important requirements that you are going to want to meet before you continue on the journey.1) Is it ready? It seems like a no brainer, but has it been well tested? Are there any dead ends in your menus or buttons, functionality you meant to develop but forgot. > Does it do what it is suppose to do? I this area I try to do a few things to insure completeness. a) Bench-check the code. Look through it top to bottom and make sure you have not left out something you meant to code. Check for logic errors and insure you open and close all your files correctly. Are there any hard coded paths to files? Is there an END statement? It is required.b) Test the code. Take your program through every single execution path that is possible. Try to break it by doing the unexpected. This phase is often called alpha testing in larger projects.c) Now have some other people try it out to see if they can break it.


2) Next there are several functional things a good application should have to meet the minimum requirements of release ready.a) An about dialog box. This little form that tells about the application, who wrote it and when has become a standard in windows programming. Don't consider going to market without it.b) A help file. The next level up from an about box this is an important component of any good software product. If your program is of any size or complexity at all consider creating a helpfile. An excellent help authoring tool (called EclipseHelp) is available from Green Eclipse software at http://www.greeneclipsesoftware.com/eh.html .

Our Vehicle

For the purpose of this article we will be expanding the little applet that appeared in Newsletter 97 called the Liberty Basic Newsletter Reader. I have updated it with a couple new twists since its publishing in May. There is code to remove the menu item EDIT that the texteditor automatically puts in the menu when a texteditor is place on a window type form. I have also changed the window to be of the type without a frame so that it can not be resized.

In order to follow this article along I recommend getting the companion file that accompanies the newsletter which contains the LBNR.ZIP file. Inside the zip file you will find the original project as released back in late May, and the new updated file called LBNR2.bas. Also, there is an additional zip file called LBNR-Release, which contains other items we will be using during this tutorial article. Unzip these in a convenient working location and we will get moving along.

In addition to the changes I mentioned above, I have also added a simple ABOUT window. It is a dialog box that reuses the main application graphic and displays some basic information about the program. The following code snippet does most of the work (There are line wraps that must be fixed - sorry):

[About]
     'Window setup
     
     WindowWidth = 317 : WindowHeight = 387
     Graphicbox #about.gbx, 10, 10, 115, 340
     Groupbox #about.gp1, "", 140, 80, 155, 10
     Groupbox #about.gp2, "", 140, 280, 155, 10
     Statictext #about.stx1, "Liberty Basic Newsletter Reader", 145, 15, 145, 65
     Statictext #about.stx2, "about", 145, 100, 145, 175
     Button #about.ok, "Close",[about.close],UL, 190, 315, 100, 30
 Open "About LBNR" For Dialog As #about
 #about "trapclose [about.close]"
     #about "font ms_sans_serif 10"
     #about.stx1 "!font arial 12 bold"
     #about.stx2 "!font arial 10"
 'Create a info string for the body of the about text
     info$ = "Quick demo showing operation of loading a file directly into"      + Chr$(13) + _
     "a textedit window. It is quick and simple. Read the Tipcorner"      + Chr$(13) + _
     "of LB Newsletter 97 (June 2002) for more information. " + Chr$(13)      + _
     "By Brad Moore : June 2002 " + Chr$(13) + Chr$(13) + _
     "This code requires LB 3.x or greater to run"
 'put the info string into the static text field
     #about.stx2 info$
 'set a flag so we know the about window is open
     aboutWin = 1
 'add the graphic last
     #about.gbx "drawbmp LBNR 0 0"
     #about.gbx "flush"
     'wait for the user to close the window
     Wait
[about.close]
     Close #about
     'reset a flag so we know the about window is now closed
     aboutWin = 0
     Return

A point or two to bear in mind is that this is a snippet from a larger program and will not run as is on its own. Also, the graphic that is displayed in the graphic box is loaded by the main application and just reused in the code above.

Managing Multiple Windows

One of the things to watch for, when a program has the potential of having multiple windows open at any one time, is how the windows are handled when the program ends. If the main window is closed and the END statement is xecuted,
and other windows are left open, it will leave the program in an error state. For that reason I add a status flag to my code to track the status of all other windows that could be opened during program execution. This is good practice
if you are seeking a professional appearing application. Here is my flag being initialize in the main program body:

'Set a flag for the about window - initialize to zero
     aboutWin = 0

And later in the main program body the flag is checked prior to closing the main window to insure that the ABOUT window is not open.

[quit]
     'Don't leave the about window open
     If aboutWin <> 0 Then
     Close #about
     End If
     
     'Now close the main window
     Close #main
     End

Finally, the flag is managed in the snippet that displays the ABOUT window. Scanning that code above you will notice that it is set to the value '1' as soon as the window is opened, and is again reset to a zero when that window is closed.

Getting Back On-track

In addition to the ABOUT dialog window that was added to the LBNR, I have also written a quick and dirty help file which has been integrated into the code. Opening a help file is very easy in Liberty Basic, just specify the help engine name and the help file name as the argument to the RUN command. Here is the little bit of code used to open our help file called LBNR.hlp:

[help]
     Run "winhlp32 lbnr.hlp"
     Wait

I created the help file with the help file editor mentioned earlier in the article. You could just as easily have created it with a word processor or one of many other help file editor tools. In fact for a fairly simple program you could have even made your own window and then loaded a simple help text file. In a later article (due later in the fall of 2002) I will discuss help file creation and tools to make the job easier.

As mentioned earlier, the finished code is LBNR2.bas and its supporting files are in the ZIP file called LBNR2.ZIP. These are the files that we will use in the next sections.

Our Second Stop

Our second stop on our journey to release covers the steps needed to prepare and package the required files to run our application away from Liberty Basic. There are several fundamental steps that we must follow to get an executable application that does not require the Liberty Basic environment to run. The Liberty Basic Help file discusses much of this, as we will also. After a brief over view of the procedures that lie ahead, we will begin the process using the LBNR2 as our subject.

Preparing our project for release and distribution requires us to:

1) Create a tokenized runtime file (often called a TKN file) from our source code.
2) Gather all of our supporting files for distribution (graphic files, text files, help files, etc)
3) Make copies of the runtime libraries and runtime engine, renaming it if necessary.
4) Optionally changing the runtime engine icon.
5) Finally testing the distribution package.

Let's go through each of these steps, elaborating on the process. Additional information on each step can be obtained from the Liberty Basic help file.

Creating a TKN File

In order to run a Liberty Basic file outside of the development environment it must be first tokenized. Tokenizing a BAS file performs the initial compile steps, ordering the source code and writing it to an intermediate p-code that the Liberty Basic virtual machine can execute. A tokenized file is stored on your machine with the file extension TKN. The file is often called a TKN file instead of a tokenized file for this reason.

Using our example file called LBNR2.bas, tokenize it following these simple steps:

1) Open the file in the Liberty Basic 3 editor.
2) Run the file to insure it does not have any syntax errors that will prevent tokenizing.
3) Under the RUN menu of the editor, select the Make *.TKN file menu option.
4) After the file has compiled into a tokenized format you will be prompted to save the file. Save it as LBNR2.TKN.

That is all there is to it. You can run your tokenized file if you would like - by selecting Run *.TKN file from the Run menu of the Liberty Basic 3 Editor. One final not about creating TKN files. You must be using a registered version of Liberty Basic in order to create tokenized files for distribution.

File Collection I

The next critical step in preparing for release is to get all your additional files together. In most cases a project will have a graphic file or two (maybe many more), a help file and maybe even a text file or two. In our case with LBNR2 we have all three types of files to add to our distribution. I find it is helpful to create a sub-folder in my project folder to begin gathering my final release files into. I usually just call this folder RELEASE. In the project we are working on the folder structure might look something like:

Upper-level-folders...
|
+--- LBNR (You project development files are in this folder)
|
+---Release (Collect release files only here - copies of original files)

In the case of our project, copy (be sure to copy and not use the original files in your release folder) the following files into the release folder:

* LBNR-Demo.txt
* LBNR.hlp
* LBNR.gid
* LBNR.bmp
* LBNR2.tkn

The first four files are files I created for this exercise. They are part of the ZIP file mentioned elsewhere in this tutorial article. If you unpacked the zip file correctly, they should all be in one working directory, and I hope you called that directory LBNR. The fifth file is the TKN file you created in the previous steps. I did not include the TKN file, you must create it yourself.

File Collection II

The next step in preparing for distribution is the bringing together of the runtime libraries and the runtime engine. These are files that are shipped with the Liberty Basic product. The help file specifies the files that are required. I have not included these in the accompanying ZIP file because you should already have them on your machine of you are using Liberty Basic 3.x, and also because they are fairly large.

You will find all the files you need in the root of the directory where you installed Liberty Basic. It is important that you have both enabled the viewing of system files and the display of file extensions in the Explorer options of Windows. If you do not do this, you will not see all the files you require to create your distribution. In Windows 98 these options can be accessed by selection FOLDER OPTIONS from the VIEW menu of the Windows Explorer. Then clicking the VIEW tab in the dialog box that is presented. On my system I have enabled the "View All Files" option and have unchecked the "Hide file extensions for known types" option.

Presuming your computer is configured correctly, you should be able to locate the following files from the root of your Liberty Basic install directory:

* vbas31w.sll
* vgui31w.sll
* voflr31w.sll
* vthk31w.dll
* vtk1631w.dll
* vtk3231w.dll
* vvm31w.dll
* vvmt31w.dll

These are the runtime libraries. As you can see there are eight of them. Copy all eight to your RELEASE folder under
your LBNR folder.

Likewise, copy the file RUN.EXE (the runtime engine) from the root of your Liberty Basic install directory to your RELEASE folder under your LBNR folder. Your application is almost ready to be run free of the Liberty Basic development environment. One step remains - renaming the runtime engine.

Several releases ago Liberty Basic was changed to simplify the way a user launches an application created in Liberty Basic. Previously a second runtime was required which had the developer's registration key and a simple line to execute the real TKN file. This intermediate file was always called Startup.TKN. Today the requirement for this intermediate file is replaced with the simple step of renaming the runtime engine to the same name as the TKN that you want to execute when the runtime engine is invoked. In the case of our application, which is called LBNR2.TKN, we would need to rename the RUN.EXE to LBNR2.EXE. Don't change the EXE file extension. This is critical.

Rename your copy in your RELEASE folder now. Do not rename the RUN.EXE in the Liberty Basic folded, it is the wrong one. Once you are done, you can launch the LBNR2 application by simply double clicking the LBNR2.EXE file. Give it a try.

Kick it up a Notch

I like Emeril (the chef on satellite TV) - if you want a little more kick, toss a little more spice in. This step is purely optional, but if you are looking for a polished look and feel to you application I recommend it. This is that little extra "BAM".

Most programs have a unique icon, and yours should too. It is easy and fun to change the runtime icon of your application. First you will need a 32x32 icon. I created my own for the LBNR2 project, and you unpacked it with the rest of the files. It is called LBNR2.ico. In most cases, in the real world, you are not going to find the icon on a platter, but you are going to have to create you own. Creating icons is very easy, and there are many tools around to make it easier. I created my icon using Alyce Watson's icon editor from her Liberty Basic 2 files area (the URL for her site is: http://iquizme.0catch.com/lb). It is free and runs under LB2 (it will not run in LB3.x - sorry). Other alternatives are the icon editor that is part of Liberty Basic 3.x, or the icon workshop that is part of Liberty Basic Workshop (also available on Alyce's web site). Or search the web - there are many third party tools that are free. Some tips to remember: the icon must be 16 colors and measure 32x32 pixels.

For the purpose of discussion, let us simply use the icon I have provided. Changing the icon on the runtime engine is a very simple mater of following a few simple steps:

1) Open Liberty Basic 3.x
2) From the SETUP menu select ICON EDITOR (it is its own little applet)
3) From the FILE menu of the Icon Editor select OPEN ICON
4) Select the icon file named LBNR2.ico using the file open dialog window
5) You can edit the icon if you would like at this point - don't forget to save the result.
6) Finally apply the icon to the runtime engine selecting SAVE TO RUNTIME EXE from the file menu - you will need to navigate to your RELEASE folder and save it to the file LBNR2.EXE (remember we renamed the runtime engine earlier)

In addition to a customized runtime you should also consider whether you wish to distribute an End User License Agreement (EULA) with you application. Most serious software developers provide this document, which the user must agree to in order to begin using (or often as a result of using) the software product. It is a smart decision to have an EULA because it protects the software developer and the end user alike.

Stock EULA's are hard to come by. Many people simply pattern their EULA after those found on other popular software offerings. I located a couple sites that sell downloadable templates that can be used to develop an EULA. Check them out at (watch for line wraps):

*http://shop.store.yahoo.com/startupbiz/enduslicageu.html
*http://www.lawvantage.com/description/technology_agreements/software_license_agreements/summaries/SWLA1004S.shtml

The second link is a site called LawVantage, and they offer the following as a list of items that a comprehensive EULA would cover:

* Grant Of License;
* Usage Limitations;
* Unauthorized Use;
* Copy;
* Redistribute or Resell;
* Network, internet, intranet;
* Reverse Engineering, Decompilation and Disassembly;
* Separation of Components;
* Export;
* Use by Others;
* Intellectual Property Rights;
* Disclaimer Or Warranties;
* Limitation Of Liability;
* Term And Termination;
* Indemnification;
* Assignment;
* Survival;
* Miscellaneous;

As an alternative, the website for Shareware developers called UpLoad.it (http://upload.it/upload_000002.htm) offers the following template that can be copied and then modified to meet your own personal needs (the URL to see this online is: http://upload.it/upload_000039.htm) :

LICENSE
--------------
ACME Company (ACME) hereby gives you a non-exclusive license to use the software YourSoftware (the Software). For evaluation, the license is granted, and is time-limited. For registered release you have to pay a license fee, by following instructions prompted by the program.
You may:
- use the Software on any single computer;
- use the Software on a second computer so long as the primary user of each copy is the same person and more than one copy is not simultaneously;
- copy the Software for archival purposes, provided any copy contains all of the original Software's proprietary notices.

You may not:
- permit other individuals to use the Software except under the terms listed above;
- modify, translate, reverse engineer, decompile, disassemble (except to the extent applicable laws specifically prohibit such restriction),
- create derivative works based on the Software;
- copy the Software (except as specified above);
- rent, lease, transfer or otherwise transfer rights to the Software;
- remove any proprietary notices or labels on the Software.

TERMINATION.
The license will terminate automatically if you fail to comply with the limitations described above. On termination, you must destroy all copies of the Software and Documentation.

DISCLAIMER OF WARRANTY
---------------------------------------------
The Software is provided on an AS IS basis, without warranty of any kind, including without limitation the warranties of merchantability, fitness for a particular purpose and non-infringement. The entire risk as to the quality and performance of the Software is borne by you. Should the Software prove defective, you and not ACME assume the entire cost of any service and repair.

ACME IS NOT RESPONSIBLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES.

Title, ownership rights and intellectual property rights in and to the Software shall remain in ACME. The Software is protected by international copyright treaties.

----------------------END------------------

Obviously the developer who will be using this EULA will need to adapt it to their own needs. This version is specific to shareware - if you are developing freeware you will want to alter the terms as they relate to software evaluation. Another point to consider is that it is not uncommon to see the EULA as a part of the help file as well as plain test file.

Don't forget that once you create this file, it should also be included in the RELEASE folder so that you will remember to distribute it along with your application. In the case of our project, copy the file EULA.txt from the working directory to the RELEASE directory.


Testing (Again)

Nothing is more demoralizing that thinking it is all done and ready and releasing your work (with out testing it well) and finding out you missed something. Usually it is something simple, just adding to the humanization. Test and test well. You are pretty much done with preparing for distribution, now insure it all works. After you have tested the program thoroughly, have a friend or family member try their hand at it. Something you overlooked usually becomes apparent. Fix the problems and try again. Now is the time to get it right.

Arrival at our Destination

The final step in preparing your application for release is packaging. There are many packaging tools available, and some are even free. My favorite free packaging tool is Inno Setup Compiler. It can be downloaded from the Inno website at: http://www.jrsoftware.org/isinfo.php . Another good installer, which I have used before is HJInstall from freebyte software. The program is free and can be downloaded from the freebyte website at: http://www.freebyte.com/hjinstall/

For the purpose of this article, I am going to presume that you have gone to jrsoftware's website and downloaded Inno Setup Compiler and installed it on your system. If you have been following along and doing the exercise as we go, you are ready to create an install script.

Inno Setup Compiler has a very strong packaging wizard, which can easily create a comprehensive and professional looking install in only a matter of minutes. Start the wizard by selecting the option to create a new script file using the Setup Wizard when you first launch Inno. The wizard will walk you through a couple pages that collect basic information about your application. Our application is called LBNR and it is version 2. The defaults are generally fine on the Application Directory page.

The heart of the Setup wizard is the Applications Files page. Navigate to the executable for our application and set it as the application main executable. This is the renamed runtime engine that should now have a custom icon and be called LBNR2.EXE - it is in the RELEASE folder. Next, click the Add Files button and browse to the RELEASE folder again and select ALL the files in that folder except the executable LBNR2.EXE (it is included in the field above). You can select all the files at once by clicking the first file in the file dialog window, then clicking the last file and holding the shift key down at the same time. To unselect the one file we do not want simply hold the control key down (it is labeled Ctrl) and click the LBNR2.EXE file. If you made a mistake, there are additional buttons to add and remove files.

The next page can be setup any way you perfer. It is nice to leave the options enabled that allow the user to change the various settings to meet their own requirements. In the following page called Application Documentation, you can link to text files that you wish to display to the user. If your program included release notes, you can display them in the installer and the user could read them when installing. This is also a great place to link the EULA that was created earlier. In the case of our project, click the browse button for the license file and browse to the RELEASE folder and link to the EULA.txt file.

Click next and finish to complete the creation of your install script. Inno will give you the option of compiling the script. Unless you plan to make manual changes to the install script, go ahead and compile now. You should now have a single executable installer that can be run on any Windows 95 or better system. If you have a second system somewhere, or have a friend who can help, run the setup program on the other machine. It should install a fully functional, stand-alone application. Remember - test you installation. If you have access to several different Operating Systems (Windows98, Windows ME, Windows XP, etc) it would be great to try you program out on all of them. I know this is rare, but getting friends together to test on their machines is a great alternative.

I have included my Inno Setup script in the project archive that is coming with this newsletter. If you have installed Inno, you can look at it, although my directory structure will be different from yours, so you will probably not be able to use the script as is. Finally, the whole executable install is in the files area of the newsletter group in Yahoo. It was fairly large due to the size of the runtime files, and I did not want to send a file of that size along with the newsletter. If you followed along, you should already have a fully functional installation.

Thanks. Hope you enjoyed the ride. We have come to the end of the Journey. We have a professional product that is ready for market. Now my challenge to you: Finish your project and prepare it for market. Have fun!

Brad Moore
Bjaz.moore@verizon.net


Home

Window Placement Techniques
Listview Report by Brent Thorn
Enhancing Liberty Basic [Array Handling]
The Road to Release
Formatted ListBox