Chapter 25: Building an Application for Distribution

Building an application for distribution is similar to developing a standard Visual FoxPro application. You work in the Visual FoxPro development environment as usual, but then you create an executable file or Automation server (a COM component) and test it in the run-time environment. You then distribute your application and any related files to your distribution sites.

This chapter describes changes you need to make to prepare an application for distribution, as well as some suggested changes that help make a distributed application look unique.

This chapter addresses:

The Distribution Process

The following list identifies the steps you need to follow to distribute a Visual FoxPro application:

Preparing an Application for Distribution

The following sections describe the steps you might need to take to prepare your application for the run-time environment. These steps include:

Choosing the Type of Build

Before you can distribute your application, you must build either an application file, with an .app extension, or an executable file, with an .exe extension. The following table lists the differences between the builds.

Build Type Characteristics
Application (.app) file 10K to 15K smaller than an .exe file.
User must own a copy of Visual FoxPro.
Executable (.exe) file Application includes the Visual FoxPro loader so users don’t need to own Visual FoxPro. You must provide the two support files Vfp6r.dll and Vfp6renu.dll (EN denotes the English version). These files must be placed in the same directory as the executable file or along the MS-DOS path. See BUILD EXE for more information about creating and distributing executables.
OLE DLL Used to create a file that can be called by other applications. For details about using this build option, see Chapter 16, Adding OLE.

When you choose the type of build, consider the size of your final application file and whether your users own Visual FoxPro.

Considering Hardware, Memory, and Network Issues

You should consider and test the minimum environment your application can operate in, including the amount of disk space and memory. The results of your testing and the resolution of other issues covered in this chapter can help determine the type of build you choose, the files you include with your application, and the way you structure your distribution directory.

The applications you create have the same hardware, memory, and network requirements as Visual FoxPro. For more information on those requirements, see “System Requirements” in Chapter 1, Installing Visual FoxPro, in the Installation Guide. For additional information on creating applications for multiuser environments, see Chapter 17, Programming for Shared Access.

An executable application file always checks for the presence of the Visual FoxPro run-time library, Vfp6r.dll. To run an application .exe file using the development version of Visual FoxPro, you must force the application to use the Visual FoxPro .exe file instead.

To run an executable application in Visual FoxPro

Ensuring Correct Run-Time Behavior

An application consisting only of modeless forms will not function properly in a run-time environment unless you provide a READ EVENTS command. You can ensure that the application runs properly by adding a calling program or setting the WindowType property.

To run a form in a run-time environment

Some Visual FoxPro applications rely heavily on Visual FoxPro system menus. At run time, some menus and commands are unavailable, and without a provision for a READ EVENTS command, a menu-driven application ends as quickly as it starts. Use the following section to review any menus you include in your application.

For more information on structuring an application with the READ EVENTS command, see “Controlling the Event Loop” and “Examples of How to Structure an Application” in Chapter 13, Compiling an Application.

Menu Options

If you use the Visual FoxPro system menu, your application file includes only the following default menus and menu commands.

Menu Menu items
File Close, Save, Save As, Exit
Edit Undo, Redo, Cut, Copy, Paste, Paste Special, Select All, Find, Replace
Window Arrange All, Hide, Hide All, Show All, Clear, Cycle, all open windows
Help Contents, Search for Help on, Technical Support, About Visual FoxPro

You can disable or remove any of the default menus and menu commands, or add your own menus and menu commands to run-time applications.

Troubleshooting   If your menu system works in the development environment but closes prematurely in your application, make sure you have a READ EVENTS command active while your menu system is running. Also be sure to include a CLEAR EVENTS command when you exit the menu system.

For more information about customizing menus, see Chapter 11, Designing Menus and Toolbars.

Including Resources in Your Applications

Visual FoxPro provides several resource files that extend the basic functionality of your applications, including FOXUSER resource files, API libraries, and ActiveX controls. If you use these files, you must include them in your project or distribution tree.

Including FOXUSER Resource Files

Visual FoxPro resource files store useful information for your application, including window positions, Browse window configurations, and label definitions. If your application relies on specific settings for any of these resource items, you must also distribute the FOXUSER database and memo files or the resource files you create specifically for your application. These resource files consist of a Visual FoxPro table with an associated memo file, usually named Foxuser.dbf and Foxuser.fpt.

Note   The FOXUSER resource file isn't the same as the locale-specific resource file that contains dialog boxes and error messages. The FOXUSER resource file stores application information such as macros you've defined; the locale-specific resource file stores system text strings. For more information, see Including a Locale-Specific Resource File later in this chapter.

