ca65-10.html

cc65 的编译器文档

<H2><A NAME=".INCBIN"></A> <A NAME="ss10.59">10.59</A> <A HREF="ca65.html#toc10.59"><CODE>.INCBIN</CODE></A>
</H2>


<P>Include a file as binary data. The command expects a string argument
that is the name of a file to include literally in the current segment.
In addition to that, a start offset and a size value may be specified,
separated by commas. If no size is specified, all of the file from the
start offset to end-of-file is used. If no start position is specified
either, zero is assume (which means that the whole file is inserted).</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        ; Include whole file
        .incbin         "sprites.dat"

        ; Include file starting at offset 256
        .incbin         "music.dat", $100

        ; Read 100 bytes starting at offset 200
        .incbin         "graphics.dat", 200, 100
  
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME=".INCLUDE"></A> <A NAME="ss10.60">10.60</A> <A HREF="ca65.html#toc10.60"><CODE>.INCLUDE</CODE></A>
</H2>


<P>Include another file. Include files may be nested up to a depth of 16.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .include        "subs.inc"
  
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME=".LINECONT"></A> <A NAME="ss10.61">10.61</A> <A HREF="ca65.html#toc10.61"><CODE>.LINECONT</CODE></A>
</H2>


<P>Switch on or off line continuations using the backslash character
before a newline. The option is off by default.
Note: Line continuations do not work in a comment. A backslash at the
end of a comment is treated as part of the comment and does not trigger
line continuation.
The command must be followed by a '+' or '-' character to switch the
option on or off respectively.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .linecont       +               ; Allow line continuations

        lda     \
                #$20                    ; This is legal now
  
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME=".LIST"></A> <A NAME="ss10.62">10.62</A> <A HREF="ca65.html#toc10.62"><CODE>.LIST</CODE></A>
</H2>


<P>Enable output to the listing. The command must be followed by a boolean
switch ("on", "off", "+" or "-") and will enable or disable listing
output.
The option has no effect if the listing is not enabled by the command line
switch -l. If -l is used, an internal counter is set to 1. Lines are output
to the listing file, if the counter is greater than zero, and suppressed if
the counter is zero. Each use of <CODE>.LIST</CODE> will increment or decrement the
counter.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .list   on              ; Enable listing output
  
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME=".LISTBYTES"></A> <A NAME="ss10.63">10.63</A> <A HREF="ca65.html#toc10.63"><CODE>.LISTBYTES</CODE></A>
</H2>


<P>Set, how many bytes are shown in the listing for one source line. The
default is 12, so the listing will show only the first 12 bytes for any
source line that generates more than 12 bytes of code or data.
The directive needs an argument, which is either "unlimited", or an
integer constant in the range 4..255.</P>
<P>Examples:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .listbytes      unlimited       ; List all bytes
        .listbytes      12              ; List the first 12 bytes
        .incbin         "data.bin"      ; Include large binary file
  
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME=".LOCAL"></A> <A NAME="ss10.64">10.64</A> <A HREF="ca65.html#toc10.64"><CODE>.LOCAL</CODE></A>
</H2>


<P>This command may only be used inside a macro definition. It declares a
list of identifiers as local to the macro expansion.</P>
<P>A problem when using macros are labels: Since they don't change their name,
you get a "duplicate symbol" error if the macro is expanded the second time.
Labels declared with <CODE>
<A HREF="#.LOCAL">.LOCAL</A></CODE> have their
name mapped to an internal unique name (<CODE>___ABCD__</CODE>) with each macro
invocation.</P>
<P>Some other assemblers start a new lexical block inside a macro expansion.
This has some drawbacks however, since that will not allow <EM>any</EM> symbol
to be visible outside a macro, a feature that is sometimes useful. The
<CODE>
<A HREF="#.LOCAL">.LOCAL</A></CODE> command is in my eyes a better way
to address the problem.</P>
<P>You get an error when using <CODE>
<A HREF="#.LOCAL">.LOCAL</A></CODE> outside
a macro.</P>


<H2><A NAME=".LOCALCHAR"></A> <A NAME="ss10.65">10.65</A> <A HREF="ca65.html#toc10.65"><CODE>.LOCALCHAR</CODE></A>
</H2>


