Installing DeSmuME from source on OS X

From DeSmuME
(Difference between revisions)
Jump to: navigation, search
m
(32 intermediate revisions by one user not shown)
Line 1: Line 1:
 
== About the Build Targets ==
 
== About the Build Targets ==
DeSmuME for OS X may be built using several different configurations. Each build configuration is listed in an Xcode project as a "build target." The Xcode project files (provided with the DeSmuME source,) provide several build targets to suit your needs. Many build targets are similar to each other, and so they have been organized into the following categories, based on what the build target produces.
+
DeSmuME for OS X may be built using several different configurations. Each build configuration is listed in an Xcode project as a "build target." The Xcode project files, provided with the DeSmuME source code, include several build targets to suit your needs. Many build targets are similar to each other, and so they have been organized into the following categories, based on what the build target produces.
  
  
=== Standard App (Universal) ===
+
=== OS X App ===
These build targets produce a self-contained OS X application package (or "app bundle"). These builds use our official OS X frontend to run the DeSmuME emulator, and are designed to run on both PowerPC and Intel processors. In addition, built app bundles are compatible with OS X v10.5 or later.
+
These build targets produce a self-contained OS X application package (or "app bundle"). These builds use our official OS X frontend to run the DeSmuME emulator, and are designed for the debugging and testing of pre-release builds. These app bundles are compatible with OS X v10.6 or later. (Also compatible with OS X v10.5 if building from the Xcode 3 project).
  
 
'''Build Target Goals:'''
 
'''Build Target Goals:'''
 
* Fully featured.
 
* Fully featured.
* Wide build target compatibility.
+
* Widest build compatibility with Xcode versions running different OS X versions.
* Wide binary compatibility.
+
* Quick debug-and-test of code changes.
  
 
'''Advantages:'''
 
'''Advantages:'''
* Produces a universal binary.
+
* Can be built on machines running OS X v10.5 or later, and Xcode v3.1.4 or later.
* Binaries run fast.
+
* Binaries can be configured to run in debug mode or in release mode.
* Can be built on machines running OS X v10.5 or later.
+
* Binaries can be configured for PowerPC or Intel compatibility.
 +
* Building the app is faster than the final release build.
  
 
'''Disadvantages:'''
 
'''Disadvantages:'''
* Requires Xcode 3 to build.
+
* Binary compatibility with OS X v10.5 requires Xcode 3 to build.
* Since Xcode 3 is required, builds do not produce the fastest binaries for Intel compared to the Intel-only builds.
+
  
  
=== Standard App (Intel-only) ===
+
=== OS X App (dev+) ===
These build targets are just like the universal builds, except they only run on Intel processors. Since builds no longer need to rely on Xcode 3 for PowerPC compatibility, build targets can be configured to take advantage of all the latest compiler features available, resulting in faster binaries.
+
This build target is just like the normal OS X App build, except it enables additional debugging features, such as the GDB remote stub. This build is meant for developer usage.
  
 
'''Build Target Goals:'''
 
'''Build Target Goals:'''
* Fully featured.
+
* Fully featured, and includes additional debugging features.
* Fastest performance.
+
* Must be compatible with the latest version of Xcode running on the latest version of OS X.
 +
* Quick debug-and-test of code changes.
  
 
'''Advantages:'''
 
'''Advantages:'''
* Produces the fastest running binaries compared to all other build targets.
+
* Can be built on machines running Xcode v4.6.3 or later.
 +
* Binaries can be configured to run in debug mode or in release mode.
 +
* Building the app is faster than the final release build.
  
 
'''Disadvantages:'''
 
'''Disadvantages:'''
 
* Must be built on a machine running OS X v10.7 or later.
 
* Must be built on a machine running OS X v10.7 or later.
 +
