Excerpt from the Build Log

Oct 13, 2025 by talynt.org 63 views

=====================================================

Adding Sherpa-Onnx to a new Xcode project can be a bit tricky, especially when you're trying to run a specific model like Kokoro TTS on iOS. In this article, we'll walk you through the steps to add Sherpa-Onnx to a new Xcode project and troubleshoot common issues.

Prerequisites

Before we dive into the steps, make sure you have the following prerequisites:

Xcode 16.2 or later
Sherpa-Onnx repository cloned and built
Onnxruntime.xcframework built and available

Step 1: Add Sherpa-Onnx.xcframework

The first step is to add the Sherpa-Onnx.xcframework to your project. You can do this by dragging and dropping the Sherpa-Onnx.xcframework from the /sherpa-onnx/build-ios directory into your project navigator.

Step 2: Add Onnxruntime.xcframework

Next, add the Onnxruntime.xcframework from the /sherpa-onnx/build-ios/ios-onnxruntime/1.17.1 directory to your project. This framework is required for Sherpa-Onnx to work properly.

Step 3: Add Framework Search Path

To ensure that Xcode can find the Sherpa-Onnx.xcframework and Onnxruntime.xcframework, add the following Framework Search Path:

/sherpa-onnx/build-ios

This will allow Xcode to find the frameworks and link them correctly.

Step 4: Add Header Search Path

To access the Sherpa-Onnx headers, add the following Header Search Path:

/sherpa-onnx/build-ios/sherpa-onnx.xcframework/Headers

This will allow Xcode to find the Sherpa-Onnx headers and compile the code correctly.

Step 5: Add Bridging Header

To use the Sherpa-Onnx Swift API, you need to add a bridging header to your project. You can do this by creating a new file called SherpaOnnx-Bridging-Header.h in the /sherpa-onnx/swift-api-examples directory and adding the following line:

#import <SherpaOnnx/SherpaOnnx.h>

Step 6: Add SherpaOnnx.swift

Finally, add the SherpaOnnx.swift file from the /sherpa-onnx/swift-api-examples directory to your project. This file contains the Swift API for Sherpa-Onnx.

Troubleshooting

If you're experiencing issues with undefined symbols, make sure that you've added the correct frameworks and headers to your project. Also, check that the Framework Search Path and Header Search Path are set correctly.

Excerpt from the Build Log

If you're seeing an error like the following in your build log, it may indicate that the Onnxruntime.xcframework is not being linked correctly:

ld: warning: Could not parse or use implicit file '/Users/milannosal/Xcode_16.2.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/SwiftUICore.framework/SwiftUICore.tbd': cannot link directly with 'SwiftUICore' because product being built is not an allowed client of it
Undefined symbols for architecture arm64:
  "std::logic_error::what() const", referenced from:
      vtable for onnxruntime::NotImplementedException in onnxruntime.a[244](data_transfer.o)
  "std::runtime_error::what() const", referenced from:
      onnx::checker::check_graph(onnx::GraphProto const&, onnx::checker::CheckerContext const&, onnx::checker::LexicalScopeContext const&) in onnxruntime.a[74](checker.o)
      onnx::checker::ValidationError::what() const in onnxruntime.a[74](checker.o)
      vtable for onnx::assert_error in onnxruntime.a[75](assertions.o)
      onnx::InferenceError::what() const in onnxruntime.a[83](old-e043934ab9f12bf3d8b23f3c45c5a479.o)
      onnx::SchemaError::what() const in onnxruntime.a[110](schema.o)
      nlohmann::detail::exception::what() const in onnxruntime.a[236](allocation_planner.o)
      onnxruntime::MergeShapeInfo(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, onnx::TypeProto const&, onnx::TypeProto&, bool, onnxruntime::logging::Logger const&) in onnxruntime.a[318](graph.o)
      ...
  "std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>::find(char, unsigned long) const", referenced from:
      kaldifst::ClassifyRspecifier(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, kaldifst::RspecifierOptions*) in sherpa-onnx.a[190](kaldi-table.cc.o)
      kaldifst::ClassifyWspecifier(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, kaldifst::WspecifierOptions*) in sherpa-onnx.a[190](kaldi-table.cc.o)
      kaldifst::ClassifyWspecifier(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, kaldifst::WspecifierOptions*) in sherpa-onnx.a[190](kaldi-table.cc.o)
      kaldifst::ClassifyWspecifier(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, kaldifst::WspecifierOptions*) in sherpa-onnx.a[190](kaldi-table.cc.o)
      kaldifst::ClassifyWspecifier(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>*, kaldifst::WspecifierOptions*) in sherpa-onnx.a[190](kaldi-table.cc.o)
