Forem: Andy Dong

How to Debug Your C/C++ Project in Flutter Apps

Andy Dong — Tue, 27 Aug 2024 15:57:38 +0000

For Flutter app development, it's easy to set up a development and debugging environment with Dart using VS Code or JetBrains IDE.

However, when using C/C++ in Flutter, things are different because the official Dart & Flutter IDE plugins are not designed for C/C++ development.

To develop and debug C/C++ on multiple operating systems, we need to configure and set up different IDEs for each platform as follows:

There are many development environments for C/C++ projects. We can use Xcode for iOS and macOS, Android Studio for Android, Visual Studio for Windows, and other IDE tools for Linux platforms.

In my personal experience, the best development IDE I have used most often is JetBrains' CLion, which provides a consistent development experience across platforms.

For developers using C/C++ in Flutter apps, it's common to deploy and share the same codebase across different platforms with various operating systems and CPU architectures. Using the same IDE makes it more convenient to reuse your experience with these tools.

Configuring Your C/C++ Project with CLion

CLion has built-in support for CMake projects. To set up CLion with IntelliSense, you need to open the project folder that contains the CMakeLists.txt file. In our example project, that will be <project_root>/src:

CLion will configure your C/C++ projects based on your CMake configuration automatically.

Debugging Your Flutter Apps with CLion

It's easier to debug Flutter apps with CLion on desktop platforms, including macOS, Windows, and Linux.

It's also recommended to develop your C/C++ code on a desktop first, then cross-compile it and run it on mobile platforms.

Starting a Flutter App with CLion LLDB Debugger

First, you need to compile your Flutter app:

flutter build macos --debug

After your Flutter app is compiled, the app will be generated at <project_root>/example/build/macos/Build/Products/Debug/flutter_native_example_example.app.

For Linux or Windows platforms, just look for your Flutter app under the <project_root>/example/build/ directory.

Adding a Debugger Configuration in CLion

Open CLion, click the Edit Configurations selection menu at the top:

Click the + button on the top left and select Native Application:

Find and select the executable file for your Flutter app in the <project_root>/example/build/ directory.

The selection results will be as follows:

Now it's ready for debugging. Click the debug icon on the top bar to start your debugging:

Attaching a Running Application with CLion Debugger

If your application started earlier than the CLion debugger, you can attach an existing running Flutter app with the Attach To Process feature in CLion:

Debugging C/C++ Code in Xcode

Xcode is an alternative IDE for C/C++ debugging on macOS and iOS platforms. First, open the Runner.xcworkspace project in Xcode.

The source code of our C/C++ code is not visible in Xcode by default, so we need additional setup to make it visible and allow setting breakpoints on it:

In Xcode, right-click the Runner project and select Add Files to "Runner":

Select the source folder that contains CMakeLists.txt, but keep in mind to unselect all targets at the bottom because we don't want Xcode to package our C/C++ code in our project.

Now we can set breakpoints in Xcode and debug the C++ source code:

Debugging C/C++ Code in Android Studio

Android Studio for Android has built-in support for developing and debugging C/C++ code.

For a Flutter app for Android, open the example/android directory in Android Studio:

Once your project is fully configured in Android Studio, you will see your C/C++ code recognized and indexed by Android Studio.

Click the app entry point at the top and select "Edit Configuration":

Make sure the debug type is set to "Dual (Java + Native)" mode:

Now our C/C++ code can be developed and debugged in Android Studio:

Debugging C/C++ Code in Visual Studio

Visual Studio on the Windows platform provides a robust developer experience for C/C++.

Flutter projects use CMake to generate Visual Studio project templates.

First, compile your Flutter app by running the following command:

flutter build windows --debug

This will generate the Visual Studio project workspace in the <project_root>/example/build/windows/x64 directory. Open Visual Studio and load the ALL_BUILD.vcproj file from this location.

Right-click on the solution title and select Properties:

Change the Single startup project value to flutter_native_example_example:

Open the C/C++ code files in the demo_library folder and set your breakpoints:

Click on Debug -> Start Debugging:

Now the debugger should be working:

Next Chapter

In the next chapter, we will focus on Dart FFI in Flutter apps, covering bidirectional synchronous and asynchronous calls, handling complex data structures, and performance optimization tips.

