A project built for platforms by name gets a binary for each, and runs in a bezel on every display it has no binary for. A flexible project gets a binary for each class of display, which fills every watch of the class (Platforms, Building apps). This page is about what changes in the project and its source.
In the pebble object of package.json:
"flexible": true
Without targetPlatforms that builds rect-color, rect-bw and
round-color, and for now a binary for each platform of those classes,
which a watch of that platform prefers. To keep reaching the frozen
platforms, name them:
"flexible": true,
"targetPlatforms": ["rect", "round", "aplite", "basalt", "chalk", "diorite"]
A flexible project builds with CMake; pebble convert-project ports a
wscript.
A flexible binary is compiled without PBL_DISPLAY_WIDTH,
PBL_DISPLAY_HEIGHT and PBL_PLATFORM_<NAME>, so code that uses the first
two no longer compiles. Most of what ties an app to a display compiles
anyway:
In the source |
What happens in a flexible binary |
Who finds it |
|---|---|---|
|
Does not compile |
The compiler |
|
Compiles; drawn for one display |
|
A table of points, |
Compiles; drawn for one display |
Running it |
|
Compiles; takes the |
|
|
Compiles; the feature is left out |
|
|
Asks the watch when it runs |
Nothing to find |
A resource with |
In no flexible binary |
Configuring warns |
So build it, run pebble doctor, and then look at it on more than one
display: the native simulators of Emery, Flint and Gabbro are three.
Take every position and size from the bounds of the window or layer.
// Before: the middle of a 144 x 168 display
s_text_layer = text_layer_create(GRect(0, 72, bounds.size.w, 20));
// After
s_text_layer = text_layer_create(GRect(0, bounds.size.h / 2 - 12, bounds.size.w, 20));
A layout written for one display often measures from its edges or its centre. Keep the offset and measure it from the bounds:
// Before
GRect(46, 114, 27, 20)
// After: 26 left of the centre, 30 below it
const GPoint center = grect_center_point(&bounds);
GRect(center.x - 26, center.y + 30, 27, 20)
Constants that stand for a display become expressions of the bounds:
// Before: the corners of a 144 x 168 display, as lengths along its perimeter
#define TOP_RIGHT 72
#define BOT_RIGHT 240
// After
#define DISPLAY (layer_get_bounds(window_get_root_layer(s_window)).size)
#define TOP_RIGHT (DISPLAY.w / 2)
#define BOT_RIGHT (TOP_RIGHT + DISPLAY.h)
A table of points drawn for one display, the hour marks of a watchface for
one, is the largest change: compute the points from the bounds, or scale the
table when the window loads. A table that was const then lives in RAM.
Shape and colour depth are the class, so PBL_IF_ROUND_ELSE,
PBL_IF_COLOR_ELSE, COLOR_FALLBACK, PBL_ROUND and PBL_COLOR work as
they did.
#if defined(PBL_PLATFORM_EMERY) || defined(PBL_PLATFORM_GABBRO)
#define SIDEBAR_WIDTH 34
#else
#define SIDEBAR_WIDTH 30
#endif
This usually means “a large display” and not the platform. Say that:
#define SIDEBAR_WIDTH (bounds.size.w >= 200 ? 34 : 30)
Where the value sizes an array, size the array for the largest case.
A watch of a class may or may not have a microphone, health or a smartstrap port. An app has two ways to deal with that, and can mix them.
Ask when the app runs. One binary per class, for every watch of it.
if (platform_has_feature(PlatformFeatureHealth)) {
health_service_events_subscribe(prv_health_handler, NULL);
}
PBL_IF_MICROPHONE_ELSE and PBL_IF_HEALTH_ELSE do this by themselves, so
an app that only uses those has nothing to change. PBL_IF_SMARTSTRAP_ELSE
does not: it is its second argument unless the binary requires a smartstrap.
Code under #if defined(PBL_HEALTH) has to become a check like the one
above, or it is left out of the binary without a word from the compiler.
Both branches are in the binary; a check costs a call.
platform_has_feature() is not in the SDK of the frozen platforms. A project
that still builds for those keeps their code under #if:
#if defined(PBL_FLEXIBLE)
const bool has_health = platform_has_feature(PlatformFeatureHealth);
#else
const bool has_health = PBL_IF_HEALTH_ELSE(true, false);
#endif
PBL_IF_HEALTH_ELSE(true, false) alone says the same in every binary.
Require the feature. A binary only for watches that have it.
"targetPlatforms": ["rect~health", "round~health"]
That builds rect-color+health, rect-bw+health and round-color+health.
In those PBL_HEALTH is defined and PBL_IF_HEALTH_ELSE is a constant, so
feature code stays as it is and the unused branch is not shipped. A watch
without the feature is not offered the app, unless the project also builds
the plain binary of the class:
"targetPlatforms": ["rect~health", "rect", "round~health", "round"]
A watch then takes the binary that requires the most of what it has.
Which to pick:
Ask when it runs |
Require |
|
|---|---|---|
Source changes for feature code |
|
None |
Binaries per class |
One |
One per set of features, plus the plain one to reach every watch |
Watches without the feature |
Run the app |
Need the plain binary, or do not get the app |
Size |
Both branches ship |
Only the branch that is used |
A resource picks its variant by tags as before: icon~color.png,
icon~bw.png, icon~round.png. A flexible binary has the tags of its
class and of the features it requires.
A resource’s own targetPlatforms has to say what it is for with tags. One
that names platforms is in no flexible binary, and configuring the project
warns about it.
Size tags (~200w) name one display and match no flexible binary.
A flexible app needs its Pebble packages to be flexible too (Building apps). A package is moved the same way as an app.
A flexible binary is given 64K for its code and heap, whatever the watch
gives. An app that needs more asks with "appMemory" in package.json, and
then only fits watches that give that much.
Generated from PebbleOS 4bbc630fa. This page is maintained in the pebbleos repository: docs/sdk/flexible_apps.md.