{"id":20647166,"url":"https://github.com/bbbbbr/romusage","last_synced_at":"2025-08-20T20:33:20.850Z","repository":{"id":46162380,"uuid":"302461133","full_name":"bbbbbr/romusage","owner":"bbbbbr","description":"A small command line tool for estimating usage of Game Boy (and other supported GBDK platform) ROMs from map files, .noi files, binary ROMs and more","archived":false,"fork":false,"pushed_at":"2025-05-12T19:52:27.000Z","size":724,"stargazers_count":51,"open_issues_count":0,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-12T20:45:27.301Z","etag":null,"topics":["game-boy-roms","gameboy","gbdk","gbdk-2020","gg","ihx-files","map-files","megaduck","noi-files","rgbds","rom","sdcc","sms"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbbbbr.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","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":"2020-10-08T21:02:13.000Z","updated_at":"2025-05-12T19:52:31.000Z","dependencies_parsed_at":"2023-10-02T03:21:04.410Z","dependency_job_id":"58da10ac-6bb6-40fb-b344-d73576641b56","html_url":"https://github.com/bbbbbr/romusage","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/bbbbbr/romusage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbbbbr%2Fromusage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbbbbr%2Fromusage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbbbbr%2Fromusage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbbbbr%2Fromusage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbbbbr","download_url":"https://codeload.github.com/bbbbbr/romusage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbbbbr%2Fromusage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271378706,"owners_count":24749197,"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-08-20T02:00:09.606Z","response_time":69,"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":["game-boy-roms","gameboy","gbdk","gbdk-2020","gg","ihx-files","map-files","megaduck","noi-files","rgbds","rom","sdcc","sms"],"created_at":"2024-11-16T16:29:25.277Z","updated_at":"2025-08-20T20:33:20.752Z","avatar_url":"https://github.com/bbbbbr.png","language":"JavaScript","readme":"### Web Version\nA web build that runs in the browser is avaialble at:\n- https://bbbbbr.github.io/romusage/\n\n### Note about GBDK-2020\nNote: This utility is now included in [GBDK-2020](https://github.com/gbdk-2020/gbdk-2020) (version 4.3.0+), so you may already have a copy if you're using that dev kit.\n\nromusage\n===========\n### Downloads\n - Releases: See the [Releases](https://github.com/bbbbbr/romusage/releases) section to the right\n\n### Description\nA small command line tool for estimating usage (free space) of Game Boy ROMs  (+ Mega Duck, Analogue .pocket, Game Gear, SMS) from the following file types:\n- .map (sdcc, rgbds)\n- .noi (sdcc)\n- .ihx (sdcc)\n- .cdb (sdcc)\n- .gb / .gbc / .pocket / .duck (ROM image file for: Game Boy / Color, Analogue Pocket, Mega Duck / Cougar Boy)\n- .gg / .sms (ROM image file for: Game Gear / Sega Master System. Note: SMS/GG is GBDK-2020 specific)\n\nIt produces a trimmed, sorted output of ROM/RAMs, their usage and optionally the Areas located in them.\n\nRuns on Linux, Windows and MacOS, it can be used with [GBDK 2020](https://github.com/Zal0/gbdk-2020/), [ZGB v2020+](https://github.com/Zal0/ZGB/) and [RGBDS](https://github.com/gbdev/rgbds). If map or noi file output is not already enabled, use either `-debug` with `lcc` or `-m` with `sdldgb` directly.\n\nExamples of color output. `-sRe` with `-sRp` for percentage based color on row ends with `-g` small graphs. `-sRd` for section based color with center columns dimmed.\n![Romusage Color Examples](/info/romusage_color_examples_linux.png)\n\n### Usage\n```\nromusage input_file.[map|noi|ihx|cdb|.gb[c]|.pocket|.duck|.gg|.sms] [options]\nversion 1.2.9, by bbbbbr\n\nOptions\n-h  : Show this help\n-p:SMS_GG : Set platform to GBDK SMS/Game Gear (changes memory map templates)\n\n-a  : Show Areas in each Bank. Optional sort by, address:\"-aA\" or size:\"-aS\" \n-g  : Show a small usage graph per bank (-gA for ascii style)\n-G  : Show a large usage graph per bank (-GA for ascii style)\n-B  : Brief (summarized) output for banked regions. Auto scales max bank\n      shows [Region]_[Max Used Bank] / [auto-sized Max Bank Num]\n-F  : Force Max ROM and SRAM bank num for -B. (0 based) -F:ROM:SRAM (ex: -F:255:15)\n\n-m  : Manually specify an Area -m:NAME:HEXADDR:HEXLENGTH\n-e  : Manually specify an Area that should not overlap -e:NAME:HEXADDR:HEXLENGTH\n-E  : All areas are exclusive (except HEADERs), warn for any overlaps\n-q  : Quiet, no output except warnings and errors\n-Q  : Suppress output of warnings and errors\n-R  : Return error code for Area warnings and errors\n\n-sR : [Rainbow] Color output (-sRe for Row Ends, -sRd for Center Dimmed, -sRp % based)\n-sP : Custom Color Palette. Colon separated entries are decimal VT100 color codes\n      -sP:DEFAULT:ROM:VRAM:SRAM:WRAM:HRAM (section based color only)\n-sC : Show Compact Output, hide non-essential columns\n-sH : Show HEADER Areas (normally hidden)\n-smROM  : Show Merged ROM_0  and ROM_1  output (i.e. bare 32K ROM)\n-smWRAM : Show Merged WRAM_0 and WRAM_1 output (i.e DMG/MGB not CGB)\n          -sm* compatible with banked ROM_x or WRAM_x when used with -B\n-sJ   : Show JSON output. Some options not applicable. When used, -Q recommended\n-nB   : Hide warning banner (for .cdb output)\n-nA   : Hide areas (shown by default in .cdb output)\n-z    : Hide areas smaller than SIZE -z:DECSIZE\n-nMEM : Hide banks matching case sensitive substring (ex hide all RAM: -nMEM:RAM)\n\nUse: Read a .map, .noi, .cdb or .ihx file to display area sizes\nExample 1: \"romusage build/MyProject.map\"\nExample 2: \"romusage build/MyProject.noi -a -e:STACK:DEFF:100 -e:SHADOW_OAM:C000:A0\"\nExample 3: \"romusage build/MyProject.ihx -g\"\nExample 4: \"romusage build/MyProject.map -q -R\"\nExample 5: \"romusage build/MyProject.noi -sR -sP:90:32:90:35:33:36\"\nExample 6: \"romusage build/MyProject.map -sRp -g -B -F:255:15 -smROM -smWRAM\"\n\nNotes:\n  * GBDK / RGBDS map file format detection is automatic.\n  * Estimates are as close as possible, but may not be complete.\n    Unless specified with -m/-e they *do not* factor regions lacking\n    complete ranges in the Map/Noi/Ihx file, for example Shadow OAM and Stack.\n  * IHX files can only detect overlaps, not detect memory region overflows.\n  * CDB file output ONLY counts (most) data from C sources.\n    It cannot count functions and data from ASM and LIBs,\n    so bank totals may be incorrect/missing.\n  * GB/GBC/ROM files are just guessing, no promises.\n```\n### Format notes\nThe usage calculation will attempt to merge overlapping areas to avoid counting shared space multiple times (such as HEADER areas). Optionally it can warn of overlap in exclusive areas, such as the Stack.\n\nIHX Files:\n- For .ihx files bank overflow can only be guessed at (aside from duplicate writes). It's often not possible to tell the difference two banks with data that perfectly aligns on a shared boundary and a single bank that spills over into the unused area of a following bank. It's better to use .map and .noi files to check for overflow.\n- Due to their nature, RAM estimates are unavailable with .ihx files\n\nCDB Files:\n- To enable .cdb output use the additional debug flags `-Wl-y` with `lcc` or `-y` with `sdldgb` directly.\n- For .cdb files the calculated output ONLY reports (most) data from C source files. It cannot count functions and data from ASM sources and LIBs, so bank totals may be incorrect/missing. It's main use is finding the size of individual functions and variables (what's using up space), not estimating the free/used space of banks.\n\nROM Files (.gb / .gbc / .pocket / .duck / gg / sms) :\n- No overflow detection\n- Usage estimates can only attempt to distinguish between \"empty space\" (0xFF's) and data that looks like empty space (0xFF's). It may be inaccurate.\n\n\n### Examples\n\nExample output with a small graph (-g) for a 32k non-banked ROM, called after completion of the link stage. Manually specify Shadow OAM and Stack as exclusive ranges (-e). Reading from the .map file.\n```\n$ romusage.exe /ReleaseColor/Petris.map -g -e:STACK:DEFF:100 -e:SHADOW_OAM:C000:A0\n\nBank           Range             Size   Used   Used%   Free  Free%\n----------     ----------------  -----  -----  -----  -----  -----\nROM            0x0000 -\u003e 0x3FFF  16384  15989   97%     395     2% |-###########################|\nROM_0          0x4000 -\u003e 0x7FFF  16384  12843   78%    3541    21% |#####################-......|\nWRAM           0xC000 -\u003e 0xCFFF   4096   4096  100%       0     0% |############################|\nWRAM_1_0       0xD000 -\u003e 0xDFFF   4096   2150   52%    1946    47% |#############.............-#|\n\n```\n\nExample of quiet mode (-q) that just reports errors and warnings, and can return an error on exit (-R) if any are present.\n```\nromusage banks.map -R -q\n\n* WARNING: Area _DATA    at  c0a0 -\u003e 115a4 extends past end of address space at  ffff (Underflow error by 5541 bytes)\n* WARNING: Area _DATA    at  c0a0 -\u003e 115a4 extends past end of memory region at  dfff (Overflow by 13733 bytes)\n* WARNING: Area _CODE_1  at 14000 -\u003e 1c023 extends past end of memory region at 17fff (Overflow by 16420 bytes)\n* WARNING: Area _CODE_12 at c4000 -\u003e c801f extends past end of memory region at c7fff (Overflow by 32 bytes)\n\n```\n\n\nAnd another example, with display of areas in the banks enabled. Reading from the .noi file.\n```\nromusage gbdk/examples/gb/new_banks.noi -a\n\nBank             Range               Size    Used  Used%    Free  Free%\n----------       ----------------   -----   -----  -----   -----  -----\nROM              0x0000 -\u003e 0x3FFF   16384    8211    50%    8173    49%\n|\n+_CODE           0x0200 -\u003e 0x111A    3867\n+_HOME           0x111B -\u003e 0x1286     364\n+_BASE           0x1287 -\u003e 0x20F2    3692\n+_GSINIT         0x20F3 -\u003e 0x219C     170\n+_GSINITTAIL     0x219D -\u003e 0x219D       1\n\nROM_1            0x4000 -\u003e 0x7FFF   16384      19     0%   16365    99%\n|\n+_CODE_1         0x4000 -\u003e 0x4012      19\n\nROM_2            0x4000 -\u003e 0x7FFF   16384      19     0%   16365    99%\n|\n+_CODE_2         0x4000 -\u003e 0x4012      19\n\nXRAM_1           0xA000 -\u003e 0xBFFF    8192      22     0%    8170    99%\n|\n+_DATA_1         0xA000 -\u003e 0xA015      22\n\nXRAM_2           0xA000 -\u003e 0xBFFF    8192      28     0%    8164    99%\n|\n+_DATA_2         0xA000 -\u003e 0xA01B      28\n\nWRAM             0xC000 -\u003e 0xCFFF    4096     102     2%    3994    97%\n|\n+_DATA           0xC0A0 -\u003e 0xC0B5      22\n+_BSS            0xC0B6 -\u003e 0xC105      80\n\n```\n\n\nWhat's taking up space? Example of .cdb file output showing which functions and variables area larger than 500 bytes (-z:500), with cdb banner noticed suppressed (-nB).\n```\n $ romusage Petris_Debug.cdb -z:500 -nB\n\nBank           Range             Size   Used   Used%   Free  Free% \n----------     ----------------  -----  -----  -----  -----  -----\nROM            0x0000 -\u003e 0x3FFF  16384  16383   99%       1     0%\n|\n| Name                            Start  -\u003e End      Size \n| ---------------------           ----------------   -----\n+ -?-                             0x1E32 -\u003e 0x2937    2822\n+ intro_screen_tiles              0x0FB0 -\u003e 0x145F    1200\n+ twilight_drive_mod              0x15A2 -\u003e 0x1909     872\n+ font_tiles                      0x06D0 -\u003e 0x099F     720\n+ pet_tiles                       0x0A50 -\u003e 0x0CDF     656\n+ freeost_charselect_mod          0x1BE7 -\u003e 0x1E31     587\n+ villainsofhiphop_mod            0x1924 -\u003e 0x1B5C     569\n+ -?-                             0x0001 -\u003e 0x01FF     511\n+ (102 items \u003c 500 hidden = 8446 total bytes)\n\nROM_0          0x4000 -\u003e 0x7FFF  16384  11001   67%    5383    32%\n|\n| Name                            Start  -\u003e End      Size \n| ---------------------           ----------------   -----\n+ board_check_completed_pet_xy    0x65DB -\u003e 0x6843     617\n+ hinting_petlength_add           0x5807 -\u003e 0x59FB     501\n+ (106 items \u003c 500 hidden = 9883 total bytes)\n\nWRAM           0xC000 -\u003e 0xCFFF   4096   4095   99%       1     0%\n|\n| Name                            Start  -\u003e End      Size \n| ---------------------           ----------------   -----\n+ music_decompressed              0xC0ED -\u003e 0xCD08    3100\n+ (16 items \u003c 500 hidden = 995 total bytes)\n\nWRAM_1_0       0xD000 -\u003e 0xDFFF   4096   1827   44%    2269    55%\n|\n| Name                            Start  -\u003e End      Size \n| ---------------------           ----------------   -----\n+ (24 items \u003c 500 hidden = 1827 total bytes)\n```\n\n\nExample output with a large graph (-G) for a 32k non-banked ROM, called after completion of the link stage. Manually specify Shadow OAM and Stack as exclusive ranges (-e). Reading from the .map file.\n```\n$ romusage.exe /ReleaseColor/Petris.map -G -e:STACK:DEFF:100 -e:SHADOW_OAM:C000:A0\n\nBank           Range             Size   Used   Used%   Free  Free%\n----------     ----------------  -----  -----  -----  -----  -----\nROM            0x0000 -\u003e 0x3FFF  16384  15989   97%     395     2%\nROM_0          0x4000 -\u003e 0x7FFF  16384  12843   78%    3541    21%\nWRAM           0xC000 -\u003e 0xCFFF   4096   4096  100%       0     0%\nWRAM_1_0       0xD000 -\u003e 0xDFFF   4096   2150   52%    1946    47%\n\n\nStart: ROM    0x0000 -\u003e 0x3FFF\n#######-........................################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\nEnd: ROM\n\n\nStart: ROM_0  0x4000 -\u003e 0x7FFF\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n################################################################\n##################################-.............................\n................................................................\n................................................................\n................................................................\nEnd: ROM_0\n\n\nStart: WRAM    0xC000 -\u003e 0xCFFF\n################################################################\n################################################################\n################################################################\n################################################################\nEnd: WRAM\n\n\nStart: WRAM_1_0  0xD000 -\u003e 0xDFFF\n################################################################\n######################################################-.........\n................................................................\n................................................################\nEnd: WRAM_1_0\n\n\n```\n","funding_links":[],"categories":["Software Development","软件开发"],"sub_categories":["Tools","工具"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbbbbr%2Fromusage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbbbbr%2Fromusage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbbbbr%2Fromusage/lists"}