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(assets: bool, purpose: str) → str

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

If ‘assets’ is False, only the binary itself will be fetched or assembled; no scripts or assets. This generally saves some time, but must only be used for very simple ‘-c’ command cases where no assets will be needed.

Be aware that it is up to the particular environment whether a gui or headless binary will be provided. Commands should be designed to work with either.

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.

When local builds are enabled, we use the same gui build targets as the ‘make cmake-build’ command. This works well if you are iterating using that build target anyway, minimizing redundant rebuilds. You may, however, prefer to instead assemble headless builds for various reasons including faster build times and fewer dependencies (equivalent to ‘make cmake-server-build’). To do so, set environment variable BA_APP_RUN_BUILD_HEADLESS=1.

batools.apprun.acquire_binary_for_python_command(purpose: str) → str

Run acquire_binary as used for python_command call.

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.bacloud module

A tool for interacting with ballistica’s cloud services. This facilitates workflows such as creating asset-packages, etc.

class batools.bacloud.App

Bases: object

Context for a run of the tool.

run() → None

Run the tool.

run_interactive_command(cwd: str, args: list[str]) → None

Run a single user command to completion.

class batools.bacloud.StateData(login_token: str | None = None)

Bases: object

Persistent state data stored to disk.

login_token: str | None = None

batools.bacloud.get_tz_offset_seconds() → float

Return the offset between utc and local time in seconds.

batools.bacloud.run_bacloud_main() → None

Do the thing.

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'

classmethod 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.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 ‘babase.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 this feature-set is included in will implicitly include these as well.

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 this one can use but can survive without. Note that each of these requirements 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 python-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.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.metabuild.gen_flat_data_code(projroot: str, in_path: str, out_path: str, var_name: str) → None

Generate a C++ include file from a Python 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.compose_docker_arm64_gui_debug() → None

Build the docker image with bombsquad cmake for arm64.

batools.pcommands.compose_docker_arm64_gui_release() → None

Build the docker image with bombsquad cmake for arm64.

batools.pcommands.compose_docker_arm64_server_debug() → None

Build the docker image with bombsquad cmake server for arm64.

batools.pcommands.compose_docker_arm64_server_release() → None

Build the docker image with bombsquad cmake server for arm64.

batools.pcommands.compose_docker_gui_debug() → None

Build the docker image with bombsquad debug cmake gui.

batools.pcommands.compose_docker_gui_release() → None

Build the docker image with bombsquad cmake gui.

batools.pcommands.compose_docker_server_debug() → None

Build the docker image with bombsquad debug cmake server.

batools.pcommands.compose_docker_server_release() → None

Build the docker image with bombsquad cmake server.

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_flat_data_code() → None

Generate a C++ include file from a Python file.

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_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_patch() → None

Patches Python to prep for building for Android.

batools.pcommands.python_android_patch_ssl() → None

Patches Python ssl to prep for building for Android.

batools.pcommands.python_apple_patch() → None

Patches Python to prep for building for Apple platforms.

batools.pcommands.python_build_android() → None

Build an embeddable Python lib for Android.

batools.pcommands.python_build_android_debug() → None

Build embeddable Android Python lib (debug ver).

batools.pcommands.python_build_apple() → None

Build an embeddable python for mac/ios/tvos.

batools.pcommands.python_build_apple_debug() → None

Build embeddable python for mac/ios/tvos (dbg ver).

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() → None

python_gather but only android bits.

batools.pcommands.python_gather_apple() → None

python_gather but only apple bits.

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_version_apple() → None

Print Apple embedded Python version.

batools.pcommands.python_winprune() → None

Prune unneeded files from windows python.

batools.pcommands.remove_docker_images() → None

Remove the bombsquad images loaded in docker.

batools.pcommands.resize_image() → None

Resize an image and save it to a new location.

args: xres, yres, src, dst

batools.pcommands.save_docker_images() → None

Saves bombsquad images loaded into docker.

batools.pcommands.stage_build() → None

Stage assets for a build.

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.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.AssetStager(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.