336 lines
6.6 KiB
Groff
336 lines
6.6 KiB
Groff
.TH oscar64 1 "June 2026" "Version 1.32" "User Commands"
|
|
.SH NAME
|
|
oscar64 \- optimizing C/C++ cross-compiler for 6502 systems
|
|
|
|
.SH SYNOPSIS
|
|
.B oscar64
|
|
.RB [ \-h ]
|
|
.RB [ \-v [ 1 | 2 | 3 ]]
|
|
.RB { \-i= "\fIincludePath\fR}"
|
|
.RB [ \-ii= "\fIincludePath\fR" ]
|
|
.RB [ \-o= "\fIoutput.prg\fR" ]
|
|
.RB [ \-rt= "\fIruntime.c\fR" ]
|
|
.RB [ \-tf= "\fIformat\fR" ]
|
|
.RB [ \-tm= "\fImachine\fR" ]
|
|
.RB [ \-pp ]
|
|
.RB [ \-strict ]
|
|
.RB [ \-psci ]
|
|
.RB [ \-n | \-bc ]
|
|
.RB [ \-e [ p | t | b | a | i ]]
|
|
.RB [ \-g [ p ]]
|
|
.RB [ \-O ( 0 | 1 | 2 | 3 | s )]
|
|
.RB [ \-O ( i | ii | a | z | p | o | x | g | m )]
|
|
.RB [ \-d \fISYMBOL\fR[=\fIvalue\fR] ]
|
|
.RB [ \-D \fISYMBOL\fR[=\fIvalue\fR] ]
|
|
.RB [ \-xz ]
|
|
.RB [ \-rmp ]
|
|
.RB [ \-d64= "\fIdiskname\fR" ]
|
|
.RB [ \-f= "\fIfile\fR" ]
|
|
.RB [ \-fz= "\fIfile\fR" ]
|
|
.RB [ \-fi= "\fIn\fR" ]
|
|
.RB [ \-cid= "\fIn\fR" ]
|
|
.RB [ \-csub= "\fIn\fR" ]
|
|
.RB [ \-cname= "\fIname\fR" ]
|
|
.RI { source.c }
|
|
.RI { source.cpp }
|
|
|
|
.SH DESCRIPTION
|
|
\fBoscar64\fR is a C/C++ compiler for the 6502 processor family. It is designed to generate high-performance 8-bit code targeting platforms such as the Commodore 64, VIC-20, PET, Commander X16, NES, Atari 8-bit, and Mega65.
|
|
|
|
.SH OPTIONS
|
|
.SS "General Options"
|
|
.TP
|
|
.B \-h
|
|
Print help text and exit.
|
|
.TP
|
|
.BI \-i= includePath
|
|
Set the include file search path.
|
|
.TP
|
|
.BI \-ii= includePath
|
|
Set the default include path (overrides built-in path).
|
|
.TP
|
|
.BI \-o= output.prg
|
|
Specify output file name.
|
|
.TP
|
|
.BI \-rt= runtime.c
|
|
Use a custom runtime startup source (or empty for none).
|
|
.TP
|
|
.B \-pp
|
|
Compile in C++ mode (automatically enabled for .cpp files).
|
|
.TP
|
|
.B \-strict
|
|
Use strict ANSI C parsing (no C++ extensions).
|
|
.TP
|
|
.B \-psci
|
|
Use PETSCII encoding for all string literals without prefix.
|
|
.TP
|
|
.B \-xz
|
|
Extended zero page usage. Provides more zero page space but disables return to BASIC.
|
|
.TP
|
|
.B \-rmp
|
|
Generate error files (.error.map and .error.asm) when the linker fails.
|
|
|
|
.SS "Symbol Definitions"
|
|
.TP
|
|
.BI \-d SYMBOL[=value]
|
|
Define a preprocessor symbol (like \fB\-D\fR in other compilers).
|
|
.TP
|
|
.BI \-D SYMBOL[=value]
|
|
Define a symbol in a gcc-compatible way (e.g., \fB\-D NAME=VALUE\fR as a separate argument).
|
|
|
|
.SS "Code Generation"
|
|
.TP
|
|
.B \-n
|
|
Create pure native code for all functions (now the default).
|
|
.TP
|
|
.B \-bc
|
|
Create byte code for all functions (disables native code generation).
|
|
.TP
|
|
.B \-e
|
|
Execute the result in the integrated emulator after compilation.
|
|
.TP
|
|
.B \-ep
|
|
Execute and profile the result in the integrated emulator.
|
|
.TP
|
|
.B \-et
|
|
Execute with trace output in the integrated emulator.
|
|
.TP
|
|
.B \-eb
|
|
Execute with break trace in the integrated emulator.
|
|
.TP
|
|
.B \-ea
|
|
Execute with asserts enabled in the integrated emulator.
|
|
.TP
|
|
.B \-ei
|
|
Execute with I/O range checking in the integrated emulator.
|
|
|
|
.SS "Optimization"
|
|
.TP
|
|
.B \-O0
|
|
Disable all optimizations.
|
|
.TP
|
|
.B \-O1 "\fBor\fR" \-O
|
|
Default optimizations.
|
|
.TP
|
|
.B \-O2
|
|
Aggressive speed optimizations (includes auto-inline of small functions).
|
|
.TP
|
|
.B \-O3
|
|
Aggressive optimization for speed (includes all sub-optimizations).
|
|
.TP
|
|
.B \-Os
|
|
Optimize for code size.
|
|
.TP
|
|
.B \-Oi
|
|
Enable auto-inline of small functions (part of O2/O3).
|
|
.TP
|
|
.B \-Oii
|
|
Enable aggressive auto-inline of all suitable functions.
|
|
.TP
|
|
.B \-Oa
|
|
Optimize inline assembler (part of O2/O3).
|
|
.TP
|
|
.B \-Oz
|
|
Enable auto-placement of global variables in zero page (part of O3).
|
|
.TP
|
|
.B \-Op
|
|
Optimize constant parameters.
|
|
.TP
|
|
.B \-Oo
|
|
Optimize size using "outliner" (extract repeated code sequences into functions).
|
|
.TP
|
|
.B \-Ox
|
|
Optimize pointer arithmetic by blocking shorter arrays from crossing page boundaries.
|
|
.TP
|
|
.B \-Og
|
|
Enable global optimization.
|
|
.TP
|
|
.B \-Om
|
|
Enable merge calls optimization.
|
|
|
|
.SS "Debug and Diagnostics"
|
|
.TP
|
|
.B \-v
|
|
Enable verbose output for diagnostics.
|
|
.TP
|
|
.B \-v2
|
|
More verbose output.
|
|
.TP
|
|
.B \-v3
|
|
Even more verbose output (implies v2).
|
|
.TP
|
|
.B \-g
|
|
Create source-level debug info and add source line numbers to .asm listing.
|
|
.TP
|
|
.B \-gp
|
|
Create source-level debug info and static profile data.
|
|
|
|
.SS "Target Format"
|
|
.TP
|
|
.BI \-tf= format
|
|
Set the output target format.
|
|
.RS
|
|
.TP
|
|
prg
|
|
Standard Commodore PRG format (default).
|
|
.TP
|
|
crt
|
|
EasyFlash cartridge format.
|
|
.TP
|
|
crt8
|
|
Generic 8KB cartridge (0x8000\-0xa000).
|
|
.TP
|
|
crt16
|
|
Generic 16KB cartridge (0x8000\-0xc000).
|
|
.TP
|
|
bin
|
|
Raw binary format.
|
|
.TP
|
|
lzo
|
|
LZO-compressed PRG output.
|
|
.RE
|
|
|
|
.SS "Target Machine"
|
|
.TP
|
|
.BI \-tm= machine
|
|
Specify the target machine.
|
|
.RS
|
|
.TP
|
|
c64
|
|
Commodore C64 (0x0800..0xa000, default).
|
|
.TP
|
|
c128
|
|
Commodore C128 (0x1c00..0xfc00).
|
|
.TP
|
|
c128b
|
|
C128 first 16KB only (0x1c00..0x4000).
|
|
.TP
|
|
c128e
|
|
C128 first 48KB only (0x1c00..0xc000).
|
|
.TP
|
|
plus4
|
|
Commodore Plus/4 (0x1000..0xfc00).
|
|
.TP
|
|
vic20
|
|
VIC-20, no expansion (0x1000..0x1e00).
|
|
.TP
|
|
vic20+3
|
|
VIC-20 +3K RAM (0x0400..0x1e00).
|
|
.TP
|
|
vic20+8
|
|
VIC-20 +8K RAM (0x1200..0x4000).
|
|
.TP
|
|
vic20+16
|
|
VIC-20 +16K RAM (0x1200..0x6000).
|
|
.TP
|
|
vic20+24
|
|
VIC-20 +24K RAM (0x1200..0x8000).
|
|
.TP
|
|
pet
|
|
Commodore PET, 8K RAM (0x0400..0x2000).
|
|
.TP
|
|
pet16
|
|
Commodore PET, 16K RAM (0x0400..0x4000).
|
|
.TP
|
|
pet32
|
|
Commodore PET, 32K RAM (0x0400..0x8000).
|
|
.TP
|
|
nes
|
|
NES NROM, 32K ROM, no mirror.
|
|
.TP
|
|
nes_nrom_h
|
|
NES NROM, 32K ROM, horizontal mirror.
|
|
.TP
|
|
nes_nrom_v
|
|
NES NROM, 32K ROM, vertical mirror.
|
|
.TP
|
|
nes_mmc1
|
|
NES MMC1 mapper, 256K PROM, 128K CROM.
|
|
.TP
|
|
nes_mmc3
|
|
NES MMC3 mapper, 512K PROM, 256K CROM.
|
|
.TP
|
|
atari
|
|
Atari 8-bit systems (0x2000..0xbc00).
|
|
.TP
|
|
x16
|
|
Commander X16 (0x0800..0x9f00).
|
|
.TP
|
|
mega65
|
|
Mega65 (0x2000..0xc000).
|
|
.RE
|
|
|
|
.SS "Disk Image"
|
|
.TP
|
|
.BI \-d64= diskname
|
|
Create a .d64 disk image with the specified name.
|
|
.TP
|
|
.BI \-f= file.xxx
|
|
Add a binary file to the disk image.
|
|
.TP
|
|
.BI \-fz= file.xxx
|
|
Add a compressed binary file to the disk image.
|
|
.TP
|
|
.BI \-fi= n
|
|
Set sector interleave for data files on disk image (default: 10).
|
|
|
|
.SS "Cartridge Options"
|
|
.TP
|
|
.BI \-cid= n
|
|
Set cartridge type ID (used by VICE emulator).
|
|
.TP
|
|
.BI \-csub= n
|
|
Set cartridge sub-type.
|
|
.TP
|
|
.BI \-cname= name
|
|
Set cartridge name string.
|
|
|
|
.SH "RUNTIME LIBRARY DEFINES"
|
|
.TP
|
|
.BI \-d NOLONG
|
|
Disable support for long integers in printf.
|
|
.TP
|
|
.BI \-d NOFLOAT
|
|
Disable floating-point support in printf.
|
|
.TP
|
|
.BI \-d HEAPCHECK
|
|
Enable heap allocation/free checking; jam if heap is full or free out of range.
|
|
.TP
|
|
.BI \-d NOBSSCLEAR
|
|
Do not clear BSS segment on startup.
|
|
.TP
|
|
.BI \-d NOZPCLEAR
|
|
Do not clear zero-page BSS segment on startup.
|
|
|
|
.SH EXAMPLES
|
|
Compile a program with optimizations:
|
|
.nf
|
|
oscar64 -i=include -O2 -o=demo.prg demo.c
|
|
.fi
|
|
|
|
Compile with emulator execution and custom runtime:
|
|
.nf
|
|
oscar64 -e -rt=startup.c -f=assets.dat game.c
|
|
.fi
|
|
|
|
Create a disk image with compiled output:
|
|
.nf
|
|
oscar64 -d64=mydisk.d64 -f=demo.prg demo.c
|
|
.fi
|
|
|
|
Compile in C++ mode with maximum optimization:
|
|
.nf
|
|
oscar64 -pp -O3 -o=demo.prg demo.cpp
|
|
.fi
|
|
|
|
.SH FILES
|
|
.TP
|
|
.B /usr/local/bin/oscar64
|
|
Main compiler executable.
|
|
.TP
|
|
.B /usr/local/share/oscar64/
|
|
Headers and startup runtime source.
|
|
|
|
.SH SEE ALSO
|
|
.BR llvm-mos (1)
|