.. _debugging_ios_instructions:

Build & run the example iOS apps

Note: This document assumes that you have installed the :ref:iOS build requirements <ios_requirements>_.

The fastest way to build and run the sample iOS apps is to run the following command::

bazel run //examples/swift/hello_world:app

This will build and run the Hello World iOS app in a new iOS Simulator.

.. _using_xcode:

Using the Xcode GUI

Envoy Mobile makes use of the rules_xcodeproj <https://github.com/buildbuddy-io/rules_xcodeproj>_ project to add support for many of Xcode's development, debugging and profiling features to Envoy Mobile.

To start, run bazel run //:xcodeproj to generate an Xcode project and xed . to open it in Xcode (or double-click Envoy.xcodeproj in Finder).

In Xcode's scheme selector, pick the app target you want to build (e.g. Hello World App), pick a Simulator to run it on, then hit cmd-R to build and run.

From there, most Xcode features should just work for all transitively compiled source files in C/C++/Objective-C/Objective-C++/Swift:

Auto-complete
Syntax highlighting
Go to definition
Breakpoints
LLDB console
Thread navigator
Symbols
Metrics like CPU/memory/networking/energy
Profiling with Instruments

|xcode_breakpoint| |instruments|

.. |xcode_breakpoint| image:: images/xcode_breakpoint.jpg :width: 45%

.. |instruments| image:: images/instruments.jpg :width: 45%

Running on a real iPhone

You can build and run the example iOS apps on a physical iPhone by following these steps:

Set the TEAM_ID value in examples/BUILD to your Apple Developer Team ID found in the Apple Developer Portal <https://developer.apple.com/account/#!/membership>_.
If needed, change the PROFILE_NAME value to the name shown by clicking the (i) next to "Xcode Managed Profile" in Xcode's "Signing and Capabilities" tab.
Follow the same steps as defined in the :ref:Using the Xcode GUI <using_xcode> section above, but targeting your device instead of a simulator.