# Command Line Several command line options can direct various aspects of the assembly process, including output format, label case-sensitivity, and diagnostic/logging features. In addition, there are available certain commands that change the mode of application behavior. These will be described more fully below. If there is no command given for the first argument the behavior is to assemble source code from the given arguments. ## Options Generally Most options have a simple form, a single `-` followed by a character, though several have longer, alternate forms, with two `--` and a name. For options that expect an argument, the argument can either follow the option token or appear as an assignment. ``` 6502.net myprog.asm -o myprog.prg 6502.net myprog.asm -o=myprog.prg ``` ## Output Options **`-a`**, **`--no-assembly`** For the listing file, do not generate assembly bytes. Example listing: ``` .c000 lda #$00 LDA #ZERO // reset .A ``` **`-d`**, **`--no-disassembly`** For the listing file, do not generate a program disassembly. Example listing: ``` .c000 a9 00 LDA #ZERO // reset .A ``` **`-e`**, **`--error`** Dump all diagnostic messages to the file specified by the argument. **`-f`**, **`--format`** Specify code output format. Setting this option overrides the .format directive in source. ``` dotnet 6502.dot.dll mydisk.asm -o mydisk.d64 -format d64 ``` **`-l`**, **`--labels`** Output all constants and labels to the file specified by the argument. **`--labels-addresses-only`** Used with `-l`, it restricts output only to address labels. **`-L`**, **`--list`** Output listing file to the file specified by the argument. Example listing: ``` .c000 a9 00 lda #$00 LDA #ZERO // reset .A ``` **`--line-numbers`** Include the line number in the listing. ``` 3 .c000 a9 00 lda #$00 LDA #ZERO // reset .A 4 .c002 ea nop NOP ``` **`-o`**, **`--output`** Specify code output file name. If this option is not given, the default output is `a.out`. **`--output-section`** Generate output for the section name in the argument only to the object file. ``` dotnet 6502.net.dll myprog.asm -o myprog.prg --output-section text ``` **`-p`**, **`--patch`** Patch the existing output file at the offset specified. Mostly for bug fixes. The offset can be any valid constant expression that evaluates to an address. ``` 6502.net.exe myfix.asm -o mygame.prg --patch=17707 ``` **`-s`**, **`--no-source`** For the listing file, do not append the original source. Example listing: ``` .c000 a9 00 lda #$00 ``` **`-t`**, **`--truncate-assembly`** Truncate the assembly bytes to one line in the listing, rather than expanding to the full series of bytes. Example listing: ``` >c100 48 45 4c 4c 4f 20 57 4f .string "HELLO WORLD, HOW ARE YOU DOING TODAY?" ``` **`-v`**, **`--verbose-asm`** Include full filename and line number in the listing. ``` myprog.a65(3):.c000 a9 00 lda #$00 LDA #ZERO // reset .A ``` **`--vice-labels`** Used with `-l`. The label listing format conforms to VICE. ``` ~$ dotnet 6502.Net.dll myprog.a65 -o myprog.prg -l labels.txt --vice-labels ``` ## Directing Assembly **`--autosize-registers`** For 65816, whenever a `rep` or `sep` is assembled, the assembler will inspect the flags and adjust the register size. ``` // --autosize-registers rep #%0010_0000 lda #$c000 ``` This behavior can be turned off with `.manual`. **`-b`**, **`--enable-branch-always`** Allow the mnemonic `bra` for 6502 mode. This will assemble to `bvc`. **`-C`**, **`--case-sensitive`** Process all symbols and reserve words case-sensitive. This flag does not affect preprocessor commands, such as .end, .include and .macro. **`-c`**, **`--cpu`** Specify the target CPU and instruction set. This option overrides the `.cpu` directive if the directive appears at the header. ``` dotnet 6502.net.dll myz80.s -o myz80.bin --cpu=z80 ``` **`-D`**, **`--define`** Define a constant. The assignment expression itself must be constant. ``` dotnet 6502.net.dll mysource.asm -o myprog.prg --define=DEBUG_MODE=true ``` **`--dsections`** Define one or more sections. ``` 6502.net myprog.asm -o myprog.prg --dsections zp,2,256 himem,61440 ``` **`--enable-pseudo-long-branches`** Enable pseudo-long branches for 65xx CPUs. **`-I`**, **`--include-path`** Include the path in the argument when attempting to open filenames, for instance with `.binary` or `.include`. ``` 6502.dot.exe myprog.asm -o myprog.prg -I C:\Users\informedcitizenry\Projects\asm\shared ``` **`--long-addressing`** Support long (24-bit) addressing mode. NOTE: This option is deprecated and will have effect on how addresses are resolved. **`--m16`** For 65816, explicitly treat the accumulator as a 16-bit register. **`--reset-pc-on-bank`** Reset the program counter on execution of the `.bank` directive. NOTE: This option is deprecated and will have effect on the program counter when an a `.bank` directive is encountered. **`--legacy-blocks`** Parse block directives using legacy delimiters. As of Version 5, all command blocks (such as for `.block`) are in `{` `}` braces, but pre-V5 source is accepted when this option is specified: ``` // with --legacy-blocks option myscope .block myscopedlabel nop .endblock ``` **`--x16`** For 65816, explicitly treat the index registers as 16-bit registers. ## Diagnostics Options **`-?`**, **`-h`**, **`--help`** Display all command-line options. **`--checksum`** Display MD5 hash of output if assembly is successful. **`--echo-each-pass`** Send output from `.echo` directives on each pass. NOTE: the `.echo` command is deprecated and this option will have no effect. **`--no-highlighting`** Do not highlight causes of errors or warnings in source when reporting errors and warnings. **`--no-stats`** Do not report assembly statistics, such as program start and end addresses, and bytes written. **`--quiet`** Do not send any diagnostic or other information when assembling. **`-V`**, **`--version`** Report the version of the 6502.Net assembly. **`-w`**, **`--no-warn`** Suppress the display of all warnings. **`--Wall`** Enable all warnings. This is a compact alternative to sending these individual flags to the CLI: ``` --Wambiguous-zp, --Wcase-mismatch, --Werror, --Wjump-bug, --Wleft, --Wno-unused-sections, --Wsimplify-call-return, --Wtext-in-non-text-pseudo-ops ``` **`--Wambiguous-zp`** Warn whenever a statement can either be a zero/direct page or absolute addressing mode. Useful if you want to identify places in code that can either be optimized or sized appropriately. ``` // --Wambiguous-zp lda $20,x // this could also be lda $0020,x, so warn ``` **`--Wcase-mismatch`** Warn if a symbol reference does not match the case of the definition. ``` MyMixedCaseLabel = 3 lda #mymixedcaselabel // creates warning ``` **`--Werror`** Treat all warnings as errors. **`--Wjump-bug`** Warn if the assembly generates an indirect jmp bug if the assembler is in 6502 mode. ``` jmp ($01ff) // warn ``` **`--Wleft`** Warn when a whitespace precedes the label in a statement. ``` nonleft lda #0 // warn ``` **`--Wno-bank-crossed`** Do not emit a warning if a bank boundary is crossed during compilation. **`--Wno-unused-sections`** If any defined sections are not used, do not emit a warning. ``` .dsection "zp",2,256 .dsection "text",2049 .section "text" lda #0 // do not warn if "zp" is never used ``` **`--Woptimize-reset-register`** Warn when `ld a,0` (z80) or `mov ax,0` (i8086) can be optimized to `and a` (z80) or `and ax,ax` (i8086). **`--Wregister-as-identifier`** Warn when a constant, label, or variable shares the same name as a CPU register. ``` .cpu "z80" ix = 0 ``` **`--Wsimplify-call-return`** If a return instruction immediately follows a call instruction, warn that the two instructions can be combined into a single jump instruction. ``` // for z80 call mysub ret // for 65xx/m68xx jsr mysub rts ``` **`--Wtext-in-non-text-pseudo-ops`** Warn if strings are used in pseudo-ops that generate numeric data. ``` .byte "H" // warn ``` **`--Wunreferenced-symbols`** Issue warnings for symbols that have been defined but never used. ``` // --- SOF --- unusedlabel = 3 // warn nop nop // --- EOF --- ``` ## Extra commands Commands select a particular feature or set of behaviors with subsequent arguments processed as command options. ## Build command This command builds a project expecting a JSON-formatted build file. If no build file is given, the default file is assumed as `build.json`. A build file can be generated from arguments using the `config` command described below. ``` 6502.Net build # builds a project from options in the build.json file 6502.Net build myproj.json ``` ## Config command The config command creates a build file from passed arguments. ``` 6502.Net.exe config mysource.s /lib/mylib.s --output=myoutput.bin --error=errors.txt --list=mylistfile.s --format=cbm --cpu=6502i --dsections=zp,2,256 text,2049,40960 ``` This would generate a `build.json` in the same folder as the executable with the contents: ```json { "listingOptions": { "listPath": "mylistfile.s" }, "loggingOptions": { "errorPath": "errors.txt" }, "outputFile": "myoutput.bin", "sources": [ "mysource.s", "/lib/mylib.s" ], "sections": { "zp": { "starts": 2, "ends": 256 }, "text": { "starts": 2049, "ends": 40960 } }, "target": { "binaryFormat": "cbm", "cpu": "6502i" } } ``` To save the build file under a different name, pass the `--build-file` option: ``` 6502.Net config --build-file=mproj.json source.s -o prog.prg ``` ## Disassemble command This command directs the assembler to act as a disassembler of a binary image. In this way behavior is opposite of assembly mode, where the expected input is a binary file whose output is a textual decoding of that binary into assembly code. The following will disassemble a Commodore program file into a disassembly listing: ``` 6502.Net disassemble myprog.prg -o myprog_disasm.txt ``` ### Disassemble options **`--cpu`, `-c`** Specify the CPU binary architecture of the input file to disassemble. **`--disassembly-offset`** Specify the offset in the input binary to begin disassembly. **`--disassembly-start`** Specify the start address of the disassembly output if the `--format` option is not set. **`--disassembly-end`** Specify the start address of the disasssembly output if the `--format` option is not set. **`--format`, `-f`** Specify the output format that the binary file conforms to. While disk/tape formats such as `d64` are not currently supported. ## Other Topics * [Getting Started](/Docs/GettingStarted.md) * [Memory And Addressing](/Docs/MemoryAndAddressing.md) * [CPU Specific Assembly](/Docs/CPUSpecificAssembly.md) * [Data Generation](/Docs/DataGeneration.md) * [Expressions](/Docs/Expressions.md) * [Symbols And Scopes](/Docs/SymbolsAndScopes.md) * [Built-In Symbols](/Docs/BuiltInSymbols.md) * [Output And Listings](/Docs/OutputAndListings.md) * [Control Assembly](/Docs/ControlAssembly.md) * [Macros](/Docs/Macros.md) * [File Inclusions](/Docs/FileInclusions.md) * [Diagnostics](/Docs/Diagnostics.md) * [Disassembler](/Docs/Disassembler.md)