
The Win32 NASM coding Toolkit v0.2
      Put Together by Gij
----------------------------------

I'm a great advocate of NASM, and i'd like to see more people use and support
the NASM project. After using it for a few months and trying to encourage people
on IRC to use it, I slowly realized that, for most people, NASM is missing some
important parts that are a standard part of the TASM package they usually use
as far as Win32 coding goes.
It's not the assembler itself that's missing features, but the needed Include 
files and a Linker.
I've researched these things in an effort to make NASM an easier development
platform for WIN32 Asm coding.

Hopefully, making the accompanying files needed for development available
freely will make coders everywhere move to NASM as their assembler of choice,
at least that's my motive in releasing this.

If you're new to Win32 asm coding, you should tknow hat this is not a good 
introduction to the subject, it's just meant to aid experienced coders in 
using NASM.

What's Included In The Toolkit
------------------------------

1) A Windows include file, win32n.inc I converted existing include files into 
   NASM syntax.
   I also converted the Structs defined in win.h, this is in a seperate file
   structs.inc , which has not been fully checked for errors for lack of time.
   Read the beginning of structs.inc for more info.

2) LCC-WIN32, an excellent free C compiler contains a linker named
   lcclnk.exe which links NASM generated obj's quite nicely.
   Unfortunately, as LCC-WIN32 is C-Oriented in design, the libraries contain
   API function names in a form easier to use for the compiler, not to an
   asm coder. The Maker of the LCC-WIN32 package has been kind enough to 
   include the files needed to recompile the libraries, so i wrote up a small
   perl script and a batch file to add easier to use API function names into the
   libraries ( '_MessageBoxA@16' becomes 'MessageBoxA' ).
   The new form names are added to the export list for each library, they do
   not replace them, because LCC-WIN32 depends internally on this exports 
   existing in the libraries .
   I've included the perl script, since the library files are quite large,
   instructions on how to use the script to make the new libraries are listed
   below.
   The linker is not included, since i have no rights over it, the address of
   LCC-WIN32's homepage is below.

3) A small example for using NASM and lcclnk.exe to make PE Files, In the
   "Example" Directory.

4) Intro.Txt , An Introduction to NASM syntax for ASM coders using TASM.


Preparing The Tools Needed For Using The Toolkit
---------------------------------- -------------

You need to Obtain Perl for Win32, NASM And LCC:

Perl: www.activestate.com

NASM: www.cryogen.com/nasm

      (Latest is 0.97 at the time of this writing )

LCC:  http://www.cs.virginia.edu/~lcc-win32/

Install all these packages. make sure the perl, nasm and LCC-WIN32 directories 
that contain the exe's are in your path, edit autoexec.bat if needed.

The next thing to do is to make new libraries for LCC, this might take a while,
but you only have to do it once, and it'll last you a lifetime :) .
Under your LCC-WIN32 directory is a directory named BUILDLIB, copy the the 
contents of the EXPMOD directory from this toolkit into that dir and run the 
batch file.
A directory named NASM will be created and inside it will be the new export
files that LCC-WIN32 will generate the libraries from. the bat file will then 
run the makefile and LCC-WIN32 should start compiling the new libraries.
When the compilation is done copy the new .lib files over the libraries in
LCC\LIB, you may back them up if you choose to. LCC-WIN32 should now be ready 
to link your nasm obj's.

Things you need to know about making PE exe's with NASM
-------------------------------------------------------

1) Although i got rid of the annoying appendixes to function names "i.e @16",
   LCC-WIN32 insists on you declaring your entry point as global and calling it
   "_WinMain@16", this way, LCC-WIN32 links in it's stub which sets up the 
   command line and other things for you.
   if you wish to avoid having a stub appended to your code, name your entry
   point _main, and declare it global, and your code will be the first to
   receive control after loading.

2) When assembling asm files with nasm use the object type "win32", this is
   the object format lcclnk.exe understands.
   example: "nasm.exe -f win32 file.asm"

3) You can include the accompanying INC files by putting this in your code:
   ' %include "filename.ext" '.

4) The LCC-WIN32 linker includes some symbol information in your exe by default,
   this can add a lot of useless bytes to your EXE's.
   use the -s switch to tell lcclnk to strip all symbol information.

5) Lcclnk.exe makes console mode exe's by default, if you wish to make real
   GUI exe's, you need to include this command line switch:
   "lcclnk.exe -subsystem 2"

6) You need to declare API functions you CALL as external, see attached code
   for example

7) it's good practice to use the CLASS part of the segment directive to specify
   segment type, CODE/DATA.

That's about all You need, now take a look at the demo code, and read the LCC
and NASM docs for more information.


Should you need to contact me, my e-mail is gij <at> iname.com.
Enjoy.