<P>Defines the character that start "cheap" local labels. You may use one
of '@' and '?' as start character. The default is '@'.</P>
<P>Cheap local labels are labels that are visible only between two non
cheap labels. This way you can reuse identifiers like "<CODE>loop</CODE>" without
using explicit lexical nesting.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .localchar      '?'

        Clear:  lda     #$00            ; Global label
        ?Loop:  sta     Mem,y           ; Local label
                dey
                bne     ?Loop           ; Ok
                rts
        Sub:    ...                     ; New global label
                bne     ?Loop           ; ERROR: Unknown identifier!
  
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME=".MACPACK"></A> <A NAME="ss10.66">10.66</A> <A HREF="ca65.html#toc10.66"><CODE>.MACPACK</CODE></A>
</H2>


<P>Insert a predefined macro package. The command is followed by an
identifier specifying the macro package to insert. Available macro
packages are:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        generic         Defines generic macros like add and sub.
        longbranch      Defines conditional long jump macros.
        cbm             Defines the scrcode macro
        cpu             Defines constants for the .CPU variable
  
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Including a macro package twice, or including a macro package that
redefines already existing macros will lead to an error.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .macpack        longbranch      ; Include macro package

                cmp     #$20            ; Set condition codes
                jne     Label           ; Jump long on condition
  
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Macro packages are explained in more detail in section 
<A HREF="ca65-12.html#macropackages">Macro packages</A>.</P>


<H2><A NAME=".MAC"></A> <A NAME="ss10.67">10.67</A> <A HREF="ca65.html#toc10.67"><CODE>.MAC, .MACRO</CODE></A>
</H2>


<P>Start a classic macro definition. The command is followed by an identifier
(the macro name) and optionally by a comma separated list of identifiers
that are macro parameters.</P>
<P>See section 
<A HREF="ca65-11.html#macros">Macros</A>.</P>


<H2><A NAME=".ORG"></A> <A NAME="ss10.68">10.68</A> <A HREF="ca65.html#toc10.68"><CODE>.ORG</CODE></A>
</H2>


<P>Start a section of absolute code. The command is followed by a constant
expression that gives the new PC counter location for which the code is
assembled. Use <CODE>
<A HREF="#.RELOC">.RELOC</A></CODE> to switch back to
relocatable code.</P>
<P>Please note that you <EM>do not need</EM> this command in most cases. Placing
code at a specific address is the job of the linker, not the assembler, so
there is usually no reason to assemble code to a specific address.</P>
<P>You may not switch segments while inside a section of absolute code.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .org    $7FF            ; Emit code starting at $7FF
  
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME=".OUT"></A> <A NAME="ss10.69">10.69</A> <A HREF="ca65.html#toc10.69"><CODE>.OUT</CODE></A>
</H2>


<P>Output a string to the console without producing an error. This command
is similiar to <CODE>.ERROR</CODE>, however, it does not force an assembler error
that prevents the creation of an object file.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .out    "This code was written by the codebuster(tm)"
  
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>See also the <CODE>
<A HREF="#.WARNING">.WARNING</A></CODE> and <CODE>
<A HREF="#.ERROR">.ERROR</A></CODE> directives.</P>


<H2><A NAME=".P02"></A> <A NAME="ss10.70">10.70</A> <A HREF="ca65.html#toc10.70"><CODE>.P02</CODE></A>
</H2>


<P>Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816
instructions. This is the default if not overridden by the
<CODE>
<A HREF="ca65-2.html#option--cpu">--cpu</A></CODE> command line option.</P>
<P>See: <CODE>
<A HREF="#.PC02">.PC02</A></CODE>, <CODE>
<A HREF="#.PSC02">.PSC02</A></CODE> and <CODE>
<A HREF="#.P816">.P816</A></CODE></P>


<H2><A NAME=".P816"></A> <A NAME="ss10.71">10.71</A> <A HREF="ca65.html#toc10.71"><CODE>.P816</CODE></A>
</H2>


<P>Enable the 65816 instruction set. This is a superset of the 65SC02 and
6502 instruction sets.</P>
<P>See: <CODE>
<A HREF="#.P02">.P02</A></CODE>, <CODE>
<A HREF="#.PSC02">.PSC02</A></CODE> and <CODE>
<A HREF="#.PC02">.PC02</A></CODE></P>


