Build Loop

Summary

Time Estimate

• 60-80 minutes for first time builders
• 10-15 minutes for repeat builders

Summary

You will:

• Run the Build Select Script to download Loop code
• Prepare to build the Loop app
• Press the Xcode Build Button to build Loop
• Watch in awe as you build your very own Loop app

FAQs

• Why does Xcode show a colorful spinning icon and not respond to me? Unfortunately, sometimes Xcode gets confused and you need to force quit the application. See Xcode Not Responding for instructions.
• Many more FAQs for building Loop are in-line with the steps that trigger the questions.

Build Video

The Loop and Learn team prepared this YouTube video showing how to build Loop 2.2.x including the steps required to update if you previously built. The steps are different now. The video may be worth watching, but once you've reviewed it, work through the new build process described on this page.

GitHub Build Loop

If you previously used GitHub Build to install Loop on this phone, you must make sure that automatically install is disabled in TestFlight, or you will not be able to install on that phone with Xcode.

Developer Mode

If you are running iOS 15 or watchOS 8 and earlier, you do not have developer mode and can skip ahead to Download Loop.

New with iOS 16 and watchOS 9, you must enable Developer Mode to run or build Loop. (This is true for any app created by Xcode directly on your device.) If you want to know more, click on this Apple Link about Developer Mode.

Loop will not run until you enable Developer Mode for iOS 16.

Prepare your Phone and Watch

• If you are running Loop and update to iOS 16 and watchOS 9; Loop will no longer run until you enable Developer Mode and you will see a message similar to the next graphic

• If you are building to a new Apple Watch - you must first build the app with Xcode before the developer mode will be available.

  

• If your device uses iOS 16 (and watchOS 9); you must enable Developer Mode to build an app on that device using Xcode or it will show up as an "Unavailable Device" under Xcode

  

Developer Mode on iOS 16 Device

To determine if Developer Mode is enabled, go into your phone settings, choose Privacy & Security, scroll to the bottom of the screen and tap on the Developer Mode row and examine the Developer Mode slider.

• If Developer Mode is enabled, the slider will be green and no further action is required
• If Developer Mode is not enabled, the slider will be blank
  • Move the slider so it is green
  • Reboot the device when asked
  • After the reboot, you will be asked if you want to turn on Developer mode
  • Tap on the Turn On option

Developer Mode on watchOS 9 Device

Build, Enable, Build

Reports from users indicate that when you are building to a new Apple Watch - you must first build the app with Xcode before the developer mode will be available. So plan to build with Watch paired, and then enable Developer Mode and build again.

This must be configured on the watch itself (not the watch app on the iPhone). To determine if Developer Mode is enabled, look at the watch face icons and find the Settings icon. Tap on it and scroll to and tap the Privacy & Security icon. Then scroll to the bottom and tap on Developer Mode.

• If Developer Mode is enabled, the slider will be green and no further action is required
• If Developer Mode is not enabled, the slider will be blank
  • Move the slider so it is green
  • Reboot the device when asked
  • After the reboot, if you are asked if you want to turn on Developer mode
  • Tap on the Turn On option

Download Loop

This page has the detailed steps to run the Build Select Script to download the Loop code, prepare your computer and build Loop.

Open Terminal

Go to the Finder app, click on Applications, then open the Utilities folder. Locate the Terminal app and double-click Terminal to open a terminal window. The terminal window is very plain looking when you open it. That is normal.

Ensure a Year

Rebuild / Update on Same Computer?

If you used this same computer to build Loop previously and you did not delete provisioning profiles - you will not get a full year with this build.

If you missed doing the Updating: Delete Provisioning Profiles, do that step now and return to this page.

or more experienced folks may want to just paste this command into their terminal:

Copy and Paste to remove Provisioning Profiles