Including External Library Files

If your application includes external library files such as ActiveX controls (.ocx files) or Visual FoxPro API libraries (.fll files), use the Setup Wizard to ensure they're placed in the appropriate directory. You can distribute the Visual FoxPro file Foxtools.fll with your applications. For more information on creating external libraries to access the Visual FoxPro API, see Part 9, Accessing APIs.

Including COM Components

If you include ActiveX controls or have created a Automation server (a COM component) as part of your application, include any .ocx files in your project and ensure the necessary support files are installed on the user’s machine in the Windows system directory. Note that you can only distribute ActiveX controls for which you are licensed. For Automation servers, you must also include registration files, such as type libraries (.tlb files) and registry files (.vbr files), with your application.

If you use the Setup Wizard to create the distribution disks, you can include these files automatically. In Step 6, make sure the ActiveX column contains check marks for the ActiveX controls you’re shipping. When you do this, the Setup program created by the Setup Wizard will ensure that COM components are registered properly on the user’s computer when the application is installed. For more information on the Setup Wizard, see Chapter 26, Creating Distribution Disks

All users can run forms containing ActiveX controls; however, your application cannot accomplish certain tasks if it is running under the run-time version of Visual FoxPro. Remember the following guidelines:

Including a Configuration File

The configuration file, Config.fpw, can establish many default Visual FoxPro settings. For instance, you can change the Visual FoxPro title, the background color, and the way a user navigates with the keyboard.

If you want the configuration file to be read-only, place it in your project and mark it as included. If you want the configuration to be modifiable, place the file in your project and mark it as excluded. Then distribute the configuration file with your application or executable file, as a separate file. By default, Visual FoxPro looks for a configuration file named Config.fpw. However, you can specify a different configuration file name using the -C command-line switch when starting Visual FoxPro.

For more information about options that you can set in the configuration file, see “Using a Configuration File” in Chapter 3, Configuring Visual FoxPro, in the Installation Guide.

Including a Locale-Specific Resource File

If you're distributing your application along with the run-time version of Visual FoxPro, you might need to include a locale-specific resource file. This file contains the dialog boxes and other user-interface elements that Visual FoxPro uses to interact with the user. There's a different run-time resource file for each language in which Visual FoxPro is available.

For more information about using locale-specific run-time files, see “Distributing Locale-Specific Run-Time Files” in Chapter 18, Developing International Applications.

Note   The locale-specific resource file isn't the same as the FOXUSER resource file, which stores application information such as macros you've defined. The locale-specific resource file stores system text strings. For more information, see Including FOXUSER Resource Files earlier in this chapter.

Including All Your Files

You can freely reproduce and distribute some Visual FoxPro files, graphics, and programs with the applications you create. For detailed information, see Removing Restricted Visual FoxPro Features and Files later in this chapter.

Before you build your application, make sure that your project includes the necessary files for your application as well as any additional resource files, such as graphics files or templates.

The following table list files you can add to your project.

If you are Add these files to your projects
Applying a custom configuration to your application Config.fpw
Applying custom settings to your application Foxuser.dbf and Foxuser.fpt
Distributing a .dbf-style Help file Your .dbf-style Help file

To add files to your application

For more information about creating a project, and including or excluding files in a project, see Chapter 13, Compiling an Application.

Removing Restricted Visual FoxPro Features and Files

The development environment of Visual FoxPro contains many features and files that are licensed for your use only. If your application contains any of these features or files, remove them.

Restricted Visual FoxPro Features

You cannot include the following Visual FoxPro menus and their menu commands in a distributed executable file.

Restricted menus
Database Project
Form Query
Menu Table
Program

If your application includes the following commands, it will return the error “Feature not available.” Although you cannot include commands that create or modify menus, forms, or queries, you can run compiled menu, form, or query programs in your application.

Unavailable commands
BUILD APP MODIFY FORM
BUILD EXE MODIFY MENU
BUILD PROJECT MODIFY PROCEDURE
COMPILE MODIFY PROJECT
CREATE FORM MODIFY QUERY
CREATE MENU MODIFY SCREEN
CREATE QUERY MODIFY STRUCTURE
CREATE SCREEN MODIFY VIEW
CREATE VIEW SUSPEND
MODIFY CONNECTION SET STEP
MODIFY DATABASE

If used in a distributed application, the following commands are ignored.

Ignored commands
SET DEBUG SET DOHISTORY
SET DEVELOPMENT SET ECHO

Restricted Visual FoxPro Files

