BYU Home pageBRIGHAM YOUNG UNIVERSITY
  Humanities Technology and Research Support Center
Back     CHum Revolution Gateway

CHum 310
The End-Game:
Building Standalone Distributions of Rev Stacks

Of course, the ultimate goal of any software developer is to get their program into the hands of users. If everyone needed to own a copy of Revolution in order to run the stack, distribution would be difficult.Fortunately, Revolution provides a robust set of tools for creating double-clickable, stand-alone applications on any supported platform. These standalone applications may be distributed without the developer having to pay royalties to Runtime Revolution (although Educational editions of Revolution are the exception to this policy).

Let's look at the tools for creating standalones.

Transcript Language Capabilities That Help Prepare for Cross-Platform Distribution.

TERM

TYPE

Description

platform

function

The platform function returns the name of the operating system Revolution is running on.
Here is a sample handler that could be used to check to see which operating system the program is running on at startup time:

on startup
  if the platform is "MacOS" then
    --do Mac stuff
  else if the platform is "Win32" then
    --do Windows stuff
  else
    --do Unix stuff
end startup

environment

function

The environment function returns the type of running environment the stack is in. The most common responses would be “standalone application” and “development”. If the environment function returns “development” the stack is being run in the Revolution development environment. If the environment function returns “standalone application” when the stack is being run as a standalone application. If you start up a stack outside of the development environment by Command-double-clicking (Mac) or Control-double-clicking (Windows) the stack icon the environment function returns “player”.

lookAndFeel

property

The lookAndFeel property specifies which platform the user-interface controls resemble. It affects the appearance of scrollbars, object borders, checkboxes and radio buttons, and button menus.This property does not give an exact representation of the appearance and behavior of the stack on the target platform. For example, it has no effect on cursors, placement of the menubar, and default fonts.

The lookAndFeel is one of the following:
Appearance Manager: standard Windows XP, Mac OS and OS X look and feel.
Macintosh: emulated Classic Mac OS Platinum appearance, used regardless of current theme.
Motif: standard Motif look and feel for Unix systems
Windows 95: standard Windows look and feel

machine

function

 The machine function returns the type of hardware the application is running on. For instance, if you were running on a Macintosh PowerBook, the function should return "Powerbook". On Windows systems the function always returns "x86".

processor

function

Use the processor function to determine which microprocessor the computer has.

The processor function returns one of the following strings:
• Motorola PowerPC on a Mac OS system with a PowerPC processor
• Motorola MC68000 on a Mac OS system with a 68000-family chip (older Macs)
• unknown on Unix systems
• x86 on Windows sytems and Mac OS X systems with an Intel processor

systemVersion

function

The systemVersion function returns the version number of the operating system.

This allows you to check for specific versions of the Mac and Windows OS as you are launching your stack.

specialFolderPath

function

The specialFolderPath function returns the path to directories that have particular functions in operating systems, but whose location differs for platform to platform. Examples include the Desktop, Documents and Preferences folders.

Differences in Appearance Between Platforms

Sometimes you will notice that a stack or standalone changes appearance in minor ways when moving them between platforms. For instance, the fonts might be slightly different, or the background color might be different. This is in part due to differing default settings that the Revolution engine uses on different platforms. One way to avoid these differences is to set the stack's textFont, textStyle, and textSize properties, and its backgroundColor, foregroundColor, and other color properties, to the values you want before creating the standalone.

Button Look and Feel

Even though Revolution presents several common button styles—Push Button, Default Button, Checkbox, etc., the appearance and behavior can be different enough between platforms that you will want to be sure to test them extensively on all platforms you are targeting.

Menus

As you know, menus look and behave differently on Mac OS vs. Windows and Linux/Unix systems. Most obviously, menus on the Mac OS appear at the top of the screen, while on Windows and Unix they appear in the application window. That means that you have to leave a little extra room at the top of your card for a menubar, if you are planning to deploy on Windows. This menubar would be hidden on Mac systems, so you have to decide if you like having the blank strip at the top of the card, or if you would rather resize the stack window slightly when running on Macs. Revolution does provide some automated help in this area, but you still need to check it on all platforms to make sure it works the way you want.

File System: Standard Storage Locations and Permissions

