Build and Compilation Guide

This document describes the RNOH build process, including how to use Debug and Release packages, CMake configuration, and environment setup.

---

1. Build Mode Overview

Mode	Purpose	Features	Package Size	Performance
Debug	Development & Debugging	Full symbols, debuggable, no optimization	Large	Slow
Release	Production Release	Stripped symbols, optimized, small size	Small	Fast
Release2	Special Scenarios	Similar to Release, may have different optimization	Small	Fast

---

2. Using Debug Package

2.1 Obtaining Debug Package

Debug packages can be obtained through:

1. Local Build: Build in Debug mode in DevEco Studio
2. npm Download: Download react-native-harmony package from npm (usually includes Debug version har)

2.2 Configuring Debug Package

Step 1: Configure oh-package.json5

Add dependency in HarmonyOS project's oh-package.json5:

{
  "dependencies": {
    "@rnoh/react-native-openharmony": "0.84.1"  // Use Debug version
  }
}

Step 2: Configure build-profile.json5

Ensure Debug configuration in build-profile.json5:

{
  "apiType": "stageMode",
  "targets": [
    {
      "name": "default",
      "runtimeOS": "HarmonyOS"
    }
  ],
  "buildOptionSet": [
    {
      "name": "debug",
      "externalNativeOptions": {
        "path": "./src/main/cpp/CMakeLists.txt",
        "arguments": [
          "-DCMAKE_BUILD_TYPE=Debug"
        ]
      },
      "nativeLib": {
        "debugSymbol": {
          "strip": false  // Debug mode keeps symbols
        }
      }
    }
  ]
}

Step 3: Configure CMakeLists.txt (Debug Mode)

cmake_minimum_required(VERSION 3.10)
project(MyApp)

# Debug mode basic configuration
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Add RNOH dependency
add_subdirectory(${RNOH_CPP_DIR} ./rnoh)

# Debug mode specific configuration
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    # Enable debug symbols
    add_compile_options(-g)
    
    # Disable optimization
    add_compile_options(-O0)
endif()

2.3 Building Debug Package in DevEco Studio

1. Open DevEco Studio
2. Select Build Mode as Debug in toolbar
3. Click Build > Make Module 'entry'
4. After build, output located at build/default/outputs/default/

2.4 Debug Package Debugging

Debug package contains full symbols, allowing:

• C++ code debugging in DevEco Studio
• Set breakpoints, view variables, step execution
• LLDB command-line debugging

---

3. Using Release Package

3.1 Obtaining Release Package

Release packages can be obtained through:

1. Local Build: Build in Release mode in DevEco Studio
2. npm Download: Download react-native-harmony_release package from npm
3. Official Release: Get Release version har from official channels

3.2 Configuring Release Package

Step 1: Configure oh-package.json5

{
  "dependencies": {
    "@rnoh/react-native-openharmony": "file:./react_native_openharmony_release.har"  // Use local Release package
  }
}

Or use npm version:

{
  "dependencies": {
    "@rnoh/react-native-openharmony": "0.84.1"  // Specify version
  }
}

Step 2: Configure build-profile.json5 (Release Mode)

{
  "apiType": "stageMode",
  "targets": [
    {
      "name": "default",
      "runtimeOS": "HarmonyOS"
    }
  ],
  "buildOptionSet": [
    {
      "name": "release",
      "externalNativeOptions": {
        "path": "./src/main/cpp/CMakeLists.txt",
        "arguments": [
          "-DRNOH_APP_DIR=${RNOH_CPP_DIR}",
          "-DCMAKE_BUILD_TYPE=Release"
        ],
        "cppFlags": "-fstack-protector-strong -Wl,-z,noexecstack"
      },
      "nativeLib": {
        "debugSymbol": {
          "strip": true  // Release mode strips symbols
        }
      }
    }
  ]
}

Step 3: Configure CMakeLists.txt (Release Mode)

Release package requires special CMake configuration:

cmake_minimum_required(VERSION 3.10)
project(MyApp)

# Release mode basic configuration
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Release mode specific configuration
if(CMAKE_BUILD_TYPE STREQUAL "Release")
    # Enable maximum optimization
    add_compile_options(-O3)
    
    # Disable debug symbols
    add_compile_options(-g0)
endif()

# Add RNOH dependency (Release version)
add_subdirectory(${RNOH_CPP_DIR} ./rnoh)

Release Package CMakeLists.txt Example:

Reference template file: CMakeLists-release.txt

3.3 Building Release Package in DevEco Studio

1. Open DevEco Studio
2. Select Build Mode as Release in toolbar
3. Set Debuggable to false
4. Click Build > Make Module 'entry'
5. After build, output located at build/release/outputs/default/

3.4 Release Package Signing

Release package needs signing to install on real device:

1. Configure signing in DevEco Studio:

   • File > Project Structure > Signing Configs
   • Add signing certificate and configuration

2. Or manually configure build-profile.json5:

{
  "signingConfigs": [
    {
      "name": "release",
      "type": "HarmonyOS",
      "material": {
        "certpath": "path/to/cert.cer",
        "storePassword": "your_password",
        "keyAlias": "your_alias",
        "keyPassword": "your_key_password",
        "profile": "path/to/profile.p7b",
        "signAlg": "SHA256withECDSA",
        "storeFile": "path/to/store.p12"
      }
    }
  ]
}

