Guide:- Compiling PPSSPP on Windows for Dummies (updated for MSVC 2013)

[solarmystic]

Acknowledgements:-

I'd like to thank daxtsu (a.k.a thedax on IRC and github) for his help in getting me up to speed with the basics of compiling in MSVC and git.

This guide would have been impossible to do without his prior guidance.

Shout outs also go to Henrik, [unknown], oioitff, raven02 and the other fabulous developers and testers of this wonderful emulator.

Thank you.

Background:-

This guide is an offshoot of a discussion daxtsu and I had in my very unrelated PPSSPP guide for AMD users.

It is intended to be a very simple how-to into compiling PPSSPP on Windows, geared towards the average user of PPSSPP on Windows.

It is not intended to teach one any form of programming and commandline usage beyond the narrow scope of this guide.

I will assume that you have some basic computing knowledge in this guide.

Objectives:-

By the end of this guide, you will have the ability to:-

1. Compile your very own PPSSPP builds with the aid of git and Microsoft Visual Studio Express 2013 for Windows Desktop.

2. Pick and choose specific builds to compile for your own purposes using git.

3. (Advanced) Compile PPSSPP builds without FFMPEG for diagnostic purposes.

4. (Advanced) Produce and post stack traces to use for debugging crashes in PPSSPP for the benefit of other advanced testers and developers to help them easily identify the root causes and to complete your issue reports on github

Handy Shortcuts for the Guide:-

Hit Ctrl-F in your browser and type in the appropriately bracketed three letter code to quickly jump to the section you wish to peruse.

It is highly recommended that you read it in order if this is your first time going through the guide.

Prerequisites [REQ]

Procedure for compiling [COM]

Procedure for compiling without FFMPEG [FFM]

Procedure for producing stack traces for PPSSPP Crash Analysis [CRA]

Frequently Asked Questions [FAQ]