Visual FoxPro installs files on your computer that are restricted and may not be reproduced or distributed, including:

Although you cannot distribute Visual FoxPro sample applications with your applications, you can refer to portions of sample application code as examples for building your own application. You can also include the wizard class library, Wizstyle.vcx, and the sample class libraries in your application.

License.txt

Visual FoxPro contains many files that are licensed for your use for design, development, and testing purposes only. See License.txt, located in your Visual FoxPro directory, for a list of restricted files.

If your application contains any of these files, remove them. Under the terms of the Microsoft License Agreement you received with this product, you aren't permitted to ship these files in your application or on your disks.

Distributable Files

You may distribute any Visual FoxPro file that isn't restricted. Pursuant to the Microsoft License Agreement you received with this product, files must be distributed in conjunction with a corresponding application. The following guidelines apply to distributable files.

Setup Wizard

The Setup Wizard checks for restricted files and will exclude them from distributable disk sets. Do not assign these file names to any files you will distribute. The Setup Wizard will exclude any file that has a name identical to one on this list.

Any files in the Visual FoxPro Distrib.src and SETUP directories that are required to support a corresponding application may be distributed. When you use the Setup Wizard to create distribution disks, it automatically places the required files from these directories on the distributable disks in a compressed format. Upon installation, these file are decompressed and are installed by name in the appropriate directories on the user’s machine. It isn't necessary to copy these files to your distribution tree.

Samples

Files in the Visual Studio …\Samples\Vfp98 folders and in the Vfp98\Api\Samples folders are provided for you to learn from and build on. Although you may not distribute unmodified Visual FoxPro sample applications, you may refer to portions of sample application code as examples for building your own application.

If you use any files in these directories (including all .bmp, .ico, and .cur files), they must be included in your project and in the application build. They must not appear by name on the distributable disks and may not be distributed independently of your applications.

Class Libraries

You can use any .vcx file, including those in the Vfp98\Ffc and Vfp98\Gallery directories, without modification in your applications. The libraries must be included in your project and in your application build.

ODBC Files

Please refer to the Microsoft License Agreement you received with this product for specific restrictions with respect to your redistribution of ODBC files.

ActiveX Controls

Visual FoxPro includes a set of ActiveX controls (.ocx files) you can add to and distribute with your applications.

Customizing an Application for Distribution

The Visual FoxPro default run-time environment looks like the development environment: it displays Visual FoxPro icons and menus. To give your application a unique appearance, you might want to customize some of its features by:

Protecting and Documenting Your Source Code

To prevent users from viewing or changing the source code of your application, encrypt your source code and remove debugging information.

Tip   Always back up your source code before encrypting it.

To protect your source code

  1. Open your application project.

  2. From the Project menu, choose Project Info.

  3. In the Project Information dialog box, select Encrypted and clear Debug info.

  4. In the Project Manager, choose Build.

  5. In the Build Options dialog box, select Recompile all files and choose OK.

  6. In the setup section of your application, include the SET DEBUG OFF command.

Before you begin the distribution process, if you haven’t already done so, you can comment and format your code so it has a consistent appearance and is easier to maintain. You can use the Beautify option from the Tools menu or the Documenting Wizard to customize your application documentation in several ways, including:

To use the Documenting Wizard

  1. From the Tools menu, choose Wizards.

  2. From the submenu, choose Documenting.

You can also use the Documenting Wizard to create cross-references of symbols you’ve used in your application and to produce an analytical summary of your project.

Calling Error-Handling and Shutdown Routines

At times, errors occur when users run your application. You can call your own error-handling routine by including ON ERROR. Typically, ON ERROR uses a DO command to run a routine which handles the error, as in:

ON ERROR DO My_Error

If your application contains no error-handling routines when an error occurs, the application pauses and Visual FoxPro displays an error message with the following options:

For more information about error handling, see “Handling Run-Time Errors” in Chapter 14, Testing and Debugging Applications.

For a complete list and explanation of Visual FoxPro error messages, see Error Messages.

Tip   Be sure to provide documentation to your users that describes the errors that they might see, and suggests ways in which they can correct errors.

Create your own shutdown routine by including the command ON SHUTDOWN in your code. Typically, ON SHUTDOWN uses a DO command to call a routine if you try to exit the application, as in the following example:

ON SHUTDOWN DO My_Shutdown

This routine typically includes a dialog box that asks if the user is sure they want to quit the current application. If the user wants to quit the application, the routine can close open files and clean up the environment, and then issue the QUIT command. If the user doesn't want to exit the current application, the routine can return control to the application.

