This is the second in our three-part series on building plugins with the Gold release of WebWorks 2.0 SDK. In case you missed it, check out “Building Cordova Plugins for BlackBerry 10 on Mac.” The final post will focus on using the Windows platform to build plugins.
Due to developer feedback, the Gold release of WebWorks 2.0 SDK is now officially supported on Linux. Even before the official release we’ve had some developers, including some students in UCOSP, working on Linux. Based on his experience creating Cordova plugins for BlackBerry 10 using Linux, one of the students this term, Jim, created this guide for other developers.
Preflight Checklist
Before we begin, this guide makes some assumptions about you, the reader:
You have some idea of what a plugin is and can do, and moreover, why you want to write one.
You have a GitHub account, and you have already forked the WebWorks-Community-APIs repository.
I am using Ubuntu 12.10, and you are (obviously) using some version of Linux.
You are working on a machine for which you have administrative rights.
You have a BlackBerry 10 device with which to work. (I am using the Dev Alpha C model.)
Your device has the latest OS installed.
You can get that here. Please note that updating the device OS via the autoloader is only possible through a Windows machine at this time.
You have a BlackBerry ID set up already. If you don’t, you can do so from your device directly, although you’ll need an Internet connection.
Go to the directory where you saved the binary, chmod it to be executable, and run it as yourself (not as root).
I recommend you use all the default settings, unless you have a good reason not to.
Allow Momentics to run after the installation is complete. If you don’t, you can always start it from the terminal: ~/bbndk/qde (assuming defaults).
On startup, it will attempt to find your device. Let it fail, and see Step 2. If you don’t have one, you can ignore this and always deal with it later.
Step 2: Device Setup
Turn on your device, and go to Settings> Storage and Access.
Set the USB connection to “Connect to Mac” (see image below).
Go back to Settings> Security and Privacy.
Scroll all the way to the bottom and select “Development Mode.”
Turn on Development Mode (see image below).
This requires the device password, which I suggest setting to something very simple while you work.
Note that Development Mode automatically turns off when the device restarts, or after 10 days.
Connect the device via USB cable, and on Momentics click “Try Again.”
Enter the device password when prompted.
Install the recommended API level, and go get a coffee (this takes a while).
If prompted about installing debug stuff, do so, but then do not click restart until it completes (see image below).
Click restart, but don’t expect it to actually open again on its own.
Step 3: More Momentics Setup
Open Momentics: ~/bbndk/qde.
Go to the menu: Window->Preferences.
Choose BlackBerry> Signing from the panel on the left.
Enter your BlackBerry ID password and click “Get Token,” which will make you actually sign in with your BlackBerry ID.
Once successful, click “Create Certificate.” You should no longer see a warning at the top of the page.
Exit Momentics.
Step 4: Install Node.js
If you aleady have this, then go to step 5, otherwise enter the following commands from the terminal:
sudo apt-get install python-software-properties python g++ make
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs
Step 5: Install Cordova
sudo npm install -g cordova
You may need to add /usr/local/share/npm to your $PATH, but I had no issues without doing this.
Step 6: Clone the WebWorks-Community-APIs repo locally
Make a directory where you want to put it. I made ~/UCOSP since I was doing this for the UCOSP program.
Notice the file “bbndk*.sh” (see image below). I found that actually running the script did not do as intended, but simply sourcing it was sufficient:
a. source bbndk*.sh b. You must do this every time you open a terminal to work, so you might as well add line 4 to your .bash_profile or similar file.
Step 8: Running the Template Sample App
cd ~/UCOSP/W*/BB10-*/T*
cordova create sample2
copy the www folder in /sample to /sample2, and overwrite anything there
cd sample2
cordova platform add blackberry10
This step could fail, if so, the easiest solution is to change ownership of ~/tmp to yourself instead of root, then try again.
If you find an alternative solution, please document it, and let us know.
cordova plugin add ../plugin
cordova run sample2 –devicepass pass -k signingpass
Where pass is, the password you set on the device.
And signingpass is your password for your RSA keyring.
Your device will eventually start an app called “Cordova3”
Click “OK” on the Web Inspector popup.
Scroll down to see the test output from the app.
Congratulations, the hard part is over!
What’s Next?
The sample app uses the Template plugin to make several different types of JavaScript calls to the native-level C++ underneath. To make your own plugin, copy the Template directory, and use it as a basis for your work. Read Template/README.md for more information.
Good luck, and happy coding.
Have you made a Linux plugin or want to get started on one? Contact Tim Windsor on Twitter or at twindsor@blackberry.com to get help and to learn how you can release your plugin back to the community through our GitHub repositories.
