batools package

Build/tool functionality specific to the Ballistica project.

This stuff can be a bit more sloppy/loosey-goosey since it is not used by the game itself.

Subpackages

• batools.project package
• batools.spinoff package

Submodules

batools.android module

Functionality related to android builds.

batools.android.androidaddr(archive_dir: str, arch: str, addr: str) → None

Print the source file location for an android program-counter.

command line args: archive_dir architecture addr

batools.androidsdkutils module

Utilities for wrangling Android SDK bits.

batools.androidsdkutils.run(projroot: str, args: list[str]) → None

Main script entry point.

batools.appmodule module

Generates parts of babase._app.py.

This includes things like subsystem attributes for all feature-sets that want them and default app-intent handling.

batools.appmodule.generate_app_module(projroot: str, feature_sets: dict[str, FeatureSet], existing_data: str) → str

Generate babase._app.py based on its existing version.

batools.apprun module

Utils for wrangling running the app as part of a build.

Manages constructing or downloading it as well as running it.

batools.apprun.acquire_binary(purpose: str, *, gui: bool = False) → str

Return path to a runnable binary, building/downloading as needed.

By default this provides a headless-server binary along with the full server asset bundle (Python scripts + fonts + data, but no audio/textures/meshes). That is enough for the binary to fully boot and is the right choice for the vast majority of tool/test workflows (dummy-module generation, import tests, transport tests, etc.).

Pass gui=True when the caller genuinely needs a GUI binary and the full (including media) asset bundle — e.g. a test that exercises rendering. This only works in environments that have the full asset source tree available; environments like ba-check that strip audio/textures/meshes will fail the asset build in this mode.

By default, downloaded prefab builds will be used here. This allows people without full compiler setups to still perform app runs for things like dummy-module generation. However, someone who is able to compile their own binaries might prefer to use their own binaries here so that changes to their local repo are properly reflected in app runs and whatnot. Set environment variable BA_APP_RUN_ENABLE_BUILDS=1 to enable that.

batools.apprun.python_command(cmd: str, purpose: str, include_project_tools: bool = False, env: Mapping[str, str] | None = None) → None

Run a cmd with a built bin and PYTHONPATH set to its scripts.

batools.apprun.test_runs_disabled() → bool

Are test runs disabled on the current platform?

batools.apprun.test_runs_disabled_reason() → str

Why are test runs disabled here?

batools.assetsmakefile module

Updates src/assets/Makefile based on source assets present.

batools.assetsmakefile.generate_assets_makefile(projroot: str, fname: str, existing_data: str, meta_manifests: dict[str, str], explicit_sources: set[str]) → dict[str, str]

Main script entry point.

batools.build module

General functionality related to running builds.

class batools.build.LazyBuildCategory(*values)

Bases: Enum

Types of sources.

ASSETS = 'assets_src'

CMAKE = 'cmake_src'

DUMMYMODULES = 'dummymodules_src'

META = 'meta_src'

RESOURCES = 'resources_src'

WIN = 'win_src'

class batools.build.PrefabPlatform(*values)

Bases: Enum

Distinct os/cpu-arch/etc. combos we support for prefab builds.

LINUX_ARM64 = 'linux_arm64'

LINUX_X86_64 = 'linux_x86_64'

MAC_ARM64 = 'mac_arm64'

MAC_X86_64 = 'mac_x86_64'

WINDOWS_X86 = 'windows_x86'

WINDOWS_X86_64 = 'windows_x86_64'

static get_current(wsl_targets_windows: bool | None = None) → PrefabPlatform

Get an identifier for the platform running this build.

Pass a bool wsl_targets_windows value to cause WSL to target either native Windows (True) or Linux (False). If this value is not passed, the env var BA_WSL_TARGETS_WINDOWS is used, and if that is not set, the default is False (Linux builds).

Throws a RuntimeError on unsupported platforms.

class batools.build.PrefabTarget(*values)

Bases: Enum

Types of prefab builds able to be run.

GUI_DEBUG = 'gui-debug'

GUI_RELEASE = 'gui-release'

SERVER_DEBUG = 'server-debug'

SERVER_RELEASE = 'server-release'

