From 1a448f56642d9958e10623e24da38a7697ececfa Mon Sep 17 00:00:00 2001 From: Eric Date: Wed, 17 May 2023 15:15:29 -0700 Subject: [PATCH] more docs tweaks --- .efrocachemap | 32 ++++++++++++++-------------- config/README.md | 9 +++++--- config/featuresets/README.md | 29 ++++++++++++++++++++++++- config/toolconfigsrc/README.md | 4 ++-- src/ballistica/README.md | 4 ++-- src/ballistica/template_fs/README.md | 3 ++- 6 files changed, 56 insertions(+), 25 deletions(-) diff --git a/.efrocachemap b/.efrocachemap index 21e52b19..75fe2c1a 100644 --- a/.efrocachemap +++ b/.efrocachemap @@ -4080,18 +4080,18 @@ "build/prefab/full/linux_x86_64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/21/b5/1a64f257cbeb89be58f87063c5a0", "build/prefab/full/linux_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/4d/2b/335fd97e4f33311f0ccf78e512c5", "build/prefab/full/linux_x86_64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/db/bc/8d436e18d99343cb36efb5028c86", - "build/prefab/full/mac_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/2c/85/2b5049e1c9825af8ae704a1a1bf2", + "build/prefab/full/mac_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/8b/01/75017f0be4b483eddf7ee8b58000", "build/prefab/full/mac_arm64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/47/85/37895e099240ce03dd575e842dc0", - "build/prefab/full/mac_arm64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/eb/1f/dd7c3a127c4ebe6928b3287e51b1", + "build/prefab/full/mac_arm64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/d7/1d/0c409b21587bac13785fe26b570a", "build/prefab/full/mac_arm64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/c8/9c/aaa3b08e408ff2a4f06ddde322cc", - "build/prefab/full/mac_x86_64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/08/5e/8a1dfb1d59ceeef8a376198f3a5b", + "build/prefab/full/mac_x86_64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/07/02/dbfbbdf05c608b0f7c05ce753f28", "build/prefab/full/mac_x86_64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/7b/84/e568ff95d86920d1a4ea066bbd28", - "build/prefab/full/mac_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/d6/e2/d27b753748d19510778ffcbf42c3", + "build/prefab/full/mac_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/5e/6c/c249fdfca8f89c5d5b89b3ca65e5", "build/prefab/full/mac_x86_64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/c5/43/b510d0cf0402ba01459703a148bc", - "build/prefab/full/windows_x86_gui/debug/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/f5/cd/c4b4642ecaf0f39ec9807dd926cf", - "build/prefab/full/windows_x86_gui/release/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/0d/33/5ae959faa370108d206f798045a0", - "build/prefab/full/windows_x86_server/debug/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/fb/8c/9e83c45b1b16a11b8a7e16f24abe", - "build/prefab/full/windows_x86_server/release/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/9c/ae/569686031f7fd7ee964e03998fcb", + "build/prefab/full/windows_x86_gui/debug/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/37/f5/7a2d705017794e7471debc615ef3", + "build/prefab/full/windows_x86_gui/release/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/85/7b/aacfb8ef9efa523013db6bf8d7db", + "build/prefab/full/windows_x86_server/debug/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/1c/ad/e71e99b64d5b84963b2dcbe66f16", + "build/prefab/full/windows_x86_server/release/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/b2/67/76541c062eb8f5dc5f5cb76d30cd", "build/prefab/lib/linux_arm64_gui/debug/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/96/3e/36fb95f8f1609a5a0c51cb2c008a", "build/prefab/lib/linux_arm64_gui/release/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/66/42/15dadfe1bce99682ea7d36b4e590", "build/prefab/lib/linux_arm64_server/debug/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/71/97/7369170323e18f341fc5dcac4370", @@ -4108,14 +4108,14 @@ "build/prefab/lib/mac_x86_64_gui/release/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/72/7d/49eb3c6d3f542379645b31c76321", "build/prefab/lib/mac_x86_64_server/debug/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/50/07/a9bbc325406fcc829367d29c2cfe", "build/prefab/lib/mac_x86_64_server/release/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/4e/80/4fb673550bb4185ebd902cf120be", - "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/aa/e0/fbe937e1e57bfbe4bd6fb6a63d9c", - "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/78/da/38826d9301481ab4896ff8807a30", - "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/92/87/58b31aac68996b683e2edcae8b54", - "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/4c/32/da1f8d35baad59dba3157259d741", - "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/26/5a/b2f27686f9a19430f08cc632d60b", - "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/31/f0/e4ca438126c315d344081365f772", - "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/9a/e5/a7e3d9f4b7f2313988cf64457884", - "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/ec/2d/4b4293589b6a113803b1306356c2", + "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/e5/7e/2a98510fdf6ba026811a3f770f14", + "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/f7/b9/538a4913b8e15e0cd885cc467f71", + "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/f5/99/71229dccb7f99b48cf3f5cc5bbdd", + "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/da/f9/49149d40797b11d16381091a396d", + "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/ba/e8/ca129a62d4a207e548e07767982d", + "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/1d/8e/c1bd73f56c2ea50a94cff51d3c90", + "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/42/0a/41d0578a63da2adf25d4cdd14e40", + "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/a2/39/a173b0fd483a128a0d0862e72b01", "src/assets/ba_data/python/babase/_mgen/__init__.py": "https://files.ballistica.net/cache/ba1/52/c6/c11130af7b10d6c0321add5518fa", "src/assets/ba_data/python/babase/_mgen/enums.py": "https://files.ballistica.net/cache/ba1/38/c3/1dedd5e74f2508efc5974c8815a1", "src/ballistica/base/mgen/pyembed/binding_base.inc": "https://files.ballistica.net/cache/ba1/b4/3d/e352190a0e5673d101c0f3ee3ad2", diff --git a/config/README.md b/config/README.md index bb680f27..589e8246 100644 --- a/config/README.md +++ b/config/README.md @@ -3,6 +3,9 @@ This directory contains overall configuration files for the project. Noteworthy files: -- **projectconfig.json**: Top level settings for the project. Various tools look for values here. -- **spinoffconfig.json**: Configures how this project can be spun off into other projects and/or what it inherits from a parent project. -- **localconfig.json**: Optional file influencing behavior only at this location. This file should not be stored in git/etc. +- [projectconfig.json](projectconfig.json): Top level settings for the project. + Various tools look for values here. +- [spinoffconfig.json](spinoffconfig.json): Configures how this project can be + spun off into other projects and/or what it inherits from a parent project. +- **localconfig.json**: Optional file influencing behavior only at this + location. This file should not be stored in git/etc. diff --git a/config/featuresets/README.md b/config/featuresets/README.md index 9158857d..c1412cd0 100644 --- a/config/featuresets/README.md +++ b/config/featuresets/README.md @@ -2,4 +2,31 @@ This directory contains a config file for each feature-set in the project. Feature sets are high level subsets of an engine or app which can be easily -added, removed, duplicated, etc. +added, removed, duplicated, etc. + +### Naming Conventions + +Feature sets should have lowercase alphanumeric names with underscores between +words. An example would be `foo_bar`. Variations of this name may be used +throughout code; for example `FooBar` may be used in class names where +camel-case is standard or `foobar` may be used in Python module names where +brevity is desirable. + +### Locations + +The build system looks for feature-set files in specific predefined locations +with specific naming conventions: + +- **Feature Set Definition**: To define feature set `foo_bar`, a file must exist + in this directory called `featureset_foo_bar.py`. +- **Python Package**: If feature set `foo_bar` provides a Python package, it + should be a directory named `bafoobar` ('ba' prefix, spaces removed) + that lives under [Python source files](../../src/assets/ba_data/python). +- **Native Code**: If feature set `foo_bar` provides a native component (C++ + code or otherwise) it should live in a directory named `foo_bar` (unmodified + feature set name) under [native source files](../../src/ballistica). +- **Meta Package**: If feature set `foo_bar` provides a meta package (that is, + code or data used to generate other source code), it should be a directory + named `bafoobarmeta` ('ba' prefix, 'meta' suffix, spaces removed) + that lives under [meta source files](../../src/meta). + diff --git a/config/toolconfigsrc/README.md b/config/toolconfigsrc/README.md index 96e3757b..38286aac 100644 --- a/config/toolconfigsrc/README.md +++ b/config/toolconfigsrc/README.md @@ -3,6 +3,6 @@ These configs can be installed via 'make prereqs' in the project root. (this should automatically happen as part of other targets such as 'make check') -Some of these are filtered to include an abs path to the project root -or other varying data, which is why we use this mechanism instead of simply +Some of these are filtered to include an abs path to the project root or other +dynamically generated data, which is why we use this mechanism instead of simply including them as flat files. diff --git a/src/ballistica/README.md b/src/ballistica/README.md index b7328b18..7713634d 100644 --- a/src/ballistica/README.md +++ b/src/ballistica/README.md @@ -78,9 +78,9 @@ global. But because `scene_v1` has its own namespace, this global will actually be `ballistica::scene_v1::g_base` which will be distinct from any `g_base` global held by any other feature-set. So as long as each feature-set correctly lives in its own namespace and uses only its own set of globals, things should -behave pretty much as they do on the Python layer; feature-sets simply import +work pretty much as they do on the Python layer; feature-sets simply import what they use when they themselves are imported and all code throughout the -feature-set can safely use those globals from that point on. +feature-set assumes it is safe to use those imported things. Check out the [Template Feature Set](template_fs) for examples of wrangling globals and namespaces to implement a feature-set-front-end in C++. diff --git a/src/ballistica/template_fs/README.md b/src/ballistica/template_fs/README.md index 36701061..161fff86 100644 --- a/src/ballistica/template_fs/README.md +++ b/src/ballistica/template_fs/README.md @@ -1,3 +1,4 @@ # Template Feature Set -This is an empty feature-set for use a starting point when implementing new ones. +This is an empty feature-set for use as reference or as a starting point when +implementing new ones.