Prerequisites:- [REQ]
(It goes without saying that you'll need a PC with some form of online connection to get the software required for this guide. If you actually intend to do this without a persistent internet connection, stop reading now, skip to the bottom of the guide, and read the answer for FAQ Question 7.)

You will need the following software properly installed on your Windows system before we can proceed any further:-

1. Microsoft Visual Studio Express 2013 for Windows Desktop
(Note:- With the move from 2010 to 2013, Windows XP and Vista users are no longer supported for compilation. The minimum OS requirement to compile PPSSPP is now Windows 7 SP1.)

a. Head to the download site.

b. Scroll down to Visual Studio Express 2013 for Windows Desktop and click on the option.

c. Choose either the Install Now option or the all in one iso for offline installations.

d. Follow the installation instructions. In the case of the iso download, a Microsoft Account (one used for a Outlook/Hotmail account for example) will be required to eventually obtain the direct download.

e. Both the web installer and iso will perform a full installation and update of every component needed automatically.


2. Git Bash. (Used for the purposes of the guide, there are others that can be used also.)

a. Head to the download site here, which should initiate the download immediately.

b. Install it using the default options, which should create shortcuts on the desktop and the start menu.

c. Click on the shortcut to open the git command line.


Procedure for compiling:- [COM]

Once you've got everything properly installed and configured, we can now begin.

(For the purpose of this guide, we shall assume that the folder that will contain ppsspp's source files is located in C:\programming\ppsspp)

(Note: If you decide to share customized builds you've compiled using this guide here on these forums, you have to provide the source code, whether it's included in the archive with the binary, or if you have your own fork + branch on Github. PPSSPP is GPL source code, so the source code MUST have a way to be obtained.)

(Warning:- If you decide to use a different path other than the one suggested by the guide, be aware that Git Bash's command prompt does NOT accept spaces nor accents in the path name, so none of the folders in the path can have neither spaces nor accents. Plan accordingly.)

1. Start off by loading up git bash from the shortcut in the start menu or on your desktop.

2. A box with the Git bash command prompt will appear.



3. We will now head to the directory we chose earlier.
(Type in the following commands, and hit enter after each one)

Code:

cd /c/programming/

4. The next step is to clone it from Henrik's repository from github into C:\Programming\ppsspp.

Code:

git clone http://github.com/hrydgard/ppsspp.git ppsspp

5. Recall that you're still at C:\Programming\ so head to the newly cloned repository located at C:\Programming\ppsspp.

Code:

cd /c/programming/ppsspp/

6. Now we shall complete the process of cloning by grabbing the submodules. This can take quite a long time depending on the speed of your internet connection, around 10 - 60 minutes, so go and do something else if you have a low end connection.

Code:

git submodule update --init

7. Next, we shall update source again just to be sure our own cloned repository is up to date.

Code:

git pull -v --progress "origin"

followed by yet another,

Code:

git submodule update --init

8. At this stage, assuming that the above steps went without a hitch, load up the solution (.sln) file (located in the windows directory of the ppsspp folder you've cloned it into, C:\Programming\ppsspp\windows) using Microsoft Visual Studio Express 2013 for Windows Desktop.



9. Ensure that the configuration menus at the top are set to the builds you intend to compile. E.g. if you intend to compile a normal 32 bit build, the options should be set to Win32 and Release.





Alternatively, if you intend to compile a normal 64bit build:-





10. Finally, build the solution by hitting the F7 button on your keyboard or heading to the BUILD menu at the top and clicking on Build Solution.

11. The first build will take the longest. Subsequent builds will take a shorter amount of time, depending on the scope of the change that each commit brings to the repository.

12. If the build is successful (meaning all 10 projects compiled successfully), you should see the following output in the program.



A complete success is indicated by "0 failed" in the output. If you're building it for the first time, you should get 10 succeeded and 0 failed.

13. You're done! The PPSSPPWindows.exe (or PPSSPPWindows64.exe for 64bit builds) file will be produced in the C:\programming\ppsspp folder you created earlier on when cloning the project. You can either execute it from that location, or move it into an existing working ppsspp folder you downloaded from Orphis to try it out.




Procedure for compiling without FFMPEG (advanced) [FFM]

(This entire segment is courtesy of daxtsu. Only recommended for diagnostic purposes, since movies will not be played in this version.)

(08-17-2013 11:42 AM)daxtsu Wrote:  Compiling without FFMPEG:

Note that this will NOT auto-skip PSMFs or other movies; you'll simply have a black screen or possibly some graphical glitches while the movie "plays".

Minimum requirements:
1. PPSSPP's source code
2. Visual Studio 2010/2012/2013
3. You've checked out lang and native via the following commands:

Code:

git submodule update --init "lang"
git submodule update --init "native"

So you've checked out a fresh copy of the source, but for one reason or another(testing, don't feel like downloading the 200 MByte/Mo+ submodule, etc.), you don't want FFMPEG support. Well here's how you can build on Windows without FFMPEG support, and without changing a single line of code.

Note: If for some reason you need Headless to build, repeat steps 1-3 for the PPSSPPHeadless project as well. If you don't need Headless, just right click it and choose Unload Project. You don't need it for gaming. You can also unload UnitTest if you wish; it's also not needed for gaming.

Make sure to change the Config/Platform dropdown boxes to reflect whichever configuration you need before changing these options.

1. Open up your PPSSPP solution/SLN file.
2. Right click on PPSSPPWindows and select Properties.
3. Go to Configuration Properties -> Linker -> Input, and change the Additional Dependencies box, then delete the following(click the textbox next to it so it shows the little dropdown arrow on the right, click it, then press "<Edit...>"):

Note: x64's text lines will look slightly different, but they still mention FFMPEG; remove them.



Now that that's done, we have to edit the Core project.
4. Right click Core and choose properties.
5. Under Configuration Properties -> C/C++ -> Preprocessor, click in the Preprocessor Definition textbox and remove USE_FFMPEG; from the list(it should be the first one). Yes, do remove the semi-colon after USE_FFMPEG.
6. Now compile and enjoy your copy of PPSSPP without FFMPEG support.

One last thing: On Core's property sheet, under Librarian -> General, x86 Release builds must delete everything under the additional dependencies line to strip out ffmpeg completely.

Procedure for producing stack traces for PPSSPP Crash Analysis (advanced) [CRA]

1. Compile PPSSPP as usual using the steps listed above.

2. Hit the F5 button on your keyboard to begin the debugging process.

3. PPSSPP will load up as usual.

4. Reproduce the steps needed to crash PPSSPP (when playing game, loading a certain function etc)

5. If the emulator crashes at this point, Visual Studio 2013 will close the program and ask you what to do next. Click on 'Break' and it will produce the stack trace (Call Stack) in the lower right corner of the screen.

Example from a crash in PPSSPP (linked since the image is massive):- https://f.cloud.github.com/assets/434515...b5602d.JPG

6. Highlight the entire section of that stack trace with your mouse, copy and paste it into your github issues report.

Frequently Asked Questions:- [FAQ]

1. How do I update my repository to the latest build when Henrik et.al pushes commits?

Open up Git Bash, head to your ppsspp directory

Code:

cd /c/programming/ppsspp

and type in the following, hitting the Enter key after each line:-

Code:

git pull -v --progress "origin"

followed by

Code:

git submodule update --init

(Do NOT neglect to type in this follow up command, you will get compile errors in MSVC 2013 if you neglect to update submodules each time you update via the git pull command.)

2. How do I pick and choose which builds I want to compile?

Let's assume that your repo has been updated to the latest (at the time of writing) v0.8.1-1055-g4e8958f.

You want to go back to v0.8.1-1040-g0a8f85a for example, because it works better in a certain game, or because a newer build broke some crucial functionality in the emulator.

a. Open up Git Bash and head to the working ppsspp directory as usual. (cd /c/programming/ppsspp)

b. Enter the following and press Enter afterwards.

Code:

git reset --hard 0a8f85a9198f768fb5ada08a485bce9893ea1664

followed by

Code:

git submodule update --init

The long line of numbers after the 'git reset --hard' represents the SHA-1 id of the commit.

Where do you get this SHA-1 id specific to each build?

By right clicking on the older build's version number in the buildbot, copying the link, and extracting the long list of hexadecimal numbers at the end.

e.g. for v0.8.1-1040-g0a8f85a, the link is https://github.com/hrydgard/ppsspp/commi...9893ea1664 which means that the SHA-1 id is 0a8f85a9198f768fb5ada08a485bce9893ea1664

OR, you can open the link itself, and on the top right hand corner of the github commit page, you'll find the SHA-1 id.



To use another build for example, returning to v0.8.1-1018-g9ac511f would mean using the SHA-1 id of 9ac511f191434fa44d92e4530ef3d88b2f791db4 extracted from the link https://github.com/hrydgard/ppsspp/commi...8b2f791db4

OR, you can just use the last 7 hexadecimal numbers from the full build version itself. For v0.8.1-1040-g0a8f85a, the command would be

Code:

git reset --hard 0a8f85a

3. So, I just followed the instructions to go back to an older build, how do I go back a newer one/latest one? HALP MY PLEAZEE!!!!

Sigh.

Type in the following in Git Bash (after heading to the working PPSSPP directory):-

Code:

git reset --hard master

Then just follow the instructions in Question 1 again.

4. I'm getting compile errors when building PPSSPP in MSVC 2013!

There are many reasons why this occurs.

Here are some common beginner mishaps. (I know, because I've been through all of them myself)

a. You forgot to properly update your submodules after performing a git pull.

Never forget to enter

Code:

git submodule update --init

after each git pull to update your submodules properly.

b. The latest builds could indeed be messed up due to errors out of your control.

In this case, just wait for a buildfix to be pushed by the devs. A common symptom of this scenario would be the lack of the latest compiled Orphis builds on the build bot website.

5. My compiled PPSSPP build shows PPSSPP UNKNOWN instead of the usual version numbers. How do I make the numbers appear correctly?

There is one file on the project directory that should be executed automatically by git bash everytime you do a git pull to update your own repository.

The file is called git-version-gen.cmd and it is located in the Windows subfolder of your ppsspp source files directory.



If git is not PATH'd correctly (which it should if you install Git Bash by default), the file isn't executed and thus, the version isn't properly accepted by the compiler.

To correct this, head to the Enviroment Variables of your Advanced System Settings dialogue box.
(Start --> Type in advanced system settings --> Enter)



In the Environment Variables dialogue box, edit the path of your user variables and add the following line to it at the very end:-

Code:

;C:\Program Files\Git\cmd

(assuming you've installed Git Bash to C:\Program Files\Git)

Hit OK and then and then repeat the instructions in Question 1 again to update your repository and force git to execute the aforementioned file.

6. How do I add commits that are pending in pull requests/that haven't been approved by Henrik et.al ?
(question courtesy of Donel)

This is where we head to rather intermediate territory for git.

As a precautionary measure, I recommend that you attempt this procedure on another cloned repository, just in case anything goes wrong with your primary, working clone. (e.g. make a new one called ppsspp2 for experimental purposes)

Let's say you see a rather tasty looking pull request from [Unknown] that you wish to manually merge into your own personal repository.

The simplest way to accomplish this is as follows:-

(Note:- If the pull request has already been merged to master by Henrik, this procedure won't work, since you already have it in your own repository by following the steps listed in Q1.)

a. Open up Git Bash and head to the working ppsspp directory as usual. (cd /c/programming/ppsspp)

b. In your Internet browser, head to the list of open ppsspp pull requests.

c. For this example I shall be using this specific [Unknown] pull request

d. Take note of the following section at the top of the pull request page, especially the part called unknownbrackets:gpu-thread:-



e. Head back into Git Bash, and now we are going to add [Unknown]'s repo as a remote branch which contains the proposed changes in the pull request

Code:

git remote add unknownbrackets http://github.com/unknownbrackets/ppsspp.git

(There might be a slim chance that the command prompt will ask you for your github login details at this point. Just enter them truthfully, using your real github username and password)

f. The next step is to fetch any progress from that remote branch

Code:

git fetch -v --progress unknownbrackets

g. The resulting screen will show you a list of available branches from [Unknown]'s forked repository. Notice that gpu-thread from the pull request we saw earlier is one of them, so now you'll want to merge that branch into your own repository.

Code:

git merge remotes/unknownbrackets/gpu-thread

h. That's it, you're done! You now have [Unknown]'s pull request merged into your own repository as a remote branch.

But then you might ask, what happens when Henrik merges those commits into the master?

Will you have to revert your merge back to accept the official commits from Henrik?

Nothing to worry about, a simple git pull -v --progress "origin" will tell you if there are any conflicts, and if the pull request got merged unaltered into master, you can continue updating your repository like normal.

If conflicts do exist, a simple git reset --hard master followed by the usual git submodule update --init should do the trick, as outlined in Question 1, 2 and 3.

7. I've a totally offline PC but have access to another PC with Internet that I can use to get the source files. How do I compile PPSSPP on my system?
(question courtesy of arg274 and answer credited to Daxtsu)

Refer to this post for the answer.

(08-13-2013 12:54 PM)daxtsu Wrote:  If you want to do an offline build, you're better off downloading the latest master zip file, followed by native, ffmpeg, lang, and dx9sdk then extracting those latter 4 in the master's native, ffmpeg, lang and dx9sdk folders, then compiling. You can skip lang and ffmpeg most of the time if you already have them; they're not updated often..

Not much point going through the whole git thing if you can't update to begin with.

Also, adjust your expectations accordingly, since without the fine control with individual commits offered by git bash that requires an online connection, you'll have redownload the bulk files everyday from your PC with the Internet connection. I highly recommend that you actually use the PC with the persistent Internet connection to compile PPSSPP.

8. I messed up the first time and manually downloaded one of the native submodules from the github site instead of using gitbash and I am gettings errors when using gitbash to update the submodules. How do I rectify this problem?
(question and answer credited to Danyal Zia)

Refer to this post for the answer.

(08-13-2013 04:41 AM)Danyal Zia Wrote:  Also, if you want to do update just one of your native library, (let's say "native") then you can do by:

Code:

cd /c/programming/ppsspp/native/

and then

Code:

git pull -v --progress "origin"

It helps in those scenarios where you've got one of native library directly from github instead of cloning it from Git Bash. In my case, I downloaded the entire ffmpeg library from github at a time when I compile for a first time, so updating submodule was giving me error that ffmpeg is already present there. It saved a lot of my time, else i would have to update submodule from the start again.

9. I'd like to customize the PPSSPP display shown on the title bar with my own version strings. Vanity reasons. How?
(question and answer credited to Daxtsu)

Refer to this post for the answer.

(08-13-2013 04:05 AM)daxtsu Wrote:  This can probably be put in an appendix or something, but if you want to have your own version strings in addition to the default "vX.X.X-gXXXX" stuff, edit Windows\git-version-gen.cmd, line 66 or so to this:

Code:

echo const char *PPSSPP_GIT_VERSION = "My Custom Build String %GIT_VERSION%"; >> "%GIT_VERSION_FILE%"

Change My Custom Build String to whatever you want, and you'll still get the nifty git version tag too.
Caveat: If you want to use backslashes( \ ) in it, make sure to use two instead(so that it's escaped): \\. Otherwise you'll get build errors.

For example, I'm using

Code:

echo const char *PPSSPP_GIT_VERSION = "TheDax Customs %GIT_VERSION%"; >> "%GIT_VERSION_FILE%"

And this displays as(Click/touch for full size):

(More will be added as they are asked in this thread. Sensible questions pertaining to the guide are welcomed.)