Win32 Programming with NASM - Making

0. Introduction
1. Overview
2. Assembling
3. Linker options
4. Linking - GUI application, no resources
5. Linking - Console application, no resources
6. Linking - DLL creation
7. Linking - GUI application with DLL
8. Linking - Adding resources

Introduction
    This document describes how to assemble and link your source code to
    produce Win32 executables.

Overview
    Generating a Win32 executable consists of two steps - assembling your
    source code (which produces object files) and then linking the
    object files to produce an executable.

Assembling
    To assemble your code, you'll need to use NASM 0.98 or later, and
    you should assemble your code via:

        nasmw -f win32 source.asm

Linker options
    The linker has a lot of different options, I'll only cover the relevant
    ones here though:

      o /DEFAULTLIB:library
        This is used to specify a library to link in. If you use EXTERN to
        define a function not in your source files, you'll need to link in
        the relevant library. All the core libraries are automagically
        linked in, so you'll probably not need to use this option at first.

      o /DLL
        Specify this option if you want to create a DLL rather than an
        executable.

      o /DEF:filename
        Specifies the definitions (.def) file when you're creating a DLL.

      o /ENTRY:symbol
        This is used to specify where your program should start. For example,
        if you defined a label _WinMain as being GLOBAL in your source file
        and wanted this to be the start of your program, you'd add
        /ENTRY:WinMain as a linker option. Notice that the leading underscore
        in the source file _isn't_ specified in the linker option.

      o /LIBPATH:directory
        Specifies where all the library files (*.lib) can be found.

      o /SUBSYSTEM:WINDOWS or CONSOLE
        Use this to specify whether your program is a Windows (ie GUI) or a
        console application. (Note that there are other choices for this
        but they're not relevant to us).

    A use of these options might be:

      link /entry:WinMain /libpath:c:\libs /subsystem:windows source.obj

    In the following sections, I will assume WinMain as the program's start
    point, c:\libs as being where the .lib files are and source.obj as being
    the object file to link. Obviously, you'll have to tailor these to your
    own system.

Linking - GUI application, no resources
    link /entry:WinMain /libpath:c:\libs /subsystem:windows source.obj

Linking - Console application, no resources
    link /entry:main /libpath:c:\libs /subsystem:console source.obj

    Note that for a console application, the entry point is usually defined
    as _main in the source for historical reasons.

Linking - DLL creation
    link /entry:DllMain /libpath:c:\libs /subsystem:console /dll /def:c:\dll.def source.obj

    When linking a DLL an extra parameter (/dll) is added to show we want
    a DLL outputted, and another (/def) to tell it where the definitions file
    for the DLL is. A definitions file looks like:

    ----Begin file----
    LIBRARY Dll
    EXPORTS
        _Function1@0
        _Function2@0
    ----End File----

    The Dll on the first line is the name of the library, and every line
    after the EXPORTS line is a label (defined as GLOBAL in your source
    file) that is to be made available to other files. Ie each line holds
    the name of each function in your DLL.

    After linking, you will get a .DLL file and also a .LIB file which can
    be used in other applications when you want to link in your DLL and
    need the library file to link it in. This all probably sounds horribly
    complex, but don't worry check out the DLL example and play around with
    assembling and linking it to make the demo and you'll soon get the
    hang of things.

Linking - GUI application with DLL
    link /entry:WinMain /libpath:c:\libs /subsystem:windows /defaultlib:Dll.lib source.obj

    Change Dll.lib to whatever your dll is called. If you have several DLLs
    to link in, use several /defaultlib:<dll name>.lib to specify them.

Linking - Adding resources
    link <link parameters> resource.res

    Linking resources into an executable merely requires adding the name of
    the resource file to add to the command line. You can add several
    resource files to an executable.
