linking

###LINKING

x65 supports linking of fully assembled object files into a single larger project. This is a fairly standard feature of compilers but supporting both common 68000 linking style and Apple II Merlin style means that x65 is not quite as straightforward.

The purpose of a linked project is to work in multiple source files without worrying about where in memory each file gets compiled to. In addition sections of code and data in a single file can be linked to different target locations. Each source file gets assembled to an object file (.x65) and all the internal and external references are stored separately from the binary code to be fixed up later.

The last step of a linked project is to load all object files and generate one or more exported programs. A special source file uses the INCOBJ directive to bring in object files one by one and piled up by using the LINK at a fixed address.

The SECTION directive starts a block of code or data to be linked later. By default x65 creates a section named "default" which can be used for linking as is but is intended to be replaced.

XDEF declares a label in a file as external and available to other files in the project

XREF references an external label in the same projects.

Example:

file1.s

XDEF GetValue

SECTION Code

GetValue {
    lda values,x
    rts
}

SECTION Data

values
    BYTE 8,7,6,5,4,3,2,1

file2.s

XREF GetValue
XDEF GetValue_x2

SECTION Code
GetValue_x2 {
    jsr GetValue
    asl
    rts
}

main.s

INCOBJ file1.x65
INCOBJ file2.x65

XREF GetValue_x2

SECTION Main
ORG $1000
    ldx #3
    jsr GetValue_x2
    rts

LINK Code
LINK Data

##EXPORTING

x65 allows a single project to emit multiple binary files which makes sense for loading overlay code into the same memory area. EXPORT Appends a string to the output filename for a given section.

SECTION Main
ORG $1000

LINK MainCode
LINK MainData

MainEnd:

Section Level1
ORG MainEnd
EXPORT Level1
LINK Level1Code
LINK Level1Data

Section Level2
ORG MainEnd
EXPORT Level2
LINK Level2Code
LINK Level2Data

##RELOCATABLE EXECUTABLE

Work is progressing on Apple II OMF executable support, this requires some additional decoration of sections.