Although Mojave has been out for a really long time, when I first upgraded I had problems with SDL 1.2.x programs starting up on a black screen. Sometimes resizing the window would work - when the application allowed it. Otherwise, I’d just be stuck with a blank screen and the program continuing without me.

It got bad enough that for some programs, like the QUASI88 PC-88 emulator, I ended up quickly porting them to SDL 2.x, which didn’t have the problem. When I was doing some research, it looked like patches had been provided, but not merged into SDL 1.x. I decided I would just work around it until the patches were accepted.

However, even a few years later, when I had upgraded to Catalina, the problem was still there. I could have saved myself a lot of time if I just figured out how Homebrew, my package manager, worked. All of the programs I was building, including those in Rust, were linking against the SDL libraries provided by Homebrew. The latest versions of the SDL packages in Homebrew had those fixes! I just needed to update to get them.

My initial understanding was that Homebrew would keep itself up to date, but it seems to get “stuck” onto a specific version and force you to manually “unlink” old versions and replace them if you ever want to upgrade a library. This makes a lot of sense to keep from breaking your existing install, but it’s a bit of a pain if one of your old libraries magically breaks and a dumb Debian-style “update everything” doesn’t work.

Here’s what I ended up doing:

1. brew unlink sdl. This removes the symlinks to the currently installed version (for me, it was sdl 1.2.15_1) and lets you install another as the “main” version.
2. brew install sdl --HEAD. This, obviously, installs SDL from the HEAD revision of its repo. This command actually failed because I didn’t have Mercurial installed on this computer, so I had to run brew install hg first.
3. Re-run the app that was breaking before. Now, since the symlinks are pointing to the fixed version of the SDL library, everything’s fine.

I also checked with FCEUX, a Nintendo emulator packaged by Homebrew, to make sure everything was working there:

I still see a lot of forum posts about this problem with no fixes, so I wanted to write up a quick article about it. This fix was first mentioned as part of this GitHub issue for the interesting-looking tcod-rs project. It appears the same bug also affected SDL2, but I must have just “gotten lucky” and installed a later version that had the fix already applied.