Learn how to take advantage of the Pebble build system by creating customized wscripts that let you concatenate JS files, automatically run linters, and internationalize your apps with Cherie Williams (Developer Evangelist).
1. 2015 Pebble Developer Retreat
waf, wscript & Your Pebble App
Cherie Williams - Troublemaker
2. Agenda
• Why modify my wscript?
• Pebble SDK & Fat PBW
• What is this “waf” thing?
• Why is Pebble using waf?
• wscript
• Why do I care about waf?
• wscript Recipes
• Debugging
3. Why modify my wscript?
Making the Pebble SDK build system work for you
4. You can…
• Add C compiler flags
• Add custom defines for your apps (eg. #ifdef
NOLOG)
• Concatenate multiple JS files or do other file
manipulations at build time
5. You can…
• Collect & build source from a non-standard
project
• Add a linter (or two!)
• Run arbitrary scripts at build time to modify
resources or other files
6. You can…
• Add automatic testing
• Profile builds or add build visualizations
• Read in arbitrary text at build (eg. appinfo.json)
7. You can…
• Include an external library
• Build libraries for distribution
…the possibilities are endless!
8. Fine Print
Recipes + content from today’s talk are
*not* compatible with CloudPebble
10. SDK: Capabilities Today
• Builds for up to 3 Pebble platforms
• Can build apps, as well as workers
• Handles platform-specific resources
• Packages a single PBW for distribution
aplite
Pebble Classic
Pebble Steel
basalt
Pebble Time
Pebble Time Steel
chalk Pebble Time Round
12. What is this “waf” thing?
A brief introduction to the Pebble build system
13. Introducing waf, a Python build system
• Open source, actively maintained
• Active community on Google Groups
• Task parallelization & dependency handling
• Language agnostic, but includes C compiler support
• Integrates with Eclipse, Visual Studio and Xcode
• Includes framework to build & distribute custom build
systems
27. Glossary
Context
An object for each command executed that stores all the
information necessary for the command execution
BuildContext
The build context holds all the information necessary for a
build
30. Glossary
Environment
A group of settings and variables that are stored in a
Context and that is cached between execution of
commands
NOTE: A single Context can have many, arbitrary
environments
33. Glossary
Task Generator
An object that handles the creation of task instances, and
helps simplify the creation of ordering constraints
Task
An object that represents the production of something
during the build (files, in general) and may be executed in
sequence or in parallel
37. Glossary
Build Order
The sequence in which tasks must be executed.
Dependency
A dependency represents the conditions by which a task can be
considered up-to-date or not, and can be explicit (dependency
on file inputs & outputs) or abstract (dependency on a value). waf
uses dependencies to determine whether tasks need to be run
(changed checksum of source files) and the build order of tasks.
41. Glossary
Node
A data structure used to represent the filesystem. Nodes
may represent files or folders. File nodes are associated
with signatures, which can be hashes of the file contents
(source files) or task signatures (build files)
43. Glossary
Command
A function defined in the wscript file that is executed
when its name is given on the command-line, and can be
chained with other commands
Ex:
waf distclean (`pebble clean`)
waf configure build (`pebble build`)
45. Agenda
• Why modify my wscript?
• Pebble SDK & Fat PBW
• What is this “waf” thing?
• Why is Pebble using waf?
• wscript
• Why do I care about waf?
• wscript Recipes
• Debugging
49. [23/35] c: src/default.c -> build/src/default.c.18.o
In file included from ../src/default.c:1:0:
/Users/cherie/pebble-dev/PebbleSDK-dev/Pebble/aplite/include/pebble.h:
974:33: error: ISO C does not permit named variadic macros [-
Werror=variadic-macros]
#define APP_LOG(level, fmt, args...)
^
/Users/cherie/pebble-dev/PebbleSDK-dev/Pebble/aplite/include/pebble.h:
1121:3: error: type of bit-field 'type' is a GCC extension [-
Werror=pedantic]
TupleType type:8;
^
/Users/cherie/pebble-dev/PebbleSDK-dev/Pebble/aplite/include/pebble.h:
1132:13: error: ISO C forbids zero-size array 'data' [-Werror=pedantic]
uint8_t data[0];
^
55. Create waftools/linter.py
def options(ctx):
ctx.add_option('--jshint', action='store_true',
help="Run JSHint on the JS files in the build")
def configure(ctx):
if ctx.options.jshint:
try:
ctx.find_program('jshint', var='JSHINT')
except ctx.errors.ConfigurationError:
print "jshint was not found"
def build(ctx):
if ctx.env.JSHINT:
ctx(rule='${JSHINT} ${SRC}', source=ctx.path.ant_glob('src/**/*.js'))
62. A Word on Future
Proofing
Sometimes the SDK default wscript will be updated, but by
abstracting code out of wscript and into waf tools, it will be
much easier to maintain customizations!
65. `pebble -vvv` (waf -vvv) for complete
21:51:50 preproc reading file '/Users/cherie/pebble-apps/
concentricity/build/chalk/src/resource_ids.auto.h'
21:51:50 deps deps for [/Users/cherie/pebble-apps/concentricity/
build/chalk/appinfo.auto.c]: [/Users/cherie/pebble-apps/
concentricity/build/chalk/src/resource_ids.auto.h]; unresolved
['pebble_process_info.h']
21:51:50 task task {task 4344651216: c appinfo.auto.c ->
appinfo.auto.c.16.o} must run as it was never run before or the
task code changed
21:51:50 runner_env kw={'shell': False, 'cwd': '/Users/cherie/
pebble-apps/concentricity/build', 'env': None}
21:51:50 envhash d751713988987e9331980363e24189ce []
66. Zone Description
runner command-lines executed (same as -v)
deps implicit dependencies found
task_gen task creation & task generator method execution
action functions to execute for building the targets
env environment contents
envhash hashes of the environment objects
build build context operations, like filesystem access
preproc preprocessor execution
group groups & task generators
$ pebble build -- --zones=deps
23:01:45 deps deps for [/Users/cherie/pebble-apps/concentricity/src/
concentricity.c]: [/Users/cherie/pebble-apps/concentricity/src/ui.h];
unresolved ['pebble.h']
67. Helpful waf Links
• Pebble Recipes
• https://developer.getpebble.com/build
• GitHub Project
• https://github.com/waf-project/waf
• Google Group
• https://groups.google.com/forum/#!forum/waf-users
• Book
• https://waf.io/book/