FruitBat 1.5

FruitBat Icon

FruitBat provides a simple user interface for the command line tools available in the Blackberry® Tablet OS SDK. It will package, install and uninstall in-development apps and without having to type a single line in the Windows Command Prompt or Terminal in Mac OS.

It is compatible with Windows XP, Windows Vista, Windows 7 in both 32 and 64-bit variations and also Mac OS X Snow Leopard and Lion through the magic of Adobe AIR. You may need to run it as Administrator in Windows Vista and Windows 7 if  UAC is active (it is by default).

As with all beta software, features included or represented in the beta release may not make it to any final non-beta release or may change drastically between now and then. This release also does not guarantee any further releases in the future.

Download FruitBat 1.5 (Win)
v 1.5.0259 - 1.58 MB – exe

Download FruitBat 1.5 (Mac)
v 1.5.0259 - 1.46 MB – dmg

What it does:

FruitBat works with both the Adobe AIR SDK and WebWorks SDK for BlackBerry Tablet OS. WebWorks for Smartphones is NOT currently supported.

Adobe AIR SDK for Tablet OS Features

  • Package, install and uninstall BAR files to/from the BlackBerry PlayBook simulator or physical hardware via an AIR descriptor file, precompiled SWF, icon file and any additional app resources available. For direct device installation, a developer debug token must be installed and active on the device.
  • If you use the FlashDevelop IDE, a PlayBook template is available for download for a fast start.

