Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/willowtreeapps/ukor
A Roku build tool with support for build flavors
https://github.com/willowtreeapps/ukor
brightscript build build-tool roku
Last synced: 3 months ago
JSON representation
A Roku build tool with support for build flavors
- Host: GitHub
- URL: https://github.com/willowtreeapps/ukor
- Owner: willowtreeapps
- License: apache-2.0
- Created: 2017-05-22T18:26:54.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-11-09T11:56:38.000Z (about 1 year ago)
- Last Synced: 2024-07-29T11:53:29.585Z (4 months ago)
- Topics: brightscript, build, build-tool, roku
- Language: Brightscript
- Homepage:
- Size: 593 KB
- Stars: 48
- Watchers: 21
- Forks: 14
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-roku - Ukor - A build tool for Roku projects (Build Tools)
README
# 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](https://join.slack.com/t/rokudevelopers/shared_invite/enQtMzU5Njc5ODM5MzAyLWE2MTIxMWQ5Nzg0Y2E3ODgzYTk4NmQxMDg2YjRjYjdiMzM5ZDU4ZTc0YmM1ZmU0Mzc5MzI3ODU3MmUxOTdlNTE).
## Requirements
* Node **v7.6** or higher.
## Project setup
You can install Ukor via NPM.
```sh
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)
```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:
```yml
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 `@{ }`. For example,
```yml
supportLabel.text = "@{strings.contactSupport}"
loginLabel.text = "@{strings.login.signIn}"
```
The final generated `*.brs` source file will have the strings inlined like so.
```yml
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 Package a channel flavor with a roku device
rekey Rekey your device (an packageReference is required)
lint 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/](../master/lib/brs/UnitTestFramework.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](https://github.com/rokudev/unit-testing-framework)
Next, dd the following snippet in your startup function, after `screen.show()` but before the event loop
```brightscript
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](/CODE_OF_CONDUCT.md)
as well as our [Contributing Guidelines ](/CONTRIBUTING.md) for more information.