Improve iOS Library Linking

[tinyjin]

Current Issues

1. Dynamic Library Limitations

• Currently using .dylib for iOS which causes App Store submission issues
• Dynamic libraries are restricted in iOS App Store distribution
• Complex code signing requirements for dynamic libraries
• Runtime loading overhead

2. Architecture Support Gaps

• Missing ARM64 simulator support (Apple Silicon Macs)
• Manual architecture management through lipo
• Duplicate binaries for different architectures

Target Architecture Support Matrix

Architecture	Device/Simulator	Current Support	With Source Inclusion
arm64	iOS Devices	✅ Supported	✅ Supported
x86_64	iOS Simulator (Intel Mac)	✅ Supported	✅ Supported
arm64	iOS Simulator (Apple Silicon)	❌ Not Supported	✅ Supported

Proposed Solution: Source Code Inclusion Approach

Overview

Instead of using dynamic libraries, we propose switching to direct source code inclusion through CocoaPods, which is the standard approach in the iOS ecosystem.

Benefits

• ✅ Full App Store compliance
• ✅ Automatic architecture support (including ARM64 simulator)
• ✅ Simplified build process
• ✅ Better performance (compile-time optimization)
• ✅ Reduced app size (only needed code is included)

Implementation Details

1. Podspec Configuration

Pod::Spec.new do |s|
  s.name = 'thorvg'
  s.version = '1.0.0'
  
  # Selective source inclusion
  s.source_files = [
    'Classes/**/*',
    '../src/tvgFlutterLottieAnimation.{h,cpp}',
    '../thorvg/inc/thorvg.h',
    '../thorvg/src/common/**/*.{h,cpp}',
    '../thorvg/src/renderer/sw_engine/**/*.{h,cpp}',
    '../thorvg/src/loaders/lottie/**/*.{h,cpp}',
    '../thorvg/src/renderer/*.{h,cpp}'
  ]
  
  # Exclude unnecessary components
  s.exclude_files = [
    '../thorvg/src/renderer/gl_engine/**/*',
    '../thorvg/src/renderer/wg_engine/**/*',
    '../thorvg/src/bindings/**/*'
  ]
  
  # iOS build configuration
  s.pod_target_xcconfig = {
    'GCC_PREPROCESSOR_DEFINITIONS' => [
      'THORVG_STATIC=1',
      'THORVG_SW_RASTER_SUPPORT=1',
      'THORVG_LOTTIE_LOADER_SUPPORT=1'
    ].join(' '),
    'HEADER_SEARCH_PATHS' => [
      '$(PODS_TARGET_SRCROOT)/../thorvg/inc',
      '$(PODS_TARGET_SRCROOT)/../thorvg/src'
    ].join(' '),
    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++14',
    'VALID_ARCHS' => 'arm64 x86_64'
  }
  
  s.libraries = ['c++']
  s.platform = :ios, '11.0'
end

2. Update FFI Loading

final DynamicLibrary _dylib = () {
  if (Platform.isIOS) {
    return DynamicLibrary.process();  // Switch to process() for static linking
  }
  if (Platform.isAndroid) {
    return DynamicLibrary.open('libthorvg.so');  // Keep dynamic loading for Android
  }
  throw UnsupportedError('Unknown platform: ${Platform.operatingSystem}');
}();

3. Architecture Support

This approach automatically supports all Apple architectures:

• ✅ arm64 (iOS devices)
• ✅ x86_64 (Intel Mac Simulator)
• ✅ arm64 (Apple Silicon Mac Simulator)

4. Build Process Simplification

• Removes need for manual architecture management
• Eliminates complex build scripts
• Leverages Xcode's native build system

[TaeBbong]

Hi,
Currently I'm following proposed solution, to support static link for iOS.

Progress

1. Update Podspec Configs

#
# To learn more about a Podspec see http://guides.cocoapods.org/syntax/podspec.html.
# Run `pod lib lint thorvg.podspec` to validate before publishing.
#
Pod::Spec.new do |s|
  s.name             = 'thorvg'
  s.version          = '1.0.0-beta.0'
  s.summary          = 'ThorVG for Flutter'
  s.description      = <<-DESC