property buildmode: str

Return the build mode for this target.

property buildtype: str

Return the build type for this target.

batools.build.archive_old_builds(ssh_server: str, builds_dir: str, ssh_args: list[str]) → None

Stuff our old public builds into the ‘old’ dir.

(called after we push newer ones)

batools.build.checkenv() → None

Check for tools necessary to build and run the app.

batools.build.cmake_prep_dir(dirname: str, verbose: bool = False) → None

Create a dir, recreating it when cmake/python/etc. versions change.

Useful to prevent builds from breaking when cmake or other components are updated.

batools.build.filter_server_config_toml(projroot: str, infilepath: str) → str

Add commented-out config options to a server config.

batools.build.lazybuild(target: str, category: LazyBuildCategory, command: str) → None

Run some lazybuild presets.

batools.changelog module

Generates a pretty html changelog from our markdown.

batools.changelog.generate(projroot: str) → None

Main script entry point.

batools.changelog.get_version_changelog(version: str, projroot: str) → list[str]

Get changelog text for a given version from CHANGELOG.md.

batools.docker module

General functionality related to docker builds.

batools.docker.docker_build(platform: str | None = 'linux/amd64', headless_build: bool | str | None = None, build_type: str | None = None) → None

Build docker image. platform == ‘linux/arm64’ or platform == ‘linux/amd64’

batools.docker.docker_compose(platform: str | None = 'linux/amd64', headless_build: bool | str | None = None, build_type: str | None = None) → None

Compose docker image. platform == ‘linux/arm64’ or platform == ‘linux/amd64’

batools.docker.docker_remove_images() → None

Remove the bombsquad images loaded in docker.

batools.docker.docker_save_images() → None

Saves bombsquad images loaded into docker.

batools.docker.get_docker_image_name(headless_build: bool | str, build_type: str) → str

Get name of docker images in predefined format.

batools.docs module

Documentation generation functionality.

class batools.docs.AttributeInfo(name: str, attr_type: str | None = None, docs: str | None = None)

Bases: object

Info about an attribute of a class.

attr_type: str | None = None

docs: str | None = None

name: str

class batools.docs.SphinxSettings(project_name: str, project_author: str, copyright: str, version: str, buildnum: int, logo_small: str, logo_large: str)

Bases: object

Our settings for sphinx stuff.

buildnum: int

copyright: str

logo_large: str

logo_small: str

project_author: str

project_name: str

version: str

batools.docs.generate_sphinx_docs() → None

Run docs generation with sphinx.

batools.docs.get_sphinx_settings(projroot: str) → SphinxSettings

Settings for our Sphinx runs.

batools.docs.parse_docs_attrs(attrs: list[AttributeInfo], docs: str) → str

Given a docs str, parses attribute descriptions contained within.

batools.dummymodule module

Generates dummy .py modules based on binary modules.

This allows us to use code introspection tools such as pylint without spinning up the engine, and also allows external scripts to import game scripts successfully (albeit with limited functionality).

class batools.dummymodule.DummyModuleDef

Bases: object

Defines custom dummy module generation behavior.

batools.dummymodule.generate_dummy_modules(projroot: str) → None

Generate all dummy-modules.

batools.enumspython module

Generate a Python module containing Enum classes from C++ code.

Note that the general strategy moving forward is the opposite of this: to generate C++ code as needed from Python sources. That is generally a better direction to go since introspecting Python objects or source code ast is more foolproof than the text based parsing we are doing here.

batools.enumspython.camel_case_convert(name: str) → str

Convert camel-case text to upcase-with-underscores.

batools.enumspython.generate(projroot: str, infilename: str, outfilename: str) → None

Main script entry point.

batools.featureset module

Functionality for working with spinoff feature-sets.

Feature-sets are logical groupings of functionality that can be stripped out of or added in to spinoff dst projects. This allows for more high level dependency management and organization than would be possible through filtering alone.

class batools.featureset.FeatureSet(name: str)

Bases: object

Defines a feature-set.

allow_as_soft_requirement: bool