* Due to the additional debugging features, performance will be slightly lower compared to the other builds.
  
  
=== Legacy App (Universal) ===
+
=== OS X App (Xcode 6 .XIB for v10.5 Leopard Release Build) ===
These build targets produce a self-contained OS X application package that uses our legacy OS X frontend to run the DeSmuME emulator. These build targets are deprecated, but continue to exist for historical reasons, and also for people who need an app bundle that can run on OS X v10.4.
+
This build target is a helper build target for producing final release builds of DeSmuME. It is used solely as an intermediate build step, and is not intended for normal usage. See [[#OS_X_App_Build_for_Final_Release]] for more details.
 +
 
 +
 
 +
=== OS X App (v10.5 Leopard Release Build) ===
 +
This build target is for producing final release builds of DeSmuME. These builds will use our official OS X frontend contained in an OS X app bundle, and are tuned for the fastest possible performance and the widest binary and OS compatibility.
  
 
'''Build Target Goals:'''
 
'''Build Target Goals:'''
* Binary compatibility with OS X v10.4.
+
* Fully featured.
* Retain legacy code for historical reference.
+
* Widest binary compatibility.
 +
* Widest OS compatibility.
 +
* Fastest performance.
  
 
'''Advantages:'''
 
'''Advantages:'''
* Produces a universal binary.
+
* Produces the fastest running binaries compared to all other build targets.
* Can be built on machines running OS X v10.5 or later.
+
* Produces a universal binary that supports both 32-bit and 64-bit.
* Built applications are backwards compatible with OS X v10.4.
+
* Binaries are compatible with OS X v10.5 and later.
  
 
'''Disadvantages:'''
 
'''Disadvantages:'''
* These builds are deprecated. We no longer do any active development work on the legacy code.
+
* Must be built on a machine running the latest version of OS X and Xcode.
* Built applications use the legacy user interface, which does not expose all of DeSmuME's features to the user.
+
* Building the app for release takes more steps than other builds.
* Requires Xcode 3 to build.
+
* Requires a separate Mac or virtual machine running OS X Mavericks in order to run Xcode v3.2.6 and Xcode v6.2 for the intermediate build steps.
* Produces the slowest running binaries compared to all other build targets.
+
  
  
Line 59: Line 68:
 
'''Build Target Goals:'''
 
'''Build Target Goals:'''
 
* Compatibility with OpenEmu.
 
* Compatibility with OpenEmu.
* Proving good code modularity in the source.
+
* Proving that the core source code is modular enough to be integrated with third-party frontends.
  
 
'''Advantages:'''
 
'''Advantages:'''
 
* Compatible with OpenEmu.
 
* Compatible with OpenEmu.
* Built plug-ins are much smaller in size than full application builds.
+
* Plug-ins are much smaller in size compared to full application builds.
  
 
'''Disadvantages:'''
 
'''Disadvantages:'''
* Must be built on a machine running OS X v10.7 or later.
+
* Must be built on a machine running OS X v10.11 or later.
* Binaries only run on machines with 64-bit Intel processors running OS X v10.7 or later.
+
* Binaries only run on machines with 64-bit Intel processors running OS X v10.11 or later.
 
* The frontend is handled by a third-party application, which will not expose all of DeSmuME's features to the user.
 
* The frontend is handled by a third-party application, which will not expose all of DeSmuME's features to the user.
  
 
=== Available Build Targets ===
 
The following chart is a summary of all of the available build targets. The chart shows where each build target resides in which project, and also which operating system that may be targeted.
 
 
{| class="wikitable" style="text-align: center;"
 
! scope="col" width="140" |
 
! scope="col" width="250" | Project File
 
! scope="col" width="80" | OS X v10.4 (Tiger)
 
! scope="col" width="80" | OS X v10.5 (Leopard)
 
! scope="col" width="80" | OS X v10.6 (Snow Leopard)
 
! scope="col" width="80" | OS X v10.7 (Lion)
 
! scope="col" width="80" | OS X v10.8 (Mountain Lion)
 
|-
 
! scope="row" | Standard App (Universal)
 
| DeSmuME (Xcode 3).xcodeproj
 
| No
 
| Yes
 
| Yes
 
| No
 
| No
 
|-
 
! scope="row" | Standard App (Intel-only)
 
| DeSmuME (Xcode 4).xcodeproj
 
| No
 
| Yes
 
| Yes
 
| Yes
 
| No
 
|-
 
! scope="row" | Legacy App (Universal)
 
| DeSmuME (Legacy).xcodeproj
 
| Yes
 
| Yes
 
| Yes
 
| No
 
| No
 
|-
 
! scope="row" | OpenEmu Plug-in
 
| DeSmuME (XCode 4).xcodeproj
 
| No
 
| No
 
| No
 
| Yes
 
| No
 
|}
 
  
 
== Set Up the Build Environment ==
 
== Set Up the Build Environment ==
All DeSmuME build targets must be built using Apple's Xcode IDE. The Xcode project files, included in the desmume/src/cocoa directory of the source code, are supported for the following versions of Xcode:
+
All DeSmuME build targets must be built using Apple's Xcode IDE. The Xcode project files, included in the "desmume/src/frontend/cocoa" folder of the source code, are supported for the following versions of Xcode:
  
 
{| class="wikitable" style="text-align: center;"
 
{| class="wikitable" style="text-align: center;"
Line 126: Line 90:
 
| v3.1.4 (if running on Leopard); v3.2.6 (if running on Snow Leopard or later)
 
| v3.1.4 (if running on Leopard); v3.2.6 (if running on Snow Leopard or later)
 
|-
 
|-
| DeSmuME (Xcode 4).xcodeproj
+
| DeSmuME (Latest).xcodeproj
| v4.3 or later
+
| v4.6.3 or later
|-
+
| DeSmuME (Legacy).xcodeproj
+
| v3.2.6
+
 
|}
 
|}
  
 
=== Xcode Setup ===
 
=== Xcode Setup ===
It is usually best to install both Xcode 3 and Xcode 4 so that you can use all of the build targets and all of the build options. However, depending on your needs, you may not necessarily need to install both versions of Xcode.
+
Refer to the following conditions to determine which Xcode version you need to install.
  
* If you want to build a standard DeSmuME application that runs on PowerPC machines, you must install Xcode 3.
 
* If you want to build a legacy DeSmuME application, you must install Xcode 3.
 
* If you want to build a standard DeSmuME application that runs on Leopard, but does not require the build enhancements of newer compilers, then you must install Xcode 3, but you may skip installing Xcode 4.
 
* If you are running OS X v10.7 (or "Lion") and you want to build a standard DeSmuME application that does not require backwards compatibility with Leopard, then you may skip installing Xcode 3 and only install Xcode 4.
 
* If you are running OS X v10.7 (or "Lion"), and you want to build a standard DeSmuME application that runs on Leopard and also includes the build enhancements of newer compilers, then you must install both Xcode 3 and Xcode 4.
 
* If you want to build the OpenEmu Plug-in, you must install Xcode 4.
 
  
==== Download Xcode ====
+
You must use Xcode 3 if any of the following conditions apply:
Below are the download links to Xcode 3 and Xcode 4.
+
* You are running OS X v10.5 or v10.6.
 +
* You are building an OS X App that runs on OS X v10.5.
 +
* You are building an OS X App that runs on PowerPC processors.
 +
* You are building an OS X App for final release.
 +
 
 +
 
 +
You must use Xcode 4 or later if any of the following conditions apply:
 +
* You are running OS X v10.7 or later.
 +
* You are building an OpenEmu Plug-in.
 +
* You are building an OS X App for final release.
 +
 
 +
 
 +
'''Note:''' ''Xcode 3 is not compatible with OS X v10.10 Yosemite. If you require the use of Xcode 3, you will need to run it on an older version of OS X.''
 +
 
 +
 
 +
==== Download Xcode 3 ====
 +
You can download Xcode 3 from the Apple Developer Connection website. Note that before you can download anything from the ADC website, you must log in using an Apple Developer ID. Once you are logged in, you may use the provided download links to download Xcode 3.
 +
 
 +
 
 +
If you do not have an Apple Developer ID, you can register one for free.
 +
* ADC Registration: https://developer.apple.com/programs/start/register/create.php
 +
 
 +
If you are not already logged in to ADC, you can log in by accessing the ADC Downloads page.
 +
* ADC Downloads: https://developer.apple.com/downloads
 +
 
 +
Once you are logged in to ADC, you can use the following download links for Xcode 3.
 +
* Xcode v3.1.4 Direct Download Link (for Leopard): http://adcdownload.apple.com/Developer_Tools/xcode_3.1.4_developer_tools/xcode314_2809_developerdvd.dmg
 +
* Xcode v3.2.6 Direct Download Link (for Snow Leopard): http://adcdownload.apple.com/Developer_Tools/xcode_3.2.6_and_ios_sdk_4.3__final/xcode_3.2.6_and_ios_sdk_4.3.dmg
 +
 
 +
If you will be building a Final Release build, then you also need Xcode 6.
 +
* Xcode v6.2 Direct Download Link (for Mavericks): http://download.developer.apple.com/Developer_Tools/Xcode_6.2/Xcode_6.2.dmg
 +
 
 +
==== Download the Latest Version of Xcode ====
 +
Downloading the latest version of Xcode is very easy! If you are running Lion or later and have any Apple ID, then you can download Xcode directly from the Mac App Store.
 +
* Xcode Mac App Store Link (for Lion or later): https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12
  
* Xcode v3.1.4 Direct Download Link: http://adcdownload.apple.com/Developer_Tools/xcode_3.1.4_developer_tools/xcode314_2809_developerdvd.dmg
 
* Xcode v3.2.6 Direct Download Link: http://adcdownload.apple.com/Developer_Tools/xcode_3.2.6_and_ios_sdk_4.3__final/xcode_3.2.6_and_ios_sdk_4.3.dmg
 
* Xcode 4 Mac App Store Link: http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12
 
  
 
==== Uninstall Previous Versions of Xcode ====
 
==== Uninstall Previous Versions of Xcode ====
Line 160: Line 146:
 
'''Note:''' ''You must be logged into an Administrator account to use this command.''
 
'''Note:''' ''You must be logged into an Administrator account to use this command.''
  
'''Note:''' ''This command assumes that Xcode was installed at the default location. The path to the uninstall-devtools script may be different if you did not use the default location when installing Xcode from before.''
+
'''Note:''' ''This command assumes that Xcode was installed at the default location, /Developer. The path to the uninstall-devtools script may be different if you did not use the default location when installing Xcode from before.''
 +
 
  
 
==== Set Up Xcode 3 ====
 
==== Set Up Xcode 3 ====
 
'''Note:''' ''If you do not require the build options that Xcode 3 provides, then you may skip this step. See the Xcode Setup section for more details.''
 
'''Note:''' ''If you do not require the build options that Xcode 3 provides, then you may skip this step. See the Xcode Setup section for more details.''
  
After Xcode 3 is downloaded, you will have a traditional .dmg disk image containing a package installer. Start the Xcode 3 installation by opening the installer, and follow the onscreen instructions until you get to the installation list.
+
After Xcode 3 is downloaded, you will have a .dmg disk image containing a package installer. Start the Xcode 3 installation by opening the installer, and follow the onscreen instructions until you get to the installation list.
  
Your installation may be different, depending on your needs:
+
Once the installation list is shown, do the following:
* If you are planning on using the Legacy project, you will need to install the Mac OS X 10.4 SDK.
+
* Unless you are planning on building other software that must run on OS X v10.4, you may deselect the Mac OS X 10.4 SDK. (DeSmuME can only run on OS X v10.5 or later.)
* If you are planning on installing Xcode 4, take note of the install location. You will need it later for when you need to make symbolic links between Xcode 3 and Xcode 4. We recommend using the default location, /Developer.
+
* If you are planning on installing the latest version of Xcode alongside Xcode 3, then deselect "System Tools" and "Essentials > iOS SDK". Since the latest Xcode will already have the newest version of the iOS SDK, installing the version included with Xcode 3 will be a waste of time and disk space.
* If you are planning on installing Xcode 4, then you should skip installing the iOS SDK, which is listed under Essentials. Since Xcode 4 already has a newer version of the iOS SDK, installing the version included with Xcode 3 will be a waste of time and disk space.
+
  
 
Continue the installation as normal and let the installation finish.
 
Continue the installation as normal and let the installation finish.
  
==== Set Up Xcode 4 ====
 
When you download Xcode 4 from the Mac App Store, the application should already install itself to the Applications folder once the download is complete.
 
  
'''Note:''' ''If you do not require the build options that Xcode 4 provides, then you may skip this step. See the Xcode Setup section for more details.''
+
==== Set Up the Latest Version of Xcode ====
 +
When you download Xcode from the Mac App Store, Xcode should automatically install itself to the Applications folder once the download is complete. There are no additional steps. Pretty easy, right?
  
To support SDKs older than OS X v10.6 (or "Snow Leopard") in Xcode 4, you must first install Xcode 3, then make symbolic links from the Xcode 3 SDKs directory into the Xcode 4 SDKs directory. To do this, open Terminal and type the following commands into the command line:
 
  
cd /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs
+
== Download the DeSmuME Source Code ==
sudo ln -s /Developer/SDKs/MacOSX10.4u.sdk
+
The DeSmuME source code is managed using git and is hosted on GitHub.
sudo ln -s /Developer/SDKs/MacOSX10.5.sdk
+
* DeSmuME "master" Branch Download Link: https://github.com/TASVideos/desmume/archive/master.zip
  
'''Note:''' ''You must be logged into an Administrator account to use these commands.''
 
  
'''Note:''' ''These commands assume that Xcode 3 was installed at the default location. The path to the SDKs directory may be different if you did not use the default location when installing Xcode 3.''
+
== Build the DeSmuME Source ==
 +
Regardless of which build target you will be using, you will need to use one of the Xcode project files provided with the DeSmuME source code. For most cases, you will want to build the latest revision. So from the source code folder, navigate to the "/desmume/src/frontend/cocoa" folder.
  
Now, the OS X v10.4 (or "Tiger") and Leopard SDKs should now be available in Xcode 4.
+
There should be two Xcode project files present in this folder:
 +
* DeSmuME (XCode 3).xcodeproj
 +
* DeSmuME (Latest).xcodeproj
  
== Download the DeSmuME Source Code ==
 
TBD
 
  
=== Download via SourceForge ===
+
=== OS X App Build ===
TBD
+
This is the quickest and easiest way to get started with using a pre-release build of DeSmuME.
  
=== Download via Command Line ===
+
==== Building Using Xcode 3 ====
TBD
+
1. Open the "DeSmuME (XCode 3).xcodeproj" project file using Xcode 3.
  
== Build the DeSmuME Source ==
+
2. In the Build Target menu (located in the upper-left corner of the project window), under Active Configuration, choose Release.
TBD
+
 
 +
3. In the Build Target menu, under Active Target, choose one of the four build targets.
 +
 
 +
4. Choose Build > Build, and then wait for Xcode to finish building the app.
 +
 
 +
And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Release" folder. If you built the app using the "DeSmuME (XCode 3).xcodeproj" project file, then the built app will also include the current git commit number.
 +
 
 +
==== Building Using the Latest Version of Xcode ====
 +
1. Open the "DeSmuME (Latest).xcodeproj" project file using Xcode.
 +
 
 +
2. Choose Product > Scheme > DeSmuME (OS X App).
 +
 
 +
3. In Xcode, choose Product > Build For > Profiling, and then wait for Xcode to finish building the app.
 +
 
 +
And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Release" folder.
 +
 
 +
 
 +
=== OS X App Dev+ Build ===
 +
The steps here are similar to that of the normal OS X App build, but will produce the developer-oriented build instead. In addition, you must be using Xcode 4 or later to make this build.
 +
 
 +
1. Open the "DeSmuME (Latest).xcodeproj" project file using Xcode.
 +
 
 +
2. Choose Product > Scheme > DeSmuME (OS X App, dev+).
 +
 
 +
''If you want to run dev+ build with Xcode's LLDB debugger:''
 +
 
 +
3a. Click Run. This will build a Debug version of the app, which will automatically launch when finished.
 +
 
 +
And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Debug" folder.
 +
 
 +
''If you need to use the dev+ build without running the debugger:''
 +
 
 +
3b. In Xcode, choose Product > Build For > Profiling, and then wait for Xcode to finish building the app. (Note that this build does use program optimizations.)
 +
 
 +
And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Release" folder.
 +
 
 +
 
 +
=== OS X App Build for Final Release ===
 +
This is the process that we use for our official release builds. To make this build, you must meet the following requirements:
 +
* You must have both Xcode v3.2.6 and Xcode v6.2 installed on a system running OS X Mavericks v10.9.5.
 +
* You must have the latest version of Xcode running on the latest version of macOS. (At the time of this writing, the latest version of Xcode is v9.1, and the latest version of macOS is 10.13.1.)
 +
 
 +
1. Let's start with building on OS X Mavericks: Open the "DeSmuME (XCode 3).xcodeproj" project file using Xcode 3.
 +
 
 +
2. In the Build Target menu (located in the upper-left corner of the project window), under Active Configuration, choose Release.
 +
 
 +
3. In the Build Target menu, under Active Target, choose the build target "DeSmuME (OS X App; PowerPC Release Build)".
 +
 
 +
4. Choose Build > Clean All Targets.
 +
 
 +
5. In the Clean All Targets sheet, check all options, then click Clean, and then wait for the clean process to finish.
 +
 
 +
6. Choose Build > Build, and then wait for the build process to finish. This will make a new app called "DeSmuME (PPC).app" in the "/desmume/src/frontend/cocoa/build/Release" folder.
 +
 
 +
7. While still on OS X Mavericks: Open the "DeSmuME (Latest).xcodeproj" project file using Xcode 6.2.
 +
 
 +
8. Choose Product > Scheme > DeSmuME (OS X App; Xcode 6 .XIB for v10.5 Leopard Release Build).
 +
 
 +
9. Choose Product > Clean, and then wait for the clean process to finish.
 +
 
 +
10. Choose Product > Build, and then wait for the build process to finish. This will make a new app called "DeSmuME (Xcode 6).app" in the "/desmume/src/frontend/cocoa/build/Release" folder.
 +
 
 +
11. Quit both Xcode 3 and Xcode 6 on OS X Mavericks.
 +
 
 +
12. On the latest macOS: Open the "DeSmuME (Latest).xcodeproj" project file using the latest version of Xcode.
 +
 
 +
13. Choose Product > Scheme > DeSmuME (OS X App; v10.5 Leopard Release Build).
 +
 
 +
14. Choose Product > Clean, and then wait for the clean process to finish.
 +
 
 +
15. Choose Product > Perform Action > Generate Optimization Profile.
 +
 
 +
16. In the Generate Optimization Profile sheet, ensure that Use Run Action is the selected option, and then click Run.
 +
 
 +
17. Wait for Xcode to finish building the app. When Xcode finishes, DeSmuME.app will automatically launch.
 +
 
 +
18. Perform the recommended PGO exercises listed on this page: TBD
 +
 
 +
19. After all PGO exercises are complete, quit DeSmuME.app. Xcode should now report that it has generated an optimization profile.
 +
 
 +
20. In Xcode, choose Product > Build For > Profiling, and then wait for Xcode to finish.
 +
 
 +
And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Merged Release" folder.
 +
 
 +
 
 +
=== OpenEmu Plug-in Build ===
 +
The DeSmuME OpenEmu plug-in is used as an extension to the OpenEmu application. Installing the plug-in involves building OpenEmuBase.framework from source, then moving the framework to the "desmume/src/frontend/cocoa/openemu" folder, then building the plug-in from source, and then finally placing the plug-in into the ~/Library/Application Support/OpenEmu/Cores folder.
 +
 
 +
 
 +
You can download the OpenEmu SDK source code from here:
 +
* OpenEmu SDK Download Link: https://github.com/OpenEmu/OpenEmu-SDK/archive/master.zip
 +
 
 +
 
 +
==== Building and installing OpenEmuBase.framework from source ====
 +
1. Open the "OpenEmu-SDK.xcodeproj" project file using the latest version of Xcode.
 +
 
 +
2. Choose Product > Scheme > OpenEmuBase.
 +
 
 +
3. Click Run. This will build a Debug version of the framework.
 +
 
 +
4. After the build finishes, choose Product > Build For > Profiling. This will start building the Release version of the framework.
 +
 
 +
5. In the Xcode sidebar, expand the Products folder. This should show "OpenEmuBase.framework".
 +
 
 +
6. Click "OpenEmuBase.framework", and then choose File > Show in Finder.
 +
 
 +
7. In the Finder window that appears, you should be in a folder named "Debug". Right-click the window title (which should read "Debug"), and then choose the "Products" folder underneath it.
 +
 
 +
8. Wait for Xcode to finish building the Release version framework.
 +
 
 +
9. In the Finder, from the "Products" folder, open the "Release" folder.
 +
 
 +
10. Move OpenEmuBase.framework into the "desmume/src/frontend/cocoa/openemu" folder.
 +
 
 +
==== Building the OpenEmu plug-in ====
 +
'''Note:''' ''In order to build the OpenEmu plug-in, it is mandatory that OpenEmuBase.framework is present in the "desmume/src/frontend/cocoa/openemu" folder. Otherwise, the build will fail due to missing frameworks.''
 +
 
 +
1. Open the "DeSmuME (Latest).xcodeproj" project file using the latest version of Xcode.
 +
 
 +
2. Choose Product > Scheme > DeSmuME (OpenEmu Plug-in).
 +
 
 +
3. Click Run. This will build a Debug version of the plug-in.
 +
 
 +
4. After the build finishes, choose Product > Build For > Profiling. This will start building the Release version of the plug-in.
 +
 
 +
5. In the Xcode sidebar, expand the Products folder. This should show the "DeSmuME.oecoreplugin" bundle.
 +
 
 +
6. Click "DeSmuME.oecoreplugin", and then choose Show in Finder.
 +
 
 +
7. In the Finder window that appears, you should be in a folder named "Debug". Right-click (or Control-click) the window title (which should read "Debug"), and then choose the "Products" folder underneath it.
 +
 
 +
8. Wait for Xcode to finish building the Release version plug-in.
 +
 
 +
9. In the Finder, from the "Products" folder, open the "Release" folder.
 +
 
 +
10. Choose New > New Finder Window.
  
=== Standard App Build Using the Xcode 3 Project ===
+
11. With the new Finder window selected, choose Go > Go To Folder.
TBD
+
  
=== Standard App Build Using the Xcode 4 Project ===
+
12. In the drop-down sheet, in the "Go to the folder" text field, enter the following exactly as shown:
TBD
+
~/Library/Application Support/OpenEmu/Cores
  
=== Official-like App Build Using lipo ===
+
13. Move the DeSmuME.oecoreplugin bundle from the Release folder into the Cores folder.
TBD
+
  
=== Legacy App Build Using the Legacy Project ===
+
And that's it! The DeSmuME OpenEmu plug-in should now be installed. You should now be able to run NDS ROMs from within OpenEmu.app.
TBD
+
  
=== OpenEmu Plug-in Build Using the Xcode 4 Project ===
 
TBD
 
  
 
== Appendix A: Comparison Charts of Different Builds ==
 
== Appendix A: Comparison Charts of Different Builds ==
TBD
 
  
 
=== Build Compatibility ===
 
=== Build Compatibility ===
TBD
+
The table below lists a summary of both binary and operating system compatibility for all possible builds.
 +
 
 +
'''Note:''' ''All binaries will not be compatible with OS X v10.4 (Tiger) or earlier.''
  
 
{| class="wikitable" style="text-align: center;"
 
{| class="wikitable" style="text-align: center;"
! scope="col" width="140" |
+
! scope="col" width="150" |
! scope="col" width="100" | Standard App (Xcode 3)
+
! scope="col" width="150" | OS X App
! scope="col" width="100" | Standard App (Xcode 4)
+
! scope="col" width="150" | OS X App (dev+)
! scope="col" width="100" | Official-like App (lipo)
+
! scope="col" width="150" | OS X App (Final Release)
! scope="col" width="100" | Legacy App (Xcode 3 Legacy)
+
! scope="col" width="150" | OpenEmu Plug-in
! scope="col" width="100" | OpenEmu Plug-in (Xcode 4)
+
 
|-
 
|-
 
! scope="row" | PowerPC, 32-bit
 
! scope="row" | PowerPC, 32-bit
| Yes
+
| Yes[1]
 
| No
 
| No
| Yes
 
 
| Yes
 
| Yes
 
| No
 
| No
 
|-
 
|-
 
! scope="row" | PowerPC, 64-bit
 
! scope="row" | PowerPC, 64-bit
| Yes
+
| Yes[1]
 +
| No
 
| No
 
| No
| Yes
 
| Yes
 
 
| No
 
| No
 
|-
 
|-
 
! scope="row" | Intel, 32-bit
 
! scope="row" | Intel, 32-bit
| Yes
 
 
| Yes
 
| Yes
 
| Yes
 
| Yes
Line 254: Line 365:
 
|-
 
|-
 
! scope="row" | Intel, 64-bit
 
! scope="row" | Intel, 64-bit
| Yes
 
 
| Yes
 
| Yes
 
| Yes
 
| Yes
Line 260: Line 370:
 
| Yes
 
| Yes
 
|-
 
|-
! scope="row" | OS X v10.4 (Tiger)
+
! scope="row" | OS X v10.5 (Leopard)
 +
| Yes
 
| No
 
| No
 +
| Yes
 
| No
 
| No
 +
|-
 +
! scope="row" | OS X v10.6 (Snow Leopard)
 +
| Yes
 
| No
 
| No
 
| Yes
 
| Yes
 
| No
 
| No
 
|-
 
|-
! scope="row" | OS X v10.5 (Leopard)
+
! scope="row" | OS X v10.7 (Lion)
 
| Yes
 
| Yes
 +
| Yes
 +
| Yes
 +
| No
 +
|-
 +
! scope="row" | OS X v10.8 (Mountain Lion)
 
| Yes
 
| Yes
 
| Yes
 
| Yes
Line 274: Line 394:
 
| No
 
| No
 
|-
 
|-
! scope="row" | OS X v10.6 (Snow Leopard)
+
! scope="row" | OS X v10.9 (Mavericks)
 
| Yes
 
| Yes
 +
| Yes
 +
| Yes
 +
| No
 +
|-
 +
! scope="row" | OS X v10.10 (Yosemite)
 
| Yes
 
| Yes
 
| Yes
 
| Yes
Line 281: Line 406:
 
| No
 
| No
 
|-
 
|-
! scope="row" | OS X v10.7 (Lion)
+
! scope="row" | OS X v10.11 (El Capitan)
 
| Yes
 
| Yes
 +
| Yes
 +
| Yes
 +
| Yes
 +
|-
 +
! scope="row" | OS X v10.12 (Sierra)
 
| Yes
 
| Yes
 
| Yes
 
| Yes
Line 288: Line 418:
 
| Yes
 
| Yes
 
|-
 
|-
! scope="row" | OS X v10.8 (Mountain Lion)
+
! scope="row" | OS X v10.13 (High Sierra)
| Unknown
+
| Yes
| Unknown
+
| Yes
| Unknown
+
| Yes
| Unknown
+
| Yes
| Unknown
+
 
|}
 
|}
  
 +
1. Available only by configuration in Xcode 3.
  
=== Feature Comparison of App Builds ===
+
== Appendix B: Installing DeSmuME From Source (Legacy Instructions) ==
TBD
+
This is a document that described an older method for installing DeSmuME from the source code. It is now obsolete and no longer supported by the DeSmuME team. You can view it here: [[Installing DeSmuME from source on Mac OS X (Legacy Instructions)]]
 
+
{| class="wikitable" style="text-align: center;"
+
! scope="col" width="140" |
+
! scope="col" width="100" | Standard App (Xcode 3)
+
! scope="col" width="100" | Standard App (Xcode 4)
+
! scope="col" width="100" | Official-like App (lipo)
+
! scope="col" width="100" | Legacy App (Xcode 3 Legacy)
+
|-
+
! scope="row" | Relative Performance
+
| Fast
+
| Fastest
+
| Fastest
+
| Slow
+
|-
+
! scope="row" | User Interface
+
| Current
+
| Current
+
| Current
+
| Based on v0.9.7
+
|}
+

Revision as of 01:07, 16 November 2017

Contents

About the Build Targets

DeSmuME for OS X may be built using several different configurations. Each build configuration is listed in an Xcode project as a "build target." The Xcode project files, provided with the DeSmuME source code, include several build targets to suit your needs. Many build targets are similar to each other, and so they have been organized into the following categories, based on what the build target produces.


OS X App

These build targets produce a self-contained OS X application package (or "app bundle"). These builds use our official OS X frontend to run the DeSmuME emulator, and are designed for the debugging and testing of pre-release builds. These app bundles are compatible with OS X v10.6 or later. (Also compatible with OS X v10.5 if building from the Xcode 3 project).

Build Target Goals:

  • Fully featured.
  • Widest build compatibility with Xcode versions running different OS X versions.
  • Quick debug-and-test of code changes.

Advantages:

  • Can be built on machines running OS X v10.5 or later, and Xcode v3.1.4 or later.
  • Binaries can be configured to run in debug mode or in release mode.
  • Binaries can be configured for PowerPC or Intel compatibility.
  • Building the app is faster than the final release build.

Disadvantages:

  • Binary compatibility with OS X v10.5 requires Xcode 3 to build.


OS X App (dev+)

This build target is just like the normal OS X App build, except it enables additional debugging features, such as the GDB remote stub. This build is meant for developer usage.

Build Target Goals:

  • Fully featured, and includes additional debugging features.
  • Must be compatible with the latest version of Xcode running on the latest version of OS X.
  • Quick debug-and-test of code changes.

Advantages:

  • Can be built on machines running Xcode v4.6.3 or later.
  • Binaries can be configured to run in debug mode or in release mode.
  • Building the app is faster than the final release build.

Disadvantages:

  • Must be built on a machine running OS X v10.7 or later.
  • Due to the additional debugging features, performance will be slightly lower compared to the other builds.


OS X App (Xcode 6 .XIB for v10.5 Leopard Release Build)

This build target is a helper build target for producing final release builds of DeSmuME. It is used solely as an intermediate build step, and is not intended for normal usage. See #OS_X_App_Build_for_Final_Release for more details.


OS X App (v10.5 Leopard Release Build)

This build target is for producing final release builds of DeSmuME. These builds will use our official OS X frontend contained in an OS X app bundle, and are tuned for the fastest possible performance and the widest binary and OS compatibility.

Build Target Goals:

  • Fully featured.
  • Widest binary compatibility.
  • Widest OS compatibility.
  • Fastest performance.

Advantages:

  • Produces the fastest running binaries compared to all other build targets.
  • Produces a universal binary that supports both 32-bit and 64-bit.
  • Binaries are compatible with OS X v10.5 and later.

Disadvantages:

  • Must be built on a machine running the latest version of OS X and Xcode.
  • Building the app for release takes more steps than other builds.
  • Requires a separate Mac or virtual machine running OS X Mavericks in order to run Xcode v3.2.6 and Xcode v6.2 for the intermediate build steps.


OpenEmu Plug-in

These build targets produce a plug-in bundle that is compatible with the OpenEmu application (http://openemu.org/). These build targets exist to prove that our DeSmuME source code is modular enough to be adapted easily into other applications. In this case, the plug-in contains the DeSmuME emulator backend, while OpenEmu acts as the frontend that runs the emulator.

Build Target Goals:

  • Compatibility with OpenEmu.
  • Proving that the core source code is modular enough to be integrated with third-party frontends.

Advantages:

  • Compatible with OpenEmu.
  • Plug-ins are much smaller in size compared to full application builds.

Disadvantages:

  • Must be built on a machine running OS X v10.11 or later.
  • Binaries only run on machines with 64-bit Intel processors running OS X v10.11 or later.
  • The frontend is handled by a third-party application, which will not expose all of DeSmuME's features to the user.


Set Up the Build Environment

All DeSmuME build targets must be built using Apple's Xcode IDE. The Xcode project files, included in the "desmume/src/frontend/cocoa" folder of the source code, are supported for the following versions of Xcode:

Project File Name Supported Xcode Version
DeSmuME (Xcode 3).xcodeproj v3.1.4 (if running on Leopard); v3.2.6 (if running on Snow Leopard or later)
DeSmuME (Latest).xcodeproj v4.6.3 or later

Xcode Setup

Refer to the following conditions to determine which Xcode version you need to install.


You must use Xcode 3 if any of the following conditions apply:

  • You are running OS X v10.5 or v10.6.
  • You are building an OS X App that runs on OS X v10.5.
  • You are building an OS X App that runs on PowerPC processors.
  • You are building an OS X App for final release.


You must use Xcode 4 or later if any of the following conditions apply:

  • You are running OS X v10.7 or later.
  • You are building an OpenEmu Plug-in.
  • You are building an OS X App for final release.


Note: Xcode 3 is not compatible with OS X v10.10 Yosemite. If you require the use of Xcode 3, you will need to run it on an older version of OS X.


Download Xcode 3

You can download Xcode 3 from the Apple Developer Connection website. Note that before you can download anything from the ADC website, you must log in using an Apple Developer ID. Once you are logged in, you may use the provided download links to download Xcode 3.


If you do not have an Apple Developer ID, you can register one for free.

If you are not already logged in to ADC, you can log in by accessing the ADC Downloads page.

Once you are logged in to ADC, you can use the following download links for Xcode 3.

If you will be building a Final Release build, then you also need Xcode 6.

Download the Latest Version of Xcode

Downloading the latest version of Xcode is very easy! If you are running Lion or later and have any Apple ID, then you can download Xcode directly from the Mac App Store.


Uninstall Previous Versions of Xcode

We highly recommend that you uninstall any previous versions of Xcode before you begin your installation. Doing so will better guarantee that you will have a clean build environment for DeSmuME. The easiest method for uninstalling Xcode is to use the uninstall-devtools script, located in the Library folder of your Xcode installation.

Note: You do not need to uninstall any versions of Xcode that are v4.3 or later. These versions of Xcode are self-contained application packages, which do not conflict with other Xcode versions.

To uninstall Xcode, open Terminal and type the following command into the command line:

sudo /Developer/Library/uninstall-devtools -mode=all

Note: You must be logged into an Administrator account to use this command.

Note: This command assumes that Xcode was installed at the default location, /Developer. The path to the uninstall-devtools script may be different if you did not use the default location when installing Xcode from before.


Set Up Xcode 3

Note: If you do not require the build options that Xcode 3 provides, then you may skip this step. See the Xcode Setup section for more details.

After Xcode 3 is downloaded, you will have a .dmg disk image containing a package installer. Start the Xcode 3 installation by opening the installer, and follow the onscreen instructions until you get to the installation list.

Once the installation list is shown, do the following:

  • Unless you are planning on building other software that must run on OS X v10.4, you may deselect the Mac OS X 10.4 SDK. (DeSmuME can only run on OS X v10.5 or later.)
  • If you are planning on installing the latest version of Xcode alongside Xcode 3, then deselect "System Tools" and "Essentials > iOS SDK". Since the latest Xcode will already have the newest version of the iOS SDK, installing the version included with Xcode 3 will be a waste of time and disk space.

Continue the installation as normal and let the installation finish.


Set Up the Latest Version of Xcode

When you download Xcode from the Mac App Store, Xcode should automatically install itself to the Applications folder once the download is complete. There are no additional steps. Pretty easy, right?


Download the DeSmuME Source Code

The DeSmuME source code is managed using git and is hosted on GitHub.


Build the DeSmuME Source

Regardless of which build target you will be using, you will need to use one of the Xcode project files provided with the DeSmuME source code. For most cases, you will want to build the latest revision. So from the source code folder, navigate to the "/desmume/src/frontend/cocoa" folder.

There should be two Xcode project files present in this folder:

  • DeSmuME (XCode 3).xcodeproj
  • DeSmuME (Latest).xcodeproj


OS X App Build

This is the quickest and easiest way to get started with using a pre-release build of DeSmuME.

Building Using Xcode 3

1. Open the "DeSmuME (XCode 3).xcodeproj" project file using Xcode 3.

2. In the Build Target menu (located in the upper-left corner of the project window), under Active Configuration, choose Release.

3. In the Build Target menu, under Active Target, choose one of the four build targets.

4. Choose Build > Build, and then wait for Xcode to finish building the app.

And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Release" folder. If you built the app using the "DeSmuME (XCode 3).xcodeproj" project file, then the built app will also include the current git commit number.

Building Using the Latest Version of Xcode

1. Open the "DeSmuME (Latest).xcodeproj" project file using Xcode.

2. Choose Product > Scheme > DeSmuME (OS X App).

3. In Xcode, choose Product > Build For > Profiling, and then wait for Xcode to finish building the app.

And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Release" folder.


OS X App Dev+ Build

The steps here are similar to that of the normal OS X App build, but will produce the developer-oriented build instead. In addition, you must be using Xcode 4 or later to make this build.

1. Open the "DeSmuME (Latest).xcodeproj" project file using Xcode.

2. Choose Product > Scheme > DeSmuME (OS X App, dev+).

If you want to run dev+ build with Xcode's LLDB debugger:

3a. Click Run. This will build a Debug version of the app, which will automatically launch when finished.

And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Debug" folder.

If you need to use the dev+ build without running the debugger:

3b. In Xcode, choose Product > Build For > Profiling, and then wait for Xcode to finish building the app. (Note that this build does use program optimizations.)

And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Release" folder.


OS X App Build for Final Release

This is the process that we use for our official release builds. To make this build, you must meet the following requirements:

  • You must have both Xcode v3.2.6 and Xcode v6.2 installed on a system running OS X Mavericks v10.9.5.
  • You must have the latest version of Xcode running on the latest version of macOS. (At the time of this writing, the latest version of Xcode is v9.1, and the latest version of macOS is 10.13.1.)

1. Let's start with building on OS X Mavericks: Open the "DeSmuME (XCode 3).xcodeproj" project file using Xcode 3.

2. In the Build Target menu (located in the upper-left corner of the project window), under Active Configuration, choose Release.

3. In the Build Target menu, under Active Target, choose the build target "DeSmuME (OS X App; PowerPC Release Build)".

4. Choose Build > Clean All Targets.

5. In the Clean All Targets sheet, check all options, then click Clean, and then wait for the clean process to finish.

6. Choose Build > Build, and then wait for the build process to finish. This will make a new app called "DeSmuME (PPC).app" in the "/desmume/src/frontend/cocoa/build/Release" folder.

7. While still on OS X Mavericks: Open the "DeSmuME (Latest).xcodeproj" project file using Xcode 6.2.

8. Choose Product > Scheme > DeSmuME (OS X App; Xcode 6 .XIB for v10.5 Leopard Release Build).

9. Choose Product > Clean, and then wait for the clean process to finish.

10. Choose Product > Build, and then wait for the build process to finish. This will make a new app called "DeSmuME (Xcode 6).app" in the "/desmume/src/frontend/cocoa/build/Release" folder.

11. Quit both Xcode 3 and Xcode 6 on OS X Mavericks.

12. On the latest macOS: Open the "DeSmuME (Latest).xcodeproj" project file using the latest version of Xcode.

13. Choose Product > Scheme > DeSmuME (OS X App; v10.5 Leopard Release Build).

14. Choose Product > Clean, and then wait for the clean process to finish.

15. Choose Product > Perform Action > Generate Optimization Profile.

16. In the Generate Optimization Profile sheet, ensure that Use Run Action is the selected option, and then click Run.

17. Wait for Xcode to finish building the app. When Xcode finishes, DeSmuME.app will automatically launch.

18. Perform the recommended PGO exercises listed on this page: TBD

19. After all PGO exercises are complete, quit DeSmuME.app. Xcode should now report that it has generated an optimization profile.

20. In Xcode, choose Product > Build For > Profiling, and then wait for Xcode to finish.

And you're done! The newly built app will be present in the "/desmume/src/frontend/cocoa/build/Merged Release" folder.


OpenEmu Plug-in Build

The DeSmuME OpenEmu plug-in is used as an extension to the OpenEmu application. Installing the plug-in involves building OpenEmuBase.framework from source, then moving the framework to the "desmume/src/frontend/cocoa/openemu" folder, then building the plug-in from source, and then finally placing the plug-in into the ~/Library/Application Support/OpenEmu/Cores folder.


You can download the OpenEmu SDK source code from here:


Building and installing OpenEmuBase.framework from source

1. Open the "OpenEmu-SDK.xcodeproj" project file using the latest version of Xcode.

2. Choose Product > Scheme > OpenEmuBase.

3. Click Run. This will build a Debug version of the framework.

4. After the build finishes, choose Product > Build For > Profiling. This will start building the Release version of the framework.

5. In the Xcode sidebar, expand the Products folder. This should show "OpenEmuBase.framework".

6. Click "OpenEmuBase.framework", and then choose File > Show in Finder.

7. In the Finder window that appears, you should be in a folder named "Debug". Right-click the window title (which should read "Debug"), and then choose the "Products" folder underneath it.

8. Wait for Xcode to finish building the Release version framework.

9. In the Finder, from the "Products" folder, open the "Release" folder.

10. Move OpenEmuBase.framework into the "desmume/src/frontend/cocoa/openemu" folder.

Building the OpenEmu plug-in

Note: In order to build the OpenEmu plug-in, it is mandatory that OpenEmuBase.framework is present in the "desmume/src/frontend/cocoa/openemu" folder. Otherwise, the build will fail due to missing frameworks.

1. Open the "DeSmuME (Latest).xcodeproj" project file using the latest version of Xcode.

2. Choose Product > Scheme > DeSmuME (OpenEmu Plug-in).

3. Click Run. This will build a Debug version of the plug-in.

4. After the build finishes, choose Product > Build For > Profiling. This will start building the Release version of the plug-in.

5. In the Xcode sidebar, expand the Products folder. This should show the "DeSmuME.oecoreplugin" bundle.

6. Click "DeSmuME.oecoreplugin", and then choose Show in Finder.

7. In the Finder window that appears, you should be in a folder named "Debug". Right-click (or Control-click) the window title (which should read "Debug"), and then choose the "Products" folder underneath it.

8. Wait for Xcode to finish building the Release version plug-in.

9. In the Finder, from the "Products" folder, open the "Release" folder.

10. Choose New > New Finder Window.

11. With the new Finder window selected, choose Go > Go To Folder.

12. In the drop-down sheet, in the "Go to the folder" text field, enter the following exactly as shown:

~/Library/Application Support/OpenEmu/Cores

13. Move the DeSmuME.oecoreplugin bundle from the Release folder into the Cores folder.

And that's it! The DeSmuME OpenEmu plug-in should now be installed. You should now be able to run NDS ROMs from within OpenEmu.app.


Appendix A: Comparison Charts of Different Builds

Build Compatibility

The table below lists a summary of both binary and operating system compatibility for all possible builds.

Note: All binaries will not be compatible with OS X v10.4 (Tiger) or earlier.

OS X App OS X App (dev+) OS X App (Final Release) OpenEmu Plug-in
PowerPC, 32-bit Yes[1] No Yes No
PowerPC, 64-bit Yes[1] No No No
Intel, 32-bit Yes Yes Yes No
Intel, 64-bit Yes Yes Yes Yes
OS X v10.5 (Leopard) Yes No Yes No
OS X v10.6 (Snow Leopard) Yes No Yes No
OS X v10.7 (Lion) Yes Yes Yes No
OS X v10.8 (Mountain Lion) Yes Yes Yes No
OS X v10.9 (Mavericks) Yes Yes Yes No
OS X v10.10 (Yosemite) Yes Yes Yes No
OS X v10.11 (El Capitan) Yes Yes Yes Yes
OS X v10.12 (Sierra) Yes Yes Yes Yes
OS X v10.13 (High Sierra) Yes Yes Yes Yes

1. Available only by configuration in Xcode 3.

Appendix B: Installing DeSmuME From Source (Legacy Instructions)

This is a document that described an older method for installing DeSmuME from the source code. It is now obsolete and no longer supported by the DeSmuME team. You can view it here: Installing DeSmuME from source on Mac OS X (Legacy Instructions)

Personal tools