doesn’t matter for wich platform you’re developing, at some point you have to support more then one API level. Same happens now to most developers of BlackBerry 10 Cascades APPs: the new platform started in January 2013 with 10.0, most used at the moment is 10.1 and 10.2 just started public Beta and will be available in August 2013.
edited 2014-10-20: In the meantime we have 10.2.1, 10.3.0 and 10.3.1 – I still prefer Branches and Git CherryPicking. See my article here. If you would like to do it all in ONE src tree: here’s a great post written by Derek (@dkonigs) : blackberry-10-multiple-os-versions-from-one-src-tree
API Levels in Momentics IDE
The new Momentics IDE 10.2 makes it easier to have projects with different API Level in one workspace, because now the API Level (10.0, 10.1, 10.2 Beta) is separate from SDK’s installed on Devices / Simulator. Let’s take a look at preferences on this in Momentics 10.2:
at of today you can select between these levels:
This API Level in Preferences is the default global API Level for this workspace and will used if creating a new Cascades project:
here you’ll see the same API Level as from Preferences plus a new one:
Use Global (BlackBerry Native SDK 10.1)
Hint: if using this Global API Level and some time later you go to preferences and switch to 10.2 then all your projects referencing this global API level will from now on compiled for 10.2. Perhaps this isn’t what you really wanted to do. From my POV it’s better to set the API Level explicit – in this case I would select 10.1.
If you want to change the API Level of a Project, go to Project properties and from there you can switch to another one.
HowTo manage API levels
There are many different ways to get this done and it depnds on your projects and also which way you like to go.
There’s an article at BlackBerry Developer Blog about this and a Forum post about Versioning Macros.
Versioning macros can only be used inside your C++ code, but not from QML. if you’re following the comments from this forum post I mentioned above, at any time later also QML will support versioning macros.
But I don’t like this way: it clutters the code and some changes from API or new Classes / Features won’t change only some lines of code, because you’re doing a redesign because of new ways possible. Using versioning macros you’re temptable not to go the best way.
I decided to go the Git – branching way to solve different API levels. This allows me to redesign parts of my app easier then having all in one codebase. But this is my personal opinion – it’s up to you to decide what’s best for your projects.
API Levels as Git branches
I’m using Git as my source repository, where my Open Source repos are at Github and private repos are at Github and Bitbucket.
To manage my repos I’m using Git Tower for OSX,
but you can also use:
SourceTree (available for Windows and Mac)
EGit (built into Eclipse) or work from commandline.
Lars Vogel provides great Tutorials on EGit and also Git via Commandline.
My Master branch is always the newest API Level I’m working on for a given project – as soon as I have to support a newer one, I’m creating a Branch from where I’ll manage support of older API. Here you see a Branch made for 10.0 while main development goes on for 10.1:
from Github | Branches it will look like this:
Branch == Eclipse Project
Now comes the interesting part 😉 We want to work on both versions – perhaps doing bugfixes in 10.0, adding new features in 10.1
Thanks to Momentics IDE 10.2 we can easy have projects with different API Level in one workspace. (Older versions must be rebooted if switching) But how to have the same project 2 times in the workspace ?
At first please checkout the project 2 times at different locations:
- only Master for work on newest API (10.1)
- Master + 10.0 API Branch for work on the 10.0 version
There’s one trick: as soon as you have created the 10.0 branch you should rename the Eclipse Project before importing this project into the workspace:
Your workspace already contains the ‘default’ project from Master branch and now we can also import the project from 10.0-API-branch:
Import existing projects
Select the project
Don’t check the box ‘copy into workspace’ – we only neeed a reference to the local Git repository.
Go to project properties API Level and set Level to 10.0
mission completed: both branches as projects in one workspace:
Now let’s test if it works and deploy version 10.0 to a device and then 10.1. In this project 10.1 contains ShortCuts{} for Q10, so at first Run the 10.0 project on Q10: Session Details Menu has no ShortCuts
and now we Run the 10.1 project on Q10:
Now ShortCuts{} are there. So we have only one app on the device deployed from different projects with different API Levels.
Cherry Picking
Cherry – Picking is a cool Git feature (also supported by Git Tower) we’ll use to get our projects in-sync.
Just today an open issue was fixed and I had to enable editing of Calendar Entries via InvocationFramework in some of my apps. This causes changes in C++ files and QML files and because some line-numbers were changed, also changes in .ts (translation) files.
As I wrote all my new work was done from Master (10.1) and in this case I also want to get this functionality into the 10.0 version.
You have to think about Cherry-Picking before doing your commits. The goal is to have commits not causing merge conflicts later. So its better to have some small commits and also to separate problematic parts. And here’s one of my rules: Never combine .ts changes with C++ / QML changes into one commit, because the chance is to get merge conflicts from .ts files. Normaly you don’t have to cherry-pic .ts files because they’ll be generated at every build of your app. Only if you did translations for some languages you should merge and commit .ts files.
Here are my changes on Master Branch (10.1):
at first I’m committing changes in C++ and QML, then as next changes from .ts files
then PUSH these commits to Github:
Now switch to the 10.0 API Branch – Repository
Doubleclick on master to change HEAD to master
PULL the changes from MASTER into this repo
Now we have the newest commits in our repo.
Switch HEAD back to 10.0 API Branch
Take a look at the commits from MASTER and select the one commit of C++ and QML files:
Right-click on this Commit and Cherry-Pick:
without any merge conflicts my work done in 10.1 now also is available in 10.0:
Now I can build the 10.0 project and get my .ts files modified:
commit and push to API-10.0-branch and you’re done 🙂
tried the new feature in my 10.0 Version:
and it works 🙂
Using Git Cherry-Picking you can pick one or more commits from one branch (Master in this case) and merge into another one (10.0 in this case).
Perhaps sounds difficult at first, but if you’ve done this some times it feels natural (at least for me).
Now I have all the freedom to refactor or redesign apps because of new features from newer API levels and also have an easy way to ‘move’ changes back to older releases. This doesn’t work always, but then it’s also easy to manage, because you have both projects in the same workspace and copy/paste/edit/…
Have fun with Cherry – Picking !
see you in september at MTC Berlin:
where I will talk about “Peer-to-peer pushes in Business Apps”
(c) 2013 Creative Commons License 3.0 (BY-NC-SA) by ekkescorner
mobile && more 