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!
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 <target>,<appname>)) for each platform to build for.
Many platforms support graphical application icons. These platforms will use <appname>.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 |
retroflt
#include <retroflt.h>
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.
mtypes
#include <mtypes.h>
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.
uprintf
#include <uprintf.h>
An augmented printf for tracing, debugging, and error reporting.
To use, include uprintf.h and call logging\_init() in program startup.
Be sure to call logging\_shutdown() on program cleanup.
Logging can then be performed by calling:
debug\_printf( lvl, format, ... )- Prints debug message.lvl- Immediacy level of debug message. See DEBUG_THRESHOLD below.format-printf()-style format string....- Variable arguments toformat.
error\_printf( format, ... )- Prints to stderr.format-printf()-style format string....- Variable arguments toformat.
uprintf's behavior can be modified by defining the following before inclusion:
| Define | Description |
|---|---|
| platform_file | Type to use instead of stdlib's FILE for log ptr. |
| platform_fopen | Function to use instead of fopen() to create a log ptr. |
| platform_fclose | Function to close log ptr. |
| platform_fflush | Function to flush log ptr to buffer. |
| platform_fprintf | Function to print to log ptr with a format string. |
| DEBUG_THRESHOLD | debug_printf() w/ this or higher lvl will be displayed. |
| DEBUG_LOG | If defined, debug will be output to LOG_FILE_NAME. |
| ANCIENT_C | Use static functions where vararg macros unsupported. |
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, )). 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.
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/.emscriptendirectory. - Copy
/usr/share/emscripten/cache/to$HOME/.emscripten/cache - Copy
/usr/share/emscripten/.emscriptento$HOME/.emscripten/config - In
$HOME/.emscripten/config:- Set
FROZEN\_CACHE = False. - Set ‘CACHE = ’/home/username/.emscripten/cache'
, where/home/usernameis whatever$HOME` expands to.
- Set
After doing this, building with emcc should work.
