gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
docs/pages/20_toolchain_settings.md
1 @page docs_toolchain_settings Toolchain settings
2 @anchor lcc-settings
3 # lcc settings
4 ```
5 ./lcc [ option | file ]...
6 except for -l, options are processed left-to-right before files
7 unrecognized options are taken to be linker options
8 -c compile only
9 -debug Turns on --debug for compiler, -y (.cdb), -j (.noi), -w (wide .map format) for linker
10 -Wa-l (assembler .lst), -Wl-u (.lst -> .rst address update)
11 -Dname=def define the preprocessor symbol `name'
12 -E only run preprocessor on named .c and .h files files -> stdout
13 --save-preproc Use with -E for output to *.i files instead of stdout
14 -help or -? print this message
15 -Idir add `dir' to the beginning of the list of #include directories
16 -K don't run ihxcheck test on linker ihx output
17 -lx search library `x'
18 -m select port and platform: "-m[port]:[plat]" ports:sm83,z80,mos6502 plats:ap,duck,gb,sms,gg,nes
19 -N do not search the standard directories for #include files
20 -no-crt do not auto-include the gbdk crt0.o runtime in linker list
21 -no-libs do not auto-include the gbdk libs in linker list
22 -o file leave the output in `file'
23 -S compile to assembly language
24 -autobank auto-assign banks set to 255 (bankpack)
25 -tempdir=dir place temporary files in `dir/'
26 -Uname undefine the preprocessor symbol `name'
27 -v show commands as they are executed; 2nd -v suppresses execution
28 -Woarg specify system-specific `arg'
29 -W[pfablimnc]arg pass `arg' to the (p)preprocessor, (f)compiler, (a)assembler, (b)bankpack,
30 (l)linker, (i)ihxcheck, (m)makebin, (n)makenes, (c)makecom
31 ```
32 @anchor sdcc-settings
33 # sdcc settings
34 ```
35 SDCC : z80/sm83/mos6502/mos65c02 TD- 4.5.1 #15267 (Linux)
36 published under GNU General Public License (GPL)
37 Usage : sdcc [options] filename
38 Options :-
39
40 General options:
41 --help Display this help
42 -v --version Display sdcc's version
43 --verbose Trace calls to the preprocessor, assembler, and linker
44 -V Execute verbosely. Show sub commands as they are run
45 -d Output list of macro definitions in effect. Use with -E
46 -D Define macro as in -Dmacro
47 -I Add to the include (*.h) path, as in -Ipath
48 -A
49 -U Undefine macro as in -Umacro
50 -M Preprocessor option
51 -W Pass through options to the pre-processor (p), assembler (a) or linker (l)
52 --include Pre-include a file during pre-processing
53 -E --preprocessonly Preprocess only, do not compile
54 --syntax-only Parse and verify syntax only, do not compile
55 -S Compile only; do not assemble or link
56 -c --compile-only Compile and assemble, but do not link
57 --c1mode Act in c1 mode. The standard input is preprocessed code, the output is assembly code.
58 -o Place the output into the given path resp. file
59 -x Optional file type override (c, c-header or none), valid until the next -x
60 --print-search-dirs display the directories in the compiler's search path
61 --vc messages are compatible with Micro$oft visual studio
62 --use-stdout send errors to stdout instead of stderr
63 --nostdlib Do not include the standard library directory in the search path
64 --nostdinc Do not include the standard include directory in the search path
65 --less-pedantic Disable some of the more pedantic warnings
66 --disable-warning <nnnn> Disable specific warning
67 --Werror Treat the warnings as errors
68 --debug Enable debugging symbol output
69 --cyclomatic Display complexity of compiled functions
70 --std Determine the language standard (c90, c99, c11, c23, c2y, sdcc89 etc.)
71 --fdollars-in-identifiers Permit '$' as an identifier character
72 --fsigned-char Make "char" signed by default
73 --use-non-free Search / include non-free licensed libraries and header files
74
75 Code generation options:
76 -m Set the port to use e.g. -mz80.
77 -p Select port specific processor e.g. -mpic14 -p16f84
78 --stack-auto Stack automatic variables
79 --xstack Use external stack
80 --int-long-reent Use reentrant calls on the int and long support functions
81 --float-reent Use reentrant calls on the float support functions
82 --xram-movc Use movc instead of movx to read xram (xdata)
83 --callee-saves <func[,func,...]> Cause the called function to save registers instead of the caller
84 --fomit-frame-pointer Leave out the frame pointer.
85 --all-callee-saves callee will always save registers used
86 --stack-probe insert call to function __stack_probe at each function prologue
87 --no-xinit-opt don't memcpy initialized xram from code
88 --no-c-code-in-asm don't include c-code as comments in the asm file
89 --no-peep-comments don't include peephole optimizer comments
90 --codeseg <name> use this name for the code segment
91 --constseg <name> use this name for the const segment
92 --dataseg <name> use this name for the data segment
93
94 Optimization options:
95 --opt-code-speed Optimize for code speed rather than size
96 --opt-code-size Optimize for code size rather than speed
97 --max-allocs-per-node Maximum number of register assignments considered at each node of the tree decomposition
98 --no-reg-params On some ports, disable passing some parameters in registers
99 --nostdlibcall Disable optimization of calls to standard library
100 --nooverlay Disable overlaying leaf function auto variables
101 --nogcse Disable the GCSE optimisation
102 --nolospre Disable lospre
103 --nogenconstprop Disable generalized constant propagation
104 --nolabelopt Disable label optimisation
105 --noinvariant Disable optimisation of invariants
106 --noinduction Disable loop variable induction
107 --noloopreverse Disable the loop reverse optimisation
108 --no-peep Disable the peephole assembly file optimisation
109 --peep-asm Enable peephole optimization on inline assembly
110 --peep-return Enable peephole optimization for return instructions
111 --no-peep-return Disable peephole optimization for return instructions
112 --peep-file <file> use this extra peephole file
113 --allow-unsafe-read Allow optimizations to read any memory location anytime
114
115 Internal debugging options:
116 --dump-ast Dump front-end AST before generating i-code
117 --dump-i-code Dump the i-code structure at all stages
118 --dump-graphs Dump graphs (control-flow, conflict, etc)
119 --i-code-in-asm Include i-code as comments in the asm file
120 --fverbose-asm Include code generator comments in the asm output
121
122 Linker options:
123 -l Include the given library in the link
124 -L Add the next field to the library search path
125 --lib-path <path> use this path to search for libraries
126 --out-fmt-ihx Output in Intel hex format
127 --out-fmt-s19 Output in S19 hex format
128 --xram-loc <nnnn> External Ram start location
129 --xram-size <nnnn> External Ram size
130 --iram-size <nnnn> Internal Ram size
131 --xstack-loc <nnnn> External Stack start location
132 --code-loc <nnnn> Code Segment Location
133 --code-size <nnnn> Code Segment size
134 --stack-loc <nnnn> Stack pointer initial value
135 --data-loc <nnnn> Direct data start location
136 --idata-loc
137 --no-optsdcc-in-asm Do not emit .optsdcc in asm
138
139 Special options for the z80 port:
140 --callee-saves-bc Force a called function to always save BC
141 --portmode= Determine PORT I/O mode (z80/z180)
142 -bo <num> use code bank <num>
143 -ba <num> use data bank <num>
144 --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas)
145 --codeseg <name> use this name for the code segment
146 --constseg <name> use this name for the const segment
147 --dataseg <name> use this name for the data segment
148 --no-std-crt0 Do not link default crt0.rel
149 --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer)
150 --fno-omit-frame-pointer Do not omit frame pointer
151 --emit-externs Emit externs list in generated asm
152 --legacy-banking Use legacy method to call banked functions
153 --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2
154 --sdcccall Set ABI version for default calling convention
155 --allow-undocumented-instructions Allow use of undocumented instructions
156
157 Special options for the sm83 port:
158 -bo <num> use code bank <num>
159 -ba <num> use data bank <num>
160 --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas)
161 --callee-saves-bc Force a called function to always save BC
162 --codeseg <name> use this name for the code segment
163 --constseg <name> use this name for the const segment
164 --dataseg <name> use this name for the data segment
165 --no-std-crt0 Do not link default crt0.rel
166 --legacy-banking Use legacy method to call banked functions
167 --sdcccall Set ABI version for default calling convention
168
169 Special options for the mos6502 port:
170 --model-small 8-bit address space for data
171 --model-large 16-bit address space for data (default)
172 --no-zp-spill place register spills in 16-bit address space
173 --no-std-crt0 Do not link default crt0.rel
174
175 Special options for the mos65c02 port:
176 --model-small 8-bit address space for data
177 --model-large 16-bit address space for data (default)
178 --no-zp-spill place register spills in 16-bit address space
179 --no-std-crt0 Do not link default crt0.rel
180 ```
181 @anchor sdasgb-settings
182 # sdasgb settings
183 ```
184
185 sdas Assembler V02.00 + NoICE + SDCC mods (GameBoy)
186
187
188 Copyright (C) 2012 Alan R. Baldwin
189 This program comes with ABSOLUTELY NO WARRANTY.
190
191 Usage: [-Options] [-Option with arg] file
192 Usage: [-Options] [-Option with arg] outfile file1 [file2 ...]
193 -h or NO ARGUMENTS Show this help list
194 Input:
195 -I Add the named directory to the include file
196 search path. This option may be used more than once.
197 Directories are searched in the order given.
198 Output:
199 -l Create list file/outfile[.lst]
200 -o Create object file/outfile[.rel]
201 -s Create symbol file/outfile[.sym]
202 Listing:
203 -d Decimal listing
204 -q Octal listing
205 -x Hex listing (default)
206 -b Display .define substitutions in listing
207 -bb and display without .define substitutions
208 -c Disable instruction cycle count in listing
209 -f Flag relocatable references by ` in listing file
210 -ff Flag relocatable references by mode in listing file
211 -p Disable automatic listing pagination
212 -u Disable .list/.nlist processing
213 -w Wide listing format for symbol table
214 Assembly:
215 -v Enable out of range signed / unsigned errors
216 Symbols:
217 -a All user symbols made global
218 -g Undefined symbols made global
219 -N Don't resolve global assigned value symbols
220 -z Disable case sensitivity for symbols
221 Debugging:
222 -j Enable NoICE Debug Symbols
223 -y Enable SDCC Debug Symbols
224
225 ```
226 @anchor sdasz80-settings
227 # sdasz80 settings
228 ```
229
230 sdas Assembler V02.00 + NoICE + SDCC mods (Zilog Z80 / Hitachi HD64180 / ZX-Next / eZ80 / R800)
231
232
233 Copyright (C) 2012 Alan R. Baldwin
234 This program comes with ABSOLUTELY NO WARRANTY.
235
236 Usage: [-Options] [-Option with arg] file
237 Usage: [-Options] [-Option with arg] outfile file1 [file2 ...]
238 -h or NO ARGUMENTS Show this help list
239 Input:
240 -I Add the named directory to the include file
241 search path. This option may be used more than once.
242 Directories are searched in the order given.
243 Output:
244 -l Create list file/outfile[.lst]
245 -o Create object file/outfile[.rel]
246 -s Create symbol file/outfile[.sym]
247 Listing:
248 -d Decimal listing
249 -q Octal listing
250 -x Hex listing (default)
251 -b Display .define substitutions in listing
252 -bb and display without .define substitutions
253 -c Disable instruction cycle count in listing
254 -f Flag relocatable references by ` in listing file
255 -ff Flag relocatable references by mode in listing file
256 -p Disable automatic listing pagination
257 -u Disable .list/.nlist processing
258 -w Wide listing format for symbol table
259 Assembly:
260 -v Enable out of range signed / unsigned errors
261 Symbols:
262 -a All user symbols made global
263 -g Undefined symbols made global
264 -N Don't resolve global assigned value symbols
265 -z Disable case sensitivity for symbols
266 Debugging:
267 -j Enable NoICE Debug Symbols
268 -y Enable SDCC Debug Symbols
269
270 ```
271 @anchor sdas6500-settings
272 # sdas6500 settings
273 ```
274
275 sdas Assembler V02.00 + NoICE + SDCC mods (Rockwell 6502/6510/65C02)
276
277
278 Copyright (C) 2012 Alan R. Baldwin
279 This program comes with ABSOLUTELY NO WARRANTY.
280
281 Usage: [-Options] [-Option with arg] file
282 Usage: [-Options] [-Option with arg] outfile file1 [file2 ...]
283 -h or NO ARGUMENTS Show this help list
284 Input:
285 -I Add the named directory to the include file
286 search path. This option may be used more than once.
287 Directories are searched in the order given.
288 Output:
289 -l Create list file/outfile[.lst]
290 -o Create object file/outfile[.rel]
291 -s Create symbol file/outfile[.sym]
292 Listing:
293 -d Decimal listing
294 -q Octal listing
295 -x Hex listing (default)
296 -b Display .define substitutions in listing
297 -bb and display without .define substitutions
298 -c Disable instruction cycle count in listing
299 -f Flag relocatable references by ` in listing file
300 -ff Flag relocatable references by mode in listing file
301 -p Disable automatic listing pagination
302 -u Disable .list/.nlist processing
303 -w Wide listing format for symbol table
304 Assembly:
305 -v Enable out of range signed / unsigned errors
306 Symbols:
307 -a All user symbols made global
308 -g Undefined symbols made global
309 -N Don't resolve global assigned value symbols
310 -z Disable case sensitivity for symbols
311 Debugging:
312 -j Enable NoICE Debug Symbols
313 -y Enable SDCC Debug Symbols
314
315 ```
316 @anchor bankpack-settings
317 # bankpack settings
318 ```
319 bankalloc [options] objfile1 objfile2 etc
320 Use: Read .o files and auto-assign areas with bank=255.
321 Typically called by Lcc compiler driver before linker.
322
323 Options
324 -h : Show this help
325 -lkin=<file> : Load object files specified in linker file <file>
326 -lkout=<file> : Write list of object files out to linker file <file>
327 -yt<mbctype> : Set MBC type per ROM byte 149 in Decimal or Hex (0xNN)
328 ([see pandocs](https://gbdev.io/pandocs/The_Cartridge_Header.html#0147---cartridge-type))
329 -mbc=N : Similar to -yt, but sets MBC type directly to N instead
330 of by intepreting ROM byte 149
331 mbc1 will exclude banks {0x20,0x40,0x60} max=127,
332 mbc2 max=15, mbc3 max=127, mbc5 max=255 (not 511!)
333 -min=N : Min assigned ROM bank is N (default 1)
334 -max=N : Max assigned ROM bank is N, error if exceeded
335 -ext=<.ext> : Write files out with <.ext> instead of source extension
336 -path=<path> : Write files out to <path> (<path> *MUST* already exist)
337 -sym=<prefix> : Add symbols starting with <prefix> to match + update list
338 Default entry is "___bank_" (see below)
339 -cartsize : Print min required cart size as "autocartsize:<NNN>"
340 -plat=<plat> : Select platform specific behavior (default:gb) (gb,sms)
341 -random : Distribute banks randomly for testing (honors -min/-max)
342 -reserve=<b:n> : Reserve N bytes (hex) in bank B (decimal)
343 Ex: -reserve=105:30F reserves 0x30F bytes in bank 105
344 -banktype=<b:t>: Set bank B (decimal) to use type T (CODE or LIT). For sms/gg
345 Ex: -banktype=2:LIT sets bank 2 to type LIT
346 -v : Verbose output, show assignments
347
348 Example: "bankpack -ext=.rel -path=some/newpath/ file1.o file2.o"
349 Unless -ext or -path specify otherwise, input files are overwritten.
350
351 Default MBC type is not set. It *must* be specified by -mbc= or -yt!
352
353 The following will have FF and 255 replaced with the assigned bank:
354 A _CODE_255 size <size> flags <flags> addr <address>
355 S b_<function name> Def0000FF
356 S ___bank_<const name> Def0000FF
357 (Above can be made by: const void __at(255) __bank_<const name>;
358 ```
359 @anchor sdldgb-settings
360 # sdldgb settings
361 ```
362
363 sdld Linker V03.00/V05.40 + sdld
364
365 Usage: [-Options] [-Option with arg] file
366 Usage: [-Options] [-Option with arg] outfile file1 [file2 ...]
367 Startup:
368 -p Echo commands to stdout (default)
369 -n No echo of commands to stdout
370 Alternates to Command Line Input:
371 -c ASlink >> prompt input
372 -f file[.lk] Command File input
373 Libraries:
374 -k Library path specification, one per -k
375 -l Library file specification, one per -l
376 Relocation:
377 -b area base address = expression
378 -g global symbol = expression
379 -a (platform) Select platform specific virtual address translation
380 Map format:
381 -m Map output generated as (out)file[.map]
382 -w Wide listing format for map file
383 -x Hexadecimal (default)
384 -d Decimal
385 -q Octal
386 Output:
387 -i Intel Hex as (out)file[.ihx]
388 -s Motorola S Record as (out)file[.s19]
389 -j NoICE Debug output as (out)file[.noi]
390 -y SDCDB Debug output as (out)file[.cdb]
391 List:
392 -u Update listing file(s) with link data as file(s)[.rst]
393 Case Sensitivity:
394 -z Disable Case Sensitivity for Symbols
395 End:
396 -e or null line terminates input
397
398 ```
399 @anchor sdldz80-settings
400 # sdldz80 settings
401 ```
402
403 sdld Linker V03.00/V05.40 + sdld
404
405 Usage: [-Options] [-Option with arg] file
406 Usage: [-Options] [-Option with arg] outfile file1 [file2 ...]
407 Startup:
408 -p Echo commands to stdout (default)
409 -n No echo of commands to stdout
410 Alternates to Command Line Input:
411 -c ASlink >> prompt input
412 -f file[.lk] Command File input
413 Libraries:
414 -k Library path specification, one per -k
415 -l Library file specification, one per -l
416 Relocation:
417 -b area base address = expression
418 -g global symbol = expression
419 -a (platform) Select platform specific virtual address translation
420 Map format:
421 -m Map output generated as (out)file[.map]
422 -w Wide listing format for map file
423 -x Hexadecimal (default)
424 -d Decimal
425 -q Octal
426 Output:
427 -i Intel Hex as (out)file[.ihx]
428 -s Motorola S Record as (out)file[.s19]
429 -j NoICE Debug output as (out)file[.noi]
430 -y SDCDB Debug output as (out)file[.cdb]
431 List:
432 -u Update listing file(s) with link data as file(s)[.rst]
433 Case Sensitivity:
434 -z Disable Case Sensitivity for Symbols
435 End:
436 -e or null line terminates input
437
438 ```
439 @anchor sdld6808-settings
440 # sdld6808 settings
441 ```
442
443 sdld Linker V03.00/V05.40 + sdld
444
445 Usage: [-Options] [-Option with arg] file
446 Usage: [-Options] [-Option with arg] outfile file1 [file2 ...]
447 Startup:
448 -p Echo commands to stdout (default)
449 -n No echo of commands to stdout
450 Alternates to Command Line Input:
451 -c ASlink >> prompt input
452 -f file[.lk] Command File input
453 Libraries:
454 -k Library path specification, one per -k
455 -l Library file specification, one per -l
456 Relocation:
457 -b area base address = expression
458 -g global symbol = expression
459 -a (platform) Select platform specific virtual address translation
460 Map format:
461 -m Map output generated as (out)file[.map]
462 -w Wide listing format for map file
463 -x Hexadecimal (default)
464 -d Decimal
465 -q Octal
466 Output:
467 -i Intel Hex as (out)file[.ihx]
468 -s Motorola S Record as (out)file[.s19]
469 -j NoICE Debug output as (out)file[.noi]
470 -y SDCDB Debug output as (out)file[.cdb]
471 List:
472 -u Update listing file(s) with link data as file(s)[.rst]
473 Case Sensitivity:
474 -z Disable Case Sensitivity for Symbols
475 End:
476 -e or null line terminates input
477
478 ```
479 @anchor ihxcheck-settings
480 # ihxcheck settings
481 ```
482 ihx_check input_file.ihx [options]
483
484 Options
485 -h : Show this help
486 -e : Treat warnings as errors
487
488 Use: Read a .ihx and warn about overlapped areas.
489 Example: "ihx_check build/MyProject.ihx"
490 ```
491 @anchor makebin-settings
492 # makebin settings
493 Also see @ref setting_mbc_and_rom_ram_banks
494 ```
495 makebin: convert a Intel IHX file to binary or GameBoy format binary.
496 Usage: makebin [options] [<in_file> [<out_file>]]
497 Options:
498 -p pack mode: the binary file size will be truncated to the last occupied byte
499 -s romsize size of the binary file (default: rom banks * 16384)
500 -Z generate GameBoy format binary file
501 -S generate Sega Master System format binary file
502 -N generate Famicom/NES format binary file
503 -o bytes skip amount of bytes in binary file
504 SMS format options (applicable only with -S option):
505 -xo n header rom size (0xa-0x2) (default: 0xc)
506 -xj n set region code (3-7) (default: 4)
507 -xv n version number (0-15) (default: 0)
508 -yo n number of rom banks (default: 2) (autosize: A)
509 -ya n number of ram banks (default: 0)
510 GameBoy format options (applicable only with -Z option):
511 -yo n number of rom banks (default: 2) (autosize: A)
512 -ya n number of ram banks (default: 0)
513 -yt n MBC type (default: no MBC)
514 -yl n old licensee code (default: 0x33)
515 -yk cc new licensee string (default: 00)
516 -yn name cartridge name (default: none)
517 -yc GameBoy Color compatible
518 -yC GameBoy Color only
519 -ys Super GameBoy
520 -yS Convert .noi file named like input file to .sym
521 -yj set non-Japanese region flag
522 -yN do not copy big N validation logo into ROM header
523 -yp addr=value Set address in ROM to given value (address 0x100-0x1FE)
524 Arguments:
525 <in_file> optional IHX input file, '-' means stdin. (default: stdin)
526 <out_file> optional output file, '-' means stdout. (default: stdout)
527 ```
528 @anchor makecom-settings
529 # makecom settings
530 ```
531 makecom image.rom image.noi output.com
532 Use: convert a binary .rom file to .msxdos com format.
533 ```
534 @anchor makenes-settings
535 # makenes settings
536 ```
537 makenes: Prepend an iNES header to a binary ROM image file.
538 Usage: makenes [options] [<in_file> [<out_file>]]
539 Options:
540 -m Mapper number (default: 0)
541 -n Nametable arrangement:
542 0: vertical arrangement / horizontal mirroring
543 1: horizontal arrangement / vertical mirroring
544 -b Battery bit set (default: 0)
545 -a Alternative nametable layout (default: 0)
546 Arguments:
547 <in_file> optional binary input file, '-' means stdin. (default: stdin)
548 <out_file> optional .nes output file, '-' means stdout. (default: stdout)
549 ```
550 @anchor gbcompress-settings
551 # gbcompress settings
552 ```
553 gbcompress [options] infile outfile
554 Use: compress a binary file and write it out.
555
556 Options
557 -h : Show this help screen
558 -d : Decompress (default is compress)
559 -v : Verbose output
560 --cin : Read input as .c source format (8 bit char ONLY, uses first array found)
561 --cout : Write output in .c / .h source format (8 bit char ONLY)
562 --varname=<NAME> : specify variable name for c source output
563 --alg=<type> : specify compression type: 'zx0', 'rle', 'gb' (default)
564 --bank=<num> : Add Bank Ref: 1 - 511 (default is none, with --cout only)
565 Example: "gbcompress binaryfile.bin compressed.bin"
566 Example: "gbcompress -d compressedfile.bin decompressed.bin"
567 Example: "gbcompress --alg=rle binaryfile.bin compressed.bin"
568
569 The default compression (gb) is the type used by gbtd/gbmb
570 The rle compression is Amiga IFF style
571 ```
572 @anchor png2asset-settings
573 # png2asset settings
574 ```
575 usage: png2asset <file>.png [options]
576 -o <filename> ouput file (if not used then default is <png file>.c)
577 -c <filename> deprecated, same as -o
578 -sw <width> metasprites width size (default: png width)
579 -sh <height> metasprites height size (default: png height)
580 -sp <props> change default for sprite OAM property bytes (in hex) (default: 0x00)
581 -px <x coord> metasprites pivot x coordinate (default: metasprites width / 2)
582 -py <y coord> metasprites pivot y coordinate (default: metasprites height / 2)
583 -pw <width> metasprites collision rect width (default: metasprites width)
584 -ph <height> metasprites collision rect height (default: metasprites height)
585 -spr8x8 for 8x8 hardware sprites (use SPRITES_8x8)
586 -spr8x16 for 8x16 hardware sprites (use SPRITES_8x16) (the default)
587 -spr16x16msx MSX only: for 16x16 hardware sprites (use SPRITES_16x16)
588 -sprite_no_optimize keep empty sprite tiles, do not remove duplicate tiles
589 -b <banknum> Bank number (default: fixed bank)
590 -area <area name> Area name. Alters "pragma bank ..." output to constseg style. (Ex: -area LIT)
591 -keep_palette_order use png palette
592 -repair_indexed_pal try to repair indexed tile palettes (implies "-keep_palette_order")
593 -noflip disable tile flip
594 -map Export as map (tileset + bg) instead of default metasprite output
595 -use_map_attributes Use CGB BG Map attributes
596 -use_nes_attributes Use NES BG Map attributes
597 -use_nes_colors Convert RGB color values to NES PPU colors
598 -use_structs Group the exported info into structs (default: false) (used by ZGB Game Engine)
599 -bpp bits per pixel: 1, 2, 4 (default: 2. using 1 auto-enables "-pack_mode 1bpp")
600 -max_palettes max number of palettes allowed (default: 8)
601 (note: max colors = max_palettes x num colors per palette)
602 -pack_mode gb, nes, sgb, sms, 1bpp (default: gb. using 1bpp auto-enables "-bpp 1")
603 -tile_origin tile index offset for maps (default: 0)
604 -tiles_only export tile data only
605 -maps_only export map tilemap only
606 -metasprites_only export metasprite descriptors only
607 -source_tileset use source tileset (image with common tiles)
608 -entity_tileset (maps only) mark matching tiles counting from 255 down, entity patterns not exported
609 -keep_duplicate_tiles do not remove duplicate tiles (default: not enabled)
610 -no_palettes do not export palette data
611 -bin export to binary format (requires -map)
612 -transposed export transposed (column-by-column instead of row-by-row)
613 -rel_paths paths to tilesets are relative to the input file path
614 -use_metafile Read extra options from file <inputfile>.meta (file missing not an error)
615 decoder error empty input buffer given to decoder. Maybe caused by non-existing file?
616 ```
617 @anchor png2hicolorgb-settings
618 # png2hicolorgb settings
619 ```
620
621 png2hicolorgb input_image.png [options]
622 version 1.4.2: bbbbbr. Based on Glen Cook's Windows GUI "hicolour.exe" 1.2
623 Convert an image to Game Boy Hi-Color format
624
625 Options
626 -h : Show this help
627 -v* : Set log level: "-v" verbose, "-vQ" quiet, "-vE" only errors, "-vD" debug
628 -o <file> : Set base output filename (otherwise from input image)
629 -s <name> : Set output variable/symbol name (otherwise derived from output filename)
630 --csource : Export C source format with incbins for data files
631 --bank=N : Set bank number for C source output where N is decimal bank number 1-511
632 --type=N : Set conversion type where N is one of below
633 1: Median Cut - No Dither (*Default*)
634 2: Median Cut - With Dither
635 3: Wu Quantiser (best quality)
636 -p : Show screen attribute pattern options (no processing)
637 -L=N : Set Left side of screen palette arrangement where N is name listed below or decimal entry
638 -R=N : Set Right side of screen palette arrangement where N is name listed below or decimal entry
639 Named options for N: "adaptive-fast", "adaptive-medium", "adaptive-best" (-p for full options)
640 --best : Use highest quality conversion settings (--type=3 -L=adaptive-best -R=adaptive-best)
641 --vaddrid : Map uses vram id (128->255->0->127) instead of (*Default*) sequential tile order (0->255)
642 --nodedupe : Turn off tile pattern deduplication
643 --precompiled : Export Palette data as pre-compiled executable loading code
644 --palendbit : Set unused bit .15 = 1 for last u16 entry in palette data indicating end (not in precompiled)
645 --addendcolor=N : Append 32 x color N (hex BGR555) in pal data to clear BG for shorter images (64 bytes) (not in precompiled)
646
647 Example 1: "png2hicolorgb myimage.png"
648 Example 2: "png2hicolorgb myimage.png --csource -o my_output_filename"
649 Example 2: "png2hicolorgb myimage.png --palendbit --addendcolor 0x7FFF -o my_output_filename -s my_variable_name"
650 * Default settings provide good results. Better quality but slower: "--type=3 -L=adaptive-best -R=adaptive-best"
651
652 Historical credits and info:
653 Original Concept : Icarus Productions
654 Original Code : Jeff Frohwein
655 Full Screen Modification : Anon
656 Adaptive Code : Glen Cook
657 Windows Interface : Glen Cook
658 Additional Windows Programming : Rob Jones
659 Original Quantiser Code : Benny
660 Quantiser Conversion : Glen Cook
661
662 ```
663 @anchor romusage-settings
664 # romusage settings
665 ```
666 romusage input_file.[map|noi|ihx|cdb|.gb[c]|.pocket|.duck|.gg|.sms] [options]
667 version 1.3.2, by bbbbbr
668
669 Options
670 -h : Show this help
671 -p : Set platform (GBDK specific), "-p:SMS_GG" for SMS/Game Gear, "-p:NES1" for NES
672
673 -a : Show Areas in each Bank. Optional sort by, address:"-aA" or size:"-aS"
674 -g : Show a small usage graph per bank (-gA for ascii style)
675 -G : Show a large usage graph per bank (-GA for ascii style)
676 -B : Brief (summarized) output for banked regions. Auto scales max bank
677 shows [Region]_[Max Used Bank] / [auto-sized Max Bank Num]
678 -F : Force Max ROM and SRAM bank num for -B. (0 based) -F:ROM:SRAM (ex: -F:255:15)
679
680 -m : Manually specify an Area -m:NAME:HEXADDR:HEXLENGTH
681 -e : Manually specify an Area that should not overlap -e:NAME:HEXADDR:HEXLENGTH
682 -b : Set hex bytes treated as Empty in ROM files (.gb/etc) -b:HEXVAL[...] (default FF)
683 -E : All areas are exclusive (except HEADERs), warn for any overlaps
684 -q : Quiet, no output except warnings and errors
685 -Q : Suppress output of warnings and errors
686 -R : Return error code for Area warnings and errors
687
688 -sR : [Rainbow] Color output (-sRe for Row Ends, -sRd for Center Dimmed, -sRp % based)
689 -sP : Custom Color Palette. Colon separated entries are decimal VT100 color codes
690 -sP:DEFAULT:ROM:VRAM:SRAM:WRAM:HRAM (section based color only)
691 -sC : Show Compact Output, hide non-essential columns
692 -sH : Show HEADER Areas (normally hidden)
693 -smROM : Show Merged ROM_0 and ROM_1 output (i.e. bare 32K ROM)
694 -smWRAM : Show Merged WRAM_0 and WRAM_1 output (i.e DMG/MGB not CGB)
695 -sm* compatible with banked ROM_x or WRAM_x when used with -B
696 -sJ : Show JSON output. Some options not applicable. When used, -Q recommended
697 -nB : Hide warning banner (for .cdb output)
698 -nA : Hide areas (shown by default in .cdb output)
699 -z : Hide areas smaller than SIZE -z:DECSIZE
700 -nMEM : Hide banks matching case sensitive substring (ex hide all RAM: -nMEM:RAM)
701
702 Use: Read a .map, .noi, .cdb or .ihx file to display area sizes
703 Example 1: "romusage build/MyProject.map"
704 Example 2: "romusage build/MyProject.noi -a -e:STACK:DEFF:100 -e:SHADOW_OAM:C000:A0"
705 Example 3: "romusage build/MyProject.ihx -g"
706 Example 4: "romusage build/MyProject.map -q -R"
707 Example 5: "romusage build/MyProject.noi -sR -sP:90:32:90:35:33:36"
708 Example 6: "romusage build/MyProject.map -sRp -g -B -F:255:15 -smROM -smWRAM"
709 Example 7: "romusage build/MyProject.gb -g -b:FF:00"
710
711 Notes:
712 * GBDK / RGBDS map file format detection is automatic.
713 * Estimates are as close as possible, but may not be complete.
714 Unless specified with -m/-e they *do not* factor regions lacking
715 complete ranges in the Map/Noi/Ihx file, for example Shadow OAM and Stack.
716 * IHX files can only detect overlaps, not detect memory region overflows.
717 * CDB file output ONLY counts (most) data from C sources.
718 It cannot count functions and data from ASM and LIBs,
719 so bank totals may be incorrect/missing.
720 * GB/GBC/ROM files are just guessing, no promises.
721 ```
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.