If True, feature-set ‘foo_bar’, will be allowed to be listed as a soft-requirement of other feature sets and its python-app-subsystem will be annotated as type ‘bafoobar.FooBarSubsystem | None’ instead of simply ‘bafoobar.FooBarSubsystem’. This forces type-checked code to account for the possibility that it will not be present. Note that this currently requires has_python_app_subsystem to be True (because if a soft-required feature-set is missing we must assume that is the case anyway because there’s no way to know).

apply_config(config_path: str) → None

Apply a user config to this feature-set.

cpp_namespace_check_disable_files: set[str]

Paths of files we should disable c++ namespace checks for. (generally external-originating code that doesn’t conform to our ballistica feature-set based namespace scheme)

dummy_module_def: DummyModuleDef

Override this to customize how your dummy module is generated.

classmethod get_active() → FeatureSet

Return the FeatureSet currently being defined.

For use by settings scripts.

classmethod get_all_for_project(project_root: str) → list[FeatureSet]

Return all feature-sets for the current project.

has_python_app_subsystem: bool

If True, for feature-set ‘foo_bar’, the build system will define a ‘ba*.app.foo_bar’ attr which points to a lazy loaded instance of type ‘bafoobar.FooBarSubsystem’.

has_python_binary_module: bool

Whether this featureset defines a native Python module within its C++ code. The build process will try to create dummy modules for all native modules, so to avoid errors you must tell it if you don’t have one.

property name: str

Our base name.

property name_camel: str

Camel case name (foo_bar -> FooBar). Used for classes, etc.

property name_compact: str

Compact name variation (foo_bar -> foobar). Used for Python bits.

property name_python_binary_module: str

Python binary module name (foo_bar -> _bafoobar).

property name_python_package: str

Python package name (foo_bar -> bafoobar).

property name_python_package_meta: str

The name of our meta Python package.

property name_python_package_tests: str

The name of our Python tests package.

property name_title: str

Title name variation (foo_bar -> Foo Bar). For pretty stuff.

property path_config_file: str

Project-relative path to the file defining this feature-set.

property path_native_source: str

Project-relative path for this feature-set’s native source.

Note that this does not mean that such source actually exists; this just shows where it would.

property path_python_package: str

Project-relative path for this feature-set’s Python package.

Note that this does not mean that the package actually exists; this just shows where it would.

property path_python_package_meta: str

Project-relative path for this feature-set’s Python meta package.

Note that this does not mean that the package actually exists; this just shows where it would.

property path_python_package_tests: str

Project-relative path for this feature-set’s Python tests package.

Note that this does not mean that the package actually exists; this just shows where it would.

property paths: list[str]

Return all file/dir paths associated with this feature-set.

Paths are project relative and may not actually exist; this just gives their theoretical locations.

python_app_subsystem_dependencies: set[str]

By default, Python app subsystems will be created in alphabetical order based on their feature set name. All subsystem callbacks adhere to this ordering. If there are any feature sets whose subsystems should always be created before this one’s, list them here. Note that this does not affect whether or not the feature set is included in the build; only the init order in cases when it is.

requirements: set[str]

Other feature-sets this one requires. Any spinoff project that includes our feature-set will implicitly include our requirements as well. We are allowed to access Python modules of our requirements directly, unlike soft-requirements where we must limit our access to their app subsystem.

classmethod resolve_requirements(featuresets: list[FeatureSet], reqs: set[str]) → set[str]

Resolve all required feature-sets based on a given set of them.

Throws descriptive CleanErrors if any are missing.

soft_requirements: set[str]

Feature-sets we can use but can survive without. All usage of soft requirements must be through app-subsystems (ba*.app.foo_bar for feature-set foo_bar, etc.). We must be prepared for these subsystems to be missing (set to None) and we must never import their modules directly (since they might not exist). Note that all featuresets we soft-require must have ‘allow_as_soft_requirement’ enabled. While it is possible to programmatically check for the presence of any feature-set, officially listing soft-requirements ensures that any expected app-subsystems are in place even for feature-sets not included in the spinoff project (though be aware their type annotations will be ‘Any | None’ in that case instead of the usual ‘FooBarSubsystem | None’ due to ‘FooBarSubsystem’ not actually existing).

static validate_name(name: str) → None