<H2><A NAME=".PAGELENGTH"></A> <A NAME="ss10.72">10.72</A> <A HREF="ca65.html#toc10.72"><CODE>.PAGELEN, .PAGELENGTH</CODE></A>
</H2>


<P>Set the page length for the listing. Must be followed by an integer
constant. The value may be "unlimited", or in the range 32 to 127. The
statement has no effect if no listing is generated. The default value is -1
(unlimited) but may be overridden by the <CODE>--pagelength</CODE> command line
option. Beware: Since ca65 is a one pass assembler, the listing is generated
after assembly is complete, you cannot use multiple line lengths with one
source. Instead, the value set with the last <CODE>.PAGELENGTH</CODE> is used.</P>
<P>Examples:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .pagelength     66              ; Use 66 lines per listing page

        .pagelength     unlimited       ; Unlimited page length
  
</PRE>
</CODE></BLOCKQUOTE>
</P>


<H2><A NAME=".PC02"></A> <A NAME="ss10.73">10.73</A> <A HREF="ca65.html#toc10.73"><CODE>.PC02</CODE></A>
</H2>


<P>Enable the 65C02 instructions set. This instruction set includes all
6502 and 65SC02 instructions.</P>
<P>See: <CODE>
<A HREF="#.P02">.P02</A></CODE>, <CODE>
<A HREF="#.PSC02">.PSC02</A></CODE> and <CODE>
<A HREF="#.P816">.P816</A></CODE></P>


<H2><A NAME=".POPSEG"></A> <A NAME="ss10.74">10.74</A> <A HREF="ca65.html#toc10.74"><CODE>.POPSEG</CODE></A>
</H2>


<P>Pop the last pushed segment from the stack, and set it.</P>
<P>This command will switch back to the segment that was last pushed onto the
segment stack using the <CODE>
<A HREF="#.PUSHSEG">.PUSHSEG</A></CODE>
command, and remove this entry from the stack.</P>
<P>The assembler will print an error message if the segment stack is empty
when this command is issued.</P>
<P>See: <CODE>
<A HREF="#.PUSHSEG">.PUSHSEG</A></CODE></P>


<H2><A NAME=".PROC"></A> <A NAME="ss10.75">10.75</A> <A HREF="ca65.html#toc10.75"><CODE>.PROC</CODE></A>
</H2>


<P>Start a nested lexical level with the given name and adds a symbol with this
name to the enclosing scope. All new symbols from now on are in the local
lexical level and are accessible from outside only via 
<A HREF="ca65-6.html#scopesyntax">explicit scope specification</A>. Symbols defined outside this local
level may be accessed as long as their names are not used for new symbols
inside the level. Symbols names in other lexical levels do not clash, so you
may use the same names for identifiers. The lexical level ends when the
<CODE>
<A HREF="#.ENDPROC">.ENDPROC</A></CODE> command is read. Lexical levels
may be nested up to a depth of 16 (this is an artificial limit to protect
against errors in the source).</P>
<P>Note: Macro names are always in the global level and in a separate name
space. There is no special reason for this, it's just that I've never
had any need for local macro definitions.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
        .proc   Clear           ; Define Clear subroutine, start new level
                lda     #$00
        L1:     sta     Mem,y   ; L1 is local and does not cause a
                                ; duplicate symbol error if used in other
                                ; places
                dey
                bne     L1      ; Reference local symbol
                rts
        .endproc                ; Leave lexical level
  
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>See: <CODE>
<A HREF="#.ENDPROC">.ENDPROC</A></CODE> and <CODE>
<A HREF="#.SCOPE">.SCOPE</A></CODE></P>


<H2><A NAME=".PSC02"></A> <A NAME="ss10.76">10.76</A> <A HREF="ca65.html#toc10.76"><CODE>.PSC02</CODE></A>
</H2>


<P>Enable the 65SC02 instructions set. This instruction set includes all
6502 instructions.</P>
<P>See: <CODE>
<A HREF="#.P02">.P02</A></CODE>, <CODE>
<A HREF="#.PC02">.PC02</A></CODE> and <CODE>
<A HREF="#.P816">.P816</A></CODE></P>