jai-resources/macos_development/how_to_debug_in_xcode.md

# Debugging on OSX

**TODO: Figure out why Xcode detaches from the process after you take a Metal snapshot, leavin the window there forever**

## Basics

1. Open XCode
2. Create a new Project using the External Build Tool configuration
3. Set the Build Tool for the target to either:
  - `/usr/bin/true` - this is essentially a no-op if you want to be building elsewhere
  - `../bin/build.sh` (or similar) - the path to your build script. IMPORTANT: it seems Xcode doesn't resolve absolute paths, just paths relative to the project location.
4. With the project open go to `Product > Scheme > Edit Scheme > Run > Info > Executable` and select the executable you want to run.
5. Cmd+R to Run.

Debugging this way, you can have Xcode run an executable in a .app or just from any directory. There do seem to be differences in the ways some graphics systems are initialized - I get different window scaling in each case.

### Breakpoints

To get breakpoints to work, you have to tell Xcode to treat your .jai files as source code.

1. Right click your file.
2. Select show file inspector.
3. In the Inspector, change Type from "Default - Plain Text" to "C Source"

You should now be able to set breakpoints in that file.
As far as I can tell, there isn't a convenient way to set all .jai files to be loaded as C Source files so you have to do this individually.

## Graphics

### OpenGL
_I didn't have any luck with any of Xcode's graphics debugging utilities while developing for OpenGL._

### Metal
If you want to use XCode's Metal Graphics Debugging utilities, follow these steps:

1. `Product > Scheme > Edit Scheme > Diagnostics`
2. Turn on/off any options in the Metal section at the bottom.

*Note: Some of these will crash your app if you fail their checks.*

## Errors

**The specified architecture 'arm64-*-*' is not compatible with 'x86_64-apple-macosx10.13.0' in '/Users/ps/work/minos/p_scratch/package/scratch.app/Contents/MacOS/scratch'**
_This will happen if you are trying to debug an x86/x86_64 executable on an arm machine._

1. Go to Product > Destination > Destination Architectures > Show Both
2. Select Intel (Rosetta)

## Sources:
- [Basics](https://developer.apple.com/forums/thread/65025)
- [Video](https://www.youtube.com/watch?v=QVcjh6Kvnyw)