Validate a standard snake-case feature-set name.

Throws descriptive CleanErrors if provided name is invalid.

batools.meta module

Generate code from input files.

Used for various metaprogramming type applications.

batools.meta.gen_pyembed(projroot: str, in_path: str, out_path: str, *, encrypt: bool, ctx_var: str = 'internal_py_context') → None

Generate a pyembed .inc from a .py file using compiled bytecode.

The emitted .inc embeds two marshaled CodeType blobs — one compiled with optimize=0 (debug) and one with optimize=1 (release) — under #if BA_DEBUG_BUILD / #else, so each C++ build links only the blob matching its own -O level. Replaces both gen_encrypted_python_code and gen_flat_data_code.

The .inc expands to a PyembedExec call using ctx_var as the execution context (internal_py_context by default — most featuresets set up that local variable before the #include). Setting encrypt=True XOR-obfuscates the bytecode so casual inspection of the binary doesn’t trivially reveal the source.

batools.metabuild module

Functionality used in meta-builds (dynamically generated sources).

batools.metabuild.gen_binding_code(projroot: str, in_path: str, out_path: str) → None

Generate binding_foo.inc file.

batools.metamakefile module

Procedurally regenerates our code Makefile.

This Makefiles builds our generated code such as encrypted python strings, node types, etc).

class batools.metamakefile.MetaMakefileGenerator(projroot: str, existing_data: str)

Bases: object

Thing that does the thing.

run() → dict[str, str]

Do the thing.

class batools.metamakefile.Target(src: list[str], dst: str, cmd: str, mkdir: bool = False)

Bases: object

A target to be added to the Makefile.

cmd: str

dst: str

emit() → str

Gen a Makefile target.

mkdir: bool = False

src: list[str]

batools.metamakefile.generate_meta_makefile(projroot: str, existing_data: str) → dict[str, str]

Update the project meta Makefile.

Returns file names and contents.

batools.pcommandmain module

A collection of commands for use with this project.

All top level functions here can be run by passing them as the first argument on the command line. (or pass no arguments to get a list of them).

batools.pcommandmain.run_pcommand_main() → None

Do the thing.

batools.pcommands module

A nice collection of ready-to-use pcommands for this package.

batools.pcommands.android_sdk_utils() → None

Wrangle android sdk stuff.

batools.pcommands.androidaddr() → None

Return the source file location for an android program-counter.

command line args: archive_dir architecture addr

batools.pcommands.archive_old_builds() → None

Stuff our old public builds into the ‘old’ dir.

(called after we push newer ones)

batools.pcommands.capitalize() → None

Print args capitalized.

batools.pcommands.check_clean_safety() → None

Ensure all files are are added to git or in gitignore.

Use to avoid losing work if we accidentally do a clean without adding something.

batools.pcommands.checkenv() → None

Check for tools necessary to build and run the app.

batools.pcommands.cmake_prep_dir() → None

Create dir & recreate when cmake/python/etc. version changes.

Useful to prevent builds from breaking when cmake or other components are updated.

batools.pcommands.efro_gradle() → None

Calls ./gradlew with some extra magic.

batools.pcommands.efrocache_get() → None

Get a file from efrocache.

batools.pcommands.efrocache_update() → None

Build & push files to efrocache for public access.

batools.pcommands.ensure_prefab_platform() → None

Ensure we are running on a particular prefab platform.

Note that prefab platform may not exactly match hardware/os. For example, when running in Linux under a WSL environment, the prefab platform may be Windows; not Linux. Also, a 64-bit os may be targeting a 32-bit platform.

batools.pcommands.gen_binding_code() → None

Generate a binding_foo.inc file.

batools.pcommands.gen_docs_sphinx() → None

Generate sphinx documentation.

batools.pcommands.gen_dummy_modules() → None

Generate all dummy modules.

batools.pcommands.gen_python_enums_module() → None

Update our procedurally generated python enums.

batools.pcommands.genchangelog() → None

Gen a pretty html changelog.

batools.pcommands.get_changelog() → None

Print the changelog for a specified version

batools.pcommands.get_master_asset_src_dir() → None

Print master-asset-source dir for this repo.