...

To fix this issue, make sure that the Onnxruntime.xcframework is being linked correctly. You can do this by checking the Framework Search Path and Header Search Path in your project settings.

Conclusion

Adding Sherpa-Onnx to a new Xcode project can be a bit tricky, but with the steps outlined in this article, you should be able to get it working correctly. Remember to add the correct frameworks and headers, and troubleshoot any issues that arise during the build process.

==================

Adding Sherpa-Onnx to a new Xcode project can be a bit tricky, but with the right guidance, you can overcome common issues and get it working correctly. Here are some frequently asked questions and answers to help you with your Sherpa-Onnx project.

Q: What is Sherpa-Onnx?

A: Sherpa-Onnx is a Swift API for the ONNX (Open Neural Network Exchange) format, which allows you to run ONNX models on iOS devices.

Q: What is ONNX?

A: ONNX is an open standard for representing machine learning models, allowing you to run models across different frameworks and platforms.

Q: What are the system requirements for Sherpa-Onnx?

A: Sherpa-Onnx requires Xcode 16.2 or later, and the ONNX Runtime framework.

Q: How do I add Sherpa-Onnx to my Xcode project?

A: To add Sherpa-Onnx to your Xcode project, follow these steps:

Add the Sherpa-Onnx.xcframework from the /sherpa-onnx/build-ios directory to your project.
Add the Onnxruntime.xcframework from the /sherpa-onnx/build-ios/ios-onnxruntime/1.17.1 directory to your project.
Add the Framework Search Path and Header Search Path to your project settings.
Add the Bridging Header to your project.
Add the SherpaOnnx.swift file to your project.

Q: What are the common issues I may encounter when adding Sherpa-Onnx to my Xcode project?

A: Some common issues you may encounter when adding Sherpa-Onnx to your Xcode project include:

Undefined symbols for architecture arm64
Could not parse or use implicit file
Cannot link directly with 'SwiftUICore' because product being built is not an allowed client of it

Q: How do I troubleshoot these issues?

A: To troubleshoot these issues, follow these steps:

Check the Framework Search Path and Header Search Path in your project settings.
Make sure that the Onnxruntime.xcframework is being linked correctly.
Check the Bridging Header to ensure that it is correctly configured.
Verify that the SherpaOnnx.swift file is correctly added to your project.

Q: Can I use Sherpa-Onnx with other frameworks and libraries?

A: Yes, you can use Sherpa-Onnx with other frameworks and libraries, such as Core ML and TensorFlow.

Q: Is Sherpa-Onnx compatible with iOS 14 and later?

A: Yes, Sherpa-Onnx is compatible with iOS 14 and later.

Q: Can I use Sherpa-Onnx with Swift 5.6 and later?

A: Yes, Sherpa-Onnx is compatible with Swift 5.6 and later.

Q: Where can I find more information about Sherpa-Onnx?

A: You can find more information about Sherpa-Onnx on the official GitHub repository, as well as in the documentation and tutorials provided by the Sherpa-Onnx team.

By following these Q&A, you should be able to overcome common issues and get your Sherpa-Onnx project working correctly. If you have any further questions or need additional assistance, feel free to ask!