Ukor

A build tool for Roku projects

Features:

• Multiple flavors
• Install to device
• Project and local configuration properties
• Save installation targets and authentication details
• Set default install targets
• Search for Rokus on your local network

Questions?

Join us in the #tooling channel on the Roku Developers Slack.

Requirements

• Node v12.22 or higher.

Project setup

You can install Ukor via NPM.

npm install -g @willowtreeapps/ukor

A Ukor project is organized in a single src folder with properties files in order to configure Ukor. The src folder contains a single main folder which contain the default built sources, optional customized flavor sources as well as test sources.

/Project
- src/
  - main/
    - components/
    - source/
    - anyThingYouWant/
    - constants.yaml
  - flavor1/
  - flavor2/
  - test/
  - testflavor1/
- ukor.properties
- ukor.local

The ukor.properties file is the main ukor configuration file for the project and should be version controlled. The ukor.local file is a local properties file that contains local customizations for ukor overriding the ukor.properties file. This file is not expected to be version controlled.

The constants.yaml file is per-flavor. In the file, you can define strings (or even any text to insert into a file), and can be identified with @{some.category.id} in brightscript OR xml source files.

Example properties (yaml)

buildDir: 'build'
sourceDir: 'src'
preBuild: 'scripts/main.js'
mainFlavor: 'flavorName'
flavors: {
  flavorName: {
    src: ['flavor', 'main']
  },
  flavorNameRelease: {
    base: 'flavorName',
    src: ['release']
  }
}
rokus: {
  roku2: {
    serial: '123123123',
    auth: {
      user: 'rokudev',
      pass: 'YourPassword'
    }
  }
}

Constants

Each flavor can contain string resources specified in the YAML format by providing constants.yaml file. Strings can be referenced by their path specified in any .xml or .brs source files. For example,

Given a constants.yaml file:

strings:
  contactSupport: 'contact support at 555-555-5555'
  login:
    signIn: 'Sign in now!'

Strings can be references in a *.brs file using the following interpolation syntax @{ <your_resource_here> }. For example,

supportLabel.text = "@{strings.contactSupport}"
loginLabel.text = "@{strings.login.signIn}"

The final generated *.brs source file will have the strings inlined like so.

supportLabel.text = "contact support at 555-555-555"
loginLabel.text = "Sign in now!"

Usage

Usage: ukor [options] [command]


  Commands:

    make [flavors...]             Bundle your channel into a zip to the build directory
    install [flavor] [roku] [-c]  Bundle then deploy your channel to a named roku
    package <flavor> <roku>       Package a channel flavor with a roku device
    rekey <roku>                  Rekey your device (an packageReference is required)
    lint <flavor>                 Lint a channel flavor
    console [roku]                Launch the Telnet console for the named roku
    debugger [roku]               Launch the Telnet debugger for the named roku
    find                          Search for rokus on the network
    init [flavors...]             Initialize a ukor project
    test                          Run the tests
    validate                      Validate ukor.properties and ukor.local
    help [cmd]                    display help for [cmd]

  Options:

    -h, --help     output usage information

    -v, --verbose  Turn on verbose logging

Quick reference

• I want to make a new project

ukor init

• I want to build my project

ukor make [flavor]

• I want to install my project on a device

ukor install [flavor] [device]

or

ukor install [flavor] [ip address] --auth=[username]:[password]

• I want to package my project using a device

ukor package [flavor] [device]

or

ukor package [flavor] [ip address] --auth=[username]:[password]

• I want to rekey my device

ukor rekey [device]

or

ukor package [ip address] --auth=[username]:[password]

NOTE: you will need to define a packageReference and packageKey in ukor.properties.yaml. packageReference represent device id and packageKey does for password

Testing

Ukor uses UnitTestFramework.brs as part of its unit test runner and test reporting feature. This is especially useful if you plan on having Continuous Integration as part of your workflow.

Setup

First, copy the modified UnitTestFramework.brs in lib/brs/ to your src/test/source/ folder, so it loads at startup for when testing.

Note that the original UnitTestFramework.brs can be found here

Next, dd the following snippet in your startup function, after screen.show() but before the event loop

if params.RunTests = "true"
  runner = TestRunner()
  if params.host <> invalid
    runner.logger.SetServer(params.host, params.port)
  else
    runner.logger.SetServerURL(params.url)
  end if
  ' other setup if needed
  runner.run()
end if

You should now be able to execute your test suite using the test command.

ukor test [flavor] [roku]

What's happening?

Basically, we modified the rokudev UnitTestFramework.brs file to make a JSON of test results, and then POST that to the specified server. ukor test [flavor] builds and deploys the specified flavor with the test src folder, and then restarts the channel with parameters to run tests and point the results to the client machine. ukor will log the results, and also output results in xml and junit format to .out/tests/ukorTests.[xml|junit].

notes:

• Ukor now copies UnitTestFramework.brs with ukor init!
• UnitTestFramework.brs is now up to date with the rokudev repo!

Contributing to Ukor

Contributions and suggestions are more than welcome. Please see our Code of Conduct as well as our Contributing Guidelines for more information.