
.. Due to something, the manpages generated by sphnix do not display the
   (sub)sections UNLESS there is a !(sub)section defined. Luckly, that
   !(sub)section is invisible in the manpage.
   Sphinx (sphinx-build) 1.2.3 & 1.4.5

.. We take advantage to that fact to put manpages with the correct title
   in other documents, but this means that we are relying on a bug.

Manpage: WLA-LINK
=================


SYNOPSIS
--------

| ``wlalink`` [``OPTIONS``] ``LINK_FILE`` ``OUTPUT_FILE``


OPTIONS
-------

-b          Program file output
-d          Discard unreferenced sections
-g          Write one combined list file per object file (implies ``-i``)
-i          Write list files (Note: WLA needs ``-i`` as wel)
-r          ROM file output (default)
-s          Write also a NO$GMB/NO$SNES symbol file
-S          Write also a WLA symbol file
-A          Add address-to-line mapping data to WLA symbol file
-E LIST     Write debug exports. Supported formats: VICE, RGBDS, MESEN,
            EMULICIOUS, CSPECT, NOCASH, MAME and JSON
-v          Verbose messages
-L LIBDIR   Look in LIBDIR for libaries before looking in CWD
-t TYPE     Output type (supported types: 'CBMPRG', 'C64CRT')

\-64 TYPE   Cartridge type for C64CRT output

-a ADDR     Load address for CBM PRG

Choose one:

-b OUT      Program file linking
-r OUT      ROM image linking


DESCRIPTION
-----------

:manpage:`wlalink(1)` is a part of WLA-DX. It links one or more object files
(and perhaps some library files) together to produce a ROM image / program file.

LINK_FILE is a text file that contains information about the files you want
to link together. Here's the format:

1. You must define the group for the files. Put the name of the group
   inside brackets. Valid group definitions are ::
       
        [objects]
        [libraries]
        [header]
        [footer]
        [definitions]

2. Start to list the file names. ::
    
        [objects]
        main.o
        vbi.o
        level_01.o
        ...

3. Give parameters to the library files::
   
        [libraries]
        bank 0 slot 1 speed.lib
        bank 4 slot 2 map_data.lib
        ...

   Here you can also use ``base`` to define the 65816 CPU bank number
   (like ``.BASE`` works in WLA)::
   
       [libraries]
       bank 0 slot 1 base $80 speed.lib
       bank 4 slot 2 base $80 map_data.lib
       ...

   You must tell WLALINK the bank and the slot for the library files.

4. If you want to use header and/or footer in your project,
   you can type the following::
   
        [header]
        header.dat
        [footer]
        footer.dat

5. If you want to make value definitions, here's your chance::
   
        [definitions]
        debug 1
        max_str_len 128
        start $150
        ...

If flag ``-i`` is given, :manpage:`wlalink(1)` will write list files. Note that
you must compile the object and library files with ``-i`` flag as well.
Otherwise :manpage:`wlalink(1)` has no extra information it needs to build list
files.

If flag ``-g`` is given, one combined list file is written per object file next
to that object file, with included files shown at the point where they are
included. This flag implies ``-i``.

The ``-E`` option writes debug exports for emulators and tools. The format list
can be comma- or space-separated. The ``MAME`` format writes a debugger command
file that can be loaded with MAME's ``source`` debugger command.

The ``-64`` option selects the cartridge type when linking ``-t C64CRT`` output.

Here is an example of a list file: Let's assume you've compiled a source file
called ``main.s`` using the ``-i`` flag. After you've linked the result also
with the ``-i`` flag :manpage:`wlalink(1)` has created a list file called
``main.lst``. This file contains the source text and the result data the source
compiled into. List files are good for debugging.

Make sure you don't create duplicate labels in different places in the
memory map as they break the linking loop. Duplicate labels are allowed when
they overlap each other in the destination machine's memory.


EXAMPLES
--------

::

    wlalink -r linkfile testa.sfc
    wlalink -d -i -b linkfile testb.sfc
    wlalink -v -S -L ../../lib linkfile testc.sfc
    wlalink -v -i -E mame,json linkfile testd.sfc

.. only:: man

    SEE ALSO
    --------

    :manpage:`wla-dx(7)`