The various operating systems take differing approaches to securing certain areas of the file system against changes that could adversely affect the performance of the system. For instance, you don't want to allow programs (or Revolution stacks!) to delete critical system files. To prevent this, operating systems impose a system of permissions that determine which users or programs can write to which directories on the disk. Operating systems also provide certain directories that are always available and "safe" to write in. Examples include the user's Documents folder, the user Preferences folder and others. Revolution provides the specialFolderPath function to provide a cross-platform way of referring to these folder locations.

Object Profiles

Another way to compensate for platform appearance differences is to use profiles. A profile is a set of object property settings that can be used to quickly change things like languages, appearance and so forth in your stack. Creating profiles can be a useful strategy of optimizing your stack for different operating systems. For example, you might create separate profiles for Macintosh and Windows that use different fonts for buttons or fields, or that set slightly different background colors to compensate for the slightly different screen gammas (darkness or lightness of colors) between Mac and Windows monitors.

Standalone Application Settings

The first step in creating a standalone application is to establish the desired settings. To do this choose Standalone Application Settings... from the File menu. This brings up a special settings window that make it simple for you to prepare a stack or stacks for distribution as a standalone application.

General settings.

Standalone Name: The name of the standalone application you want to create.

Inclusions. Here you can choose to include various types of resource in the standalone file. The first radio button ("Search for required inclusions...") will scan your stack and attempt to automatically include the required libraries in the standalone. Alternatively, you can check the"Select inclusions..." button to manually choose the libraries to include in the standalone. What you check depends upon what resources your stack uses. For instance, if you have no animations in your stack you don't need to keep the Animation Libraries in the distribution. If you use the ask and answer commands in your stack be sure to check the Ask Dialog and Answer Dialog check boxes.

Property Profiles. A profile is a set of property settings for an object. You can create multiple profiles for each object in your stack in the Profile panel of the Property Inspector. In this section you can choose which profile will be used when building your standalone application. For example, you might create separate profiles for Macintosh and Windows that use different fonts for button or field objects. Here you can choose to either remove all profiles from all objects in your stack (in effect making the settings in Master profile the ones that are used), choosing a specific profile for all objects to use, or to include all profiles and the profile library, making it possible for users of your standalone to choose a profile.

Stack files to include.

Here you may select the stack files that are to be included in the distribution. There are buttons that let you add or remove stack files. The mainstack of the selected stack file will always appear first in the "Stacks in the selected stack file" list.

Advanced Options Section
   For the selected stack file checkboxes

Move substacks into individual files: Save substacks as separate files instead of as part of the standalone application.
Rename files generically: Renames substack files using numbers instead of the substack names.
Create folder for substacks: Here you can choose to have a separate folder for substacks or not. If you choose to have a folder, give it a name.

  Stacks in the selected stack file list

Lists all stacks in the stackfile selected in the list on the left. The mainstack always appears first in bold face.

  For the selected stack checkboxes

Set destroyStack property to true: If checked, the stack will be removed from memory when all of its windows are closed.

Encrypt with password: Allows you to require a password to enter the program.

Copy Files into the App

If you want to automatically copy external files—images, video or sound files,for example —into your standalone application folder, use this pane. The files that you add to the application will then be copied to a location that makes it possible for the standalone to find and use them.

For Windows executables and Classic Mac OS applications the files will be copied into the same folder as the standalone executable file.

For Mac OS X applications: Applications on Mac OS X are actually specialized folders called packages or bundles. Copied external files will be put inside this package so that they will not be immediately visible in the Finder. To see where the files are placed, Control-click or right-click on the application file and choose Show Package Contents from the popup menu. A window will open showing a folder called Contents. Open the Contents folder, then the MacOS folder. Here is where you will find copied files. (Note: If you have set the defaultFolder property in your stack to the folder that contains the stack file, when you create the standalone the defaultFolder will be this MacOS folder. On the other hand, if you never explicitly set the defaultFolder property in your stack, when you create the standalone the defaultFolder is set to the folder that contains the application package.)

Set OS Specific Settings

These four panes allow you to specify settings that determine how the standalone file will appear in the file system of the operating systems for which you are building your app. Here you can set things like application icon*, version number, and copyright notices.

Engine Download