---

4. CMake Configuration Details

4.1 CMakeLists.txt Basic Structure

cmake_minimum_required(VERSION 3.10)

# Project name
project(MyRNApp)

# C++ standard
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# RNOH related paths (adjust based on actual project)
set(RNOH_CPP_DIR "${OH_ROOT_DIR}/native/api/10/packages/react_native_openharmony")

# Add compile definitions
add_compile_definitions(
    WITH_HITRACE_SYSTRACE=1
    WITH_HITRACE_REACT_MARKER=1
)

# Add source files
add_executable(my_app
    src/main/cpp/main.cpp
    src/main/cpp/PackageProvider.cpp
)

# Link RNOH libraries
target_link_libraries(my_app
    ${OH_LIB_DIR}/librnoh_core.so
    ${OH_LIB_DIR}/librnoh_core_package.so
)

# Add RNOH module
add_subdirectory(${RNOH_CPP_DIR} ./rnoh)

4.2 Common CMake Variables

Variable	Description	Example Value
CMAKE_BUILD_TYPE	Build type	Debug / Release
RNOH_CPP_DIR	RNOH C++ source path	${OH_ROOT_DIR}/native/api/10/packages/react_native_openharmony
CMAKE_CXX_STANDARD	C++ standard	17
OH_LIB_DIR	OpenHarmony library path	${OHOS_SDK}/native/llvm/lib

4.3 Common Compile Options

Option	Description	Debug	Release
-g	Generate debug symbols	✓	✗
-O0	No optimization	✓	✗
-O3	Maximum optimization	✗	✓
-fstack-protector-strong	Stack protection	Optional	✓
-Wl,-z,noexecstack	Disable stack execution	Optional	✓

4.4 RNOH Specific Compile Options

# RNOH specific options
add_compile_definitions(
    # Hitrace support (performance analysis)
    WITH_HITRACE_SYSTRACE=ON
    WITH_HITRACE_REACT_MARKER=ON
    
    # Log level
    LOG_VERBOSITY_LEVEL=1
    
    # JSVM support
    ADD_JSVM_SO=ON
)

---

5. Environment Configuration

5.1 DevEco Studio Environment

SDK Configuration

1. Open DevEco Studio
2. File > Settings > HarmonyOS SDK
3. Configure SDK path and version:
   • HarmonyOS SDK: Recommend API 10 or higher
   • Native SDK: Includes NDK toolchain

NDK Configuration

Ensure NDK toolchain is properly configured:

// build-profile.json5
{
  "nativeCompiler": "BiSheng"  // Use BiSheng compiler
}

5.2 Command Line Environment

Configure Environment Variables

# HarmonyOS SDK path
export OHOS_SDK=/path/to/harmonyos/sdk

# NDK path
export OHOS_NDK=${OHOS_SDK}/native

# Toolchain path
export PATH=${OHOS_NDK}/llvm/bin:$PATH

Hvigorw Commands

# Build Debug version
hvigorw --mode module -p product=default -p module=entry@default -p buildMode=debug assembleHap

# Build Release version
hvigorw --mode module -p product=default -p module=entry@default -p buildMode=release -p debuggable=false assembleHap

5.3 Environment Check

# Check CMake version
cmake --version

# Check LLVM toolchain
llvm-clang --version

# Check Hvigorw
hvigorw -v

---

6. Build Commands Reference

6.1 DevEco Studio GUI Operations

Operation	Menu Path
Build Module	Build > Make Module 'xxx'
Clean Project	Build > Clean Project
Rebuild Project	Build > Rebuild Project
Package HAP	Build > Build Hap(s)/APP(s) > Build Hap(s)

6.2 Command Line Operations

# Clean
hvigorw clean

# Build Debug
hvigorw --mode module -p buildMode=debug assembleHap

# Build Release
hvigorw --mode module -p buildMode=release -p debuggable=false assembleHap

# Package APP
hvigorw --mode module -p buildMode=release assembleApp

---

7. Common Issues

7.1 Debug Package Slow Build

Cause: Debug mode has no optimization, includes debug info

Solution:

• Use Debug package during development
• Use Release package for performance testing
• Temporarily use Release package for quick validation

7.2 Release Package Cannot Debug

Cause: Release package stripped debug symbols

Solution:

• Use matching .sym symbol file for crash analysis
• Refer to detailed symbol management guide: RNOH Build and Symbol Management Guide

7.3 Build Error Cannot Find RNOH

Cause: RNOH dependency configuration error

Solution:

1. Check dependency configuration in oh-package.json5
2. Check path configuration in CMakeLists.txt
3. Ensure ohpm install has been executed

7.4 Release Package Installation Failed

Cause: Signing configuration error

Solution:

1. Check if signing configuration is correct
2. Ensure using correct certificate and profile
3. Check signingConfigs configuration in build-profile.json5

---

8. Related Documents

• RNOH Build and Symbol Management Guide
• Environment Setup
• Performance Optimization