Usage

The general command-line syntax is:

asar.exe [options] {asm_file} [rom_file]

For convenience, double-clicking the Asar executable will prompt you to enter paths to an ASM file and a ROM file and thus allow you to directly use Asar without passing any command line arguments to it.

Options

The valid options are:

`--version`

Displays Asar version information and exits.

asar.exe --version

`-v` / `--verbose`

Enables verbose mode.

asar.exe --verbose C:/homebrew/my_game/main.asm

`--no-title-check`

Disables input ROM title and checksum verification when using Asar to apply a patch to an existing ROM file. Note that irresponsible use of this option will likely corrupt your ROM.

asar.exe --no-title-check C:/homebrew/my_game/main.asm

`--pause-mode={mode}`

Sets Asar's pause mode, specifying when Asar should pause the application before exit, where {mode} can be one of the following:

never: Don't pause the application (default)
on-error: Pause the application if an error was thrown.
on-warning: Pause the application if an error or a warning was thrown.
always: Always pause the application.

asar.exe --pause-mode=always C:/homebrew/my_game/main.asm

`-I{path}` / `--include {path}`

Adds an include search path for file-based commands to Asar. Normally, commands like incsrc, incbin etc. look for files relative to the ASM file that is currently being compiled. If those files aren't found, an error is thrown, unless you specify include search paths, in which case Asar will look for the file in each respective directory before throwing an error. For example, imagine you compiled the file

C:/homebrew/my_game.asm

with Asar, adding the include search path

-I"C:/homebrew/binary data"

and the ASM file included the line:

incbin "data/player_gfx.bin"

Asar would now look for a file:

C:/homebrew/data/player_gfx.bin

If this file didn't exist, it would then look for a file:

C:/homebrew/binary data/data/player_gfx.bin

If this file didn't exist, Asar would throw an error, otherwise Asar would include it. See section Includes for details on Asar's handling of file names.

asar.exe -IC:/homebrew/my_game/includes -IC:/homebrew/shared
    C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

asar.exe --include C:/homebrew/my_game/includes
    C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

`-D{identifier}[=value]` / `--define {identifier}[=value]`

Adds a define to Asar. When no value is provided, the define is set to an empty string. See section Defines for details.

asar.exe -Ddebug -Dskip_title_screen=0
    C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

asar.exe --define debug=1 --define mytext=" value with whitespace "
    C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

`--symbols={format}`

Specifies the format of the symbols output file generated by Asar. The following values are supported for {format}:

none: Don't generate a symbols file (default).
wla: Generate a symbols file in the WLA format. This format additionally includes an address-to-line mapping which can be used by some debuggers to provide source-level debugging.
nocash: Generate a symbols file in the no$sns format.

asar.exe --symbols=wla C:/homebrew/my_game/main.asm

`--symbols-path={path}`

Specifies the path and file name to use for generating the symbols output file. By default, the path is the path of [rom_file] and the file name is the base name of [rom_file] with an extension of .sym. Ignored when --symbols is set to none.
Note that relative paths here are relative from the current working directory, not relative from {asm_file} or [rom_file].

asar.exe --symbols=wla
    --symbols-path=C:/homebrew/my_game/symbols/main.symbols
    C:/homebrew/my_game/main.asm

`-w{name}`

Enables the warning with the specified name. See section Warnings for details.

asar.exe -wWimplicitly_sized_immediate C:/homebrew/my_game/main.asm

`-wno{name}`

Disables the warning with the specified name. See section Warnings for details.

asar.exe -wnoWfreespace_leaked C:/homebrew/my_game/main.asm

`-werror`

Causes Asar to treat all warnings as errors.

asar.exe -werror main.asm

`--fix-checksum={on/off}`

Overrides Asar's default behavior of enabling or disabling checksum generation based on context. When set to on, Asar always generates a checksum. When set to off, Asar never generates a checksum.

asar.exe --fix-checksum=on C:/homebrew/my_game/main.asm

`--full-error-stack`

This option makes Asar print a complete call stack whenever an error or warning occurs. This is very useful for patches that use nested macros or mutiple incsrc.

asar.exe --full-error-stack C:/homebrew/my_game/main.asm

`--error-limit={n}`

Sets the maximum number of errors that Asar will print before stopping. The default is 20.

asar.exe --error-limit=500 C:/homebrew/my_game/main.asm

Positional arguments

`{asm_file}`

Path to the ASM source file.

`[rom_file]`

Path to the ROM file that is modified by Asar. If this file doesn't exist yet, Asar creates a new ROM file instead. When omitted, Asar checks if asm_file_name.sfc or asm_file_name.smc exists and uses the one it finds. When zero or two ROMs with that filename are found, Asar defaults to the .sfc extension. As a convention, Asar always treats .smc files as headered and .sfc files as unheadered ROMs. This means that headered .sfc files or unheadered .smc files cannot be used with Asar unless their extension is changed. This is by design and meant to encourage compliance with the convention.

Examples:

asar.exe C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc
asar.exe C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.smc
asar.exe C:/homebrew/my_game/main.asm

Asar Manual