Ballistica Logo

batools package

Subpackages

Submodules

batools.android module

Functionality related to android builds.

batools.android.androidaddr(archive_dir: str, arch: str, addr: str) None[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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

batools.apprun.test_runs_disabled() bool[source]

Are test runs disabled on the current platform?

batools.apprun.test_runs_disabled_reason() str[source]

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][source]

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[source]

Bases: object

Context for a run of the tool.

run() None[source]

Run the tool.

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

Run a single user command to completion.

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

Bases: object

Persistent state data stored to disk.

login_token: str | None = None
batools.bacloud.get_tz_offset_seconds() float[source]

Return the offset between utc and local time in seconds.

batools.bacloud.run_bacloud_main() None[source]

Do the thing.

batools.build module

General functionality related to running builds.

class batools.build.LazyBuildCategory(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

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(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

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[source]

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(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

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[source]

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

(called after we push newer ones)

batools.build.checkenv() None[source]

Check for tools necessary to build and run the app.

batools.build.cmake_prep_dir(dirname: str, verbose: bool = False) None[source]

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[source]

Add commented-out config options to a server config.

batools.build.lazybuild(target: str, category: LazyBuildCategory, command: str) None[source]

Run some lazybuild presets.

batools.changelog module

Generates a pretty html changelog from our markdown.

batools.changelog.generate(projroot: str) None[source]

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[source]

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

batools.docker.docker_remove_images() None[source]

Remove the bombsquad images loaded in docker.

batools.docker.docker_save_images() None[source]

Saves bombsquad images loaded into docker.

batools.docker.get_docker_image_name(headless_build: bool | str, build_type: str) str[source]

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)[source]

Bases: object

Info about an attribute of a class.

attr_type: str | None = None
docs: str | None = None
name: str
batools.docs.generate_pdoc(projroot: str) None[source]

Generate a set of pdoc documentation.

batools.docs.generate_sphinxdoc() None[source]

Generate a set of pdoc documentation.

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

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[source]

Bases: object

Defines custom dummy module generation behavior.

class batools.dummymodule.Generator(projroot: str, modulename: str, outfilename: str)[source]

Bases: object

Context for a module generation pass.

run() None[source]

Run the actual generation from within the app context.

batools.dummymodule.generate_dummy_modules(projroot: str) None[source]

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[source]

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

batools.enumspython.generate(projroot: str, infilename: str, outfilename: str) None[source]

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)[source]

Bases: object

Defines a feature-set.

apply_config(config_path: str) None[source]

Apply a user config to this feature-set.

classmethod get_active() FeatureSet[source]

Return the FeatureSet currently being defined.

For use by settings scripts.

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

Return all feature-sets for the current project.

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.

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

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

Throws descriptive CleanErrors if any are missing.

static validate_name(name: str) None[source]

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[source]

Generate binding_foo.inc file.

batools.metabuild.gen_flat_data_code(projroot: str, in_path: str, out_path: str, var_name: str) None[source]

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)[source]

Bases: object

Thing that does the thing.

run() dict[str, str][source]

Do the thing.

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

Bases: object

A target to be added to the Makefile.

cmd: str
dst: str
emit() str[source]

Gen a Makefile target.

mkdir: bool = False
src: list[str]
batools.metamakefile.generate_meta_makefile(projroot: str, existing_data: str) dict[str, str][source]

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[source]

Do the thing.

batools.pcommands module

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

batools.pcommands.android_sdk_utils() None[source]

Wrangle android sdk stuff.

batools.pcommands.androidaddr() None[source]

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

command line args: archive_dir architecture addr

batools.pcommands.archive_old_builds() None[source]

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

(called after we push newer ones)

batools.pcommands.build_docker_arm64_gui_release() None[source]

Build the docker image with bombsquad cmake for arm64.

batools.pcommands.build_docker_arm64_server_release() None[source]

Build the docker image with bombsquad cmake server for arm64.

batools.pcommands.build_docker_gui_debug() None[source]

Build the docker image with bombsquad debug cmake gui.

batools.pcommands.build_docker_gui_release() None[source]

Build the docker image with bombsquad cmake gui.

batools.pcommands.build_docker_server_debug() None[source]

Build the docker image with bombsquad debug cmake server.

batools.pcommands.build_docker_server_release() None[source]

Build the docker image with bombsquad cmake server.

batools.pcommands.capitalize() None[source]

Print args capitalized.

batools.pcommands.check_clean_safety() None[source]

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[source]

Check for tools necessary to build and run the app.

batools.pcommands.cmake_prep_dir() None[source]

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[source]

Calls ./gradlew with some extra magic.

batools.pcommands.efrocache_get() None[source]

Get a file from efrocache.

batools.pcommands.efrocache_update() None[source]

Build & push files to efrocache for public access.

batools.pcommands.ensure_prefab_platform() None[source]

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[source]

Generate a binding_foo.inc file.

batools.pcommands.gen_docs_pdoc() None[source]

Generate pdoc documentation.

batools.pcommands.gen_docs_sphinx() None[source]

Generate sphinx documentation.

batools.pcommands.gen_dummy_modules() None[source]

Generate all dummy modules.

batools.pcommands.gen_flat_data_code() None[source]

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

batools.pcommands.gen_python_enums_module() None[source]

Update our procedurally generated python enums.

