ropm
v0.10.27
Published
A package manager for the Roku platform.
Downloads
692
Keywords
Readme
ropm
A package manager for the Roku platform.
Installation
- Install Node.JS from here
- install the
ropm
node module globallynpm i ropm -g
Discovering packages
Click here to search npm for packages with the ropm
keyword.
You can also search GitHub for ropm
packages, but since GitHub doesn't support searching by keyword, you'll need to know what you're looking for.
Creating a package
See the Creating ropm Packages section for guidance about creating ropm
packages.
How it works
ropm
leverages NodeJS's npm
module system behind the scenes. This means when you create packages, they should be pushed to an npm
registry such as npm, GitHub packages, or even an on-premise registry.
The Roku project structure is fairly strict. There are a few rules:
- Components must be stored somewhere underneath
pkg:/components/
. - Component names must be unique across the entire project
- Components each create their own scope
- All files found underneath
pkg:/source/
are compiled into a single scope. - All functions in a scope must have a unique name
This provides unique challenges for a Roku package manager, because file paths alone are not enough to prevent symbol collisions. ropm
solves the naming collision problem by rewriting the names of all functions and components in an ropm module.
ropm will create a roku_modules/<ropm module name>
folder into each corresponding folder of your project. For example, if a ropm module named "logger"
has the following folders:
- source/
- components/
- images/
- fonts/
then ropm install
will create the following folders in your project
- source/roku_modules/logger
- components/roku_modules/logger
- images/roku_modules/logger
- fonts/roku_modules/logger
Sanitizing module names
Most npm
-style package registries allow many characters in package names that are not valid identifiers within a Roku application. As such, these names need to be sanitized. The following transformations will be applied to every module name.
- registry namespaces will have the
@
symbol removed and the/
replaced with an underscore. (i.e.@roku/sgdex
would becomeroku_sgdex
) - All characters except for numbers, letters, and underscore will be removed. (i.e.
cool-package
would becomecoolpackage
)
While extremely unlikely, this does have the potential for name collisions. If collisions occur, you will need to define a custom prefix for one of the dependencies in question.
Prefixes
When module authors publish their modules, they should not include any baseline prefix or namespace in front of their component or function names. The prefixing will be handled by ropm
itself.
ropm
will scan every module for:
- function declaractions (i.e.
function LogInfo(message)...end function
) - function calls (i.e.
LogInfo("do something")
) - function references (i.e.
log = LogInfo
) - string function name in every object's
observeField
calls - component declarations
- component usage:
- component names in XML
extends
attribute - use of a component as an element in XML files
- component names in XML
Then, ropm
will append a prefix to each of the previously-mentioned items. For example, consider the FancyKeyboards
package:
xml
<component name="SimpleKeyboard" extends="Keyboard">
<AdvancedKeyboard />
becomes
<component name="FancyKeyboards_SimpleKeyboard" extends="fancyKeyboards_Keyboard">
<FancyKeyboards_AdvancedKeyboard />
brs
sub SetKeyboardLanguage(language)
WriteToRegistry("KeyboardLanguage", language)
end sub
sub WriteToRegistry(key, value)
'...
end sub
CreateObject("RoSGNode", "SimpleKeyboard")
node.CreateChild("AdvancedKeyboard")
becomes
sub FancyKeyboards_SetKeyboardLanguage(language)
FancyKeyboards_WriteToRegistry("KeyboardLanguage", language)
end sub
sub FancyKeyboards_WriteToRegistry(key, value)
'...
end sub
CreateObject("RoSGNode", "FancyKeyboards_SimpleKeyboard")
node.CreateChild("FancyKeyboards_AdvancedKeyboard")
WARNING: ropm
does not currently support rewriting components created with ifSGNodeChildren
's update()
call (see the docs here). If you are a ropm package author and need support for this, please raise an issue.
Special case
Leading underscore
Some languages use leading underscore to represent private
or internal
. Ropm detects leading underscores, and starts the prefixing process at the first non-underscore character. For example:
sub _SecretKeyboardSub1()
end sub
sub ________SecretKeyboardSub2()
end sub
becomes
sub _FancyKeyboards_SecretKeyboardSub1()
end sub
sub ________FancyKeyboards_SecretKeyboardSub2()
end sub
File paths
ropm
will rewrite file paths as well. These file paths will be rewritten based on the final location. ropm
looks for:
- all absolute file paths found anywhere in the source code (i.e.
"pkg:/path/to/something"
) - relative file paths in script tags (i.e.
<script uri="../../some/file.brs" />
)
Some packages may wish to look for files in predefined locations in the host application's folder structure (like a config file that should be placed at exactly pkg:/config/loggerConfig.json
for example). In these situations, you will need to trick ropm into not rewriting your file path. The trick is to restrict the first part of the string to ONLY contain "pkg:/"
and nothing else. ropm
looks for pkg:/
and at least one additional character, so standalone "pkg:/"
paths will be ignored. Here are a few examples:
sub GetImagePath(imageName)
'will be rewritten because we have content after 'pkg:/'
image1 = "pkg:/images/" + imageName
'will not be rewritten because the 'pkg:/' is isolated
image2 = "pkg:/" + "images/" + imageName
end sub
Result:
sub CatPhotoLib_GetImagePath(imageName)
'will be rewritten because we have content after 'pkg:/'
image1 = "pkg:/images/roku_modules/CatPhotoLib/" + imageName
'will not be rewritten because the 'pkg:/' is isolated
image2 = "pkg:/" + "images/" + imageName
end sub
Tasks (m.top.functionName
)
BrightScript Task objects have a special m.top.functionName
property that specifies which function should be run during the task. ropm will find all instances of m.top.functionName = "<anything>"
and add the prefix to the beginning of the string.
The syntax must be exactly m.top.functionName =
followed by a string (i.e. m.top.functionName = "taskCallback"
). ropm will skip the statement if anything other than a string is found to the right-hand-side of the equals sign. If you dynamically generate the value for m.top.functionName
, or assign it in some other fashion, consider using the ROPM_PREFIX source literal instead.
Never-prefixed functions
Due to their special handling within the Roku architecture, the following functions will never be prefixed:
RunUserInterface
Main
RunScreenSaver
Init
OnKeyEvent
ROPM_PREFIX source literal
ropm provides a source literal called ROPM_PREFIX
which, during ropm install, gets replaced with a string literal containing your module's prefix. This enables developers to decide the best way to construct their own function name strings. Consider the following exmaple.
Your ropm module code:
sub init()
m.top.functionName = getFunctionName()
end sub
function getFunctionName()
if isLoggedIn()
return ROPM_PREFIX + "initLoggedIn"
else
return ROPM_PREFIX + "initLoggedOut"
end if
end function
After ropm install (the module prefix is "logger"):
sub init()
m.top.functionName = getFunctionName()
end sub
function getFunctionName()
if isLoggedIn()
return "logger_" + "initLoggedIn"
else
return "logger_" + "initLoggedOut"
end if
end function
Renaming modules
By default, ropm
will install modules with their default names from the registry. For example, if you run ropm install roku-promise
, then the ropm package name will be rokupromise
. But what if you wanted to reference it as promise
in your project? You can accomplish this by leveraging the flexibility of the package.json dependencies
section. Here's the command to install roku-promise
with an alternate name:
ropm install promise@npm:roku-promise
This will install the roku-promise
library from the npmjs.com
registry and call it promise
.
Here's the resulting package.json dependencies
section:
{
"dependencies": {
"promise": "npm:[email protected]"
}
}
Semantic versioning
It is highly recommended that ropm
package authors strictly adhere to the rules of Semantic Versioning. This will provide the most stability and consistency for consumers of your package, as well as provide the highest performance and smallest possible package size.
Version narrowing
Whenever ropm encounters a project that directly or indirectly requires multiple versions of a ropm module, ropm will attempt to minimize the number of versions of that package.
For example, consider a project that has these dependencies:
- roku-promise version 1.1.0
- roku-promise version 1.4.0
ropm will only install 1.4.0
since semantic versioning states that the only differences between 1.1.0
and 1.4.0
are new features and bugfixes, and should not contain breaking changes.
Here's another example:
- roku-promise@
1.1.0
- roku-promise@
1.4.0
- roku-promise@
2.0.0
- roku-promise@
2.3.4
ropm will only install 1.4.0
and 2.3.4
since those are the highest versions within the same major range.
Prerelease versions
Due to their unstable nature, prerelease versions of packages have special treatment in ropm. Each prerelease version will be considered a standalone package. Example:
- roku-promise@
1.0.0-beta.1
- roku-promise@
1.0.0-beta.2
Both versions will be copied to the project. We do not recommend publishing packages that depend on prerelease versions of a package.
Version prefixing
As previously mentioned, all packages will have prefixes applied to functions and components. All direct dependencies of a project (i.e. the packages listed in your app's package.json
dependencies
section) will use the exact dependency name listed. However, in order to resolve version conflicts and maintain consistency, any indirect dependencies (i.e. the dependencies of your dependencies) will be prefixed using the major version.
For example, consider the following dependency graph:
- logger@
1.0.0
- fileLogger@
2.0.0
- fileLogger@
- simple-list@
1.2.0
- complex-list@
3.0.0
- complex-list@
The prefixes will be as follows:
- logger
- fileLogger_v2
- simplelist
- complexlist_v3
Disabling module prefixing
If you need to disable ropm
's module prefixing, you can do this on a per-module basis by adding the names of of the desired modules to the ropm.noprefix
key in package.json
. Here's an example:
{
"dependencies": {
"roku-logger": "1.0.0"
},
"ropm": {
"noprefix": [
"roku-logger"
]
}
}
Be sure you're using the npm alias of the package, not the original package name. The alias is the string on the left-hand-side of the dependency. For example:
{
"dependencies": {
"p": "npm:[email protected]"
},
"ropm": {
"noprefix": [
"p"
]
}
}
In this example, the actual name of the package is "roku-promise"
, but we are using the npm alias "p". So "p"
is what you should add to ropm.noprefix
.
Here's another example:
{
"dependencies": {
"roku-promise": "1.0.0",
"r": "npm:[email protected]"
},
"ropm": {
"noprefix": [
"roku-promise",
"r"
]
}
}
The npm aliases in this example is "roku-promise"
and "r"
.
Do not use ropm.noprefix
in published packages
Ropm will reject installing any ropm package that has the ropm.noprefix
key in its package.json, so package authors should NOT use ropm.noprefix
.
Do not change the code within roku_modules
The files and folders within the roku_modules
folders should not be altered at all, as these changes could be erased by future ropm install
commands. If there are issues with a ropm module you are using, consider reaching out to the module publisher to have them fix and release a new version.
Don't commit roku_modules
The roku_modules
folders that ropm creates should not be commited to your project repository. Instead, developers should follow the practice of running ropm install
anytime they fetch code from a repository. Here's how to ignore roku_modules in your .gitignore
file:
.gitignore
roku_modules
The algorithm
Running ropm install
executes the following operations for each package:
- For each folder in the ropm package's
rootDir
folder, delete${rootDir}/<folder_name>/roku_modules/<package_name>
and then copy all of the files from that corresponding folder. - Rewrite function names, function calls, callfunc statements, and component names to have a prefix. (this prevents naming collisions)
- Rewrite in-code file references to point to their new locations
Configuring ropm
You can configure certain characteristics of ropm by specifying ropm options in the package.json
.
rootDir
If you wish to install all ropm dependencies in a different location, then you should specify the rootDir
ropm option in package.json. Here's an example
{
"name": "your-app-name",
"ropm": {
//tell ropm that the files for this module reside in the "./src" folder
"rootDir": "src"
}
...
}
CLI commands
install
Install one or more packages locally in both node_modules
and roku_modules
. This also updates the local package.json
dependencies
section.
Examples:
ropm install roku-promise
ropm install module1 module2 module3
clean
Clean out all ropm_modules
folders found in rootDir
Example:
ropm clean
copy
Similar to install, but does not fetch missing dependencies from the registry. This command should be faster than install as long as all the necessary dependencies are already downloaded. Example:
ropm copy
uninstall
Uninstall one or more packages from both node_modules
and roku_modules
. This also updates the local package.json
dependencies
section
Examples:
ropm uninstall roku-promise
ropm uninstall module1 module2 module3
Creating ropm Packages
Overview
Here is some overview information to help ropm
package authors get started:
ropm
modules are simply npm packages with theropm
keyword (see How to create a ropm package)ropm
uses the BrighterScript parser to assist with prefixing. (see Syntax parsing)- Follow semantic versioning strictly. Make major breaking changes as infrequently as possible. (see Semantic Versioning)
ropm
rewrites everypkg:/
path, so use string concatenation if you need to bypass this logic. (see File paths)- Don't give local variables the same names as functions in your package. (See Finding function references)
- Don't write BrightScript in XML
CDATA
blocks (See BrightScript in XML CDATA blocks is unsupported) - Don't define a baseline namespace. On install,
ropm
will prefix your package for you. (See Prefixes) - Don't reference dependency functions in component interfaces. (see Component interface handling)
- use the
ropm
options inpackage.json
to customize various settings in your packageropm.rootDir
- where you wantroku_modules
installed within your packageropm.packageRootDir
where your package's files reside (i.e.dist
,build
,./
, etc...)- Don't use
ropm.noprefix
, as can not be used within publishedropm
packages.
How to create a ropm package
The ropm
package system leverages the npm package system from Node.js. Simply follow these instructions from npm on how to create a package.
Steps:
Create a new package.json in your project (you can run
ropm init
to have it help build one)Add
"ropm"
to thekeywords
portion of the package.json. Without this tag,ropm
will completely ignore your package when installed in an application folder.Ensure that all files are contained within a folder (preferably
source/
,/components
,images/
, andfonts/
). Files at the root of a ropm package will be ignored.Here's a simple package.json showing how to add the
ropm
keyword:{ "name": "pretty-list", "version": "0.0.1", "description": "", "keywords": ["ropm"] //...additional package.json properties }
publish your package to a registry using the instructions from your registry of choice (npm, GitHub Packages)
Changing where the module's files are copied from (As a package author)
By default, ropm
will copy every file from the root of your module (the folder where package.json
resides), with a few exceptions:
These files will always be excluded (not copied):
package.json
- README
- CHANGES / CHANGELOG / HISTORY
- LICENSE | LICENCE
- NOTICE
All folders named roku_modules
that are found in a ropm module will be ignored. This is due to the fact that modules should not be publishing their own copies of their ropm modules. ropm will handle this for them. So as a package author, be sure to exclude all folders named roku_modules
during your publishing process.
We recommend excluding extraneous files when you create your package using npm's files property. In certain situations, you may want to store your files in a subdirectory. In this situation, you should use the ropm.packageRootDir
property to specify the relative path to the root of your module. This pattern is useful when you want to publish documentation or other extraneous files with your package, but don't want those files to be included when published to a Roku device.
Here's an example (NOTE: comments are included here for explanation purposes but are invalid within an package.json
)
{
"name": "quick-list"
//when npm creates the package, only include these files
"files": [
"src/**/*",
"instructions/**/*"
],
"ropm": {
//tell ropm that the files for this module reside in the "./src" folder
"packageRootDir": "src"
}
}
Syntax parsing using BrighterScript
ropm
uses the BrighterScript parser to find and apply the prefixes to ropm
modules. While fairly comprehensive, there are still a few BrightScript syntax bugs that BrighterScript
does not yet support, and will therefore cause your package to fail during install. Please open an issue if you encounter any syntax issues that prevent your package from working properly.
Finding function references is a package-wide operation
HINT: do not give local variables the same name as any function in your package
Function reference replacement is package-wide and does not operate on a per-scope basis, meaning ropm
could add prefixes to local variables that share a name with any function across your entire package. We recommend that you do not give local variables the same name as any function your package.
Component interface handling
SceneGraph components can declare interface functions which will be callable via the callFunc
function on a node. For example, the following LoggerComponent exposes a function called doSomething
:
<?xml version="1.0" encoding="utf-8" ?>
<component name="LoggerComponent">
<script uri="LoggerComponent.brs" />
<interface>
<function name="doSomething"/>
</interface>
</component>
ropm
will not rename functions referenced by component interfaces because prefixing those functions would change the public API of declared components. This does introduce a small risk for function name collisions, but those risks can be avoided if you adhere to the following guidelines:
- do not reference
ropm
dependency functions as component interface functions.- for example, if your package depends on
roku-logger
, do not add a function interface to<function name="rokulogger_writeToLog" />
.
- for example, if your package depends on
- create a "codebehind" file for each component, which is only imported into that component, and keep all interface exported functions in that codebehind file
- do not reference functions from common/shared files as component interface functions
rootDir versus packageRootDir
rootDir
- specifies where ropm_modules should be installed in your project.packageRootDir
is exclusively for package authors to specify where their package module code resides (like indist
,out
,build
,src
, etc...).
BrightScript in XML CDATA blocks is unsupported
It is considered bad practice to insert BrightScript code into <![CDATA[
xml script blocks, and as such, ropm
does not support CDATA
blocks.
Any BrightScript code found in CDATA
blocks will be ignored by the ropm
prefixing logic, so use at your own risk (or peril!).
Handling observeField
ropm
will auto-detect most common observeField
function calls. In order to prevent naming conflicts, please do not use the name observeField
for custom object functions.
Here are the requirements for having ropm
prefix your observeField
string function names.
- Use a single string literal for the function name. For example,
m.top.observeField(fieldName, "callbackFunction")
- The
observeField
call must be on a single line. For example, this call would remain unprefixed:m.top.observeField(getFieldName({ componentName: "something" }, "callbackFunction")
Sponsors
Changelog
Click here to view the changelog.