BPM Commands Reference
Complete reference for all BPM (Build and Package Manager) commands.
Table of Contents
Commands
BPM (Build and Package Manager) provides the following commands:
| Command | Description |
|---|---|
bpm new |
Initialize a new Orix package in the current directory |
bpm build |
Build the project (compile and create binaries) |
bpm doc / bpm d |
Build project documentation |
bpm run |
Run the project in Oricutron emulator |
bpm list |
List all installed packages and dependencies |
bpm add <package>@<version> |
Add a dependency to the project's manifest file |
bpm remove <package> |
Remove a dependency from the project's manifest file |
bpm install |
Install all dependencies listed in the manifest file |
bpm search <package> |
Search for a package in the repository |
bpm publish |
Publish the current package to the repository |
bpm unpublish |
Remove a published package from the repository |
bpm plugins |
Manage plugins |
bpm config |
Manage configuration parameters |
bpm package |
Create a package (.tgz) from the built project |
bpm addsrc <folder> |
Add a source folder to the build manifest |
bpm update |
Update all dependencies and plugins to their latest versions |
Command Details
bpm new
Initialize a new Orix package in the current directory. This command creates a new project structure with the necessary configuration files.
Initialize an new project
For a command line program :
~$ mkdir mylib
~$ bpm new
This project is :
1) A binary program
2) A library
3) A rom
answer ? 1
Init bpm.tml
Init src folder
Init src/tmp.c
Init VERSION file
Add github action main.yml into project: y/N ?N
initialized
Usage:
bpm new
bpm build
Build the project. Compiles all source files and creates the output binaries in the build folder.
Usage:
bpm build
Options:
- The build process respects the enable_build setting in bpm.tml
bpm doc or bpm d
Build project documentation. Uses mkdocs by default or the tool specified in the web_doc_command parameter of your bpm.tml file.
'bpm doc' generate several docs, depending of the plugins installed.
Generate docs
bpm doc
md2hlp plugin
All docs/{name}.md will be generated into .hlp (for man orix command) and inserted in "build/usr/share/man/". md2hlp.cfg into project will be modifyed in order to modify title of .hlp (part Heading1, property : Head)
generatedoc plugin
Generate docs from source code see asm.md and c.md
Change docs target folder
use docsfolder param in package section.
Default : docs/
ex:
[package]
...
docsfolder = "mkdocs/docs/"
...
Folder
Docsfolder is always formatted with version of the program like :
docs/2025.2/
Usage:
bpm doc
# or
bpm d
Note: The documentation command is defined in your project's bpm.tml file with the web_doc_command parameter.
bpm run
Run the project in Oricutron emulator. Uses the configuration from oricutron_path and oricutron_replace_autoboot_run parameters.
Build an run program.
The Oricutron path must be set in main config file or local config file (manifest).
add a oricutron path for main config :
bpm config set main oricutron_path /mnt/c/Users/mypath/oric/oricutron_plugins/oricutron
for current manifest :
bpm config set project oricutron_path /mnt/c/Users/mypath/oric/oricutron_plugins/oricutron
Behavior for 'bpm run'
oricutron_path is missing, it will read oricutron_path from main config.
Behavior in oricutron sdcard/ folder
If AUTOBOOT is already in etc/autoboot. bpm saves it and restore it.
If there is no autoboot before "bpm run starts", sur autoboot from bpm will be removed.
For autoexecute AUTOBOOT, 'submit' binary must bin in sdcard/bin/
Orix kernel must be greater than 2023.3
Specify command to launch : bpm run --bin hello
To specify args :
bpm run --bin "hello -y"
Specify extra args
bpm run -- arg1 arg2
Launch a command before the project program (only for bin program)
$ mkdir scripts/
$ echo "netchk" > scripts/network.sub
$ bpm config set project orix_run_pre_script scripts/network.sub
$ bpm run
It will start scripts/network.sub and the main project binary
Usage:
bpm run
Options:
- --bin <binary>: Specify which binary to run
- --verbose: Enable verbose output
Example:
bpm run --bin myapp
bpm run --verbose
Note: Requires Oricutron to be installed and configured (see oricutron_path in configuration files).
bpm list
List all installed packages and dependencies for the current project.
Usage:
bpm list
bpm add <package>@<version>
Add a dependency to the project's manifest file (bpm.tml). The dependency will be listed in the [dependencies] section.
Usage:
bpm add <package>@<version>
Example:
bpm add orixsdk@2023.3.0
bpm add curl@2024.1
Note: After adding a dependency, run bpm install to download and install it.
bpm remove <package>
Remove a dependency from the project's manifest file.
Usage:
bpm remove <package>
Example:
bpm remove sdllib
bpm install
Install all dependencies listed in the manifest file ([dependencies] section of bpm.tml). This will download the specified versions of each dependency and install them in the ~/.bpm/plugins/ directory.
Usage:
bpm install
bpm search <package>
Search for a package in the Orix repository.
$ bpm search
orixsdk 2023.3 - Orix Software Toolkit
netdb 2024.4 - Network database operations
ksocket 2025.1 - Only use this package in Kernel source code (socket management part)
ch395 2024.4 - ch395 low hardware routine. Use socket lib for socket management under Orix
kch395 2025.1 - Only for orix kernel
inet 2025.1 - Provide inet_aton
socket 2025.2 - Socket management https://orix-software.github.io/socketlib/api/
curl 2025.1 - Curl lib for Orix https://orix-software.github.io/curllib/api/
Usage:
bpm search <package>
Example:
bpm search sdl
bpm publish
Publish the current package to the Orix repository (repo.orix.oric.org).
Usage:
bpm publish
Options:
- --alpha: Publish to alpha repository instead of stable
Example:
bpm publish
bpm publish --alpha
Note: Requires BPM_PUBLISH_KEY environment variable to be set. To get a publish key, send an email to jede[at]oric[dot]org.
bpm unpublish
Remove a published package from the repository.
Usage:
bpm unpublish
Options:
- --alpha: Unpublish from alpha repository instead of stable
Example:
bpm unpublish
bpm unpublish --alpha
bpm plugins
Manage BPM plugins. Plugins extend BPM functionality with additional features.
A plugin is a tool in order to manage some part of the development. Each day, bpm will try to update plugins, and will ask if plugin must be installed
bpm plugins
Usage : bpm plugins
bpm plugins install
Usage : bpm plugins install [plugin_name] [--replace-for-new-project]
--replace-for-new-project option will set this plugin version for next project but it does not update it for current project (it needs to be changed in bpm.tml of the project)
bpm plugins update
Update all plugins :
bpm plugins update
bpm plugins -h
Usage : bpm plugins install -h
Displays installed plugins
~$ bpm plugins
Use 'bpm plugins -h' for 'plugins' help
md2hlp: Build markdown into hlp file (text mode) [Installed]
orixsdk: Useful ca65 macro for Orix and reloc binary (Mandatory for Orix projects) (Available versions : ['2023.3.0']) [Installed]
asm_bin_tpl: Assembly binary template for Orix (Available versions : ['alpha']) [Installed]
asm_rom_tpl: Assembly rom template for Orix (Available versions : ['2024.4', 'alpha']) [Installed]
github_action: Template for github action (Available versions : ['2024.4']) [Installed]
generatedoc: Tool to comment source code and generate markdown (Available versions : ['2025.1', '2024.4']) [Installed]
Available plugins:
- md2hlp: Build markdown into hlp file (text mode)
- orixsdk: Useful ca65 macro for Orix and reloc binary (Mandatory for Orix projects)
- asm_bin_tpl: Assembly binary template for Orix
- asm_rom_tpl: Assembly ROM template for Orix
- github_action: Template for github action
- generatedoc: Tool to comment source code and generate markdown
Subcommands:
- bpm plugins list: List all available plugins and their installation status
- bpm plugins install <plugin>: Install a specific plugin
- bpm plugins update: Update all plugins to their latest versions
Usage:
bpm plugins list
bpm plugins install orixsdk
bpm plugins update
bpm config
Manage configuration parameters for both main and project settings.
'bpm config' modify behavior of bpm
It can modify main configuration and project configuration.
Main parameters are :
oricutron_path Set Oricutron path for main (general behavior), value must be path of Oricutron binary with filename binary in the path
oricutron_replace_autoboot_run Set False or True. False will not modify /etc/autoboot in Oricutron
default_rom_oricutron_for_code Default rom when code type is rom : the .rom will be inserted into this slot
Project parameters are :
name Name of the project
version Version of the project
codetype Code type of the project (lib is a library, bin a command line [lib|bin])
oricutron_replace_autoboot_run Set False or True. False will not modify /etc/autoboot in Oricutron when bpm run is executed
oricutron_path Set Oricutron path for current project
default_rom_oricutron_for_code Default rom when code type is rom : the .rom will be inserted into this slot
orix_run_pre_script Pre submit script : will be added before project command
md2hlp Activate md2hlp : enable set to yer, disabled set to no
bpm config set
"config set" can be used to set any parameter in global configuration (main) or project configuration
bpm config add project binary : add a source code to build during build stage
For example, we want to add curl.c into build stage with the output name called "curl"
Add a "curl" binary into bin list to generate :
bpm config add project binary curl tests/curl.c
Add args :
bpm config add project binary curl tests/curl.c "arg1 arg2"
In that case, "bpm run --bin curl" will launch "curl" compiled from tests/curl.c
Add a 'pre' script before main command is launched
~$ mkdir scripts/
~$ echo "netchk" > scripts/network.sub
~$ bpm config set project orix_run_pre_script scripts/network.sub
Subcommands:
- bpm config set main <parameter> <value>: Set a main configuration parameter
- bpm config set project <parameter> <value>: Set a project configuration parameter
- bpm config add project <type>: Add a project configuration section
Usage:
bpm config set main oricutron_path /usr/local/bin/oricutron
bpm config set project name myproject
bpm config set project version 1.0.0
bpm config add project binary
Main configuration parameters:
- oricutron_path: Path to Oricutron emulator binary
- oricutron_replace_autoboot_run: Enable/disable autoboot replacement
- default_rom_oricutron_for_code: Default ROM slot for code projects
- default_orixsdk_version: Default orixsdk plugin version
- default_asm_bin_tpl_version: Default asm_bin_tpl plugin version
- default_asm_rom_tpl_version: Default asm_rom_tpl plugin version
- default_github_action_version: Default github_action plugin version
- default_kernel_version: Default kernel version
- default_generatedoc_version: Default generatedoc plugin version
Project configuration parameters: See bpm_tml.md for complete list.
bpm package
Create a package (.tgz) from the built project. This package can then be published or distributed.
"src/include/*.s" will be added into "/usr/include"
"src/include/*.inc" will be added into "/usr/include/asm"
In that case, if a binary calls theses include, "bpm build" will include theses paths automaticly
bpm package
Usage:
bpm package
Note: The package type is defined in bpm.tml with the packagetype parameter (default: tgz).
bpm addsrc <folder>
Add a source folder to the build manifest. This allows you to include additional directories in the build process.
addsrc command can add a folder into build process.
In that case, bpm will build src/* and folder in addsrc section. It's not used to have a test program.
It's a folder to add and will be linked with main project.
bpm addsrc src/plugins
Usage:
bpm addsrc <folder>
Example:
bpm addsrc tests
bpm addsrc lib
Note: Added folders will appear in the [srcfolders] section of bpm.tml.
bpm update
Update all dependencies and plugins to their latest versions.
Usage:
bpm update
Options:
- --force-update: Force the update even if already up to date
- --replace-for-new-project: When used with --force-update, install plugin versions for new projects
Example:
bpm update
bpm update --force-update
bpm update --force-update --replace-for-new-project
Environment Variables
| Variable | Description | Required |
|---|---|---|
BPM_PUBLISH_KEY |
Required for publishing packages to repo.orix.oric.org | Yes (for publish) |
To get a publish key: Send an email to jede[at]oric[dot]org
Return Codes
| Code | Description |
|---|---|
0 |
Success |
1 |
Error (build failed, command not found, configuration error, etc.) |
See Also
- bpm_tml.md - Project configuration file (
bpm.tml) reference - bpm_tml_main.md - Main configuration file (
~/.bpm/bpm) reference - Installation Guide