Exposing functions to the SDK

How the SDK generator works

The generator (tools/generate_native_sdk/generate_pebble_native_sdk_files.py) runs automatically as part of the firmware build (normal variant only — PRF and test builds skip it). It exports the white-listed functions, typedefs and #defines from the firmware tree and produces the files needed to build native watchapps, all under build/:

• build/sdk/<platform>/include/pebble.h — typedefs, defines and function prototypes for apps (plus pebble_worker.h for background workers and a few version/fonts headers). Exported declarations are copied verbatim, so the SDK also ships pbl/kernel/compiler.h and its backends, included from pebble.h, and exported headers use its PBL_* macros rather than raw __attribute__.

• build/sdk/<platform>/lib/libpebble.a — static library containing trampolines that call the exported functions in flash

• build/fw/pebble.auto.c — g_pbl_system_tbl, the table of function pointers the trampolines use to find an exported function’s address; compiled into the firmware image

The rest of the distribution is packaged by the firmware build’s sdk target, which fills in the same build/sdk/ tree:

pbl configure --board $BOARD
pbl build sdk

tools/cmake/sdk.py copies the common files from sdk/ into build/sdk/common/ — the app project templates under sdk/defaults/, and the tools and resource pipeline the app build shares with the firmware — and bundles sdk/waftools/ into the waf binary app developers use to build their apps. That waf is the only one left in the tree: everything it needs lives under sdk/, and it is built out of tree, so packaging leaves the checkout untouched.

exported_symbols.json format

{
  "revision": "<exported symbols revision number>",
  "version": "x.x",
  "files": ["<files to parse>"],
  "exports": ["<symbols to export>"]
}

Each exported symbol has a type of function, define, type, forward_struct, or group:

{
  "type": "function",
  "name": "<symbol name>",
  "sortName": "<sort order>",
  "addedRevision": "<revision number>"
}

A group nests further exports under a name. Functions support additional flags (internal, removed, deprecated, appOnly, workerOnly, implName, skipDefinition) — see existing entries and tools/generate_native_sdk/exports.py for their meaning.

Notes:

• Functions are sorted by addedRevision, then alphabetically (by sortName if present, else name) within a revision. This ordering is the ABI — it is why new functions must use a new revision: it guarantees new firmware stays backwards compatible with apps compiled against an older libpebble.a.

• types are emitted in the order listed; put typedefs after the typedefs they depend on (includeAfter is the escape hatch for ordering exceptions).

• The generator errors out on exports it cannot find in the parsed headers and on inconsistent revision numbers, but it does not verify that the resulting pebble.h compiles — review its output.

• The comment ledger above PROCESS_INFO_CURRENT_SDK_VERSION_MINOR is the only mapping between SDK revisions and version minors: no formula relates them (the minor once jumped 0x19 → 0x20 between revs 35 and 36, and a few minors and revs are skipped or doubled up). Treat the ledger as append-only history.