The Comprehensive Guide to Using C/C++ in Flutter — Part I

Andy Dong — Tue, 27 Aug 2024 15:46:35 +0000

Flutter is an open-source UI software development kit created by Google. Its core advantage compared to other cross-platform UI development kits is that it uses its own rendering engine, originally based on Chrome’s Skia. Currently, a new engine called Impeller has been introduced on iOS and Android. With the advantage of a self-owned rendering engine, Flutter controls every pixel on all platform devices, including mobile and desktop platforms, eliminating implementation differences on the UI between these platforms.

Flutter and Dart excel on the UI side, but for commercial business apps in production, there is a lot of business logic that often depends on other hardware or components provided by the target platform OS. The Dart programming language was intentionally designed for building delightful UIs but is not suitable for accessing hardware I/O and native system components, multithreaded programming, or high-performance computing areas. Therefore, we need to use “low-level” programming languages such as C/C++ or to handle these tasks. Not only do these languages interact directly with hardware without the need for an abstraction layer, but they also work well and efficiently across all platforms.

This guide is designed for mobile/desktop developers who want to integrate C/C++ codes into their Flutter apps. It includes best practices for configuring build tools, debugging on mobile and desktop, using Dart FFI for bidirectional synchronous and asynchronous calls, handling complex data structures, performance optimization tips, listening for essential Dart VM callbacks on the C/C++ side, and some essential reminders for the Windows platform.

Initialize the Flutter Project

The Flutter command includes a built-in scaffold project for using C/C++ with Dart FFI examples.

flutter create --template=plugin_ffi demo_library --platforms android,ios,macos,windows,linux

This command creates a Flutter plugin package that contains the basic build scripts for adding C/C++ source code into Flutter packages.

The C/C++ code is configured and compiled by CMake on Windows, Linux, and Android, and it works well. However, for iOS and macOS, it is configured and compiled using CocoaPods directly.

Managing two build systems for more complex C/C++ projects is not practical for production use. Therefore, we need to modify the src/CMakeLists.txt file to generate a static archive library and link the build system from CocoaPods to CMake for the iOS and macOS platforms.

Configure Static Linked Build with CMake for macOS

First, we need to update our src/CMakeLists.txt file and change our build target to a static library for generating a static archive library:

if (${CMAKE_SYSTEM_NAME} MATCHES "Darwin")
  set(CMAKE_OSX_ARCHITECTURES "x86_64;arm64")
endif()

if (${CMAKE_SYSTEM_NAME} MATCHES "Darwin" OR ${CMAKE_SYSTEM_NAME} MATCHES "iOS")
  add_library(demo_library STATIC
    "flutter_native_example.c"
  )
else()
  add_library(demo_library SHARED
    "flutter_native_example.c"
  )
endif()

When the build targets the macOS or iOS platform, we set the library type to a static library.

Then, add the following shell script named build_macos.sh or build_ios.sh to build our static library:

# Define the function for macOS build
build_macos() {
  BUILD_TYPE="${1:-Debug}"
  echo "Building for macOS in $BUILD_TYPE mode"
  cmake -DCMAKE_BUILD_TYPE=$BUILD_TYPE -G "Unix Makefiles" -B $BASEDIR/cmake-build-macos -S $BASEDIR/
  cmake --build $BASEDIR/cmake-build-macos
}

build_macos "$@"

Run the following command: ./build_macos.sh Release or ./build_macos.sh Debug for debug purposes.

➜  src ./build_macos.sh Release
Building for macOS in Release mode
-- Configuring done (0.0s)
-- Generating done (0.0s)
-- Build files have been written to: /Users/andycall/workspace/flutter_native_example/src/cmake-build-macos
[ 50%] Building C object CMakeFiles/demo_library.dir/flutter_native_example.c.o
[100%] Linking C static library libdemo_library.a
[100%] Built target demo_library

We can see that libdemo_library.a was generated at <project>/src/cmake-build-macos/libdemo_library.a.

Link CMake with CocoaPods in macOS

Now, open <project>/macos/flutter_native_example.podspec and add a "Script Phase" to call the CMake command automatically when the user executes the flutter run or flutter build command.

