Garmin Connect IQ Rules For Bazel

Overview

This repository provides Bazel rules for building, simulating, and testing Garmin Connect IQ applications. It streamlines the development process by integrating the Connect IQ SDK with Bazel's powerful build system.

Features

• Project Scaffolding: Automatically generate manifest.xml and jungle files based on your build targets.
• Resource Scaling: Automatically scale drawable resources for different device resolutions and icon sizes.
• Font Generation: Automatically generate and scale bitmap fonts from TrueType/OpenType files, ensuring they match specific screen dimensions or native SDK font sizes.
• Device Builds: Build .prg application files for specific devices with type checking and optimization options.
• Simulation: Launch your application in the Connect IQ Simulator directly from the command line (optionally with hot-reload).
• Testing: Run unit tests in the simulator (optionally with hot-reload).
• Device Deployment: Upload applications to physical Garmin devices via MTP (Media Transfer Protocol).
• Log Retrieval: Fetch debug logs from physical devices.
• Performance Profiling: Analyze device profiling logs generating statistical reports with call stack resolution.
• Release Packaging: Export .iq files for submission to the Connect IQ Store.
• App Store Assets: Generate device-framed screenshots and optimized animated GIFs for the Connect IQ Store.
• Multi-Device Management: Use macros to generate build, test, and simulation targets for multiple devices at once.

Limitations

Currenly only macOS is supported.

Getting started

1. Before using these rules, ensure you have the following installed:

   • Bazel: It's recommended to use Bazelisk to manage your Bazel version.
   • Garmin Connect IQ SDK: Install an SDK using the Connect IQ SDK Manager.
   • libmtp: Required for physical device communication:
     • macOS: Install via Homebrew: brew install libmtp
   • Optional:
     • Bazel watcher aka ibazel
     • Bazel plugin for Visual Studio Code

2. Create a .bazelrc file (see documentation) containing the following reference to your CIQ developer key:

   build --action_env=CIQ_DEVELOPER_KEY_PATH=/path/to/your/developer_key.der

3. Create a MODULE.bazel file for your project and add the rules_ciq dependency:

   bazel_dep(name = "rules_ciq", version = "0.2.0")

   If you'd prefer to be on the bleeding edge, instead use:

   bazel_dep(name = "rules_ciq")
   
   git_override(
       module_name = "rules_ciq",
       remote = "https://github.com/semolina-solutions/rules_ciq",
       branch = "main",
   )

4. Create a BUILD.bazel file for your project and declare targets using the rules provided by this repository. See thesamples/hello_world project for an introductory example. As a minimal demonstration, here is what to put in the BUILD.bazel file to generate an app manifest for a widget file:

   load("@rules_ciq//:defs.bzl", "ciq_manifest")
   
   ciq_manifest(
       name = "my_manifest",
       entry = "MyApp",
       id = "00000000-0000-0000-0000-000000000001",
       launcher_icon_drawable_resource_id = "MyLauncherIconResource",
       min_api_level = "3.0.0",
       name_string_resource_id = "MyAppNameResource",
       type = "widget",
   )

5. Build, run or test your Bazel targets using bazel build, bazel run, or bazel test. To generate the manifest file from the minimal example above, in the same directory as the BUILD.bazel file, run in the terminal:

   bazel build my_manifest

   The generated file will be written to the bazel-bin directory. You can observe that all devices that support widgets and a minimum API level 3.0.0 are included.

Samples

Sample	Purpose
samples/hello_world	Introductory example demonstrating project structure, manifest generation, simulating, unit testing, uploading to physical devices, and .iq export.
samples/device_parametrics	Illustrates how to generate device-specific resources like icons and backgrounds.
samples/custom_font	Examples of generating custom bitmap fonts, including scaling relative to screen size or matching native SDK font heights.
samples/screen_ppi	Demonstrates how to scale resources based on physical screen dimensions.
samples/store	Examples of generating store assets, including device-framed screenshots and animated GIFs.

Documentation

Stardoc-generated documentation is available in the stardoc directory.

File	Purpose
stardoc/defs.bzl	Documentation for rules and supporting functions in defs.bzl
stardoc/macros.bzl	Documentation for helper macros in macros.bzl

Commercial support

This SDK is free and open-source under the MIT license.

If you're using it in a commercial or production environment and need:

• Priority support
• Integration help
• Feature development
• Long-term maintenance assurances

you can purchase a commercial support contract.

Contact: garmin@semolina.solutions