ThorVG Flutter Runtime
                      DESC
  s.homepage         = 'https://github.com/thorvg/thorvg.flutter'
  s.license          = { :file => '../LICENSE' }
  s.author           = { 'Jinny You' => 'jinny@lottiefiles.com' }

  # This will ensure the source files in Classes/ are included in the native
  # builds of apps using this FFI plugin. Podspec does not support relative
  # paths, so Classes contains a forwarder C file that relatively imports
  # `../src/*` so that the C sources can be shared among all target platforms.
  s.source           = { :path => '.' }
  s.dependency 'Flutter'
  s.platform = :ios, '11.0'

  s.source_files = [
    'Classes/**/*',
    '../src/tvgFlutterLottieAnimation.{h,cpp}',
    '../thorvg/inc/thorvg.h',
    '../thorvg/src/common/**/*.{h,cpp}',
    '../thorvg/src/renderer/sw_engine/**/*.{h,cpp}',
    '../thorvg/src/loaders/lottie/**/*.{h,cpp}',
    '../thorvg/src/renderer/*.{h,cpp}'
  ]

  s.exclude_files = [
    '../thorvg/src/renderer/gl_engine/**/*',
    '../thorvg/src/renderer/wg_engine/**/*',
    '../thorvg/src/bindings/**/*'
  ]

  s.pod_target_xcconfig = {
    'GCC_PREPROCESSOR_DEFINITIONS' => [
      'THORVG_STATIC=1',
      'THORVG_SW_RASTER_SUPPORT=1',
      'THORVG_LOTTIE_LOADER_SUPPORT=1'
    ].join(' '),
    'HEADER_SEARCH_PATHS' => [
      '$(PODS_TARGET_SRCROOT)/../thorvg/inc',
      '$(PODS_TARGET_SRCROOT)/../thorvg/src'
    ].join(' '),
    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++14',
    'VALID_ARCHS' => 'arm64 x86_64'
  }

  s.dependency 'Flutter'
  s.static_framework = true

  s.libraries = ["c++"]
  s.pod_target_xcconfig = { 
'DEFINES_MODULE' => 'YES', 
'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386', 
'GCC_SYMBOLS_PRIVATE_EXTERN' => 'NO',  // Added to expose symbol
'DEAD_CODE_STRIPPING' => 'NO' // Added to prevent stripping
}
  s.vendored_libraries = 'Frameworks/libthorvg.dylib'

  s.platform = :ios, '11.0'
  s.swift_version = '5.0'
end

2. Update FFI Loading

/* Linking library */

const String _libName = 'thorvg';

final DynamicLibrary _lib = () {
  if (Platform.isIOS) {
    return DynamicLibrary.process();
  }
  if (Platform.isAndroid) {
    return DynamicLibrary.open('lib$_libName.so');
  }
  throw UnsupportedError('Unknown platform: ${Platform.operatingSystem}');
}();

3. (DISCUSS POINT) Update header file to prevent stripping by attribute(used)

#include <stdint.h>
#include <stdbool.h>

typedef struct _FlutterLottieAnimation FlutterLottieAnimation;

#ifdef __cplusplus
extern "C"
{
#endif

#define TVG_API __attribute__((visibility("default"), used))

    TVG_API FlutterLottieAnimation *create();
    TVG_API bool destroy(FlutterLottieAnimation *animation);
    TVG_API const char *error(FlutterLottieAnimation *animation);
    TVG_API float *size(FlutterLottieAnimation *animation);
    TVG_API float duration(FlutterLottieAnimation *animation);
    TVG_API float totalFrame(FlutterLottieAnimation *animation);
    TVG_API float curFrame(FlutterLottieAnimation *animation);
    TVG_API void resize(FlutterLottieAnimation *animation, int w, int h);
    TVG_API bool load(FlutterLottieAnimation *animation, char *data, char *mimetype, int width, int height);
    TVG_API uint8_t *render(FlutterLottieAnimation *animation);
    TVG_API bool frame(FlutterLottieAnimation *animation, float no);
    TVG_API bool update(FlutterLottieAnimation *animation);

#ifdef __cplusplus
}
#endif

Status

On debug mode with iOS Simulator, I faced following error;

ArgumentError (Invalid argument(s): Failed to lookup symbol 'create': dlsym(RTLD_DEFAULT, create): symbol not found)

I've searched about this error and found that stripping cpp codes could been occured.
I tried to solve this error by adding __attribute__ tag, adding no-strip config on podspec.
But error keep occurs....

If you know of any other possible causes for this error, or have any insights or suggestions, could you please share them?

[TaeBbong]

Additional tries

I've tried flutter's official example, and checked difference between thorvg.flutter and provided example.

Key points were:

1. Flutter's official example used ductape, which has standalone c, h file while thorvg has multiple modules and inclusions even when we only use lottie functions.
2. Flutter's official example used Cmake based build system, while thorvg uses meson and ninja. I know this doesn't matter, but I don't have enough knowledge about c++ build system configs.

Due to point #1, I've tried to merge essential dependencies and modules into tvgFlutterLottieAnimation.cpp to make it standalone, but didn't work so well. Also I've tried several more ways to fix this issue, but there wasn't meaningful try.