yasm/Mkfiles/vc8/readme.vc8.txt

Building YASM with Microsoft Visual Studio 2005

-----------------------------------------------



This note describes how to build YASM using Microsoft Visual Studio 2005.



1. The Compiler

---------------



If you want to build the 64-bit version of YASM you will need to install

the Visual Studio 2005 64-bit tools, which are not installed by default.



2. YASM Download

----------------



The following files are not built by default on VC++ and are not contained

in the YASM subversion repository (but they are included in the nightly

YASM snapshots):



    gas-bison.c

    gas-bison.h

    nasm-bison.c

    nasm-bison.h

    re2c-parser.c

    re2c-parser.h



However, if you want to build these files from source, follow these step:

  1) Install bison.  This can be done in a number of ways, the easiest is

     probably to download and run the Win32 Bison Setup program from

     http://gnuwin32.sourceforge.net/packages/bison.htm

  2) In Visual Studio, go to Tools|Options,

     Projects and Solutions|VC++ Directories, and add the directory where

     you installed Bison to the list of directories.

  3) For each of the .y files in the build, right click, select Properties,

     and change the "Excluded From Build" setting to No.  These files are:

     re2c/Source Files/re2c-parser.y

     modules/Source Files/gas-bison.y

     modules/Source Files/nasm-bison.y



If you wish to build from the latest files in the subversion repository,

you will need to add these files from the latest snapshot to the repository

files. They should be placed in the YASM root directory.



3. Building YASM with Microsoft VC8

-----------------------------------



First YASM needs to be downloaded and the files placed within a suitable

directory, which will be called <yasm> here but can be named and located

as you wish. If the Visual Studio 2005 project files have been obtained

seperately the subdirectory 'vc8' and its subdirectories and files need to

be placed in the 'Mkfiles' subdirectory within the YASM root directory.



If building from the subversion repository, obtain the additional files

discussed above and place them in the YASM root directory.



Now locate and double click on the yasm.sln solution file in the 'Mkfiles/vc8'

subdirectory to open the build project in the Visual Studio 2005 IDE and then

select:



    win32 or x64 build

    release or debug build



as appropriate to build the YASM binaries that you need.



4. Using YASM with Visual Sudio 2005 and VC++ version 8

-------------------------------------------------------



1. Firstly you need to locate the directory (or directories) where the VC++

compiler binaries are located and put copies of the appropriate yasm.exe

binary in these directories.



On a win32 system you will use the win32 version of YASM. On an x64 system

you can use either the 32 or the 64 bit versions.  The win32 YASM binary

should be placed in the 32-bit VC++ binary directory, which is typically

located at:



 Program Files (x86)\Microsoft Visual Studio 8\VC\bin



If needed the 64-bit YASM binary should be places in the 64-bit tools

binary directory, which is typically at:



 Program Files\Microsoft Visual Studio 8\VC\bin



2. To use the new custom tools facility in Visual Studio 2005, you need to

place a copy of the yasm.rules file in the Visual Studio 2005 VC project

defaults directory, which is typically located at:



 Program Files (x86)\Microsoft Visual Studio 8\VC\VCProjectDefaults



This allows you to configure YASM as an assembler within the VC++ IDE. To

use YASM in a project, right click on the project in the Solution Explorer

and select 'Custom Build Rules..'. This will give you a dialog box that

allows you to select YASM as an assembler (note that your assembler files

need to have the extension '.asm').



To assemble a file with YASM, select the Property Page for the file and the

select 'Yasm Assembler' in the Tool dialog entry. Then click 'Apply' and an

additional property page entry will appear and enable YASM settings to be

established.



As alternative to placing the yasm.rules files as described above is to set

the rules file path in the Visual Studio 2005 settings dialogue.



It is also important to note that the rules file passes the symbols 'Win32'

or 'x64' to YASM by using the Visual Studio 2005  $(PlatformName) macro in

order to obtain either a 32 or a 64 bit assembler mode. This is a recent

enhancement to YASM so you will need to be sure that your YASM files are at

revision r1331 or higher to use this facility.



5. A Linker Issue

-----------------



There appears to be a linker bug in the VC++ v8 linker that prevents symbols

with absolute addresses being linked in DLL builds.  This means, for example,

that LEA instructions of the general form:



   lea, rax,[rax+symbol]



cannot be used for DLL builds.  The following general form has to be used

instead:



   lea rcx,[symbol wrt rip]

   lea rax,[rax+rcx]



This limitation may also cause problems with other instruction that use

absolute addresses.



I am most grateful for the fantastic support that Peter Johnson, YASM's

creator, has given me in tracking down this issue.



  Brian Gladman, 16th January 2006