{"id":19190501,"url":"https://github.com/indigoparadox/maug","last_synced_at":"2026-04-05T01:34:05.720Z","repository":{"id":37678364,"uuid":"502732509","full_name":"indigoparadox/maug","owner":"indigoparadox","description":"Utilities for building retro projects relatively quickly","archived":false,"fork":false,"pushed_at":"2025-07-27T03:16:18.000Z","size":4207,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-27T05:50:34.627Z","etag":null,"topics":["aleggro","c89","debug","debugging","dos","logging","maug","nintendo-ds","opengl1","retro","sdl","win16"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indigoparadox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-12T21:31:29.000Z","updated_at":"2025-07-27T03:12:23.000Z","dependencies_parsed_at":"2024-01-14T04:34:09.535Z","dependency_job_id":"44d2fd7c-de9a-47d5-9809-d5b398182eae","html_url":"https://github.com/indigoparadox/maug","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/indigoparadox/maug","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigoparadox%2Fmaug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigoparadox%2Fmaug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigoparadox%2Fmaug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigoparadox%2Fmaug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indigoparadox","download_url":"https://codeload.github.com/indigoparadox/maug/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigoparadox%2Fmaug/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267645105,"owners_count":24120876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aleggro","c89","debug","debugging","dos","logging","maug","nintendo-ds","opengl1","retro","sdl","win16"],"created_at":"2024-11-09T11:34:36.515Z","updated_at":"2026-04-05T01:34:05.711Z","avatar_url":"https://github.com/indigoparadox.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![maug Icon](maug.png) maug\n\nAugmented minimal standard library for C89 and legacy compilers.\n\n**The API is currently in flux and is not yet completely final!**\n\nCurrent maug-based projects may be found under [The maug topic on GitHub](https://github.com/topics/maug)!\n\n## Breaking Changes\n\n- 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`.\n\n## Requirements\n\n### All Platforms\n\n- xxd\n- GNU make\n- ImageMagick convert\n\n**TODO**: List platform-specific requirements.\n\n**TODO**: Platform-specific compiler setup.\n\n### Nintendo DS\n\nThe Nintendo DS port has been modernized to run on top of the Calico RTOS, so it now requires a devkitpro toolchain post-2022.\n\nTheoretically, `-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:\n\n- devkitARM r56\n- libnds 1.8.1-2\n- default\\_arm7 0.7.4-4\n- other-stuff/grit 0.9.2\n- other-stuff/ndstool 2.1.2\n\nAnd 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`.\n\n## Design Constraints\n\nMaug has the following design goals and constraints:\n\n- Must work in C89 compilers. C99-like features like stdint or snprintf are\n  available by internal implementation.\n- Memory allocation uses a flat model (calloc/free), with no handle management.\n- Standard library calls are allowed, so long as they are universally\n  available even in very old C89 compilers.\n\nIn addition, where modules may full functions or pull constants from is limited by the layer architecture described in **Modules**, below.\n\n## Roadmap\n\n- Clearly enumerate which headers rely on which to create modular hierarchy.\n\n- Solidify API.\n\n- Setup Makefile to compile .solib/.dll/.ovl dynamic libs.\n\n- Square-tile-based isometric engine.\n\n- Reimplement retrotile with vectors for tiledefs.\n\n- Replace iffy semi-vectors in mhtml/mcss with vectors.\n\n- Replace obj vertice arrays with vectors in retroglu.\n\n- Implement lambdas in mlisp with separators for pruning sequentally added env args.\n\n- Implement resolution detection in Windows CE.\n\n- Implement timing/blit mode setting options on all platforms.\n\n- Move platform-specific struct into platform-specific translation unit.\n\n- Add switchable support for inline functions.\n\n- Turn platform-specific macros into (inline) functions.\n\n- Make API modules dynamically loadable where applicable.\n\n## Modules\n\nIn principle, the library is split into the following parts:\n\n| Layer         | Location         | \n|---------------|------------------|\n| retro*        | `src/retro*.h`   |\n| retroflat API | `api/retapi*.h`  |\n| maug          | `src/m*.h`       |\n\nEach 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`.\n\nThe 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:\n\n| API     | Description                     |\n|---------|---------------------------------|\n| file    | Filesystem access.              |\n| font    | Drawing text on-screen.         |\n| input   | Input polling/translation.      |\n| log     | Debug/error logging.            |\n| mem     | Dynamic memory allocation.      |\n| retro2d | Drawing primatives on-screen.   |\n| retro3d | Drawing 3D primatives.          |\n| sound   | Digital sound and sequencing.   |\n\nThe **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.\n\n### Makefiles\n\nApplication Makefiles should `include maug/Makefile.inc` to enable the build macros. From there, a target must be defined with `$(eval $(call \u003ctarget\u003e,\u003cappname\u003e))` for each platform to build for.\n\nMany platforms support graphical application icons. These platforms will use \\\u003cappname\\\u003e.bmp if present, and the maug default icon if not.\n\nSome 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.\n\nThe following targets are currently available (possibly among others):\n\n|Target                    | OS           | Cplr   | API       | Notes        |\n|--------------------------|--------------|--------|-----------|--------------|\n|TGTDOSALE                 | DOS          | Watcom | Allegro   |              |\n|TGTDOSGAL                 | DOS          | DJGPP  | Allegro   |              |\n|TGTDOSBIOS                | DOS          | Watcom | BIOS      |              |\n|TGTNDSLIBN                | Nintendo DS  | GCC    | libn      | OpenGL (Opt) |\n|TGTOS2GL                  | OS/2         | Watcom | GLUT      | OpenGL ONLY  |\n|TGTOS2SDL                 | OS/2         | Watcom | SDL       |              |\n|TGT\\_WATCOM\\_WIN32\\_PLUG  | Windows NT   | Watcom | Win32     | Plugins only |\n|TGT\\_GCC\\_UNIX\\_PLUG      | UNIX         | GCC    | SDL       | Plugins only |\n|TGTUNIXSDL                | UNIX         | GCC    | SDL       |              |\n|TGTUNIXALE                | UNIX         | GCC    | Allegro   |              |\n|TGTUNIXGLUT               | UNIX         | GCC    | GLUT      | OpenGL ONLY  |\n|TGTWASMSDL                | Web          | emcc   | SDL       | OpenGL (Opt) |\n|TGTWINNT                  | Windows NT   | Watcom | Win32     | OpenGL (Opt) |\n|TGTWINGL                  | Windows NT   | Watcom | GLUT      | OpenGL ONLY  |\n|TGTWINSDL                 | Windows NT   | Watcom | SDL       | OpenGL (Opt) |\n|TGTWIN16                  | Windows 3.x  | Watcom | Win16     |              |\n|TGTWIN386                 | Windows 3.x  | Watcom | Win16     | 32-bit clean |\n|TGTWINNTGCC               | Windows NT   | GCC    | Win32     | OpenGL (Opt) |\n|TGTWIN64GCC               | Windows NT   | GCC    | Win32     | OpenGL (Opt) |\n|TGT\\_CECL\\_WINCE\\_SH3     | Windows CE   | VC     | WinCE     |              |\n|TGT\\_CECL\\_WINCE\\_MIPS    | Windows CE   | VC     | WinCE     |              |\n|TGT\\_CECL\\_WINCE\\_X86     | Windows CE   | VC     | WinCE     |              |\n|TGTMAC68K                 | MacOS 6      | Retro68| Toolbox   | Monochrome   |\n|TGTPSXPSN                 | PlayStation  | psn00b | psn00b    |              |\n\n### retroflt\n\n`#include \u003cretroflt.h\u003e`\n\nRetroFlat 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.\n\nThis documentation is also available at [https://indigoparadox.codeberg.page/maug/group__maug__retroflt.html](https://indigoparadox.github.io/maug/group__maug__retroflt.html).\n\n### mtypes\n\n`#include \u003cmtypes.h\u003e`\n\nRough common approximation of types for interoperability between our projects.\n\nIncludes common types from stdint.h, guaranteed to be of the named size:\n\n * int8\\_t\n * uint8\\_t\n * int16\\_t\n * uint16\\_t\n * int32\\_t\n * uint32\\_t\n\nWhen using this header, do not include stdint.h. This header will include it if the current platform supports it. Otherwise, it will improvise.\n\n## MVFS\n\nThe 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.\n\nTo 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).\n\nMVFS 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.\n\n## mlisp\n\nmlisp 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).\n\n## Troubleshooting\n\n### size of segment x exceeds 64k by y bytes\n\nRetroFlat 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.\n\n### Cache loading errors which retrogxc.h is never included\n\nFor 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.\n\n### Emscripten in Debian Complains About FROZEN\\_CACHE\n\nDo the following, to create a mutable emscripten cache in your `$HOME`:\n\n - Make `$HOME/.emscripten` directory.\n - Copy `/usr/share/emscripten/cache/` to `$HOME/.emscripten/cache`\n - Copy `/usr/share/emscripten/.emscripten` to `$HOME/.emscripten/config`\n - In `$HOME/.emscripten/config`:\n   * Set `FROZEN\\_CACHE = False`.\n   * Set `CACHE = '/home/username/.emscripten/cache'`, where `/home/username` is whatever `$HOME` expands to.\n\nAfter doing this, building with emcc should work.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findigoparadox%2Fmaug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findigoparadox%2Fmaug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findigoparadox%2Fmaug/lists"}