WebWorks for Tablet OS SDK Features

  • Package BAR files using only the app’s config.xml file. It works just like an AIR descriptor.
  • Creates the required ZIP file during packaging, which saves you time. The ZIP is recreated every time you package your app, so all added/changed files are included automatically.
  • All testing packages created and installed are created with the remote inspector console enabled, so you can debug from your favorite web browser (Chrome works well) by visiting your PlayBook’s IP address under port 1337 (ex. http://255.255.255.255:1337).

Both AIR & WebWorks

  • Displays your app icon with the PlayBook’s default shadow in the main FruitBat interface. If your icon does not show, something isn’t right – iconless BAR files are rejected in the AppWorld review. Missing icons will show the SDK’s default Question Mark icon instead.
  • Excludes files from the packaging process that are not necessary or desired. Any file that meets any one of the following rules is automatically excluded from your BAR file if it:
    • …has any of the following extensions: exe, msi, bar, bat, ini, com, vb, vbs, dmg, app, sea, air, tmp, deb, rpm, script.
    • …is named or name begins with: thumbs.db, .ds_store, .trash, .__macosx, ._, .gitignore, gitattributes.
    • …is a hidden file (version control, platform specific system files, etc).
    • …is a symbolic link.
    • …is a directory (files in directories ARE included, and the directory structure is maintained, but directories are not added exclusively and empty directories are excluded completely).
    • …is the WebWorks ZIP file (all other ZIP files are not excluded, so you can zip all of your assets together to be unzipped by your app once installed, if that’s how you work).
  • Install signed or unsigned, prepackaged BAR files to the simulator or device (debug token rules apply for unsigned apps).
  • Uninstall prepackaged BAR files from the simulator or device.
  • Dynamically creates everything the command line needs from the AIR descriptor and bar-descriptor or blackberry-tablet files or from config.xml for WebWorks apps.
  • Package and sign completed apps so they are 100% ready for BlackBerry AppWorld.
  • Register signing keys for both application signing and debug tokens.
  • Request/create and install debug tokens to your tablet device for installing unsigned apps.

What it doesn’t do:

  • Compile SWF files from ActionScript and/or MXML files. It could do this, if I can find a friendly way to prepare a configuration file for mxmlc.
  • Connect to any Flash debugging solution. Maybe later.
  • Feature requests are welcomed with open arms via the contact form, though know I have a lot more in mind to create a well-rounded product, even extending outside of the BlackBerry ecosystem.

Known Issues:

  • The menu button mouse over highlighting sticks occasionally. Something with the menu opening is interfering with the mouse out event for the button. This only a visual defect and does not affect any functionality.
  • Updater cannot be cancelled if an update is available. The only option at that point is to “Update Now” or exit the application. The cancel buttons past this point do not stop the update process, despite the update UI being hidden; download will continue and when it has finished, FruitBat will exit and install the update. I’ll fix this in the next update so you can still cancel if an update is found.

How to use it:

All of the following assume the proper fields have been filled in with correct values in the Settings/Preferences window.

  1. Install FruitBat.
  2. On first run, fill in as many of the fields in the Settings/Preferences window as possible. For basic functionality (no signing, debug tokens, etc), the following are required, depending on your development environment: AIR SDK location, WebWorks SDK location, simulator IP address and simulator password and/or your PlayBook hardware’s IP address and password.
  3. Place all of the files required for your application in a common folder. The specifics below sound complicated, but really, just put all of your final files (SWF, HTML, images, icons, etc – not raw AS or MXML files) together in a single folder.
    • The location of your AIR descriptor file or WebWorks config.xml file is FruitBat’s working directory. Everythingyour application requires should be in this folder…
    • A BlackBerry QNX Manifest XML file named blackberry-tablet.xml (for SDK version 1.0) or bar-descriptor.xml (for version 2.0 of the SDK) should also be placed in the working directory. This file contains PlayBook specific properties, including the location of your 86×86 pixel application icon and splash screen images.
    • Of the next files, only the SWF file is required for a functioning PlayBook app built with AIR. Of course, for WebWorks, the app’s HTML, JS, CSS, etc. are needed. You can place these items in subfolders of the working directory or in the working directory itself:
      • SWF file that is your main application container. If this isn’t in the working directory, make sure you’ve defined the relative path in the initialWindow->contentnode of the application descriptor file.
      • Any other assets that are required by your application (HTML, JS, CSS, images, sounds, video, etc) and should be packaged with your app for distribution. These can be sorted and organized in any way you like. FruitBat will do a recursive search for files in the working directory and include everything it finds, minus the files that match one of the exclusion rules above, in your compiled BAR file.
  4. Drag and Drop the AIR descriptor or WebWorks config.xml file onto FruitBat (or use File > Open App XML [ctrl+o] in the menu)
  5. Fire up the simulator in or your tablet hardware in Development mode if it isn’t already and click the Package & Install button.
    • There are arrow buttons on either side of this button to change the command between “Package & Install” and “Uninstall.” Of course, they both relate to the app whose XML file currently loaded.
  6. To switch apps just drag another descriptor on top of the FruitBat window and drop it (or use the menu item).

Package & Install the Currently Loaded App:

  1. Click either arrow on either side of the multi-button in the main FruitBat interface until the Package & Install button is shown (it is shown by default, but will never be more than one click away)
  2. Click the Package & Install button. Remember, this is only a testing/debugging BAR file. The debug or d flag is enabled depending on the development platform.

The BAR file is placed in the current working directory if it is an AIR app. WebWorks apps are created in a folder called “bar” inside of the working directory.

Uninstall the Currently Loaded App:

  1. Click either arrow on either side of the multi-button in the main FruitBat interface until the Uninstall button is shown (should only be one click, max).
  2. Click the Uninstall button.

To Install and Uninstall BAR files:

  1. Use the File menu and choose either Install BAR File (ctrl/cmd+i) or Uninstall BAR File (ctrl/cmd+u). If the BAR file is not signed, and will be installed to tablet hardware, make sure you have a debug token installed and that your app is properly configured according to RIM’s instructions.
  2. Browse and select the BAR file.
  3. Click the Open button.

To Package and Sign a Completed App:

Use the Publish menu and choose Package Final Release (ctrl/cmd+p). As with all other actions, the app related to the XML file that is loaded into FruitBat will be packaged and signed. If no XML is loaded, a file dialog will automatically open so you can choose the proper XML file.

To Register App Signing CSJ with RIM’s Server:

Make sure both App Signing CSJ Pin & App Signing CSK Password are both defined in the Settings/Preferences window.

  1. Use the Publish menu and choose Register Signing Keys.
  2. Navigate and select your CSJ file (you’ll have 2 – the correct file’s name includes “rdk”)
  3. Click the Open button.

To Register Debug Token CSJ with RIM’s Server:

Make sure both App Signing CSJ Pin & App Signing CSK Password are both defined in the Settings/Preferences window.

  1. Use the Publish menu and choose Register Debug Token.
  2. Navigate and select your debug token CSJ file (you’ll have 2 – the correct file’s name includes “pbdt”)
  3. Click the Open button.

To Request a 30-day Debug Token BAR File for Tablet Installation:

  1. Use the Publish menu and choose Request Debug Token (ctrl/cmd+r).
  2. Choose a folder where the debug token BAR file should be created.
  3. Click the OK button.

The debug token will be named debug_token.bar. This process will automatically update the proper field in the settings window with the file’s location.

To Install a 30-day Debug Token BAR File onto Tablet Hardware:

  1. Use the Publish menu and choose Install Debug Token (ctrl/cmd+d).
  2. If the Debug Token Save Location setting has not been set, navigate to and select the debug token BAR file to install.
  3. Click the Open button.

Toggle the Settings/Preferences Window:

Click the gear button from the bottom right corner of the main app window. Mac users may also use the usual cmd+, shortcut.

Toggle the FruitBat Console Window:

Click the console button (to the left of the gear button) from the bottom right corner of the main app window. Windows users may use the File > FruitBat Console menu item while Mac OS users may use the Console item in the main app menu.

Updating FruitBat

You may update at your convenience by using the application menu (Help > Check for Updates). In the future, updates will be completely automatic and not optional.

FruitBat Settings/Preferences File Location:

Windows

%appdata%\FruitBat\Local Store\settings.json

Mac OS

/Users/[username]/Library/Preferences/FruitBat/Local Store/settings.json

One Response to “FruitBat 1.5”

This is a HUGE help for me. Thanks for your hard work Chris!

Leave a Reply