batools.pcommands.lazy_increment_build() → None

Increment build number only if C++ sources have changed.

This is convenient to place in automatic commit/push scripts. It could make sense to auto update build number when scripts/assets change too, but a build number change requires rebuilding all binaries so I’ll leave that as an explicit choice to save work.

batools.pcommands.lazybuild() → None

Run a build command only if an input has changed.

batools.pcommands.logcat() → None

Get logcat command for filtering.

batools.pcommands.make_prefab() → None

Run prefab builds for the current platform.

batools.pcommands.prefab_binary_path() → None

Print the path to the current prefab binary.

batools.pcommands.prefab_platform() → None

Print the current prefab-platform value.

batools.pcommands.prefab_run_var() → None

Print the current platform prefab run target var.

batools.pcommands.printcolors() → None

Print all colors available in efro.terminals.TerminalColor.

batools.pcommands.prune_includes() → None

Check for unnecessary includes in C++ files.

Pass –commit to actually modify files.

batools.pcommands.push_ipa() → None

Construct and push ios IPA for testing.

batools.pcommands.python_android_build() → None

Build Android Python lib using new in-tree build script.

batools.pcommands.python_android_build_debug() → None

Build Android Python lib using new in-tree script (debug).

batools.pcommands.python_android_gather() → None

Gather Android Python build into project.

batools.pcommands.python_android_patch_old() → None

Patches Python to prep for building for Android (old pipeline).

batools.pcommands.python_android_patch_ssl_old() → None

Patches Python ssl to prep for building for Android (old pipeline).

batools.pcommands.python_apple_gather() → None

Gather Apple Python slices into XCFramework and copy to project.

batools.pcommands.python_build_android_old() → None

Build an embeddable Python lib for Android (old pipeline).

batools.pcommands.python_build_android_old_debug() → None

Build embeddable Android Python lib (old pipeline, debug ver).

batools.pcommands.python_build_apple() → None

Build one Apple Python slice using new in-tree script.

batools.pcommands.python_gather() → None

Gather build python components into the project.

This assumes all embeddable py builds have been run successfully.

batools.pcommands.python_gather_android_old() → None

python_gather but only android bits (old pipeline).

batools.pcommands.python_version_android() → None

Print Android embedded Python version.

batools.pcommands.python_version_android_base() → None

Print built Python base version.

batools.pcommands.python_winprune() → None

Prune unneeded files from windows python.

batools.pcommands.resize_image() → None

Resize an image and save it to a new location.

args: xres, yres, src, dst

batools.pcommands.stage_build() → None

Stage assets for a build.

batools.pcommands.static_dependencies_build_debug() → None

Build static dependencies for Android and Apple platforms.

batools.pcommands.update_project() → None

Update project files.

This command is in charge of generating Makefiles, IDE project files, etc. based on the current structure of the project. It can also perform sanity checks or cleanup tasks.

Updating should be explicitly run by the user through commands such as ‘make update’, ‘make check’ or ‘make preflight’. Other make targets should avoid running this command as it can modify the project structure arbitrarily which is not a good idea in the middle of a build.

If this command is invoked with a –check argument, it should not modify any files but instead fail if any modifications would have been made. (used in CI builds to make sure things are kosher).

batools.pcommands.upper() → None

Print args uppercased.

batools.pcommands.version() → None

Check app versions.

batools.pcommands.warm_start_asset_build() → None

Prep asset builds to run faster.

batools.pcommands2 module

A nice collection of ready-to-use pcommands for this package.

batools.pcommands2.android_archive_unstripped_libs() → None

Copy libs to a build archive.

batools.pcommands2.asset_package_assemble() → None

Assemble asset package data and its manifest.

batools.pcommands2.asset_package_resolve() → None

Resolve exact asset-package-version we’ll use (if any).

batools.pcommands2.clean_orphaned_assets() → None

Remove asset files that are no longer part of the build.

batools.pcommands2.cst_test() → None

Test filtering a Python file using LibCST.

batools.pcommands2.gen_monolithic_register_modules() → None

Generate .h file for registering py modules.

batools.pcommands2.gen_python_init_module() → None

Generate a basic __init__.py.

