Project Configuration File (bpm.tml)
Each BPM project has its own configuration file named bpm.tml located in the project root directory. This file contains project-specific settings.
File format: TOML
[package] Section
The package section contains all project metadata and configuration parameters.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | - | Project name |
version |
string | Yes | - | Project version (format: YYYY.M.M) |
codetype |
string | Yes | - | Code type: bin (binary), lib (library), rom, bank_kernel_module |
templatecode |
string | No | "" |
Template code type (asm_bin_tpl, asm_rom_tpl) |
pathsrc |
string | No | "src" |
Source code directory |
documentation |
string | No | "" |
URL to project documentation |
mike_management |
boolean | No | "False" |
Enable Mike for documentation deployment |
enable_publish |
boolean | No | "True" |
Enable package publishing |
enable_build |
boolean | No | "True" |
Enable project building |
lib |
boolean | No | "True" |
Project contains library code |
rom_compatible |
boolean | No | "False" |
Project is ROM compatible |
authors |
array | No | - | List of authors (email addresses) |
license |
string | No | - | Project license (MIT, Apache-2.0, etc.) |
edition |
string | No | - | Edition/year |
cpu |
string | No | "6502" |
Target CPU architecture |
readme |
string | No | - | Path to README file |
repository |
string | No | - | Project repository URL |
description |
string | No | - | Project description |
homepage |
string | No | - | Project homepage URL |
buildfolder |
string | No | "build" |
Build output directory |
packagetype |
string | No | "tgz" |
Package type (tgz) |
oricutron_path |
string | No | - | Override main config's oricutron_path for this project |
oricutron_replace_autoboot_run |
boolean | No | - | Override main config's oricutron_replace_autoboot_run |
default_rom_oricutron_for_code |
integer | No | - | Override main config's default_rom_oricutron_for_code |
orixsdk_version |
string | No | - | Version of orixsdk to use |
asm_bin_tpl_version |
string | No | - | Version of asm_bin_tpl plugin |
asm_rom_tpl_version |
string | No | - | Version of asm_rom_tpl plugin |
default_github_action_version |
string | No | - | Version of github_action plugin |
default_generatedoc_version |
string | No | - | Version of generatedoc plugin |
orix_minimal_kernel_version |
string | No | - | Minimum kernel version required |
orix_run_pre_script |
string | No | "" |
Path to pre-run script (executed before project in Oricutron) |
md2hlp |
string | No | "yes" |
Enable md2hlp (yes/no) |
web_doc_command |
string | No | "mkdocs build" |
Command to generate HTML documentation |
docsfolder |
string | No | - | Documentation source folder |
Parameter Details
name
Type: string
Required: Yes
Description: The name of your project. This will be used for package naming and identification.
Example:
name = "myproject"
version
Type: string
Required: Yes
Description: The version of your project. Follows the format YYYY.M.M (Year.Month.Minor).
Example:
version = "2025.1"
codetype
Type: string
Required: Yes
Description: The type of code your project produces.
Values:
- bin: Standard binary executable
- lib: Library
- rom: ROM cartridge
- bank_kernel_module: Banked kernel module
Example:
codetype = "bin"
templatecode
Type: string
Required: No
Description: The template type used for your project.
Values:
- asm_bin_tpl: Assembly binary template
- asm_rom_tpl: Assembly ROM template
Example:
templatecode = "asm_bin_tpl"
pathsrc
Type: string
Default: "src"
Description: The directory containing your source code files.
Example:
pathsrc = "src"
documentation
Type: string
Default: ""
Description: URL to your project's documentation.
Example:
documentation = "https://orix-software.github.io/myproject/"
mike_management
Type: boolean
Default: "False"
Description: Enable Mike for documentation deployment. Mike is a Python-based static site generator that can deploy documentation to multiple branches.
Example:
mike_management = "False"
enable_publish
Type: boolean
Default: "True"
Description: Enable package publishing to the repository. Set to False to prevent accidental publishing.
Example:
enable_publish = "True"
enable_build
Type: boolean
Default: "True"
Description: Enable project building. Set to False to disable the build process.
Example:
enable_build = "True"
lib
Type: boolean
Default: "True"
Description: Indicates whether the project contains library code.
Example:
lib = "True"
rom_compatible
Type: boolean
Default: "False"
Description: Indicates whether the project is ROM compatible.
Example:
rom_compatible = "False"
authors
Type: array
Required: No
Description: List of authors with their email addresses.
Example:
authors = [ "author@example.com", "contributor@domain.org"]
license
Type: string
Required: No
Description: The software license for your project.
Example:
license = "MIT"
edition
Type: string
Required: No
Description: The edition or year of your project.
Example:
edition = "2025"
cpu
Type: string
Default: "6502"
Description: The target CPU architecture for your project.
Example:
cpu = "6502"
readme
Type: string
Required: No
Description: Path to your project's README file.
Example:
readme = "README.md"
repository
Type: string
Required: No
Description: URL to your project's source code repository.
Example:
repository = "https://github.com/example/myproject"
description
Type: string
Required: No
Description: A short description of your project.
Example:
description = "My Orix project for managing files"
homepage
Type: string
Required: No
Description: URL to your project's homepage.
Example:
homepage = "https://example.com/myproject"
buildfolder
Type: string
Default: "build"
Description: The directory where build outputs will be placed.
Example:
buildfolder = "build"
packagetype
Type: string
Default: "tgz"
Description: The type of package to create. Currently only tgz is supported.
Example:
packagetype = "tgz"
oricutron_path
Type: string
Default: -
Description: Override the main configuration's oricutron_path for this specific project. This is the full path to the Oricutron emulator binary.
Example:
oricutron_path = "/opt/oricutron/oricutron"
Note: This overrides the global oricutron_path setting from ~/.bpm/bpm.
oricutron_replace_autoboot_run
Type: boolean
Default: -
Description: Override the main configuration's oricutron_replace_autoboot_run setting for this project. When set to True, BPM will replace Oricutron's autoboot configuration when running this project.
Example:
oricutron_replace_autoboot_run = "True"
default_rom_oricutron_for_code
Type: integer
Default: -
Description: Override the main configuration's default_rom_oricutron_for_code for this project. This specifies which ROM slot to use for code type projects.
- Values 1-42: ROM slots (e.g., rom04)
- Values 43+: RAM slots (e.g., ram01 for 43, ram10 for 52)
Example:
default_rom_oricutron_for_code = 4
orixsdk_version
Type: string
Default: -
Description: Version of the orixsdk plugin to use for this project. This overrides the default version specified in the main configuration file.
Example:
orixsdk_version = "2023.3.0"
asm_bin_tpl_version
Type: string
Default: -
Description: Version of the asm_bin_tpl (Assembly Binary Template) plugin to use.
Example:
asm_bin_tpl_version = "2024.4"
asm_rom_tpl_version
Type: string
Default: -
Description: Version of the asm_rom_tpl (Assembly ROM Template) plugin to use.
Example:
asm_rom_tpl_version = "2024.4"
default_github_action_version
Type: string
Default: -
Description: Version of the github_action plugin to use for this project.
Example:
default_github_action_version = "2024.4"
default_generatedoc_version
Type: string
Default: -
Description: Version of the generatedoc plugin to use for this project.
Example:
default_generatedoc_version = "2025.1"
orix_minimal_kernel_version
Type: string
Default: -
Description: Minimum kernel version required for this project to run.
Example:
orix_minimal_kernel_version = "2024.1"
orix_run_pre_script
Type: string
Default: ""
Description: Path to a pre-run script that will be executed before the project in Oricutron. This script is added before the project command in the autoboot configuration.
Example:
orix_run_pre_script = "scripts/starting.sub"
md2hlp
Type: string
Default: "yes"
Description: Enable md2hlp documentation generation. Set to "yes" to enable, "no" to disable.
Example:
md2hlp = "yes"
web_doc_command
Type: string
Default: "mkdocs build"
Description: Command to generate HTML documentation. This command will be executed when running bpm doc.
Example:
web_doc_command = "mkdocs build"
docsfolder
Type: string
Default: -
Description: The folder containing your documentation source files.
Example:
docsfolder = "mkdocs/docs/"
[[bin]] Section (Array of Tables)
Defines binary executables to build. Multiple entries can be specified to build multiple binaries from your project.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Binary name (7 characters max for Orix compatibility) |
path |
string | Yes | Path to source file (relative to project root) |
extra_args_<name> |
string | No | Extra arguments for this specific binary |
Note: Binary names should be 7 characters maximum for Orix compatibility. Use the convert_binary_name_to_seven_chars() function for automatic conversion.
Example
[[bin]]
name = "main"
path = "src/main.s"
[[bin]]
name = "helper"
path = "src/helper.s"
[[dynamic-lib]] Section (Array of Tables)
Defines dynamic libraries to build. Each entry specifies a dynamic library that your project provides.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Library name |
targetfilename_<name> |
string | Yes | Output filename for the library |
path_<name> |
string | Yes | Path to source file |
Example
[[dynamic-lib]]
name = "mylib"
targetfilename_mylib = "mylib.so"
path_mylib = "src/mylib.s"
[dependencies] Section (Table)
Lists project dependencies. Dependencies are other Orix packages required by this project. When you run bpm install, BPM will download and install all dependencies listed here.
Format
[dependencies]
orixsdk = "2023.3.0"
curl = "2024.1"
Managing Dependencies
- Add a dependency:
bpm add <package>@<version> - Remove a dependency:
bpm remove <package> - Install all dependencies:
bpm install
[srcfolders] Section (Table)
Defines additional source folders to include in the build process. This allows you to organize your source code across multiple directories.
Format
[srcfolders]
src = "src"
tests = "tests"
lib = "lib"
Usage
You can add source folders using the command:
bpm addsrc <folder>
Complete Example
[package]
name = "myproject"
version = "2025.1"
codetype = "bin"
templatecode = "asm_bin_tpl"
pathsrc = "src"
authors = [ "author@example.com",]
license = "MIT"
cpu = "6502"
readme = "README.md"
repository = "https://github.com/example/myproject"
description = "My Orix project"
homepage = "https://example.com/myproject"
buildfolder = "build"
packagetype = "tgz"
orixsdk_version = "2023.3.0"
oricutron_replace_autoboot_run = "True"
orix_minimal_kernel_version = "2024.1"
orix_run_pre_script = "scripts/starting.sub"
md2hlp = "yes"
web_doc_command = "mkdocs build"
docsfolder = "mkdocs/docs/"
[[bin]]
name = "main"
path = "src/main.s"
[[bin]]
name = "helper"
path = "src/helper.s"
[[dynamic-lib]]
name = "mylib"
targetfilename_mylib = "mylib.so"
path_mylib = "src/mylib.s"
[dependencies]
orixsdk = "2023.3.0"
curl = "2024.1"
[srcfolders]
main = "src"
tests = "tests"
Code Types
| Code Type | Description | Output |
|---|---|---|
bin |
Standard binary executable | .o and relocated binary files |
lib |
Library | .lib file |
rom |
ROM cartridge | .rom file |
bank_kernel_module |
Banked kernel module | Special module files |
Template Types
| Template | Description | Use Case |
|---|---|---|
asm_bin_tpl |
Assembly binary template | Creating binary executables for Orix |
asm_rom_tpl |
Assembly ROM template | Creating ROM cartridges for Orix |
Special Notes
-
Binary Names: For Orix compatibility, binary names should be 7 characters maximum. The
convert_binary_name_to_seven_chars()function can automatically convert longer names. -
Version Format: Versions should follow the format
YYYY.M.M(Year.Month.Minor) for consistency across all Orix projects. -
Plugin Versions: Default plugin versions are defined in the main configuration file (
~/.bpm/bpm) but can be overridden per project in this file. -
Path Overrides: Project-specific settings (like
oricutron_path,oricutron_replace_autoboot_run,default_rom_oricutron_for_code) override the corresponding settings from the main configuration file. -
Dynamic Libraries: Use the
bpm dynamiclibcommand to manage dynamic library configurations (though this command appears to be commented out in the current version).
Configuration Management
You can manage project configuration parameters using the bpm config command:
Setting Project Configuration Parameters
# Set project name
bpm config set project name myproject
# Set project version
bpm config set project version 2025.1
# Set code type
bpm config set project codetype bin
# Enable documentation generation
bpm config set project md2hlp yes
# Set pre-run script
bpm config set project orix_run_pre_script scripts/setup.sub
# Override oricutron path
bpm config set project oricutron_path /custom/path/to/oricutron
Adding Project Sections
# Add a binary to build
bpm config add project binary
# Add a dynamic library
bpm config add project dynamic-lib
File Location
The project configuration file bpm.tml is located in the root directory of your BPM project.
Example:
myproject/
├── bpm.tml # Project configuration file
├── src/
│ └── main.s
├── README.md
└── ...
See Also
- bpm_command.md - Complete BPM commands reference
- bpm_tml_main.md - Main configuration file reference
- Installation Guide