rm ~/Library/MobileDevice/Provisioning\ Profiles/*.mobileprovision

Build Select Script

• With the release of Loop 3, the build process is different and simpler
  • Please read each step as if you are a new builder
  • Don't assume you know what you are doing
  • FreeAPS is no longer supported by the Build Select Script
  • Loop 3 with Patches is provided instead

These instructions show each step needed to download Loop using the Build-Select script.

Optional

The Build Select Script can also be used to build a companion app, called Loop Follow, and a fork of Loop, which has selected patches added. Follow these links to different websites for more information about those options.

For those used to seeing FreeAPS here, it has been removed from the Build Select Script.

Consider using Loop 3 as designed. If you need Libre or want the CustomTypeOne patches, those are provided in the Loop with Patches selection in the Build Select Script.

• Information about Loop Follow
• Information about Loop with Patches

You do not need to know about these options to build Loop.

Copy the line below that starts with /bin/bash by hovering the mouse near the bottom right side of the text and clicking the copy icon (should say Copy to Clipboard when you hover over it). When you click the icon, a message that says “Copied to Clipboard” will appear on your screen.

Copy and Paste to start the BuildLoop.sh script

/bin/bash -c "$(curl -fsSL \
  https://raw.githubusercontent.com/loopnlearn/LoopBuildScripts/main/BuildLoop.sh)"

Paste the line of text into Terminal. Be sure to click anywhere in the terminal before trying to paste. (Ways to paste: CMD-V; or CNTL-click and select from menu or Edit-Paste at top of Mac screen.)

Read the screen (shown below). Type 1 and return if you understand the warning and agree.

• Please read what is on the screen as you progress.
• Adjust font size as directed if you have difficulty seeing the directions.

Next you will see an introduction to the Build-Select script. Please read this. To build Loop, you will select the Build Loop option by typing 1 and return.

Next you are asked which version of Loop you would like to build. Type 1 and return to build Loop (as shown in the graphic below) or 2 for the fork of Loop with added Libre CGM options and CustomTypeOne patches.

XCode Errors with Build-Select

WARNINGS

If you see errors like these . . .

• xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
• xcode-select: Failed to locate 'git', requesting installation of command line developer tools
• xcode-select: error: tool 'xed' requires Xcode

You missed one of these steps:

• Install Xcode
• Xcode command line tools

Wait for Download to Complete

This download can take from 3 minutes to 30 minutes depending on your download speed. You can leave the room and return later to check on progress. When you read the words in the terminal, as the script runs, you may see terminology you do not understand - don't worry - you do not need to understand enumeration or submodule or cloning. You only need to review the display to look for any error messages.

The next graphic shows terminal messages for the beginning of a successful download.

When the download completes, the "Check for successful download" message is displayed as shown in the graphic below. You will need to scroll up in the terminal window to look through all the messages output to the terminal from the beginning of the download. (Your messages that start with "Submodule path" may differ.)

If you do not find the word error in your terminal window, continue with Download was Successful.

If you see the word "error" in your terminal window:

• Read the error message
• Try to figure out the problem
• If you need help, reach out to your favorite Loop Social Media site
• Tap any key other than 1, followed by return to cancel

Download was Successful

If there are no errors, type 1 in the terminal window to continue. At this point you choose how to sign the targets, so first an explanation.

Sign Targets

What does Sign Targets Mean?

"Sign Targets" in Xcode identifies who built the app. You cannot deploy an app to a phone if you do not sign each target associated with that app.

Experienced Builders

This replaces several of the steps that used to be required to build Loop.

The first time you use the script, you will be asked how you want to sign the targets. If you have previously run the script and configured your computer to have a permanent file that contains your Apple Developer ID, this question will not be shown. Skip ahead to Review LoopConfigOverride.xcconfig.

The next question, as shown in graphic below, is whether you will (1) Sign Automatically or (2) Sign Manually.

• If you are building with a paid developers account, choose option 1, and continue on this page
• If you are building with a Free option or plan to build to a simulator on your computer, choose option 2 and click on Build Free Loop to move to the page with those instructions

Paid Developer Account

Continue with this page only if you have a paid developer account.

• You need to switch to the Loop Free Build page for a free account.

Create Permanent LoopConfigOverride.xcconfig

The following graphics show the terminal display after selecting option 1 to use Apple Developer ID.

• Graphic below:
  • User is presented with instructions for getting Team ID from the Membership page
    • After review, the user hits return

• Graphic below:
  • The instructions remain on the screen for reference
  • The developer.apple.com web page (not shown) opened automatically in the browser after user hit return
    • User obtains ID
  • User enters ID in terminal and then hits return

After hitting return, the user can verify the entry.

Review LoopConfigOverride.xcconfig

Use Your Team ID

The ID, 0123456789, shown in the graphic below is for illustration purposes only. Your terminal display shows your Apple Developer ID (the Team ID on the Membership page).

If you previously built with this computer using the script, you already have the file configured. The review step is the same each time.

• Graphic below:
  • The developer ID stored in the permanent file is displayed for review
  • After review, hit return to continue and Plug in Your Phone
  • OR - to modify the ID in the file, see Problem with the ID?

Problem with the ID?

If there is a problem with the ID that is stored on your computer, you can modify it before continuing. The instructions, shown in the terminal message, are repeated here:

To edit the LoopConfigOverride.xcconfig file with a different developer ID:

1. Open finder, navigate to Downloads/BuildLoop
2. Locate and double click on LoopConfigOverride.xcconfig
   • This will open that file in Xcode
3. Edit in Xcode and save file

You can now return to the terminal and hit return for the next step.

Build Loop

Plug in Your Phone

Refer to the graphic below. The messages in the terminal instruct you to:

• Unlock your phone
• Plug Phone into the computer
  • (Optional) If you have an Apple Watch that has never had Loop on it
    • Make sure watch is paired, unlocked and on your wrist
  • If you have never "Trusted" this computer with these device(s), do so now
    • A screen will pop up on your phone (and watch) asking if you trust the computer
    • Select "Trust"
    • After trusting phone and watch, phone should remain plugged in, but watch does not need to stay in proximity of the phone
• Now you are ready to hit return in the terminal window

The next action of the script is to

• Open a browser window displaying this section of LoopDocs
• Open Xcode

The final script message informs you that you can close the terminal window.

• Wait until you've successfully built the app before closing the terminal

Initial Xcode Screens

watchOS Simulators

Yes, watchOS simulators are required to build Loop. If Xcode asks if you want to download them - say yes. It's slow but you cannot build Loop without the simulator.

• Tap on New with Xcode 14 for more information

First select Loop (Workspace) and confirm your phone is selected. Refer to the GIF below and follow the directions:

• Frame 1: Xcode screen opened by the script after a fresh download
  • Fresh Download? Wait for indexing to begin
    • If you see messages about fetching symbols or resolving packages, please wait until you see the Indexing message as shown in the GIF below just to the left of the dashed-blue rectangle
  • The red rectangle indicates where you will change Loop to Loop (Workspace)
  • The red x in the dashed-blue rectangle region indicates you need to fix a problem before building
• Frame 2: Inset shows the action needed to select Loop (Workspace)
• Frame 3: Loop (Workspace) selected but there's a red x in the dashed-blue rectangle region

Most Common Mistake

• The most common mistake in this step is:
  • not selecting Loop (Workspace)
  • not selecting your actual phone

Package Dependency Error

If there is no red x in the dashed-blue rectange region on your Xcode screen, skip ahead to Start Build on this page.

Otherwise, tap on the red x in the dashed-blue rectange region:

• If your screen is similar to the figure below, perform the Fix for Package Dependency (instructions are repeated on this page for convenience; duplicated on Build Errors page)
• If you have a different error, search the Build Error page

Fix for Package Dependency

1. Click on the folder icon (indicated by red square)
2. Hold down the Control-Key and click the Package Dependency row to display the dropdown menu (shown in the inset)
3. Select Resolve Package Versions from the dropdown menu
4. Once that completes, the red x should resolve and you can build as soon as the Indexing message appears

Start Build

The first time you build, there will be steps that will not be required for subsequent builds. These are clearly marked in the intructions with the word First-Time.

Refer to the GIF below:

• Frame 1: Package Dependency resolved (no red x)
  • Xcode is Indexing as seen in dashed-green rectangle region
    • Indexing makes searching faster; it does not need to complete before building
  • Click the "Play" button highlighted by red rectangle to start the build
  • First-Time for this Phone: A Device isn't registered screen appears, as shown in the graphic below the GIF
    • This happens for any phone not registered to the selected Developer ID
    • You must be connected to the internet so the device can be registered
    • Click register and then the build will continue (as shown in the GIF)
• Frame 2: Build has started
  • Xcode is Building as seen in dashed-green rectangle region
  • First-Time on This Computer:
    • Follow the Always Allow Instructions the first time this Developer ID is used on this computer
    • Never hit Deny
• Frame 3: Build succeeded
  • App is running as seen in dashed-green rectangle region
  • If your phone locked during the build process, you will see a message to unlock your phone, as shown in the graphic below the GIF
    • Simply unlock your phone and Xcode does the rest
    • If you tapped on Cancel Running, just hit the build button again
  • First-Time for this Phone: You may also see a "Could Not Launch Loop" message
    • Follow the Update Settings for Developer

If the app opened on your phone, the next two sections for first-time builders are not needed. Skip ahead to Successful Build.

If you got red error messages, skip ahead to Build Failed?

Codesign / Keychain Access

First Time Using Developer ID on Computer

During your first build with a given Developer ID on your computer, you will see a codesign/keychain access prompt, as shown in the graphic below. Enter the same password you use to log in to the mac, select "Always Allow" and then do it again each time you are asked.

It is normal for this prompt to come up repeatedly even after you enter the correct password (once for each target Loop needs to sign).

In frustration, people think the prompt must be broken because it keeps reappearing and press deny or cancel. Don't press deny. Keep entering your computer password and pressing the "Always Allow" button as many times as it takes. The build will then continue.

FYI: codesign is for code sign - nothing to do with design.

Update Settings for Developer

First Time Building on a New Device?

If this is the first time you have installed an app on your iPhone using a free account, you will see warnings in both Xcode and on your phone after a successful build and install on your phone.

Don't worry, dismiss the messages and do this extra step on the phone. These instructions are valid for iOS 15:

• Open Phone Settings
• Select General
• Select VPN & Device Management
• Under the Developer App section, tap on icon
• Tap on Trust
• You should now be able to open the app

Build Failed?

No red error messages? Skip ahead to Successful Build.

Red Errors

If you get a message that your build failed and see RED ERROR messages:

• Go to the Build Errors page to find the steps to fix your build error
• (Optional) Follow the Clear the Error Message process
• Return to Start Build to try again

FAQ: But what about those yellow or purple warnings that remain in Xcode? Should I worry about them?

If you see yellow or purple warnings after your build is done...those are not an issue. Don't try to resolve them or fret about them. They mean nothing to the successful use of your Loop app.

Clear the Error Message

Once you've resolved a build error and start the build process again, Xcode will continue to show a red indicator on the top line from the previous failure. If you don't like seeing that, clean the build folder to clear the error. Otherwise, as long as the steps of the build are showing across the top line, Xcode is still working on the build. When the build succeeds, the red circle will disappear.

Clean Build Folder

• In Xcode menu, select Product, then Clean Build Folder
• Wait for cleaning to complete: you'll see a "Clean Finished" message

Successful Build

After you see the Loop app open on your phone, you can unplug your phone and acknowledge the Xcode message: Lost connection to the debugger on . . .. The square icon next to the play button goes away as soon as you unplug your phone from Xcode.

The Loop app on your phone closes (but does not quit) when you unplug the phone. Open the Loop app on your phone just to be sure.

Congratulations!

If you plan to build again on a backup phone, or want to try a customization, easiest for you to leave Xcode open. Otherwise, you can quit out of Xcode now.

Protect that App

Protect Against Deletion

Prevent your Loop app from being deleted accidentally.

If you, or a child, deletes the app from the home screen, it is gone - you have to rebuild and reenter all settings and start a new pod or add back in your Medtronic pump.

The steps vary depending on iOS. With iOS 15 and 16, it is under Screen Time, Content & Privacy Restrictions, iTunes & App Store Purchases, Deleting Apps. Choose Don't Allow. If those steps don't help, do an internet search like this, where you use your current phone iOS version number:

• "turn off app deletion iOS ##"
• "iOS ## prevent app deletion"

Follow the instructions to prevent deletion of what is now a critical medical app.

IMPORTANT SAFETY REMINDER

• STAY IN OPEN LOOP UNTIL YOU UNDERSTAND THE SYSTEM
• Do NOT skip the Set Up and Operate material; at least skim it.
• Keep reviewing LoopDocs - some material will be more impactful once you have the app in your hands.
• Ask questions if you are confused.
• Learn to use the LoopDocs search feature

New to Loop 3

If this is your first build with Loop 3, head to the Set Up tab starting here: Loop 3 Overview.

Pro Tip: Read Along in LoopDocs as you Onboard

One of the goals for Loop 3 is to make the app robust even if you don't read the documentation, but a lot of questions may be resolved if you read along in LoopDocs as you onboard.

All those mentors who answer questions are volunteers.

Even if you don't read all the pages under the Set Up tab now, these links are important.

• New Looper: Onboarding
• Building Loop 3 over Loop 2.2.x or FreeAPS: Experienced Looper Onboarding

Add a Calendar Reminder

• It is good practice to add a reminder to your calendar when the app will expire
• Be sure to add an alert to that reminder so you have enough time to do all the Loop Updating steps to build the app again before it expires
• Even better, practice building every 3 to 6 months so you don't forget and keep that expiration date far in the future

Optional Steps

Code Customizations

New Loop users: Customizations are not a required part of any Loop build. As you gain experience using your Loop app, you may want to customize some of the features. First time builders are encouraged to build with the standard, default code. You can always update your Loop app to add customizations at a later time, using the same download. Subsequent build time is much faster than the initial build for a given download.

Pro Tip

With a fresh download of code, it's always best to build without customization to ensure the build works without errors.

To add custom configurations to your Loop or Loop Apple Watch apps, follow the step-by-step instructions on the Code Customizations page and then build the app again.

Apple Watch

Existing Apple Watch users: Please update your watchOS prior to building the Loop app. The current version of Loop requires watchOS 4.1 or newer.

New Apple Watch users: If you have an Apple watch and want to use it with Loop, first pair the watch with the iPhone before continuing to the next steps. If you get a new watch after building the Loop app, you'll need to redo your Loop build.

Build Again with this Download

Follow the Find My Downloaded Loop Code instructions if you later wish to build with this same dowload. Plug in an unlocked phone and start at the Start Build section of this page. You may need to select the phone you just plugged in. Everything else should be ready for you the start the build process.

Don't use a really old download

Do not use a really old download.

Check the date of your download against the latest Current Release date and decide whether to get a fresh download instead.