Visual Studio has come with the built-in Macro Assembler and providing many debugging capabilities (Register & Memory View, Breakpoints and Step over). However there is no explicit assembly project template to choose from. So, this article will describe the required steps to setting up the assembly project on Visual Studio 2019.
I had compiled the knowledge from many sources and do the trial and error by myself.
1. Installing Visual Studio 2019
Visual Studio 2019 could be downloaded from the site: https://visualstudio.microsoft.com/vs/
The Community 2019 edition is free of charge.
When prompting to select an installed language, I choose C++. I’m not sure whether selecting other languages would work or not for assembly project.
2. Creating a C++ project as a base
Create a C++ empty project.
Named the project: “MASM”. So that, in the later step, we will save this project as a project template for further use. Set the save location to any preferred folder (I have precreated the folder C:\VSProj). Select “Place solution and project in the same directory” to prevent two nested folders with the same name.
The Visual Studio will create the folder with the same project name automatically.
3. Setup the Build Customization as Assembly Language
Right click at the project name > Build Dependencies > Build Customizations…
Select the “masm”, then OK.
Right click at the project name > properties > Linker > System > SubSystem : Windows
This will prevent the assembly program to show the console window ( the black text-mode window). But if you want the console window you can leave it at the default: Console mode.
I prefer the Windows mode because it has look-and-feel of native windows app. For debugging, just use breakpoint and watch windows to look at register and memory values at real-time. However, if we want to test the text mode input/output, we should use the console mode.
4. Creating a Test Assembly File
Right click at the project name > Add > New Item…
Name the file: “Main.asm” . The selected item type is not important. Any type can be selected. But the important is to name it with the “.asm” file extension.
Write a test program. You can copy the code from below. I adapted the code from the wonderful book : Assembly Language for x86 Processors by Kip Irvine. I highly recommend this book for anyone start learning the Assembly language.
.386 .model flat, stdcall .stack 4096 ExitProcess PROTO, dwExitCode:DWORD .data myList DWORD 2, 3, 5, 8 .code main PROC mov eax, 7 add eax, 8 INVOKE ExitProcess, eax main ENDP END main ;specify the program's entry point
Press the green, play button: (run with) Local Windows Debugger.
The program will sum 7 with 8 and return the result 15 as shown in the debug output window.
5. (Optional) Setup Listing File
The listing file is useful for examining what the assembler has generated. To setup the listing file generation, right click the project name > Properties > Microsoft Macro Assembler > Listing File > Assembled Code Listing File : $(IntDir)$(ProjectName).lst
Note: The page “Microsoft Macro Assembler” will appear only when there are some assembly files in the project.
Build (and/or run) the project again. You will see the listing file generated at the project’s debug folder.
Drag the listing file into Visual Studio to view it. The listing file content will be like this:
5. (Optional) Setup for Release Mode Build
This section could be skip because it is quite complex. Do it when you need to use the release mode for release build. Or you could come to this section later when in need.
In Visual Studio, there is a separate release mode build configuration. The release mode configuration could be set differently from the debug mode configuration. For example, the release mode may have more optimizations and less debugging features.
If the release mode is needed, we should do the same as the step 3 and 5. Additionally, we need to customize the safe exception handler configurations.
5.1 Setup Subsystem (Windows or Console) and Listing File Generation
Go to the project properties > change the configuration mode to : Release.
Choosing your prefer subsystem (Windows or Console).
Setting up the listing file generation.
Changing the active configuration to Release.
Try building and running the program using the green play button. You will see the error message: “fatal error: LNK1281: Unable to generate SAFESEH image.”.
The next step 5.2 will solve this error.
5.2 Fully Enable or Disable the Safe Exception Handlers
In the release build mode, the default option of the linker is that every images (object files) should have safe exception handlers. However, the default option of the assembler (compiler) is not to use safe exception handlers. These conflicts cause the above error. Now, we have two choices to fix the error.
Way 1: Enable the safe exception handlers in the assembler (compiler).
Way 2: Or we could entirely disable the use of safe exception handler at the linker.
Linker > Advance > Image has Safe Exception Handlers : No
Choose one way but not both!
I preferred way 1 because it looks safer to have safe exception handlers. But, in fact, I am not 100% sure because I don’t have much knowledge about safe exception handlers.
After that we should be able to build and run the program in the release mode without any error.
Caution on switching between Debug and Release : When changing the active configuration in the toolbar and then open the project property pages, the property pages may not be conformed to the current active configuration. This could cause confusion when changing some project settings appear to not affect the current build. If this occur, please ensure the matching of active configuration and the property pages.
6. Save as a Project Template
After these long steps, we might not want to do them every time to create a new Assembly project. Fortunately, Visual Studio can save the project as a project template.
First, edit the Main.asm to contain only template code:
.386 .model flat, stdcall .stack 4096 ExitProcess PROTO, dwExitCode:DWORD .data .code main PROC INVOKE ExitProcess, 0 main ENDP END main ;specify the program's entry point
Try running it to make sure that the program works correctly.
If you still use release mode (from step 5), switch back to the debug mode.
Click: Project > Export Template …
Choose our “MASM” project from the drop down list.
Describe the template description.
After that when you create a new project, you could select MASM as a project template.
Debugging is straightforward in Visual Studio. To set a breakpoint, just clicking the grey area in front of the line of the source code. When running, the program will pause before the execution of the breakpoint line.
To look at registers, select Debug > Windows > Registers
To look at variables, select Debug > Windows > Watch. Then type the variable name.
Or select Debug > Windows > Memory > Memory 1. Then type “&varname” at the address box.