Introduction to Build-Select Script
This page will help you use menu-driven scripts to install the latest version of Loop Master (which now includes automatic bolus as a dosing strategy), FreeAPS (Loop fork) or Loop Follow. It also has utility options to assist with cleanup, Xcode updates and provisioning profiles.
- If you’ve used this page before and don’t need the instructions, you can skip ahead to Script Instructions.
- If your Xcode is at 12.5 or later – you can build to iOS 14 phones
- If your phone is at iOS 15, you must
- Have Xcode 13 AND
- Download new Loop code AND
- Build using the workspace build method (which is provided by this script)
- If your Xcode is too old for your phone’s iOS, there may be help for you – read the Xcode Too Old section
- WARNING – Be aware that if you use this method for building with Xcode 12.4 or earlier:
- You cannot update your phone to iOS 15 because your Loop app will no longer be available
- WARNING – Be aware that if you use this method for building with Xcode 12.4 or earlier:
What is a script?
A script is a series of commands that are meant to be issued to your Mac OS in the terminal window (on a mac or a virtual mac on a PC). The script issues the commands in order and checks status as it goes along. It just makes your Loop build easier. For more in-depth knowledge, read the Loopdocs pages on building or updating. (Note, the link to Loopdocs goes to the updating page.)
What will the script do?
First, the script will warn you that this is a DIY system. You must acknowledge to continue.
Please read the options carefully:
- Build Loop
- Build Loop Follow
- Utility Scripts
Selection 1: Build Loop
If you type 1 for Build Loop and return, the script will ask which version of Loop you want to install. Once you make a selection, it will check that your system has required elements, download the latest version of code to a new download folder, and help you install it.
If you don’t know which version you want after reading the information at Compare Versions or are confused about any of the steps – please stop and ask for help.
Please ensure that you have a compatible version of Xcode installed and your phone is plugged into your computer.
You may want to check out the Version Updates page (which has links to lots of other helpful pages) to make sure your phone, operating system and Xcode versions are compatible.
Loop master branch is Loop v2.2.6.
- If you built Loop v2.2.5 during the short window from Aug 22 through Sep 6, 2021, please rebuild ASAP.
Loop Version Choices
- Master Branch (supports temporary basals and automatic bolus as dosing strategies)
The script will automatically
- Download the latest code for the version that you selected
- Start Xcode pointing to the newly downloaded code
- Open a page showing you how to do a Workspace build (it’s easy)
- Optional: If you have favorite customizations, enter them before hitting the build button
Note about carthage
Most builders can bypass this section since you no longer need to install carthage to build Loop Master or FreeAPS. Carthage is a package that, in the past, you had to manually install.
If you get a carthage error message while building Loop, check out LoopDocs Build Error Page. That link takes you straight to the error fix section for an incompatible version of carthage. If you need to post for help, go to the top of that page and follow the directions for how to fix most problems yourself and how to ask for help.
Selection 2: Build Loop Follow
If you type 2 for Build Loop Follow and return, then the script will download the latest version of Loop Follow code and install it. If you are not familiar with Loop Follow, there is information at the Loop Follow ReadMe. You can join and ask for help in the Loop Follow Facebook group.
Selection 3: Utilities
If you type 3 for Utilities and return, then the script will offer some choices. PLEASE read carefully.
- Clean Derived Data
- Xcode Cleanup (The Big One)
- Clean Profiles and Derived Data
Option 3 is recommended for each time that you build. It resets the provisioning profiles so you get a full year from the date of the build and cleans out previous build stored data that might interfere with a successful build.
If you’ve run these utility scripts in the hope of cleaning up unused and unneeded files and you still need more space, check out Xcode Cleanup.
Should You Delete Provisioning Profiles Before You Rebuild?
August 2021 Update: Starting with version 2.2.5, Loop will alert you when there are fewer than 20 days remaining before your provisioning profile expires. When there are less than 24 hours remaining before your profile expires, you will get an alert as frequently as every hour (at most).
What’s a provisioning profile? It tells your phone that it’s OK to run this app – but it also has an expiration date. As soon as the expiration date is past – your app will not open! Please don’t be that person. Please follow the steps to delete provisioning profiles (from your computer) and rebuild Loop (to your phone with a year until expiration) at least once a year. And put that expiration date in your calendar – give yourself plenty of time. The less frequently you build, the more time you will need. A week is pushing it. A month is better.
If you don’t delete provisioning profiles, Xcode may reuse the ones on your phone and your Loop app would then expire when the old provisioning profile expires.
If you build frequently, you do not need to delete the profiles every time. There is a small chance that deleting the profiles will force a new certificate (you will be directed to revoke the certificate) – which will affect all apps built with your developer user ID (more details below). So you should decide when to delete the profiles – it is not an automatic step in the script.
To check your expiration date so you don’t get surprised, see expiration date.
For more information about provisioning profiles, see Loopdocs update steps 4a.
What does new certificate mean?
The certificate was assigned to your Apple Developers ID when you signed up at Apple Developer Account. Normally that certificate is yours for as long as you keep your account paid annually. The provisioning profiles are based off your certificate, and last only one year.
So far, a few people have reported that deleting the provisioning profiles forced them to get a new certificate from Apple, which means the old certificate is no longer available. Any app built on any phone that used that certificate will expire, probably within 24 hours. That means backup phone, kids phones, friends you helped by building Loop for them (remember that it NOT recommended), etc. Make sure you know every device that uses your certificate and keep a list so you can contact them if you have to revoke your certificate.
New Provisioning Profile, New Cert
You are still you. Your Apple Developer ID has not changed. You can still build a new Loop on your phone over the old one and have all your settings, pump and CGM keep working. Although we do recommend you check the settings after a build – just in case.
For experts – (still true on Oct 4, 2021) if you have been using the dev branch and switch back to Loop master or FreeAPS – you must start first delete your dev-branch Loop app from your phone. You can transition from master (or FreeAPS) to dev but cannot return. Save your settings, delete the app and then build Loop Master or FreeAPS. You cannot build dev using the Build-Select script.
For everyone else, all the versions in this script are compatible – you can switch between any of these versions: Loop Master or FreeAPS (fork) and back. The new app will build over the old app on your phone and all standard Loop settings should transfer – but always check to be sure.
Carefully read what is on the screen before making any choices.
Step 1: Open Terminal.
Tip: press command-space to open spotlight search. Start typing “term” (without the quotes) and you will see the Terminal application icon in the box. Hit enter to open.
Step 2: Copy/Paste this code into the Terminal by using the link on the right (in the grey box):
/bin/bash -c "$(curl -fsSL https://git.io/JImiE)"
Step 3: Hit Enter, then select Utility Scripts and choose Option 3 to give you a full year with this build
When done, rerun script and select a new option by simply hitting up arrow on the keyboard while in the terminal and hit return when you see the command appears
Step 4: Hit Enter to run the script a second time (up-arrow and hit return) and select Option 1 Build Loop. When your Loop code is finished downloading, two windows will open:
- Diagram that depicts the steps that you’ll need to take within Xcode
Step 5: Plug your charging cable into your Mac and connect it to your iPhone.
What if your Xcode is too old for your phone iOS? The traditional wisdom is to follow the steps to update mac OS and Xcode version, but sometimes you cannot do that and you need to build Loop anyway.
If this is you, once you’ve downloaded the code, you should follow this video provided by Jon Fawcett that enables you to build Loop anyway as long as your iOS version is 14.x. This method does not work with iOS 15. (The link to the video is repeated on the workspace build instructions that automatically open when you run the script.)
- If you use this method with Xcode 12.4 or earlier you cannot build to an iOS 15 phone
- If you use this method with Xcode 12.4 and build to an iOS 14 or earlier phone – the Loop app will stop working if you later upgrade that phone to iOS 15
And for any who are reading this and wondering:
- If you build your Loop app with Xcode 12.5 or later – the Loop app will continue working on the phone when you upgrade to iOS 15
- Just remember – it is good policy to always be able to rebuild Loop
History (if you’re interested)
First there was a set of separate scripts that each did a separate task.
Then the authors made a front-end script so you can select which task you want to do by running the BuildLoop.sh script one or more times.
The scripts are open source – you can make a pull request or post an issue at https://github.com/loopnlearn/loopbuildscripts