batools.pcommands2.get_modern_make() → None

Print name of a modern make command.

batools.pcommands2.py_examine() → None

Run a python examination at a given point in a given file.

batools.pcommands2.spinoff_check_submodule_parent() → None

Make sure this dst proj has a submodule parent.

batools.pcommands2.spinoff_test() → None

Test spinoff functionality.

batools.pcommands2.tests_warm_start() → None

Warm-start some stuff needed by tests.

This keeps logs clearer by showing any binary builds/downloads we need to do instead of having those silently happen as part of tests.

batools.pcommands2.update_cmake_prefab_lib() → None

Update prefab internal libs; run as part of a build.

batools.pcommands2.win_ci_binary_build() → None

Simple windows binary build for ci.

batools.pcommands2.win_ci_install_prereqs() → None

Install bits needed for basic win ci.

batools.pcommands2.wsl_build_check_win_drive() → None

Make sure we’re building on a windows drive.

batools.pcommands2.wsl_path_to_win() → None

Forward escape slashes in a provided win path arg.

batools.pcommands3 module

A nice collection of ready-to-use pcommands for this package.

batools.pcommands3.compose_docker_arm64_gui_debug() → None

Build the docker image with bombsquad cmake for arm64.

batools.pcommands3.compose_docker_arm64_gui_release() → None

Build the docker image with bombsquad cmake for arm64.

batools.pcommands3.compose_docker_arm64_server_debug() → None

Build the docker image with bombsquad cmake server for arm64.

batools.pcommands3.compose_docker_arm64_server_release() → None

Build the docker image with bombsquad cmake server for arm64.

batools.pcommands3.compose_docker_gui_debug() → None

Build the docker image with bombsquad debug cmake gui.

batools.pcommands3.compose_docker_gui_release() → None

Build the docker image with bombsquad cmake gui.

batools.pcommands3.compose_docker_server_debug() → None

Build the docker image with bombsquad debug cmake server.

batools.pcommands3.compose_docker_server_release() → None

Build the docker image with bombsquad cmake server.

batools.pcommands3.gen_pyembed() → None

Gen a pyembed .inc file using compiled bytecode.

Args: <in_path> <out_path> [encrypt={0,1}] [ctx=<var_name>]

Replaces gen_encrypted_python_code (encrypt=1) and gen_flat_data_code (encrypt=0) for pyembed modules.

batools.pcommands3.generate_flathub_manifest() → None

Generate a Flathub manifest for Ballistica and push to submodule. This function is intended to be run within a GitHub Actions workflow.

This function: 1. Copies files from config/flatpak/ to config/flatpak/flathub 2. Generates the manifest from template using latest GitHub release info

batools.pcommands3.generate_flatpak_release_manifest(version: str, asset_url: str, checksum: str, github_repo: str, release_date: str) → None

Generate a Flatpak release manifest for Ballistica.

This function:

1. Adds a new release entry to net.froemling.bombsquad.releases.xml

2. Updates the net.froemling.bombsquad.releases.xml file with the new release information

Parameters:

• version – Version string from GitHub release (e.g., ‘1.7.60’)

• asset_url – URL to the release asset

• checksum – SHA256 checksum of the release asset

• github_repo – GitHub repository in format ‘owner/repo’

• release_date – Release date in YYYY-MM-DD format

batools.pcommands3.remove_docker_images() → None

Remove the bombsquad images loaded in docker.

batools.pcommands3.save_docker_images() → None

Saves bombsquad images loaded into docker.

batools.pcommands3.test_game_run() → None

Run the game for testing purposes in a siloed instance dir.

Usage:

tools/pcommand test_game_run [--instance NAME] [--gui]
    [--port N] [--exec CODE] [--log LEVELS] [--timeout SECONDS]
    [--fleet FLEET] [--user-data]

Always runs in the foreground and blocks until the process exits or --timeout elapses. Callers that want to supervise multiple concurrent instances, keep a server alive across sessions, or manage output on their own should wrap their own invocation (e.g. a terminal multiplexer, nohup ... &, or the host automation’s background-task mechanism) rather than relying on backgrounding baked into this command.