batools.pcommands.genchangelog() None[source]

Gen a pretty html changelog.

batools.pcommands.get_master_asset_src_dir() None[source]

Print master-asset-source dir for this repo.

batools.pcommands.lazy_increment_build() None[source]

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[source]

Run a build command only if an input has changed.

batools.pcommands.logcat() None[source]

Get logcat command for filtering.

batools.pcommands.make_prefab() None[source]

Run prefab builds for the current platform.

batools.pcommands.prefab_binary_path() None[source]

Print the path to the current prefab binary.

batools.pcommands.prefab_platform() None[source]

Print the current prefab-platform value.

batools.pcommands.prefab_run_var() None[source]

Print the current platform prefab run target var.

batools.pcommands.printcolors() None[source]

Print all colors available in efro.terminals.TerminalColor.

batools.pcommands.prune_includes() None[source]

Check for unnecessary includes in C++ files.

Pass –commit to actually modify files.

batools.pcommands.push_ipa() None[source]

Construct and push ios IPA for testing.

batools.pcommands.python_android_patch() None[source]

Patches Python to prep for building for Android.

batools.pcommands.python_android_patch_ssl() None[source]

Patches Python ssl to prep for building for Android.

batools.pcommands.python_apple_patch() None[source]

Patches Python to prep for building for Apple platforms.

batools.pcommands.python_build_android() None[source]

Build an embeddable Python lib for Android.

batools.pcommands.python_build_android_debug() None[source]

Build embeddable Android Python lib (debug ver).

batools.pcommands.python_build_apple() None[source]

Build an embeddable python for mac/ios/tvos.

batools.pcommands.python_build_apple_debug() None[source]

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

batools.pcommands.python_gather() None[source]

Gather build python components into the project.

This assumes all embeddable py builds have been run successfully.

batools.pcommands.python_gather_android() None[source]

python_gather but only android bits.

batools.pcommands.python_gather_apple() None[source]

python_gather but only apple bits.

batools.pcommands.python_version_android() None[source]

Print Android embedded Python version.

batools.pcommands.python_version_android_base() None[source]

Print built Python base version.

batools.pcommands.python_version_apple() None[source]

Print Apple embedded Python version.

batools.pcommands.python_winprune() None[source]

Prune unneeded files from windows python.

batools.pcommands.remove_docker_images() None[source]

Remove the bombsquad images loaded in docker.

batools.pcommands.resize_image() None[source]

Resize an image and save it to a new location.

args: xres, yres, src, dst

batools.pcommands.save_docker_images() None[source]

Saves bombsquad images loaded into docker.

batools.pcommands.stage_build() None[source]

Stage assets for a build.

batools.pcommands.update_project() None[source]

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[source]

Print args uppercased.

batools.pcommands.version() None[source]

Check app versions.

batools.pcommands.warm_start_asset_build() None[source]

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[source]

Copy libs to a build archive.

batools.pcommands2.asset_package_assemble() None[source]

Assemble asset package data and its manifest.

batools.pcommands2.asset_package_resolve() None[source]

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

batools.pcommands2.clean_orphaned_assets() None[source]

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

batools.pcommands2.gen_monolithic_register_modules() None[source]

Generate .h file for registering py modules.

batools.pcommands2.gen_python_init_module() None[source]

Generate a basic __init__.py.

batools.pcommands2.get_modern_make() None[source]

Print name of a modern make command.

batools.pcommands2.py_examine() None[source]

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

batools.pcommands2.spinoff_check_submodule_parent() None[source]

Make sure this dst proj has a submodule parent.

batools.pcommands2.spinoff_test() None[source]

Test spinoff functionality.

batools.pcommands2.tests_warm_start() None[source]

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[source]

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

batools.pcommands2.win_ci_binary_build() None[source]

Simple windows binary build for ci.

batools.pcommands2.win_ci_install_prereqs() None[source]

Install bits needed for basic win ci.

batools.pcommands2.wsl_build_check_win_drive() None[source]

Make sure we’re building on a windows drive.

batools.pcommands2.wsl_path_to_win() None[source]

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])[source]

Bases: object

Wrangles a prune operation.

run() None[source]

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)[source]

Bases: object

Does the thing.

run() str[source]

Does the thing.

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

Bases: object

A target to be added to the Makefile.

cmd: str
dst: str
emit() str[source]

Gen a Makefile target.

mkdir: bool = False
src: list[str]

batools.staging module

Stage files for builds.

class batools.staging.AssetStager(projroot: str)[source]

Bases: object

Context for a run of the tool.

run(args: list[str]) None[source]

Do the thing.

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

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[source]

Main script entry point.

batools.version module

Util to get ballisticakit versions.

class batools.version.Mode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Mode we can run this command in.

API = 'api'
BUILD = 'build'
INFO = 'info'
VERSION = 'version'
batools.version.get_current_api_version() int[source]

Pull current api version from the project.

batools.version.get_current_version() tuple[str, int][source]

Pull current version and build_number from the project.

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

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)[source]

Bases: object

Does the thing.

add_paths(parent_pbxgrp: Any) None[source]

Do the thing.

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

Make a simple hash based on inputs to the project.

mod_app_delegate_mm() None[source]

Set per-file compiler flags.

project: Any
run(force: bool = False) str[source]

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[source]

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

Module contents

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.