Building SourceMod Plugins With Visual Studio

From AlliedModders Wiki
Revision as of 12:03, 16 January 2009 by Daedilus (talk | contribs) (Adding .sp Files to the Project)
Jump to: navigation, search

By: Cleveland “Daedilus” Raymond

Date: January 15th, 2009

Before We Begin

This tutorial will walk you through the process of creating a Custom Build Rule in Visual Studio for SourcePawn. Once you have completed

the following steps, you will be able to create a Custom Build Rule for any tool that you may wish to integrate into Visual Studio.


To learn more about custom build rules, go to http://msdn.microsoft.com/en-us/library/03t8bzzy.aspx


In order for all of us to be able to share our projects, it is important that we use the same Custom Build Rules. I have provided the following

link to the SourcePawn for Visual Studio Custom Build Rule file that was created during the process of making this tutorial. Save the file to

<Visual Studio Path>\VC\VCProjectDefaults and read through the tutorial. This link, MyPlugin, is where you can grab my test project.

Once you have downloaded and installed the .rules file, you will still need to set up the environment variables.


Note: .rules files are compatible with both, VS 2005 Pro and VS 2008 Pro (These are the only versions I have to test with.)

Setting the path to the SourcePawn Compiler Using Environment Variables

Bring up the “System Properties” dialog and press the “Advanced” tab and then press the “Environment Variables” button.

(To open the “System Properties” dialog, right click “My Computer”, choose “Properties” from the menu).

Step1.jpg

Press the “New” button in the “System Variables” group.

Step2.jpg

Name the variable, “SourcePawn” and set value to the path to spcomp.exe (without the trailing ’\’)

Do not include spcomp.exe in the path. ex. G:\Valve\HLServer\orangebox\dod\addons\sourcemod\scripting

Step3.jpg

If you want to be able to use spcomp from cmd.exe, add the newly created environment variable, %SourcePawn%, to the Path.

Step4.jpg

Creating the Visual Studio Solution

To create a blank Visual Studio Solution, select File->New->Project…

Step5.jpg

Name the solution and press OK.

Step6.jpg


Adding the Visual Studio Project for SourceMod to the Solution

To add the Visual Studio Project for SourceMod to the Solution, right click the Solution, Add->New Project…

Step7.jpg

Create a Win32 C++ Project. This will be used as the base for our SourceMod Plugin Project and press OK.

Step8.jpg

Choose “DLL” for the application type and check “Empty project” under additional options and press Finish.

Step9.jpg


Configuring the Visual Studio Project for SourceMod

To configure the Visual Studio Project for SourceMod, right click the Project, and choose “Properties” from the menu.

Note: I removed “Header Files” and “Resource Files” filters since they are no longer needed. You can setup your own folder filters to how you see fit.

(I modified my menu graphic to reduce the image size. “Properties” will be found at the bottom of the context menu)

Step10.jpg

Set the Configuration to “All Configurations” and set the properties for “General” settings as defined below. Under

“Project Default”, make sure the “Configuration Type” is set to “Utility”. This will keep us from building a DLL.

Step11.jpg


(The next steps are optional. You can skip this and go to the next section, “Creating a Custom Build Rule for SourcePawn“.)


Press the “Configuration Manager…” button located at the top right and edit the “Active solution configuration”.

Step12.jpg

Remove the “Debug” configuration and rename the “Release” configuration to “Build”.

Step13.jpg

Edit the “Active solution platform”.

Step14.jpg

Rename the “Win32” platform to “SourcePawn”.

Step15.jpg

Edit the project’s configuration.

Step16.jpg

Remove the “Debug” configuration and rename the “Release” configuration to “Build” (Yes we already did this for the solution, not the project).

Step17.jpg

We are finished setting up the Visual Studio Project. Now on to configuring the custom build options for SourcePawn (Unfortunately you can’t edit the project’s platform to change its name).

