Creating a working compiled app for one Operating System is one thing. Creating versions for multiple Operating Systems is another - especially when you throw things into the mix like multiple underlying technologies and a multitude of Linux based Operating Systems that each do things differently!

This may mean that even though we try to provide working build scripts that you can use to compile Sonic Pi on your preferred Operating System, occasionally there might be situations where they don't work for you. What follows is a guide to troubleshooting some of the most common issues that occur, (including some workarounds or possible solutions), and details of the best way to raise an issue if you still end up needing to ask for help or bring something to our attention.

If you come across any other issues, and want to help others going through them, then do let us know, and we can update this list. :)

If the device you are using to compile Sonic Pi does not have enough RAM available to complete the build process, it may stop with an error. This is typically more of a problem on devices such as the Raspberry Pi.

Solutions include:

• Creating (or increasing the size of) a swap file. Information such as More Memory On Raspberry Pi may help.

Sometimes the pace of software updates in various Operating Systems moves faster than Sonic Pi development. This can mean that occasionally the versions of software packages that Sonic Pi is built to depend on become outdated and no longer available through that Operating System's standard software repositories, (or new additional packages are required), and the missing software packages prevent the build from completing successfully.

Solutions include:

• Finding out which packages are missing by examining the messages in the unsuccessful build process, and what the dependencies actually are. (Maybe they've just been renamed slightly). Then, updating Sonic Pi's build scripts or guides to change the required software dependencies.

If changes are made to the code that require compilation, but there are leftover build artifacts from a previous build attempt still hanging around that relate to the code you've just changed, the compiler might get confused, and the new build attempt may fail.

Solutions include:

• Deleting the old build artifacts by running one of the scripts we have that are designed to do this. (In the app folder of the Sonic Pi source code, we have mac-clean.sh, linux-clean.sh, pi-clean.sh and win-clean.bat to handle each of the major platforms). Once this is done, you can attempt to compile Sonic Pi again.

Anaconda (a popular data science toolkit) installs a lot of extra programs, including one called macdeployqt which conflicts with the build process on macOS.

If you run:

conda deactivate

Before the build steps that should stop things breaking. Once Sonic Pi is built, you can use conda as normal after that.

Don't worry! Here's some ways you can look for more clues, or ask for help:

Searching the GitHub Issues page is useful if your problem is not covered by this guide. It's possible that someone has encountered the same problem that you have, or a similar one, that might give you some clues or answers. Most of the issues on that page that are about compiling Sonic Pi are tagged with the label 'developer experience', so it's also worth seeing if using that can narrow things down.

If there's nothing relevant in the common issues and solutions in this guide, and you haven't found any existing issues on the GitHub Issues page that match your specific errors or situation, then it's fine to add a new one there. Keep in mind that 1) the smaller the list of issues the better, (so that it's easier for the developers to manage!) but also 2) it's helpful when each issue's details are as unique as possible (so that we can see every kind of issue separately at a glance). If you're going to raise a new issue, then the more information you can provide about your problem, and the setup of your Sonic Pi system, the better. There are many details that will be useful for helping other people to troubleshoot with you. Some of these might include:

• Your computer's Operating System (and which version).
• The version of the Sonic Pi code that you are trying to compile (eg. the Git commit).
• Detailed steps or descriptions of what you were doing, and what happened.
• Information from the messages displayed during the build process.
• Ideas about possible causes and/or solutions, if you have any. (Even better, send us a pull request!)