|Getting Started with MASM and Visual Studio 2013|
Updated 5/6/2015This tutorial assumes that you are using the Seventh Edition of Assembly Language for x86 Processors. We show you how to set up Visual Studio 2013 (including Visual Studio 2013 Express for Windows Desktop, and Visual Studio Community 2013 edition) to work with the Microsoft assembler. Visual Studio 2013 Express and Visual Studio Community 2013 may be downloaded from Microsoft.com. (Note: the directions shown here are not designed for use with "Visual Studio Express 2013 for Windows" That product is designed for creating Windows Store apps in Visual Basic and C#.) Topics:
Required Setup for 32-bit ApplicationsFirst, you must install Visual Studio and select the C++ language configuration option the first time you run it. All versions of Visual Studio include the Microsoft Assembler (MASM) version 12.0. You can verify that the Microsoft Assembler is installed by looking for the file ml.exe in the \vc\bin folder of your Visual Studio installation directory, such as c:\Program Files\Microsoft Visual Studio 12.0\vc\bin.
Installing the Book's Example Programs
Click this link to get the latest copy of the book's link libraries and example programs. The examples are stored in a Microsoft Install (.MSI) file that installs into the c:\Irvine folder. Unless you have some objection to using that location, do not alter the path. (Note to lab administrators: you can designate c:\Irvine directory as read-only.) If you plan to change the installation location, read our instructions relating to Creating a Project from Scratch.
The folllowing files will be copied into the c:\Irvine directory:
A subdirectory named Examples will contain all the example programs shown in the book, source code for the book's 16-, 32-, and 64-bit libraries, and two sample Visual Studio projects.
Setting up Visual StudioYou will only have to do these steps the first time you use Visual Studio.
Add the Start Without Debugging command to the Debug menu
It's very useful to run programs without having to debug them. To do that, you will want to add a new command to the Debug menu: Start Without Debugging. Here's how to do it:
In fact, you can use the same sequence to customize any of the menus and toolbars in Visual Studio.
Select the C++ Configuration(Skip this topic if you installed Visual Studio Express.) Visual Studio Professional, Ultimate, and Premium editions support multiple programming languages and application types. The C++ programming language configuration most closely matches that of assembly language programming, so we suggest the following steps:
Set the Tab Size to 5(This is an optional step.) Start Visual Studio, and select Options from the Tools menu. Select Text Editor, Select All Languages, and select Tabs. Optionally, you may want to select the Insert spaces radio button:
Set the Tab Size and Indent Size to 5.
Tutorial: Building a 32-Bit Assembly Language ProgramNow you're ready to open and build your first 32-bit project.
Opening a Project
Visual Studio requires assembly language source files to belong to a project, which is a kind of container. A project holds configuration information such as the locations of the assembler, linker, and required libraries. A project has its own folder, and it holds the names and locations of all files belonging to it. We have created a sample project folder in the c:\Irvine\examples directory, and its name is Project32.
Do the following steps, in order:
You should see the following program in the editor window:
In the future, you can use this file as a starting point to create new programs by copying it and renaming the copy in the Solution Explorer window.
Build the Program
Now you will build (assemble and link) the sample program. Select Build Project from the Build menu. In the Output window for Visual Studio at the bottom of the screen, you should see messages similar to the following, indicating the build progress:
If you do not see these messages, the project has probably not been modified since it was last built. No problem--just select Rebuild Project from the Build menu.
Run the Program
Select Start without Debugging from the Debug menu. The following console window should appear, although your window will be larger than the one shown here:
The "Press any key to continue..." message is automatically generated by Visual Studio.
Congratulations, you have just run your first Assembly Language program!
Press any key to close the Console window.
Any time you want to remove a source file from the Visual Studio window, right-click its filename and select Remove. The file will not be deleted from the file system. On the other hand, if you want to delete the file, select it and press the Del key.
Step 5: Running the Sample Program in Debug Mode
In this step, you set a breakpoint inside the sample program. Then you use the Visual Studio debugger to step through the program's execution one statement at a time.
If you want to display the CPU registers, do the following: Start debugging the program, then select Windows from the Debug menu. Select Registers from the drop-down list. The Registers window may appear at the bottom of the workspace, as a tab highlighted in yellow. Use the mouse to drag the window to the right side of the work area. Right click inside the Registers window and check the item Flags to enable the display of CPU status flags.
You can interrupt a debugging session at any time by selecting Stop Debugging from the Debug menu. You can do the same by clicking the maroon-colored square button on the toolbar. To remove a breakpoint from the program, click on its red dot to make it disappear.
Setting a BreakPoint
If you set a breakpoint in a program, you can use the debugger to execute the program a full speed (more or less) until it reaches the breakpoint. At that point, the debugger drops into single-step mode.
You can remove a breakpoint by clicking its red dot with the mouse. Take a few minutes to experiment with the Debug menu commands. Set more breakpoints and run the program again. For the time being, you can use the F11 key to step through the program in the same way the F10 key did.
Building and Running Other Programs
Suppose you want to run another example program, or possibly create your own program. You can remove the existing assembly language file from the Solution Explorer window and insert a new .asm file into the project.
Adding a File to a Project
An easy way to add an assembly language source file to an open project is to drag its filename with the mouse from a Windows Explorer window onto the name of your project in the Solution Explorer window. The physical file will not be copied--the project only holds a reference to the file's location. Try this now:
Copying a Source File
One way to make a copy of an existing source code file is to use Windows Explorer to copy the file into your project directory. Then, right-click the project name in Solution Explorer, select Add, select Existing Item, and select the filename.
Tutorial: Building and Running a 64-Bit ProgramIn this tutorial, we will show you how to assemble, link, and run a sample 64-bit program. We assume you have already completed our tutorial entitled Building a 32-Bit Assembly Language Program.
Do the following steps, in order:
You should see the following program in the editor window:
; AddTwoSum_64.asm - Chapter 3 example. ExitProcess proto .data sum qword 0 .code main proc mov rax,5 add rax,6 mov sum,rax mov ecx,0 call ExitProcess main endp end
Build the ProgramSelect Build Project from the Build menu. You should see text written to Visual Studio's output window like the following:
1>------ Build started: Project: Project64, Configuration: Debug Win64 ------ 1> Assembling ..\ch03\64 bit\AddTwoSum_64.asm... 1> Project64.vcxproj -> D:\ASM Book Examples\Project64\Debug\Project64.exe ========== Rebuild All: 1 succeeded, 0 failed, 0 skipped ==========If you do not see these messages, the project has probably not been modified since it was last built. No problem--just select Rebuild Project from the Build menu. You use the same Visual Studio commands to run and debug 64-bit programs as you would for 32-bit programs.
Only Chapters 14 through 17 require you to build 16-bit applications. Except for a few exceptions, which are noted in the book, your 16-bit applications will run under the 32-bit versions of Windows (XP, Vista, 7). But 16-bit applications will not run directly in any 64-bit version of Windows.
If you plan to build 16-bit applications, you need to add two new commands to the Visual Studio Tools menu. To add a command, select External Tools from the Tools menu. The following dialog will appear, although many of the items in your list on the left side will be missing. The filename in the sample image (make16.bat) has been replaced by two files:
Step 1: Create the Build 16-bit ASM Command
Click the Add button and fill in the Title, Command, Arguments, and Initial directory fields as shown in the screen snapshot. If you click the buttons with arrows on the right side of the Arguments and Initial directory fields, a convenient list appears. You can select an item without having to worry about spelling:
Click the Apply button to save the command.
Step 2: Create the Run 16-bit ASM Command
Click the Add button again, and create a new command named Run 16-bit ASM:
Uncheck the "Close on exit" option and click the OK button to save the command and close the External Tools dialog.
Testing Your new 16-Bit Commands
To test your new 16-bit commands, close any Visual Studio project that happens to be open. Then, select File | Open | File from the menu and choose the file named 16-bit.asm from the ch03 folder in the book's example programs. Select Build 16-bit ASM from the Tools menu. The following command window should appear, showing the successful execution of the assembler and linker, followed by a listing of all files related to this program:
Press a key to close the window. Next, you will run the program. Select Run 16-bit ASM from the Tools menu. The following window will appear, although the contents of all registers except EAX will be different:
Press a key to close the window.
You have completed the setup for building and running 16-bit assembly language programs.
Creating a Project From Scratch
Visual Studio makes it possible (in 12 easy steps) to create an Assembly Language project from scratch. In the first step, you will create a Win32 Console application designed for C++, and just modify the custom build rules.
Step 1: Select New from the File menu, then select Project. In the New Project window, select Win32 under Visual C++ in the left panel, and select Win32 Console Application in the middle panel. Give your project a suitable name (near the bottom of the window):
(Depending on your Visual Studio configuration, you might have to find Visual C++ under the "Other Languages" category in the left panel.)
Step 2: Click the OK button to continue. The Win32 Application Wizard window will appear. Select Application Settings, and then select the Empty project check box.
Step 3: Click the Finish button to save the new project. Step 4: In the Solution Explorer window, delete the Header Files, Resource Files, and Source Files folders. They are not necessary. In the same window, right click your project name and select Build Customizations from the popup menu. When you see this window, select the check box next to masm and click the OK button to close the dialog. Step 5: Select Properties from the Project menu. Expand the entry under Configuration Properties. Then expand the entry named Microsoft Macro Assembler. This is what you should see:
Step 6: Modify the Include Paths option so it equals "C:\Irvine". This tells the assembler where to find files having a filename extension of ".inc". Here is a sample:
Step 7: Next, select the Listing File entry, also in the Microsoft Macro Assembler group. Modify the Assembled Code Listing File entry (shown below) so it contains $(ProjectName).lst. This uses a built-in variable to identify the name of the source input file, with a file extension of .lst. So, if your program were named main.asm, the listing file would be named main.lst:
Step 8: Find the Linker entry under Configuration Properties. Select the Input entry, and insert irvine32.lib; at the beginning of the Additional Dependencies entry. The irvine32.lib file is the link library file supplied with this book. The filenames must be separated by semicolons.
Step 9: Select Linker under Configuration Properties, and then select General. The Additional Library Directories entry must contain c:\Irvine so the linker can find the Irvine32.lib library file:
Step 10: Select Linker under the Configuration Properties and select Debugging. Verify that the Generate Debug Info option is equal to Yes:
Step 11: Select Advanced under the Linker entry. Set the Image Has Safe Exception Handlers option to No.
Step 12: Click the OK button to close the Property Pages window. Verify that your project has been created correctly by doing the following: (1) Add the AddTwo.asm program from the Chapter 3 examples folder to the project; (2) Build and debug the program as you did earlier in this tutorial. Return to top
Return to top
When a text editor uses syntax highlighting, language keywords, strings, and other elements appear in different colors. Visual Studio highlights MASM reserved words and strings, as shown in the following example:
This won't happen automatically, but you can create a syntax definition file named Usertype.dat that contains MASM keywords. Then when Visual Studio starts, it reads the syntax file and highlights MASM keywords.
Here are the required steps to set up MASM syntax highlighting:
1) Download the Usertype.dat file (enclosed in a ZIP file) given here to a folder in which you have read/write permissions. If you are using Windows 7, download to My Documents, or C:\temp, or any folder that doesn't have security restrictions.
2) Copy Usertype.dat to the C:\Program Files\Microsoft Visual Studio 12.x\Common7\IDE folder. In 64-bit windows, Program Files will be named Program Files(x86).Windows will display a verification dialog before copying the file.
3) Open Visual Studio, select Options from the Tools menu, select Text Editor, and select File Extension. On the right side of the dialog (shown below), enter asm as the extension, select Microsoft Visual C++ from the Editor list, and click the Add button. Click the OK button to save your changes.
Close Visual Studio and restart it. Open your project and display an ASM file. You should see syntax highlighting in the editor. There is a glitch in the highlighting--assembly language comment line starts start with a semicolon, which C++ doesn't recognize. But this is a simple workaround: add an extra // right after the semicolon, like this, which will cause the comments to appear in their usual green color:
;// AddTwo.asm - adds two 32-bit integers. ;// Chapter 3 exampleReturn to top
Many people like to use a Windows batch file to assemble and link programs. A batch file is a text file containing a sequence of commands that execute as if they had been typed at the command prompt. In fact, they are powerful enough to contain variables, loops, IF statements, and so on.
The easiest way to run a batch file is to first open a Command window and then type the name of the batch file (along with arguments) at the command prompt. To open a Command window, you must execute a program named cmd.exe. We will make that easy for you.Step 1: Download a ZIP file containing the following items:
set VS_HOME=C:\Program Files\Microsoft Visual Studio 12.0And change it to the correct path for Visual Studio:
set VS_HOME=C:\Program Files (x86)\Microsoft Visual Studio 12.0Step 4: Do the following:
Type the following command to assemble and link a source file named main.asm:
You should see the following messages:
In fact, several files were produced.
If there were syntax errors in your program, you would see error messages generated by the assembler. Here is an example:
You would then open the main.asm file with a text editor (such as Notepad), fix the errors, and run the asm32 batch file again.
Assembling Programs in Other Directories
No doubt, you will want to assemble programs in various different disk folders, not just the batch_sample folder used in the foregoing example. All you need to do is copy the cmd.exe shortcut we gave you to your working directory, where your assembly language source files are located. When you double-click to run the shortcut, it will open a Command window in the current folder.
Assembling, Linking, and Debugging