[ox] Add Project Structure section to docs
All checks were successful
Build / build (push) Successful in 2m36s

This commit is contained in:
Gary Talent 2024-10-04 01:15:17 -05:00
parent ea9f50de8d
commit 3271a37115

36
deps/ox/ox-docs.md vendored
View File

@ -1,17 +1,33 @@
# Ox Docs # Ox Docs
## Project Structure
All components have a platform indicator next to them:
(OB) - OS, Bare Metal
(-B) - Bare Metal
(O-) - OS
* Ox - Library of things useful for portable bare metal and userland code. Not really that external...
* clargs - Command Line Args processing (OB)
* claw - Reads and writes Metal or Organic Claw with header to indicate which
* event - Qt-like signal system (OB)
* fs - file system (OB)
* logconn - connects logging to Bullock (O-)
* mc - Metal Claw serialization, builds on model (OB)
* oc - Organic Claw serialization (wrapper around JsonCpp), builds on model (O-)
* model - Data structure modelling (OB)
* preloader - library for handling preloading of data (OB)
* std - Standard-ish Library with a lot missing and some things added (OB)
## Systems ## Systems
### Error Handling ### Error Handling
The GBA build has exceptions disabled. Ox provides ```ox::Error``` to report errors.
Instead of throwing exceptions, all engine code must return ```ox::Error```s. ```ox::Error``` is a struct that has overloaded operators to behave like an
For the sake of consistency, try to stick to ```ox::Error``` in non-engine code integer error code, plus some extra fields to enhance debuggability.
as well, but non-engine code is free to use exceptions when they make sense.
Nostalgia and Ox both use ```ox::Error``` to report errors. ```ox::Error``` is
a struct that has overloaded operators to behave like an integer error code,
plus some extra fields to enhance debuggability.
If instantiated through the ```OxError(x)``` macro, it will also include the If instantiated through the ```OxError(x)``` macro, it will also include the
file and line of the error. file and line of the error.
The ```OxError(x)``` macro should only be used for the initial instantiation of The ```OxError(x)``` macro should only be used for the initial instantiation of
@ -87,9 +103,6 @@ back up the call stack, ```oxReturnError```, ```oxThrowError```, and
```oxReturnError``` is by far the more helpful of the two. ```oxReturnError``` is by far the more helpful of the two.
```oxReturnError``` will return an ```ox::Error``` if it is not 0 and ```oxReturnError``` will return an ```ox::Error``` if it is not 0 and
```oxThrowError``` will throw an ```ox::Error``` if it is not 0. ```oxThrowError``` will throw an ```ox::Error``` if it is not 0.
Because exceptions are disabled for GBA builds and thus cannot be used in the
engine, ```oxThrowError``` is only really useful at the boundary between
engine libraries and Nostalgia Studio.
Since ```ox::Error``` is always nodiscard, you must do something with them. Since ```ox::Error``` is always nodiscard, you must do something with them.
In rare cases, you may not have anything you can do with them or you may know In rare cases, you may not have anything you can do with them or you may know
@ -370,9 +383,6 @@ That reads:
* Type ID is net.drinkingtea.nostalgia.core.NostalgiaPalette * Type ID is net.drinkingtea.nostalgia.core.NostalgiaPalette
* Type version is 1 * Type version is 1
Except when the data is exported for loading on the GBA, Claw is always used as
a wrapper around the bare formats.
#### Metal Claw Example #### Metal Claw Example
##### Read ##### Read