diff --git a/docs/workflow/building/coreclr/ios.md b/docs/workflow/building/coreclr/ios.md index d854fca86b18a4..3c6b6f9aa76f60 100644 --- a/docs/workflow/building/coreclr/ios.md +++ b/docs/workflow/building/coreclr/ios.md @@ -1,33 +1,132 @@ -# Cross Compilation for iOS/tvOS Simulator on macOS +# Experimental support of CoreCLR on iOS/tvOS -## Requirements +This is the internal documentation which outlines experimental support of CoreCLR on iOS/tvOS platforms. -Build requirements are the same as for building native CoreCLR on macOS. iPhone SDK has to be enabled in Xcode installation. +## Table of Contents -## Cross compiling CoreCLR +- [Building CoreCLR for iOS/tvOS](#building-coreclr-for-iostvos) + - [macOS](#macos) + - [Prerequisites](#prerequisites) + - [Building the runtime, libraries and tools](#building-the-runtime-libraries-and-tools) +- [Building and running a sample app](#building-and-running-a-sample-app) + - [Building HelloiOS sample](#building-helloios-sample) + - [Running HelloiOS sample on a simulator](#running-helloios-sample-on-a-simulator) +- [Building and running tests on a simulator](#building-and-running-tests-on-a-simulator) +- [Debugging the runtime and the sample app](#debugging-the-runtime-and-the-sample-app) + - [Steps](#steps) +- [See also](#see-also) +- [Troubleshooting](#troubleshooting) -Build the runtime pack and tools with +## Building CoreCLR for iOS/tvOS +Supported host systems for building CoreCLR for iOS/tvOS: +- [macOS](#macos) ✔ + +Supported target platforms: +- iOS Simulator ✔ +- tvOS Simulator ❌ (not yet supported) +- Mac Catalyst ✔ +- iOS Device ✔ +- tvOS Device ❌ (not yet supported) + +Supported target architectures: +- x64 ✔ +- arm64 ✔ + +### macOS + +#### Prerequisites + +- macOS with Xcode installed +- iPhone SDK enabled in Xcode installation +- Build requirements are the same as for building native CoreCLR on macOS +- Xcode command line tools installed: + ```bash + xcode-select --install + ``` + +> [!NOTE] +> Make sure you have accepted the Xcode license agreement: +> ```bash +> sudo xcodebuild -license accept +> ``` + +#### Building the runtime, libraries and tools + +To build CoreCLR runtime, libraries and tools, run the following command from ``: + +```bash +./build.sh clr+clr.runtime+libs+packs -os -arch arm64 -cross -c ``` -./build.sh clr+clr.runtime+libs+packs -os [iossimulator/tvossimulator/maccatalyst] -arch [x64/arm64] -cross -c Release + +> [!NOTE] +> The runtime packages will be located at: `/artifacts/packages//Shipping/` + +## Building and running a sample app + +To demonstrate building and running an iOS application with CoreCLR, we will use the [HelloiOS sample app](../../../../src/mono/sample/iOS/Program.csproj). + +A prerequisite for building and running samples locally is to have CoreCLR successfully built for the desired iOS platform. + +### Building HelloiOS sample + +To build `HelloiOS`, run the following command from ``: + +```bash +./dotnet.sh build src/mono/sample/iOS/Program.csproj -c /p:TargetOS= /p:TargetArchitecture=arm64 /p:UseMonoRuntime=false /p:RunAOTCompilation=false /p:MonoForceInterpreter=false ``` -## Running the sample iOS app +On successful execution, the command will output the iOS app bundle. -Build and run the sample app with +### Running HelloiOS sample on a simulator +To run the sample on a simulator, run the following command from ``: + +```bash +./dotnet.sh publish src/mono/sample/iOS/Program.csproj -c /p:TargetOS= /p:TargetArchitecture=arm64 /p:DeployAndRun=true /p:UseMonoRuntime=false /p:RunAOTCompilation=false /p:MonoForceInterpreter=false ``` -./dotnet.sh publish src/mono/sample/iOS/Program.csproj -c Release /p:TargetOS=iossimulator /p:TargetArchitecture=arm64 /p:DeployAndRun=true /p:UseMonoRuntime=false /p:RunAOTCompilation=false /p:MonoForceInterpreter=false + +The command also produces an Xcode project that can be opened for debugging: + +```bash +open ./src/mono/sample/iOS/bin/-arm64/Bundle/HelloiOS/HelloiOS.xcodeproj ``` -The command also produces an Xcode project that can be opened with `open ./src/mono/sample/iOS/bin/iossimulator-arm64/Bundle/HelloiOS/HelloiOS.xcodeproj` and debugged in Xcode. +> [!NOTE] +> Make sure you have a simulator available. You can list available simulators with: +> ```bash +> xcrun simctl list devices +> ``` -## Running the runtime tests +## Building and running tests on a simulator -Build the runtime tests with +To build the runtime tests for iOS with CoreCLR, run the following command from ``: +```bash +./src/tests/build.sh -os -p:UseMonoRuntime=false ``` -./src/tests/build.sh -os iossimulator arm64 Release -p:UseMonoRuntime=false -``` -Running the tests is not implemented yet. It will likely need similar app bundle infrastructure as NativeAOT/iOS uses. \ No newline at end of file +> [!NOTE] +> Running the tests is not fully implemented yet. It will likely need similar app bundle infrastructure as NativeAOT/iOS uses. + +## Debugging the runtime and the sample app + +Native debugging is supported through Xcode. You can debug both the managed portion of the sample app and the native CoreCLR runtime. + +### Steps + +1. Build the runtime and `HelloiOS` sample app in `Debug` configuration. +2. Open the generated Xcode project: + ```bash + open ./src/mono/sample/iOS/bin//Bundle/HelloiOS/HelloiOS.xcodeproj + ``` +3. In Xcode, set breakpoints in the native CoreCLR code or managed code as needed. +4. Run the app in the iOS Simulator from Xcode to start debugging. +5. Use Xcode's debugging tools to inspect variables, call stacks, and step through code. + +> [!NOTE] +> For debugging native CoreCLR code, you may need to build with debug symbols. + +## See also + +- [Building CoreCLR on macOS](../macos.md)