Skip to content

Latest commit

 

History

History
50 lines (33 loc) · 3.24 KB

generating_code.md

File metadata and controls

50 lines (33 loc) · 3.24 KB
Raw

Generating Code

This SDK relies heavily on code generation, as the specification is defined in the Profile.xlsx file provided by Garmin in their Official SDK release. This document serves as guidance for generating the files, outlines considerations before generation, and provides recovery steps in case issues arise during code generation.

We only generate Global Profile specified in Profile.xlsx retrieved from the Official SDK. For generating your own custom SDK containing Product Profile, please see How to customize the FIT SDK

Conventions to follow

  1. Go cmd says: To convey to humans and machine tools that code is generated, generated source should have a line that matches the following regular expression (in Go syntax): 
    ^// Code generated .* DO NOT EDIT\.$
  2. While there is no naming convention for generated go files, we use the suffix _gen for all files created by fitgen to easily distinguish code-generated files from others. For example: activity_gen.go
  3. Items not adequately defined in Profile.xlsx or lacking sufficient details are encouraged to code manually when possible to enhance robustness. For example: FIT Base Type segregated into profile/basetype/basetype.go

How we generate

When Garmin releases a new SDK, we review the changes they've made. If they are trivial, we update the Profile.xlsx from the latest release to trigger CI to generate the files. For major changes, we open an issue to have discussions before proceeding further to ensure the stability of our SDK.

After generating code we make sure all existing tests are passes locally and on CI. In case the code breaks, we should revert first and fix the issue locally. The fix can be submitted later using pull requests.

Generate Custom FIT SDK

FIT is designed to have the ability to include a Product Profile, which contains manufacturer-specific specifications not defined in the Global Profile. The Product Profile declares manufacturer-specific types and messages used in their FIT-generated files.

To work with these files perfectly, we must include the specification in Profile.xlsx and then generate the code. Otherwise, if we encounter a manufacturer specific message, it will be an unknown message.

Here are the steps to follow:

  1. Clone this repository to your local machine.

  2. Make a copy of Profile.xlsx (the file retrieved from official FIT SDK), let's say Profile-copy.xlsx.

  3. Add manufacturer specific types and messages to Profile-copy.xlsx file.

  4. Remember, modifying official specifications is prohibited, you can only add/edit your own specifications.

  5. Go to fit/internal/cmd/fitgen, run the CLI and point it to the updated Profile-copy.xlsx. Example:

    go run main.go --profile-file Profile-copy.xlsx --path ../../../../ --builders all --profile-version 21.115 --verbose -y

    The path ../../../../ is targeting the root of fit directory (github.com/muktihari/fit).

    For details of how to use the CLI, please do:

    go run main.go --help