Since switching over to a Macbook Pro at work about 8 months ago, I've been slowly fine tuning my development environment to meet my needs. There is quite a bit of setup involved to get up and running so I'm going to attempt to document my environment in a series of posts in hopes of helping others and also to remind me of the steps needed if I ever migrate to a new system. This initial post will layout the basics needed to build a BlackBerry WebWorks application which uses Cordova.
Software Requirements:
- Java - Apple decided to no longer ship Java as part of the base OS beginning with OS X 10.7. If you are running OS X 10.7+ you'll need to manually install it.
- Adobe Air SDK - Only required for PlayBook development. Install this before the BlackBerry WebWorks SDK for Tablet OS since it prompts for the install location.
- BlackBerry WebWorks SDK - Smartphone and/or Tablet.
For example:
$ ln -sf /Work/BlackBerry/WebWorksSDK_2.3.1.5 /Work/BlackBerry/WebWorksSDK
Cordova Project Setup
After installing all the necessary requirements, its time to grab a copy of Cordova. Eventually, releases will be hosted somewhere on Apache but for now the easiest place to grab the latest version is from phonegap.com. The download file is a zip file. Extract the contents to a location of your choice. The best way to get started developing a Cordova BlackBerry project is to make a copy of the lib/blackberry/sample folder. That folder contains a complete working project with Ant build tools to automate building and deploying the builds to simulators/devices. Copy the sample folder to a location of your choice then change the working directory to that folder. You should see the following contents in that directory:
lib - Contains a copy of ant-contrib used by the build script
and a copy of the Cordova resources.
www - Contains all the application resources.
project.properties - Configuration file for the build script.
blackberry.xml - Smartphone implementation of the build script.
build.xml - Build script.
playbook.xml - Playbook implementation of the build script.
The only configuration that needs to be done before building the sample project is to open the project.properties file and specify paths to the SDK(s) previously installed. Open the file in an editor the following values with your install locations. Please note that the path must specified for each must be the folder that contains the bbwp executable.
blackberry.bbwp.dir=/Work/BlackBerry/WebWorksSDK playbook.bbwp.dir=/Work/BlackBerry/WebWorksTabletSDK/bbwp
Building the Sample Project
After configuring the project, executing the ant command from a terminal will provide usage information similar to the following snippet:
help:
[echo]
[echo] NAME
[echo] Build and Deploy a Cordova BlackBerry WebWorks Project
[echo]
[echo] SYNOPSIS
[echo] ant TARGET COMMAND [-D
=
]... [echo] [echo] DESCRIPTION [echo] You can build and deploy your project to a device or simulator. [echo] [echo] TARGETS [echo] blackberry ........ Builds a cod file and deploys to a device or simulator [echo] [echo] playbook .......... Builds a bar file and deploys to a device or simulator [echo] [echo] COMMANDS [echo] help .............. Show this help menu. [echo] ant, ant help [echo] [echo] load-device ....... Builds and deploys project to a connected USB device. [echo] ant load-device [echo] [echo] load-simulator .... Builds and deploys project to default simulator. [echo] ant load-simulator [echo] [echo] build ............. Compiles and packages the project for deployment. [echo] ant build [echo] [echo] clean ............. Remove all files from the build/ directory. [echo] ant clean [echo] [echo] clean-device ...... Remove this project from the connected USB device. [echo] ant clean-device [echo] [echo] clean-simulator ... Remove this project from the simulator (takes a while). [echo] ant clean-simulator
The build script supports building both smartphone and playbook applications through the TARGET option. There are commands to deploy the application to a simulator and device which will be discussed in future posts, but for now we're just focussing on building. To build the sample application enter the following in the terminal ant TARGET build where TARGET is the platform ( blackberry or playbook ) you want to build for. Note that you must have the associated SDK installed and configured in project.properties .
$ ant blackberry build
Buildfile: /Work/Cordova/sample/build.xml
blackberry:
build:
generate-cod-name:
[echo] Generated name: CordovaSample.cod
clean:
[delete] Deleting directory /Work/Cordova/sample/build
package-app:
[mkdir] Created dir: /Work/Cordova/sample/build/widget
[copy] Copying 8 files to /Work/Cordova/sample/build/widget
[zip] Building zip: /Work/Cordova/sample/build/CordovaSample.zip
build:
[exec] [INFO] Parsing command line options
[exec] [INFO] Parsing bbwp.properties
[exec] [INFO] Validating application archive
[exec] [INFO] Parsing config.xml
[exec] [WARNING] Failed to find the
element [exec] [INFO] Populating application source [exec] [INFO] Compiling BlackBerry WebWorks application [exec] [INFO] Generating output files [exec] [INFO] BlackBerry WebWorks application packaging complete BUILD SUCCESSFUL Total time: 12 seconds
The output from the build is placed in the build folder. Now you've successfully built a Cordova BlackBerry application. In subsequent posts I'll detail how to setup and deploy to simulators and devices.javascript
This is part 2 of my attempt to document what my development environment looks like for developing Cordova for BlackBerry on Mac OS X. Be sure to read
Part 1 if you missed it.
The quickest way I've found to test applications is through the BlackBerry simulators. Unlike some other mobile platforms the BlackBerry simulators are quite good and are an easy way to smoke test your application on multiple OS versions. The only problem is if you're running Mac OS X as your development environment the smartphone simulators aren't supported and the PlayBook simulator requires VMWare Fusion which is not free. So, if you want to development for BlackBerry on Mac OS X, you're likely going to have to fork out some money. However, you should be used to forking out money if you're using a Mac anyway :-)
Once the simulator has loaded you can install your application into it. If you try to use the simulator GUI to load your application, you'll notice that in order to update the application you have to restart the simulator. This is a real nuisance when developing/debugging an application. Instead of using the GUI to install/update an application I use the following script ( updateapp.sh) which allows an application to update without requiring a restart of the simulator:
As I stated earlier, the WebWorks SDK comes with a default simulator. There are many other simulators available and I would encourage you to download additional ones to verify your application on different devices. The OS 7 simulators are particularly useful due to Web Inspector debugging support. BlackBerry devices are extremely varied when it comes to screen size, screen orientation, keyboards, operating systems. Its always funny when I hear talk about Android fragmentation. I'm pretty sure BlackBerry invented mobile fragmentation.
Similar to the smartphone version of the WebWorks SDK, the PlayBook version also provides a default simulator. The WebWorks documentation provides adequate documentation on getting the PlayBook simulator up and running in VMWare Fusion and enabling developer mode. Make note of the simulator IP address and password as they are needed to automate deploying an application to the simulator from a Cordova BlackBerry project.
Return to your Cordova BlackBerry project and edit the following entries in the project.properties file with the values from your simulator:
After configuring the file you can now execute ant playbook load-simulator from the terminal to build and load your application to the simulator.
The quickest way I've found to test applications is through the BlackBerry simulators. Unlike some other mobile platforms the BlackBerry simulators are quite good and are an easy way to smoke test your application on multiple OS versions. The only problem is if you're running Mac OS X as your development environment the smartphone simulators aren't supported and the PlayBook simulator requires VMWare Fusion which is not free. So, if you want to development for BlackBerry on Mac OS X, you're likely going to have to fork out some money. However, you should be used to forking out money if you're using a Mac anyway :-)
Smartphone Simulators
The BlackBerry smartphone simulators only run on a Windows OS. I get around this on Mac OS X through the use of running Windows within VMWare Fusion. A free alternative is to use VirtualBox which works for smartphone simulators but it does not work with the PlayBook p_w_picpath. I used to use VirtualBox but switched to VMWare Fusion when I needed to do PlayBook development and have appreciated the closer integration with Mac OS X that it provides. The steps I document here are specific to VMWare Fusion but similar steps can be done in VirtualBox.- Install VMWare Fusion.
- Setup a VMWare Fusion Windows OS p_w_picpath. I use Windows OS 7.
- Install VMWare tools.
- Install Java 1.6 JDK 32 bit version.
- Install the Windows version of the WebWorks SDK into it. I found it best to make the install location as short a path as possible. I changed from the default to C:\BBWW.
- (Optional) Install cygwin. Who wants to use DOS?
- I use the Unity view feature in Fusion to view the Windows application inline with Mac OS X.
- I also map my development directory on Mac OS X to Windows so I can build on Mac and simply deploy to the simulator in the Windows p_w_picpath.
Once the simulator has loaded you can install your application into it. If you try to use the simulator GUI to load your application, you'll notice that in order to update the application you have to restart the simulator. This is a real nuisance when developing/debugging an application. Instead of using the GUI to install/update an application I use the following script ( updateapp.sh) which allows an application to update without requiring a restart of the simulator:
Loading ....
The above script is written in shell script since I use cygwin as my terminal on Windows. An equivalent
.bat file could easily be written for those that prefer DOS. The
COD_FILE,
SIMULATORS and
SIMVER variables will need updated based on your system as follows:
- COD_FILE - The full path to the .cod file built for your application with .pending appended to it. In this example I'm using the path that is a shared location from my host Mac OS X system.
- SIMULATORS - The full path to the folder where your simulators are installed.
- SIMVER - The folder containing the specific simulator that you are testing. Typically is a BlackBerry OS version number.
As I stated earlier, the WebWorks SDK comes with a default simulator. There are many other simulators available and I would encourage you to download additional ones to verify your application on different devices. The OS 7 simulators are particularly useful due to Web Inspector debugging support. BlackBerry devices are extremely varied when it comes to screen size, screen orientation, keyboards, operating systems. Its always funny when I hear talk about Android fragmentation. I'm pretty sure BlackBerry invented mobile fragmentation.
PlayBook Simulators
The PlayBook simulators are a better story when it comes to integration with Mac OS X. PlayBook simulators are simply a VMWare p_w_picpath that can be loaded and ran in VMWare Fusion. The only drawback is you have to buy VMWare Fusion if you don't already own it, as the p_w_picpath will not work in VirtualBox (believe me I tried).Similar to the smartphone version of the WebWorks SDK, the PlayBook version also provides a default simulator. The WebWorks documentation provides adequate documentation on getting the PlayBook simulator up and running in VMWare Fusion and enabling developer mode. Make note of the simulator IP address and password as they are needed to automate deploying an application to the simulator from a Cordova BlackBerry project.
Return to your Cordova BlackBerry project and edit the following entries in the project.properties file with the values from your simulator:
# Playbook Simulator IP # # If you leave this field blank, then # you cannot deploy to simulator # playbook.sim.ip=192.168.130.129 # Playbook Simulator Password # # If you leave this field blank, then # you cannot deploy to simulator # playbook.sim.password=playbook
After configuring the file you can now execute ant playbook load-simulator from the terminal to build and load your application to the simulator.
$ ant playbook load-simulator
Buildfile: /Work/Cordova/sample/build.xml
playbook:
load-simulator:
generate-cod-name:
[echo] Generated name: CordovaSample.bar
clean:
[delete] Deleting directory /Work/Cordova/sample/build
package-app:
[mkdir] Created dir: /Work/Cordova/sample/build/widget
[copy] Copying 7 files to /Work/Cordova/sample/build/widget
[copy] Copying 1 file to /Work/Cordova/sample/build/widget
[copy] Copying 2 files to /Work/BlackBerry/WebWorksTabletSDK/bbwp/ext
[zip] Building zip: /Work/Cordova/sample/build/CordovaSample.zip
build:
[exec] [INFO] Parsing command line options
[exec] [INFO] Parsing bbwp.properties
[exec] [INFO] Validating WebWorks archive
[exec] [INFO] Parsing config.xml
[exec] [WARNING] Failed to find the
element [exec] [INFO] Populating application source [exec] [INFO] Compiling WebWorks application [exec] [INFO] Packaging the bar file [exec] [INFO] Bar packaging complete [exec] [INFO] WebWorks application packaging complete load-simulator: [echo] This tool will not open the simulator for you [exec] Info: Sending request: Install and Launch [exec] Info: Action: Install and Launch [exec] Info: File size: 413806 [exec] Info: Installing CordovaSample8b2ac05459054dcc69c2bdc781cb2... [exec] Info: Processing 413806 bytes [exec] Info: Progress 100%... [exec] Info: Progress 100%... [exec] actual_dname::CordovaSample8b2ac05459054dcc69c2bdc781cb2... [exec] actual_id::testDev_c2bdc781cb2fb9ced6e [exec] actual_version::1.0.0.1 [exec] result::success [exec] Info: Launching CordovaSample8b2ac05459054dcc69c2bdc781cb2... [exec] result::15159365 [exec] Info: done BUILD SUCCESSFUL Total time: 23 seconds
Additional PlayBook simulators are also available and I would encourage you to test your application on them as well.html
This is part 3 of my attempt to document what my development environment looks like for developing Cordova for BlackBerry on Mac OS X. Go read
Part 1 - Basics and
Part 2 - Simulators if you missed them.
I spend the majority of my debugging time in the simulators and not on a device. It is so much quicker/easier to reload applications and simulate events in the smartphone simulators that I typically leave device verification as my final round of testing. Device based testing is certainly needed, but I've found it much more efficient to iron out most of the bugs in the simulators first. Review my Simulators write up for information on setting up and installing a smartphone simulator environment when using Mac OS X.
Newer BlackBerry operating system version simulators contain greater simulation capabilities when compared with their older counter parts. This is another reason why I would recommend using an OS 7 simulator as your primary test target. Changing properties through the simulate menu will take effect in your running application without having to exit your application. This is an invaluable test tool as it can be rather difficult to properly simulate some conditions on a physical device. Some of the events can also be staged. For instance, via the Manipulate Device... entry you can predefine a series of orientation events and then replay that while your application is running. The GPS Location... option allows you to predefine a GPS route and then replay it.
For my development needs I have been satisfied with simulating events through the GUI. However, events can also be simulated via the command line. Command line simulation facilitates scripting of a series of events which may be useful during your testing.
All logging in Cordova BlackBerry ( org.apache.cordova.util.Logger.log() in Java code and console.log() in JavaScript) is sent to the BlackBerry EventLogger. Viewing the log on a device or in a simulator has historically been a pain as you had to enter a device specific key sequence to bring up the log. Thankfully, OS 7 simulators have added the ability to display a window showing the real time output to the event log. The log screen is accessed via Tools->Show Output Log. Confusing the matter is that there has historically been an entry named Show Event Log in the simulators, but just trust me when I say you want the one labeled Show Output Log .
One piece of functionality missing from the GUI output of the event log is the ability to filter the messages. Accessing the event log directly through the simulator or on a device allows you to specify which messages you want to see. This is not possible through the GUI so you end up seeing a lot of system level messages which may be unrelated to your application. However, I've found having the real time output display of the messages is superior to having to back out of the application to view them so I've learned to live with the additional messaging.
In order to enable remote Web Inspector, your application must be built with the debug flag. If you are using the sample project format provided by Cordova BlackBerry, edit the blackberry.xml file and add the "/d" argument to the BlackBerry WebWorks packager invocation as shown below:
After editing and saving the file, rerun your build and deploy it to the simulator. Once it has deployed, launch your application and eventually the application will startup and display a notification prompt with an IP address (Do not click OK yet!):
Now, maybe there is some flakiness in my setup but if I click the OK button in the notification at this point then subsequent connection from my browser fails so I'd recommend waiting until I indicate to click it.
Now, if you are developing on Mac OS X, then your simulator is running in a VMWare Fusion p_w_picpath and you cannot trust the network ID section of the IP address specified. However, you do want to keep track of the host ID (31) and port (1338) as those are accurate. Open a terminal window in Mac OS X and run ifconfig to determine the network ID assigned to the VMWare guest operating system (192.168.130 on my system).
Append the host ID(31) and port(1338) from the notification window to the network ID(192.168.130) to determine the full IP address (192.168.130.31:1338).
Next, launch the Safari browser on your Mac. You will have to use Safari as it is the only browser that is still compatible with the Web Sockets implementation being used by the BlackBerry browser. In the Safari address bar enter the full IP address and port:
You'll know things are working if you see a link with your application name displayed in the browser. Click the link to open Web Inspector and then click on the Resources tab:
Now its finally time to go back to the simulator and click the OK button in the notification popup. After clicking OK the application will be in a waiting state. Go back to the Safari browser and click 'Enable resource tracking' button in the Resources tab. The application should now finish loading in the simulator and the Web Inspector is now attached to it and ready to debug/analyze the application:
I spend the majority of my debugging time in the simulators and not on a device. It is so much quicker/easier to reload applications and simulate events in the smartphone simulators that I typically leave device verification as my final round of testing. Device based testing is certainly needed, but I've found it much more efficient to iron out most of the bugs in the simulators first. Review my Simulators write up for information on setting up and installing a smartphone simulator environment when using Mac OS X.
Simulator Choice
There are a large number of BlackBerry
smartphone simulators to choose from. Its useful/recommended to test your application on multiple OS versions / phone form factors, but I choose one simulator for my initial testing and debugging. My recommendation is to use an OS 7 based simulator as your primary testing platform as they provide additional features not available in older simulators. I'm currently using a Torch 9810 running OS 7.0.0.540 as my initial test point. I use a Torch since it allows me to test with or without a keyboard on a single simulator. I've included a list of my recommended simulators below. I use these because they provide a good sample of the various form factors available on BlackBerry. Select simulators appropriate to the devices you are targeting.
- Torch 9810 OS 7 (Primary test target)
- Torch 9860 OS 7.1 - Large touch screen
- Bold OS 5, OS 6, OS 7 - 3:2 aspect ratio screen
- Storm 2 9550 OS 5 - Touch screen only OS 5 device.
Event Simulation
One thing the BlackBerry smartphone simulators are rather good at is exposing event simulation through the GUI. The simulation events can be accessed through the Simulate toolbar section:
Newer BlackBerry operating system version simulators contain greater simulation capabilities when compared with their older counter parts. This is another reason why I would recommend using an OS 7 simulator as your primary test target. Changing properties through the simulate menu will take effect in your running application without having to exit your application. This is an invaluable test tool as it can be rather difficult to properly simulate some conditions on a physical device. Some of the events can also be staged. For instance, via the Manipulate Device... entry you can predefine a series of orientation events and then replay that while your application is running. The GPS Location... option allows you to predefine a GPS route and then replay it.
For my development needs I have been satisfied with simulating events through the GUI. However, events can also be simulated via the command line. Command line simulation facilitates scripting of a series of events which may be useful during your testing.
The Event Log
Its inevitable that at some point during development you'll want to be able to log messages in order to trace the flow of code or provide some additional information for debugging. This is especially the case when working on Java code for a Cordova plugin as there is no simple integration to attach to a WebWorks application through a debugger and step through Java code.All logging in Cordova BlackBerry ( org.apache.cordova.util.Logger.log() in Java code and console.log() in JavaScript) is sent to the BlackBerry EventLogger. Viewing the log on a device or in a simulator has historically been a pain as you had to enter a device specific key sequence to bring up the log. Thankfully, OS 7 simulators have added the ability to display a window showing the real time output to the event log. The log screen is accessed via Tools->Show Output Log. Confusing the matter is that there has historically been an entry named Show Event Log in the simulators, but just trust me when I say you want the one labeled Show Output Log .
One piece of functionality missing from the GUI output of the event log is the ability to filter the messages. Accessing the event log directly through the simulator or on a device allows you to specify which messages you want to see. This is not possible through the GUI so you end up seeing a lot of system level messages which may be unrelated to your application. However, I've found having the real time output display of the messages is superior to having to back out of the application to view them so I've learned to live with the additional messaging.
Web Inspector
If I haven't convinced you to make an OS 7 based simulator your primary test environment yet, then this final section should push you over the edge. All the OS 7 based simulators support remote Web Inspector debugging. Although I've found it to be a bit temperamental, it is an invaluable tool for debugging and analyzing the web content in your application.In order to enable remote Web Inspector, your application must be built with the debug flag. If you are using the sample project format provided by Cordova BlackBerry, edit the blackberry.xml file and add the "/d" argument to the BlackBerry WebWorks packager invocation as shown below:
<else>
<exec executable="${properties.blackberry.bbwp.bin}">
<arg file="${build.dir}/${cod.name}.zip">
<arg value="/o">
<arg file="${build.dir}">
<arg value="/d"> <!-- ENABLE DEBUG -->
</exec>
</else>
After editing and saving the file, rerun your build and deploy it to the simulator. Once it has deployed, launch your application and eventually the application will startup and display a notification prompt with an IP address (Do not click OK yet!):
Now, maybe there is some flakiness in my setup but if I click the OK button in the notification at this point then subsequent connection from my browser fails so I'd recommend waiting until I indicate to click it.
Now, if you are developing on Mac OS X, then your simulator is running in a VMWare Fusion p_w_picpath and you cannot trust the network ID section of the IP address specified. However, you do want to keep track of the host ID (31) and port (1338) as those are accurate. Open a terminal window in Mac OS X and run ifconfig to determine the network ID assigned to the VMWare guest operating system (192.168.130 on my system).
$ ifconfig vmnet8 vmnet8: flags=8863
Append the host ID(31) and port(1338) from the notification window to the network ID(192.168.130) to determine the full IP address (192.168.130.31:1338).
Next, launch the Safari browser on your Mac. You will have to use Safari as it is the only browser that is still compatible with the Web Sockets implementation being used by the BlackBerry browser. In the Safari address bar enter the full IP address and port:
You'll know things are working if you see a link with your application name displayed in the browser. Click the link to open Web Inspector and then click on the Resources tab:
Now its finally time to go back to the simulator and click the OK button in the notification popup. After clicking OK the application will be in a waiting state. Go back to the Safari browser and click 'Enable resource tracking' button in the Resources tab. The application should now finish loading in the simulator and the Web Inspector is now attached to it and ready to debug/analyze the application:
At this point you can go to the Scripts tab and enable debugging, set break points, see output in the console tab, and all the other functionality available via the Web Inspector utility.
In regards to the temperamental comment I made earlier. Not sure if its due to my setup or the way I install applications but I've found that building an application in debug mode makes it impossible for my application to retrieve resources from a remote URL. The application works fine when not in debug so I'm not sure what is going on. Also, I've found that debug mode causes me to get more ClassCastException and fledgecontroller failures from my application update method which forces me to restart the simulator and reload my application. However, despite those annoyances the ability to run remote Web Inspector is extremely useful for debugging and analyzing your web content.html5
原文連接： http://whatdrewknows.blogspot.com/2012/04/cordova-blackberry-development-part-2.htmljava