Adding Help to Your Application

You can integrate context-sensitive Help into your applications, so that users can press F1 or choose Help from a menu to get assistance with your application. The Help that you provide with your application has the same features as the Help in Visual FoxPro. For more information, see Part 7, Creating Help Files.

If you create graphical Help for your application, include the .chm or .hlp file in your application distribution directory so that the Setup Wizard includes it on your distribution disks.

Note   You cannot distribute Winhelp.exe or the Help files shipped with Visual FoxPro. For more information, see Removing Restricted Visual FoxPro Features and Files later in this chapter.

Modifying the Appearance of Your Application

You can modify the appearance of your application without changing your application code by:

Changing the Default Visual FoxPro Menus

You can add your own menus and menu options to distributed applications by using the Menu Designer. If you don't create your own menu, the run-time environment displays a default Visual FoxPro menu.

For details on the default menus, see Ensuring Correct Run-Time Behavior earlier in this chapter. For more information about the Menu Designer, see Chapter 11, Designing Menus and Toolbars.

Changing the Default Title

Your application runs in the main Visual FoxPro window. By default, the text “Microsoft Visual FoxPro” appears in the title bar.

To customize the title of the main Visual FoxPro window

To include a Visual FoxPro function as part of the title, use the Caption property of the main window as in the following example.

COMMAND=_SCREEN.Caption=;
"Visual FoxPro " + SUBSTR(VERSION(),25,3)

Changing the Default Application Icon

After your application is compiled, the default Visual FoxPro icon appears in the Windows Explorer or Start Menu as the application icon. You can use the generic icon that is supplied by Visual FoxPro or design your own.

If you want to display your own icon, create an icon (.ico) file with two images: one small (16 by 16) and one standard (32 by 32). Create both images as 16-color icons.

You can change the default Visual FoxPro icon in the Project Info dialog box of the Project menu. If you use the Setup Wizard to create distribution disks for your application, you can also specify an application icon there.

To change the default application icon using the Project Manager

  1. In the Project Manager, select the main file for your project.

  2. From the Project menu, choose Project Info and then select the Project tab.

  3. Choose Attach icon.

  4. Choose Icon and then select an icon (.ico) file to assign to your project.

Backing Up Your Source Code

In all application development, it’s a good practice to make complete backup copies of your original program files before you build an application. Store the backup copies separately from your compiled applications.

Important   Be sure to maintain separate copies of your original source programs for future use. You cannot re-create your source programs from their compiled code.

Building Your Application

When your application project contains all the necessary files, you're ready to build a distributable file. You can build your project as a standard application that only runs when Visual FoxPro is present, or as an executable application that runs without Visual FoxPro.

Note   You can also build your application as an Automation server. For details, see Creating Automation Servers in Chapter 16, “Adding OLE”.

Building a Standard Visual FoxPro Application

You can build a standard Visual FoxPro application with the Project Manager or with the BUILD APP command. However, more build options are available when you create an application through the Project Manager.

To build a standard application

Building an Executable File

You can build a Visual FoxPro executable file with the Project Manager or with the BUILD EXE command.

To build an executable file

You can also build an Automation server, which creates a DLL that can be called from other Windows programs.

To compile an Automation server

Preparing to Make Distribution Disks

Now that you’ve considered all the requirements and options that Visual FoxPro provides, and built an application from your files, follow these steps:

Creating a Distribution Directory

The distribution directory contains copies of all the project files that comprise your application. The structure of this distribution tree represents the way the Setup routine created by the Setup Wizard will install files on a user’s machine.

Mapping the project files to the distribution tree

To create the distribution directory

  1. Create a directory named as you want it to appear on a user’s machine.

  2. Divide the distribution directory into any subdirectories folders that are appropriate for your application.

  3. Copy files from the application project into the directory folder.

You can use this directory to test your application in the run-time environment. If necessary, temporarily reset defaults on your development machine to reflect the minimum settings on a target user machine. When everything works correctly, use the Setup Wizard to create disk images that will reproduce the correct environment when you distribute copies of your application.

Creating the Distribution Disks

To create distribution disks, use the Setup Wizard. The Setup Wizard compresses the files in the distribution tree and copies these compressed files to the disk image directory, placing them in a separate subdirectory for each disk. After you use the Setup Wizard to create images of your application disks, copy the contents of each disk image directory to a separate disk.

When you distribute the package, the user can install all the files for your application by running Setup.exe from Disk 1.

For details on using the Setup Wizard, see Chapter 26, Creating Distribution Disks.