If you are building for another operating system the standalone builder will check to make sure that you have the runtime engine for that OS in your Revolution installation. If it is not there it will ask you if you want to download it.

Note: On Unix and Windows systems, you cannot create a standalone application for Classic Mac OS systems. (You can create OS X, Unix and Windows standalone applications on any system.)

This is because Classic Mac OS applications contain a resource fork, which is a part of the file specific to the Mac OS filesystem and which other filesystems cannot accommodate. To create a standalone application that will run on Mac OS systems, you need to have at least short-term access to a Mac OS or OS X system.

 

Mac OS Pane

Build for: This refers to the various processors that Classic Mac OS may run under. If in doubt, choose Mac OS fat.

Creator Signature and Document Type :
All Macintosh files have a creator signature that the OS uses to determine which applications open which documents. For example, Revolution's creator signature is 'RApp'. You can use the default '????' or make up your own. If you make your own creator signature you should register it with Apple Computer to make sure it is unique.

Document type refers to the type of document your application can create or open. It can be an existing type or you may make your own custom type. In the latter case it should also be registered with Apple to avoid conflicts with existing type codes.

Include resources from file: Every Mac file can have what is called a resource fork, where special resources like cursors, icons, sounds, menus and others are stored. This option allows you to bring resources from any file into your own stack.

Macintosh Memory Information:
On the classic Mac OS (9.X and earlier) each application must designate an amount of memory to be assigned to it when launching. These settings can be chosen here.

Version Information:
These settings allow you to establish a version number for each build you make of your standalone application. It is important to carefully increment your version number with each successive build to avoid confusion over which build is the latest.

OS X Pane

Check the Build for Mac OS X box to save a standalone that will run under Mac OS X.

Icons*: You can assign a finder icon to the application by choosing a previously-created icon with the Choose... button next to the Application Icon field.

You can assign a Finder icon to the application's documents by choosing a previously-created icon with the Choose... button next to the Document Icon field.

You can also specify a custom icon to be displayed in ask and answer dialogs.

PLIST: A plist is basically a specially-formatted preference file. Unless you are familiar with XML and plists in OS X, choose the first option.

Name, Signature, Document section:

Name: The name is the name your application will be saved under. It is important that you get it right here. If you create the application then try to change the name in the Finder, you may break the application.

Signature: All Macintosh files have a creator signature that the OS uses to determine which applications open which documents. For example, Revolution's creator signature is 'RApp'. You can use the default '????' or make up your own. If you make your own creator signature you should register it with Apple Computer to make sure it is unique.

Document type refers to the type of document your application can create or open. It can be an existing type or you may make your own custom type. In the latter case it should also be registered with Apple to avoid conflicts with existing type codes.

Document extension refers to the extension that appears after the '.' in name of files your application may create. For example, if your application saves plain text files, set this to 'txt'. You may also use a custom extension.

Version Information section.

The information you provide in here will help you keep track of version, copyright and other information under Macintosh OS X. The Long Version and Short Version fields hold strings that describe which version of the application this build is. It is important to carefully increment your version number with each successive build to avoid confusion over which build is the latest.

The copyright notice appears in the Finder's Get Info box for your application. The bundler identifier helps identify your application to the OS. Normally you shouldn't have to change this.

 

Windows Pane

This tab is where you may include Windows-specific information, such as which icons* will appear with the application, version and copyright information, and others. It is important to carefully increment your version number with each successive build to avoid confusion over which build is the latest.

You can assign an icon to your Application by clicking Choose... and navigating to a previously-created .ico file.

Unix Pane

Build for: Choose the version of Unix you want to run your application on.

Include: Unix-specific libraries you may wish to include in your application.

Bug Report Pane

If you wish to provide a mechanism for your users to report bugs and errors back to you, click the Include Error Reporting Dialog box. You can then customize the error dialog text, assign a custom error dialog icon, and allow the user to save the report, enter their own comments, and even email you a copy of the error to assist you in debugging.

*Custom application icons: More information on creating icons for standalone applications can be found in this excellent tutorial by Chipp Walters of Altuit, Inc., a major Revolution developer.

Back     CHum Revolution Gateway
Maintained by Devin Asay.
Copyright © 2005 Brigham Young University