PCSX2 Documentation/Compiling on Windows

From PCSX2 Wiki
Jump to navigation Jump to search

Setting up the Build Environment

In order to compile PCSX2 you will need to configure a working build environment based on Microsoft's Visual Studio. There are some things to download, so I've placed links to them at the front of the guide so you can get everything you'll need at the first step.

Downloading the Prerequisites

Downloading build environment

First you have to download a build environment. Microsoft Visual Studio 2015 and 2017 are capable of compiling PCSX2. At this time, the recommended build environment is Visual Studio 2015 Community, as Express does not support the ATL libraries used by GSdx (issue 970[1]).

Downloading additional prerequisites

A Visual C++ redistributable runtime matching the build environment major release (Only needed if you're compiling the Installer):

Installing Microsoft Visual Studio

Microsoft Visual Studio 2015 and 2017 are capable of compiling PCSX2. Depending on whether or not you develop professionally, as well as other factors, you may or may not have access to a copy of Microsoft Visual Studio Professional. This guide will cover the installation and configuration of Visual Studio 2015 Community and Visual Studio 2015 Express for Windows Desktop.

Installing Visual Studio Community 2015

Download Visual Studio Community 2015 installer from the link above, and run it.

  1. Choose the 'Custom' installation type.
  2. On the 'Select Features' screen, select everything under 'Programming languages -> Visual C++'. Everything else is optional.
  3. I recommend keeping the default installation location. Click Install.
  4. The components will be downloaded to your computer.
  5. Once done downloading, they will then be installed.
  6. Once the installation has finished, you may be prompted to restart the system.
  7. Click Restart Now or Close depending on your situation.

Installing Visual Studio Express 2015 for Windows Desktop

Download Visual Studio Express 2015 for Windows Desktop installer from the link above, and run it.

  1. I recommend keeping the default installation location. Click Install.
  2. The components will be downloaded to your computer.
  3. Once done downloading, they will then be installed.
  4. Once the installation has finished, you will see the following screen.
  5. Click Restart Now

Vs-express-2015-0.png Vs-express-2015-1.png Vs-express-2015-2.png

Installing SDKs

Recent revisions of PCSX2 only require DirectX SDK to compile successfully. OpenGL Extension Wrangler library becoming redistributable allowed its integration into the codebase. nVidia CG Toolkit, now defunct, its functionality has been replaced by a more popular shading language called GLSL. This shading language is now implemented in all graphics driver releases.

DirectX SDK

DirectX SDK installer is a problematic peace of software as installers that drop unsolicited software on target machine behind user's back are nothing good mainly due to 2 reasons:

  1. the unsolicited software eats system resources, this is even more unpleasant if any of these unsolicited peaces of software is never used;
  2. in these days when IT security threats are at large any unsolicited software is equivalent to a collection of security holes.

Experimented with this installer on a virtual machine and discovered it installs the following components without consent:

  • .NET Framework v2.0
  • Visual C++ 2008 Redistributable runtimes
  • Visual C++ 2010 Redistributable runtimes

None of these software products are any more supported by Microsoft, meaning no more security patches and none of these are needed to build PCSX2. Bellow are described 2 ways of installing DirectX SDK, one secure and minimal and another easier but dirty and insecure.

Secure and minimal installation
  1. Download the DirectX SDK Web Installer and 7-zip;
  2. Install 7-zip with default settings, the installer in executable format it's by far the easiest to use and has minimum system footprint;
  3. Open 7-zip and navigate to folder where you downloaded DirectX SDK installer;
  4. Right click on the installer and Select 7-Zip - Open Inside, this opens the installer as an archive;
  5. Extract Lib and Include to a folder that will host DirectX SDK. If that folder doesn't exist it's going to be created;
  6. Set DirectX SDK environment variable (DXSDK_DIR).
Setting DirectX SDK environment variable

There is a large palette of possibilities of setting DirectX SDK environment variable (DXSDK_DIR):

  • as system environment variable;
  • as an environment variable for currently logged on user;
  • programmatically.

There are some important conditions regarding the value of this environment variable:

  • it must be an absolute folder path or an expression that evaluates to an absolute folder path;
  • it must end with an extra "\".

Examples:

c:\dev\dep\dxsdk
..\dep\dxsdk

are both incorrect because they don't end with "\" and even more, the second one is not an absolute path.

c:\dev\dep\dxsdk\

is correct.

Now that we know what kind of value DXSDK_DIR must have, all that's left is to set it. There are various guides online describing how to set an environment variable using various editions of Windows, so I will not enter in details, instead I'll describe a tip on how to easily set DXSDK_DIR programmatically using Git Bash. This git client has 2 launchers: one with UNIX-like interface and another using Windows command prompt itself, both launchers being batch scripts. The one that interests us is the simpler batch file, that one that opens Windows Command Prompt.

Most of this batch script looks like this:

@rem Do not use "echo off" to not affect any child calls.
@setlocal

@rem Get the absolute path to the current directory, which is assumed to be the
@rem Git installation root.
@for /F "delims=" %%I in ("%~dp0") do @set git_install_root=%%~fI
@set PATH=%git_install_root%bin;%git_install_root%mingw\bin;%git_install_root%cmd;%PATH%

@if not exist "%HOME%" @set HOME=%HOMEDRIVE%%HOMEPATH%
@if not exist "%HOME%" @set HOME=%USERPROFILE%

@set PLINK_PROTOCOL=ssh
@if not defined TERM set TERM=msys

If both PCSX2 repository and git installation folder are under a common folder, and if we create a batch file with this source in that common folder, we can set DXSDK_DIR using git_install_root value. For example we have a folder tree that looks like this:

c:\dev\dep     \
                dxsdk\
       git     \  
       projects\      
                pcsx2\
  • The batch file goes in c:\dev
  • git_install_root variable value in this case is c:\dev\

We need to do some tweaks to our batch script in order to work:

  • Thirst we have to adjust the line that customizes PATH. In this case just add git\ after %git_install_root% on all 3 spots;
  • Append a code line where DXSDK_DIR is set:
@set DXSDK_DIR=%git_install_root%dep\dxsdk\
  1. Append a command that launches Visual Studio.

Finding the location of Visual Studio executable is easy. Just right click on Visual Studio Start Menu entry or Start screen tile (on Windows 8/8.1) and click properties. Grab the contents of the target field and past it in the batch file source. You can insert an @ prior to that code to inhibit display output. When ready proced to next step.

Standard (dirty and insecure installation)
  1. Remove any previous installations of "Microsoft Visual C++ 2010 Redistributable Packages". This is important otherwise the installation may fail.
  2. Download the Web Installer from the link above. Run it, and click next at the Welcome Screen (shown below.)
  3. Accept the EULA as shown.
  4. You will be prompted to join the Windows Customer Experience Improvement Program. I chose not to, but the decision is yours to make. It won't impact anything you'll be doing with the software.
  5. You will then be prompted for a destination folder, I recommend choosing the default to make life easier later on.
  6. You will be prompted with a list of components.Only headers and libs are needed to build PCSCX2, the rest are entirely subject to your choice if you need them. Then go ahead and click Next.
  7. The DirectX SDK will then begin installing.
  8. You should then be presented with this screen.
  9. Click finish and move on to the next step.

Directxsdk1.jpg Directxsdk2.jpg Directxsdk3.jpg Directxsdk4.jpg Directxsdk5.jpg Directxsdk6.jpg Directxsdk7.jpg

Configuring the Build Environment

Because the only remaining dependency required by PCSX2 is DirectX SDK and because it can be located via an environment variable, all the necessary path related tweaks were integrated into the codebase, so there is no more configuration of build environment to perform.

Getting the Source Code

If using a command-line git client like Git Bash you have to do the followings:

  • navigate to a folder that will host the repository;
  • clone pcsx2 repository.

Example:

cd /dev/projects
git clone --recurse-submodules https://github.com/PCSX2/pcsx2.git pcsx2
  • enter repository
cd pcsx2
  • create a dev branch and switch to it (optional). Good git practices recommend to never develop in master branch.
git branch dev
git checkout dev.

I named my working branch dev, but it can have any name. When ready proceed to next step.

Compiling PCSX2's Binary

You've now completed all of the "leg work" required in order to compile PCSX2 on your machine. Congratulations!

Compiling Git Builds of PCSX2

Open the PCSX2 directory you have downloaded the source code into (in this case, C:\Development\Project Source\PCSX2) and double-click on the solution file (PCSX2_suite.sln). This will open Visual Studio (if it is not already open) and you will see a screen similar to this.

VisualStudio2015.png

Build Target Selection

At the top of your screen, you will see a small drop down list which contains what is known as your "Build Target", as shown in the screenshot. This menu corresponds to the build of PCSX2 that you will be compiling. SSE2, SSSE3, SSE4, AVX, AVX2 refer to CPU instruction sets and only apply to the GSdx Plugin (though they compile the full solution as well). The Release Build Target does not specify an instruction set target for the GSdx compile and will not compile GSdx. It is recommended that you choose all five (SSE2, SSSE3, SSE4, AVX and AVX2) as a build target (Release is unnecessary) if preparing a release build to ensure that all users have available versions of the plugin. Once you have selected the Build Target, it is time to build the solution. You can either select the Build Menu from the top menu, and choose Build Solution, or use the appropriate shortcut key. This is the moment of truth! If you've followed the instructions properly, this process should finish with 0 errors. Warnings are usually nothing to worry about, so, as long as the solution compiles with 0 errors and you have the output files, you should be good to go. Congratulations!

Effective Build Troubleshooting Steps

So, your build failed. What now? Even in the most perfect of circumstances, there is always the possibility that your build is going to fail for some reason or another. I've included a few things to try that should take care of almost all of the common compiling issues that users have.

If at first you don't succeed, retry the build, at least once. Visual Studio is notorious for spamming errors about files being in use, access denied, or errors returned from mt.exe. If this happens to you, or frankly in pretty much any other case, make sure to retry the build at least once to ensure you have a reproducible build failure!

It is good practice to clean your build environment of Visual Studio build-process temporary files and post-build remnants of the solution if you encounter errors while building. This is a quick and painless process. To begin, open the PCSX2_suite.sln Solution file. Once Visual Studio has opened, select the build of PCSX2 that you are having trouble building from the Build Target dropdown (e.g., SSE2, SSSE3, SSE4, etc.) Click on the Build menu and select Clean Solution from the list. Try to build again, and see if this solves your problem.

When all else fails, the error log and output screens can be a wealth of information. Even if you're not a developer, you can look at the error log and extrapolate what files are involved in the error you're having. Once you know that, search for the files and see if any of them are in the directories that are supposed to be configured in the search paths -- if so, go verify in your VC++ Directories setting that you have properly entered the dependency directories. Mistyping the directory names, including the wrong directory, or overlooking a directory is one of the most common causes of build failure and can be easily and quickly fixed. If that doesn't work, post about your experiences on the PCSX2 forum under the relevant topic and someone should be able to help you out.

Stopping Unwanted Components from Compiling

If you are developing a specific project and do not want to compile the other projects every time you re-build the solution, or if you just don't want to compile a specific plug-in for some reason or another, you can easily accomplish this. Open the PCSX2_suite.sln Solution file and right-click on the Project you wish not to compile. Select "Unload" from the context menu. You will now see that the project is listed as "(Unavailable)", as shown in the screenshot. When you compile, this solution will be skipped. Best of all, this option is persistent, but does not write to the Solution (.sln) file, so this change will not be included in your your Git commits.

Unwantedcomponents1.jpg Unwantedcomponents2.jpg

Running PCSX2 from the Visual Studio Debugger

It is possible (and quite easy) to run PCSX2 from the Visual Studio Debugger, if you feel so compelled to do so. See below for instructions on how to do it for all supported version of Visual Studio.

Select build target from top, just like you would do to build PCSX2, then press F5. If you are an experienced developer you can even mess with Configuration manager to debug specific components of PCSX2, certain plugins for example.

Packaging PCSX2 with Nullsoft Scriptable Install System

Just Because It Compiles Doesn't Mean It Works!

The steps included in this guide will pretty much guarantee that you can set up an environment in which you can compile the .NSI file included in the PCSX2 source to a .exe installer, but PLEASE NOTE THE FOLLOWING: Just because you can get it to compile without erroring does not mean that the output file will be a functional installer! Just like any other piece of code, the .NSI installer needs maintenance whenever there are changes to the file and directory structure of PCSX2. The installer is not the highest priority on the list, so it is possible that the .NSI is out of date and may be including out-dated files, or may not be including new files. It may complete compilation but net an installation that crashes every time it's run due to missing or unlinked .DLLs. With that said, it is NOT recommended that you use these installers without testing them in a sandbox / virtualized environment first to ensure that they properly install! A successful .NSI file compile does NOT equate to a truly successful installer build!

Installing the Nullsoft Scriptable Install System

Download the installation package from the link above and run it. You will be presented with this Welcome Screen. Click Next. Accept the terms of the EULA. Select "Full Install", if it is not already checked. It is recommended that you keep the default installation directory, and click Next. The Nullsoft Scriptable Install System will install very quickly and present you with the final screenshot. Click Finish and the installer will close.

Nsis1.jpg Nsis2.jpg Nsis3.jpg Nsis4.jpg Nsis5.jpg

Lastly, you need to copy the vc_redistx86.exe that you downloaded from the prerequisites above into the following directory:

C:\Development\Project Source\PCSX2\NSIS\

If you skip this step, the NSIS compile will fail. This file must be present for any branch of PCSX2 as well, including wxGUI.

Packaging PCSX2 with NULL Plugins

After you install NSIS and .NSI files are associated with the Nullsoft Scriptable Installer System, you can Right-Click on .NSI files and select "Compile NSIS Script", as shown in the picture.

Nsis6.jpg


This will compile a PCSX2 installer and include all of the null plugins. This will NOT include the additional plugins (gsDX, SPU-X, etc.)

Packaging PCSX2 with all Plugins

In order to compile PCSX2 and include the Plugins, you must specify the INC_PLUGINS variable to makensis.exe. To do this, run the following in a command prompt (assuming default installation directories):

"C:\Program Files\NSIS\makensis.exe" "C:\Development\Project Source\PCSX2\NSIS\pcsx2_installer_script.nsi" /DINC_PLUGINS

This will compile PCSX2 and include all of the plugins in the installer file.