https://github.com/indigoparadox/maug
Utilities for building retro projects relatively quickly
https://github.com/indigoparadox/maug
aleggro c89 debug debugging dos logging maug nintendo-ds opengl1 retro sdl win16
Last synced: 3 months ago
JSON representation
Utilities for building retro projects relatively quickly
- Host: GitHub
- URL: https://github.com/indigoparadox/maug
- Owner: indigoparadox
- License: lgpl-3.0
- Created: 2022-06-12T21:31:29.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2025-07-27T03:16:18.000Z (11 months ago)
- Last Synced: 2025-07-27T05:50:34.627Z (11 months ago)
- Topics: aleggro, c89, debug, debugging, dos, logging, maug, nintendo-ds, opengl1, retro, sdl, win16
- Language: C
- Homepage:
- Size: 4.01 MB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
README
#  maug
Augmented minimal standard library for C89 and legacy compilers.
**The API is currently in flux and is not yet completely final!**
Current maug-based projects may be found under [The maug topic on GitHub](https://github.com/topics/maug)!
## Breaking Changes
- 2026/03/20 - `maug_malloc` no longer exists and has been replaced with `maug_malloc_test`, which accepts the handle as its first arg, and shunts to the `cleanup` label with `retval` `MERROR_ALLOC` if the allocator returns `NULL`.
## Requirements
### All Platforms
- xxd
- GNU make
- ImageMagick convert
**TODO**: List platform-specific requirements.
**TODO**: Platform-specific compiler setup.
### Nintendo DS
The Nintendo DS port has been modernized to run on top of the Calico RTOS, so it now requires a devkitpro toolchain post-2022.
Theoretically, `-DRETROFLAT_API_CALICO` may be removed from `make/Makends.inc` to work with older toolchains. These can be found at https://wii.leseratte10.de/devkitPro/ and some packages that work at minimum are:
- devkitARM r56
- libnds 1.8.1-2
- default\_arm7 0.7.4-4
- other-stuff/grit 0.9.2
- other-stuff/ndstool 2.1.2
And 1.2.0 of the linker scripts at https://github.com/devkitPro/devkitarm-crtls/releases/tag/v1.2.0 (these can just be installed with `make`/`make install`.
## Design Constraints
Maug has the following design goals and constraints:
- Must work in C89 compilers. C99-like features like stdint or snprintf are
available by internal implementation.
- Memory allocation uses a flat model (calloc/free), with no handle management.
- Standard library calls are allowed, so long as they are universally
available even in very old C89 compilers.
In addition, where modules may full functions or pull constants from is limited by the layer architecture described in **Modules**, below.
## Roadmap
- Clearly enumerate which headers rely on which to create modular hierarchy.
- Solidify API.
- Setup Makefile to compile .solib/.dll/.ovl dynamic libs.
- Square-tile-based isometric engine.
- Reimplement retrotile with vectors for tiledefs.
- Replace iffy semi-vectors in mhtml/mcss with vectors.
- Replace obj vertice arrays with vectors in retroglu.
- Implement lambdas in mlisp with separators for pruning sequentally added env args.
- Implement resolution detection in Windows CE.
- Implement timing/blit mode setting options on all platforms.
- Move platform-specific struct into platform-specific translation unit.
- Add switchable support for inline functions.
- Turn platform-specific macros into (inline) functions.
- Make API modules dynamically loadable where applicable.
## Modules
In principle, the library is split into the following parts:
| Layer | Location |
|---------------|------------------|
| retro* | `src/retro*.h` |
| retroflat API | `api/retapi*.h` |
| maug | `src/m*.h` |
Each layer relies on functionality provided by the layers below it. This means that a function in `retroglu.h` or `retroflt.h` in the `src/` directory may call a function provided by `api/dosbios/retapif.h` or `src/maug.h`, but a function in `src/maug.h` may not call a function from `src/retroflt.h`.
The API layer acts as a set of modules that can be swapped, depending on the platform. They should all provide the same functionality, but using the specific mechanisms of the platform they're designed for. The API layer can be further divided as follows:
| API | Description |
|---------|---------------------------------|
| file | Filesystem access. |
| font | Drawing text on-screen. |
| input | Input polling/translation. |
| log | Debug/error logging. |
| mem | Dynamic memory allocation. |
| retro2d | Drawing primatives on-screen. |
| retro3d | Drawing 3D primatives. |
| sound | Digital sound and sequencing. |
The **retro2d** API is special, as it also contains the definition of how the platform handles its main loop (e.g. message polling on Windows or the loop callback for WASM). Most platforms can simply use `retroflat_loop_generic()`, which is a generic loop that executes the program's loop callbacks repeatedly until `retroflat_quit()` is called.
### Makefiles
Application Makefiles should `include maug/Makefile.inc` to enable the build macros. From there, a target must be defined with `$(eval $(call ,))` for each platform to build for.
Many platforms support graphical application icons. These platforms will use \.bmp if present, and the maug default icon if not.
Some platforms support OpenGL (1.1), noted below. GLUT can **only** be used with OpenGL. Platforms that do not mention OpenGL at all in the notes, do not support OpenGL. OpenGL support on the Nintendo DS is finnicky.
The following targets are currently available (possibly among others):
|Target | OS | Cplr | API | Notes |
|--------------------------|--------------|--------|-----------|--------------|
|TGTDOSALE | DOS | Watcom | Allegro | |
|TGTDOSGAL | DOS | DJGPP | Allegro | |
|TGTDOSBIOS | DOS | Watcom | BIOS | |
|TGTNDSLIBN | Nintendo DS | GCC | libn | OpenGL (Opt) |
|TGTOS2GL | OS/2 | Watcom | GLUT | OpenGL ONLY |
|TGTOS2SDL | OS/2 | Watcom | SDL | |
|TGT\_WATCOM\_WIN32\_PLUG | Windows NT | Watcom | Win32 | Plugins only |
|TGT\_GCC\_UNIX\_PLUG | UNIX | GCC | SDL | Plugins only |
|TGTUNIXSDL | UNIX | GCC | SDL | |
|TGTUNIXALE | UNIX | GCC | Allegro | |
|TGTUNIXGLUT | UNIX | GCC | GLUT | OpenGL ONLY |
|TGTWASMSDL | Web | emcc | SDL | OpenGL (Opt) |
|TGTWINNT | Windows NT | Watcom | Win32 | OpenGL (Opt) |
|TGTWINGL | Windows NT | Watcom | GLUT | OpenGL ONLY |
|TGTWINSDL | Windows NT | Watcom | SDL | OpenGL (Opt) |
|TGTWIN16 | Windows 3.x | Watcom | Win16 | |
|TGTWIN386 | Windows 3.x | Watcom | Win16 | 32-bit clean |
|TGTWINNTGCC | Windows NT | GCC | Win32 | OpenGL (Opt) |
|TGTWIN64GCC | Windows NT | GCC | Win32 | OpenGL (Opt) |
|TGT\_CECL\_WINCE\_SH3 | Windows CE | VC | WinCE | |
|TGT\_CECL\_WINCE\_MIPS | Windows CE | VC | WinCE | |
|TGT\_CECL\_WINCE\_X86 | Windows CE | VC | WinCE | |
|TGTMAC68K | MacOS 6 | Retro68| Toolbox | Monochrome |
|TGTPSXPSN | PlayStation | psn00b | psn00b | |
### retroflt
`#include `
RetroFlat is a rough, quick-and-dirty compatibility layer for making graphical programs that work on Win16 (32-bit via OpenWatcom's Win386), MS-DOS (32-bit via DOS/32a or DOS4GW via Allegro), and possibly other platforms in the future.
This documentation is also available at [https://indigoparadox.codeberg.page/maug/group__maug__retroflt.html](https://indigoparadox.github.io/maug/group__maug__retroflt.html).
### mtypes
`#include `
Rough common approximation of types for interoperability between our projects.
Includes common types from stdint.h, guaranteed to be of the named size:
* int8\_t
* uint8\_t
* int16\_t
* uint16\_t
* int32\_t
* uint32\_t
When using this header, do not include stdint.h. This header will include it if the current platform supports it. Otherwise, it will improvise.
## MVFS
The maug virtual filesystem is a "special case" file API available on platforms that may have lots of RAM but no supported filesystem. It allows for the compiling of resources into programs.
To use MVFS, an MVFS target must be specified in the program's Makefile, for example like `$(eval $(call MVFS,$(ASSET_FILES) $(BITMAP_FILES)))`. Then, `FORCE_MVFS` must be set to `1` in the Makefile before the targets that use it are called (i.e. every `$(eval $(call TARGET))` statement that comes after the first `FORCE_MVFS` statement in the Makefile will use the MVFS).
MVFS is not supported on platforms like 16-bit DOS or Windows 3.x, as these platforms are restricted to very tiny segments that make it too problematic.
## mlisp
mlisp is a basic fully interpreted scripting language using S-expressions. More information on the available commands is in [the mlisp documentation](https://indigoparadox.codeberg.page/maug/group__maug__mlisp__commands.html).
## Troubleshooting
### size of segment x exceeds 64k by y bytes
RetroFlat can be quite bulky for 16-bit DOS. Please try adding RETROFLAT\_DOS\_MEM\_LARGE=1 to your Makefile before Makefile.inc is included to enable a large code model.
### Cache loading errors which retrogxc.h is never included
For 16-bit builds, `GLOBAL\_DEFINES += -DRETROFLAT\_NO\_RETROGXC` must be specified in the Makefile explicitly, or the cache will be enabled in the DOS stubs.
### Emscripten in Debian Complains About FROZEN\_CACHE
Do the following, to create a mutable emscripten cache in your `$HOME`:
- Make `$HOME/.emscripten` directory.
- Copy `/usr/share/emscripten/cache/` to `$HOME/.emscripten/cache`
- Copy `/usr/share/emscripten/.emscripten` to `$HOME/.emscripten/config`
- In `$HOME/.emscripten/config`:
* Set `FROZEN\_CACHE = False`.
* Set `CACHE = '/home/username/.emscripten/cache'`, where `/home/username` is whatever `$HOME` expands to.
After doing this, building with emcc should work.