Creating a Custom Build Rule for SourcePawn

To create a Custom Build Rule for SourcePawn, right click the Project, and choose “Custom Build Rules…” from the menu

Step18.jpg

Press the “New Rule File…” button.

Step19.jpg

Fill out the “New Rule File” dialog with the settings below and press the “Add Build Rule…” button.

(Note: The default path for C++ .rules files is, “<Visual Studio Install Path>\VC\VCProjectDefaults”)

Step20.jpg

Fill out the “Add Custom Build Rule” dialog with the settings below and press the “Add Build Rule…” button. The “Command Line”

property has three entries separated by newlines. (Note: this is where we use the environment variable we made in the beginning)


$(SourcePawn)\spcomp.exe "$(ProjectDir)[InputFile].sp" [CmdLine]

if exist "$(ProjectDir)[InputFile].smx" move "$(ProjectDir)[InputFile].smx" "$(OutDir)\[OutputFile].smx"

if exist "$(ProjectDir)[InputFile].asm" move "$(ProjectDir)[InputFile].asm" "$(OutDir)\[OutputFile].asm"


Once you have filled in the settings, press the “Add Property…” button.

Step21.jpg

Fill out the “Add User Property” dialog with the settings below. This will allow us to specify the output .smx file name In the project properties dialog.

The “Description” property is set to: Specifies the input (.sp) file relative to the project directory. Do not include the file extension in the name.

Step22.jpg

Add another property. This will allow us to specify the output .smx file name In the project properties dialog.

The “Description” property is set to: Specifies the output (.smx) file name. Do not include the file extension in the name.

Step23.jpg

Let’s add one more property to handle additional command line options.

The “Description” property is set to: Specifies additional command line arguments. ex. -a

Step24.jpg

Keep pressing the ok buttons until you are back to the main window.

Congratulations you have setup SourcePawn to work with Visual Studio.


Adding Syntax Highlighting for .sp and .inc Files

To add syntax highlighting, go to Tools->Options.

Step25.jpg

Select Text Editor->File Extension and add .inc and .sp to the “Extension” list. Choose “Microsoft Visual C++” for the editor.

Don’t close the “Options” dialog cause we need to tell Visual Studio where to find SourceMod’s .inc files.

Step26.jpg

Note: You will have to restart Visual Studio for the highlighting to take effect.


Enable #include <file> Navigation

Visual Studio will try to open any included file if you right click the file name and choose “Open Document <file name>”.

Step27.jpg

However, Visual Studio doesn’t know where to look for SourceMod’s .inc files. So, let’s tell Visual Studio where to find them. Select Projects and

Solutions->VC++ Directories and then select “Include files” from the “Show directories for:” combo. Press the ‘folder’ button and enter the path.

Step28.jpg

Note: Visual Studio will not navigate to an include file without the file extension. ex. #include <sourcemod> cannot be found.

This is because we are piggy backing on a Visual Studio C++ Project and Visual Studio only knows how to open .h and .hpp files.


Visual Studio will open the include file if you include the file extension: ex. #include <file.sp> or #include <sourcemod.inc>.


SourcePawn Custom Build Project Settings

Reopen the project’s properties and check out the new “SourcePawn” options. The “Input File” and “Output File”, default to the project’s name. This means that I would have

to have a MyPlugin.sp file in the project’s directory and the build would produce a MyPlugin.smx file in the location defined Configuration Properties->General: Output Directory.

Step29.jpg


Adding .sp Files to the Project

To add a new .sp file to the project, right click the “Source Files” folder filter and select Add->New Item from the menu.

Step30.jpg

Select Visual C++->Utility: Text File (.txt) and name the file including the extension.

Step31.jpg


I will releasing a Visual Studio SourceMod AppWiz to go along with the Visual Studio C++ Metamod AppWiz.

The application wizards will allow us to easily create projects as well as provide wizards to add new .sp files.


Happy Coding, Daedilus…