s.prepare_command = 'bash build_macos.sh'
s.script_phase = {
  :name => 'Trigger Native Build',
  # First argument is relative path to the `rust` folder, second is name of rust library
  :script => 'ln -fs "$OBJROOT/XCBuildData/build.db" "${BUILT_PRODUCTS_DIR}/build_phony"',
  :execution_position=> :before_compile,
  :input_files => ['${BUILT_PRODUCTS_DIR}/build_phony'],
  :output_files => [__dir__ + "/../src/cmake-build-macos/libdemo_library.a"],
}
s.pod_target_xcconfig = {
  'DEFINES_MODULE' => 'YES',
  'OTHER_LDFLAGS' => '-force_load ' + __dir__ + '/../src/cmake-build-macos/libdemo_library.a',
}

Remove the C++ Source Files Included in CocoaPods

Don't forget to remove all contents in <project>/macos/Classes/flutter_native_example.c to avoid duplicate symbols compile errors.

Test with flutter run Command

Now it's time to test our modified build scripts and see if everything is working well.

cd example && flutter run -d macos

Migrating to iOS Platform Support

The build configuration for iOS is very similar to macOS builds.

Building for the iOS platform on macOS requires additional steps for configuring the cross-compilation toolchain.

Use the following commands at the root of the project to get the ios-cmake project and compile iOS targets using CMake:

git subtree add --prefix src/ios-cmake https://github.com/leetal/ios-cmake.git master --squash

Add Shell Scripts to Build a Static Library for iOS

# Define the function for iOS build
build_ios() {
  BUILD_TYPE="${1:-Debug}"
  echo "Building for iOS with $BUILD_TYPE mode"
  cmake -DPLATFORM=OS64COMBINED -DCMAKE_TOOLCHAIN_FILE=$BASEDIR/ios-cmake/ios.toolchain.cmake -G "Xcode" -B $BASEDIR/cmake-build-ios -S $BASEDIR/
  cmake --build $BASEDIR/cmake-build-ios --config $BUILD_TYPE
}

Run the following command: ./build_ios.sh Release or ./build_ios.sh ios Debug for debug purposes.

The static library will be located in <project>/src/cmake-build-ios/Debug-iphoneos with a Debug build and <project>/src/cmake-build-ios/Release-iphoneos with a Release build variant.

Link CMake with CocoaPods in iOS

Now it's time to modify <project>/ios/flutter_native_example.podspec to add the build phase and connect our scripts with the CocoaPods build.

s.prepare_command = 'bash build_ios.sh'
s.script_phase = {
  :name => 'Trigger Native Build',
  # First argument is relative path to the `rust` folder, second is name of rust library
  :script => 'ln -fs "$OBJROOT/XCBuildData/build.db" "${BUILT_PRODUCTS_DIR}/build_phony"',
  :execution_position=> :before_compile,
  :input_files => ['${BUILT_PRODUCTS_DIR}/build_phony'],
  :output_files => [__dir__ + "/../src/cmake-build-ios/$CONFIGURATION-iphoneos/libdemo_library.a"],
}

# Flutter.framework does not contain a i386 slice.
s.pod_target_xcconfig = {
  'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386',
  'OTHER_LDFLAGS' => '-force_load ' + __dir__ + '/../src/cmake-build-ios/$CONFIGURATION-iphoneos/libdemo_library.a',
}

Remove the C++ Source Files Included in CocoaPods

Don't forget to remove all contents in <project>/ios/Classes/flutter_native_example.c to avoid duplicate symbols compile errors.

Test with flutter run Command

Now it's time to test our modified build scripts and see if everything is working well.

cd example && flutter run -d <device_id>

Compile for Android, Linux, and Windows

The Flutter scaffold project already has good configuration for building on Android, Linux, and Windows using dynamic library loading.

Check the Demo and Try It Yourself

All the code in this article is located in this GitHub repository:

https://github.com/andycall/The_Comprehensive_Guide_to_Using_Cpp_in_Flutter/tree/main/Chapter-1

Next Chapter

In the next chapter, we will focus on debugging C/C++ code in Flutter apps across multiple platforms, using a range of development IDEs such as Xcode, Visual Studio, Android Studio, and CLion.