OpenHarmony symbols

To help you debug your application, Tuanjie can generate a package that contains symbol files for native Tuanjie libraries. Symbol files contain a table that translates active memory addresses into information you can use, like a method name. The translation process is called symbolication.

There are two types of symbol files:

• Public: A small file that contains a symbol table. For more information, refer to Public symbols.
• Debug: Contains everything that a public symbol file contains, and full debugging information that you can use for more in-depth debugging. For more information, refer to Debugging symbols.

You can generate symbol files for the following libraries:

• libtuanjie: Tuanjie’s engine code.
• libil2cpp: Contains C# scripts from the project converted to C++ code.

Tuanjie generates the libtuanjie symbol files. Hvigor generates the libil2cpp symbol file.

Public symbols

A public symbol file contains information that resolves function addresses to human-readable strings.This makes public symbol files and packages smaller than debugging symbol files and packages.

Debugging symbols

A debugging symbol file contains full debugging information and a symbol table. Use it to:

• Resolve stack traces and to debug applications that you have source code available for.
• Attach a native debugger to the application and debug the code.

Note: If debugging symbols aren’t available, Tuanjie places a public symbol file in your project at build time. For the libtuanjie libraries, debugging symbols aren’t available and Tuanjie always generates public symbol files.

Custom symbols

You can instruct Tuanjie to include additional symbol files. This is useful if you use shared libraries and want your local debugger, to resolve the shared library stack traces if the application crashes.

To make Tuanjie include a custom symbols file:

1. In the Project window, select a plug-in that has a .so file extension.
2. In the Inspector, find the Platform settings section.
3. Set CPU to the CPU architecture that the symbols file is compatible with.
4. Set Shared Library Type to Symbol.

Whenever Tuanjie generates a symbols package, it adds the additional symbol files to the symbols package.

If you want to make Tuanjie include a custom symbols file from a C# script, the TuanjieEditor.OpenHarmony namespace includes the following APIs to set the CPU and Shared Library Type respectively:

• PluginImporter.SetOpenHarmonyCPU
• PluginImporter.SetOpenHarmonySharedLibraryType

Note: The symbols file name must match the name of the shared library that the symbols file is for. For example, if a shared library is called mylibrary.so, the symbols file must also be named mylibrary.so. To avoid file name collisions, the symbols file and the shared library must be in separate directories.

Important: Ensure the symbols file is up to date and compatible with the shared library that contains the executable code. If you don’t, your local debugger will fail to resolve stack traces for code in the shared library.

Generating a symbols package

There are two ways to enable symbols package generation for your application:

• Through the Build Settings window.
• Using the EditorUserBuildSettings.openharmonyCreateSymbols API.

To enable symbols package generation through the Build Settings window:

1. Open the Build Settings window (menu: File > Build Settings).

2. Select the OpenHarmony platform.

3. Set Create symbols.zip to one of the following:

   • Public
   • Debugging

After you enable symbols package generation, building your project generates a .zip file that contains symbol files for the libtuanjie library. the scripting backend always is IL2CPP, the .zip also contains a symbol file for the libil2cpp library. Tuanjie places this symbols package within the output directory.

If you enable Export Project in the OpenHarmony Build Settings, Tuanjie doesn’t build the project. Instead, it exports the project for DevEco Studio, generates symbols for libtuanjie and libil2cpp, then places them within entry/symbols/<architecture>/ in the output directory.