Default is a headless server build; the headless binary starts faster, pops no window, and is the right fit for the programmatic testing this command is optimized for. Pass --gui when you actually want to interact with the UI.

Every run invokes the appropriate make target first so edits to .py / .cc sources land in the binary we launch. Lazybuild makes this a near-noop when nothing changed, so there’s no need to manually make cmake-build / make cmake-server-build before running this — the pcommand handles it.

Each instance lives under build/test_run/<name>/ with its own ba_root/ and config.toml (server only). Silos auto-create on first use. Run two instances concurrently by passing different --instance names; give server instances distinct --port values so they don’t fight over UDP 43210.

Flags:

• --instance NAME: Silo name under build/test_run/. Defaults to default.

• --gui: Launch the interactive GUI client build instead of the default headless server build.

• --port N: Only valid at silo creation time for headless instances. Writes the port into the silo’s new config.toml. Ignored (with a note) for pre-existing silos.

• --exec CODE: Python snippet passed via the binary’s --exec flag. Works for both GUI and headless builds; for headless, connect_to_party calls are allowed in developer builds only (shipped builds hard-block this path).

• --log LEVELS: Comma-separated logger=LEVEL pairs (e.g. ba.net=DEBUG). Passed via BA_LOG_LEVELS.

• --timeout SECONDS: Hard timeout before the process is killed (default 10).

• --fleet FLEET: Override master-server fleet (prod, test, dev).

• --user-data: GUI only. Drop --config-dir so the binary uses its default per-user data dir — you see the caller’s real signed-in state, saved options, unlocked characters, etc. instead of the silo’s fresh slate. Handy for reproducing user-reported issues that only manifest with real account state. Incompatible with headless (servers have no user data dir in the same sense).

batools.pruneincludes module

Utility to scan for unnecessary includes in c++ files.

class batools.pruneincludes.Pruner(commit: bool, paths: list[str])

Bases: object

Wrangles a prune operation.

run() → None

Do the thing.

batools.resourcesmakefile module

Generate our resources Makefile.

(builds things like icons, banners, images, etc.)

class batools.resourcesmakefile.ResourcesMakefileGenerator(projroot: str, existing_data: str, projname: str)

Bases: object

Does the thing.

run() → str

Does the thing.

class batools.resourcesmakefile.Target(src: list[str], dst: str, cmd: str, mkdir: bool = False)

Bases: object

A target to be added to the Makefile.

cmd: str

dst: str

emit() → str

Gen a Makefile target.

mkdir: bool = False

src: list[str]

batools.staging module

Stage files for builds.

class batools.staging.BuildStager(projroot: str)

Bases: object

Context for a run of the tool.

run(args: list[str]) → None

Do the thing.

batools.staging.stage_build(projroot: str, args: list[str] | None = None) → None

Stage assets for a build.

batools.toplevelmakefile module

Updates top level Makefile based on project elements present.

batools.toplevelmakefile.generate_top_level_makefile(projroot: str, existing_data: str) → str

Main script entry point.

batools.version module

Util to get ballisticakit versions.

class batools.version.Mode(*values)

Bases: Enum

Mode we can run this command in.

API = 'api'

BUILD = 'build'

INFO = 'info'

VERSION = 'version'

batools.version.get_current_api_version() → int

Pull current api version from the project.

batools.version.get_current_version(projroot: str = '') → tuple[str, int]

Pull current version and build_number from the project.

batools.version.run(projroot: str, args: list[str]) → None

Main entry point for this script.

batools.xcodeproject module

XCode related functionality.

class batools.xcodeproject.Updater(projroot: str, path: str, existing_data: str, sources: list[str], projname: str)

Bases: object

Does the thing.

add_paths(parent_pbxgrp: Any) → None

Do the thing.

hash_inputs(sources: list[str], include_us: bool, project_source: str) → str

Make a simple hash based on inputs to the project.

mod_app_delegate_mm() → None

Set per-file compiler flags.

project: Any

run(force: bool = False) → str

Do the thing.

batools.xcodeproject.update_xcode_project(projroot: str, path: str, existing_data: str, all_source_files: list[str], projname: str, force: bool = False) → str

Given an xcode project, update it for the current set of files.