DEV Community

Cover image for Best Practices for Publishing an SDK to the OpenHarmony Central Repository in HarmonyOS Next
kouwei qing
kouwei qing

Posted on

Best Practices for Publishing an SDK to the OpenHarmony Central Repository in HarmonyOS Next

#harmonyosnext

Best Practices for Publishing an SDK to the OpenHarmony Central Repository in HarmonyOS Next

Background Introduction

Previously, during the adaptation of Mars in HarmonyOS Next, we submitted a PR to the official Mars repository for xlog compatibility. Some developers privately requested compiled xlog dynamic libraries, so we decided to open-source the qlog source code (https://gitcode.com/wodekouwei/qlog) for easier access. To facilitate usage, we aimed to upload the compiled binaries to the OpenHarmony central repository. This article documents the publishing process to help other developers.

QLog Introduction

QLog is a persistent logging library that asynchronously encrypts and compresses console logs into files, making it easier for developers to view and analyze logs, especially for troubleshooting online issues.

QLog is based on WeChat's XLog, a high-performance logging system designed for WeChat's mobile clients (Android/iOS). Key features include:

  1. Encryption & Security

    • Log Encryption: All logs are encrypted (e.g., AES) during storage and transmission to prevent sensitive data leaks and comply with privacy regulations.
    • Tamper-Proof: Encrypted logs cannot be modified, ensuring integrity and trustworthiness.

  2. High Performance & Low Overhead

    • Asynchronous Writing: Logs are written in background threads to avoid blocking the main thread, ensuring app smoothness.
    • Memory-Mapped Files (mmap): Direct file writing via memory mapping reduces I/O operations, improving efficiency.
    • Compression: Logs are compressed before storage or upload, reducing disk usage and network traffic.

  3. Flexible Log Levels

    • Supports multiple log levels (VERBOSE, DEBUG, INFO, WARN, ERROR), allowing developers to filter logs as needed.
    • Dynamic log level adjustment (e.g., only ERROR logs in production) balances debugging and performance.

  4. Log Retrieval Mechanism

    • Remote Trigger: Servers can instruct clients to upload specific logs without user intervention, simplifying issue diagnosis.
    • Conditional Filtering: Logs can be retrieved by time, user ID, log level, etc., for precise debugging.

  5. Fault Tolerance & Stability

    • Error Handling: Automatically downgrades or caches logs if writing fails or storage is full, preventing crashes.
    • Chunked Storage: Logs are split by size or time to avoid performance issues with large files.

  6. Cross-Platform Support

    • Supports Android and iOS with a unified API, reducing maintenance costs.

  7. Selective Logging Control

    • Non-critical logs can be disabled to save resources in production.
    • Dynamic module-level logging enables targeted debugging.

  8. Typical Use Cases

    • Issue Tracking: Encrypt and retrieve logs to diagnose user-reported crashes.
    • Performance Monitoring: Record key metrics (e.g., startup time) with minimal overhead.
    • Security Auditing: Encrypted logs provide tamper-proof records of sensitive operations.

XLog balances security, performance, and flexibility, making it ideal for large-scale mobile apps. QLog brings these capabilities to the HarmonyOS platform.

Usage

Dependency Installation 
ohpm i @qing/qlog
Enter fullscreen mode Exit fullscreen mode

For OpenHarmony ohpm setup, refer to How to Install OpenHarmony ohpm Packages.

Initialize QLogSDK 
class LogDep implements LogDependency {
  isDebug(): boolean {
    return true; // Debug mode prints more logs
  }

  getFileLogLevel(): number {
    return LogLevel.LEVEL_DEBUG; // Set log level
  }
}

LogSdk.init(this.context.getApplicationContext(), new LogDep());
Enter fullscreen mode Exit fullscreen mode
Log Messages 
Logg.d('HelloWorldTAG', 'debug log...');
Logg.i('HelloWorldTAG', 'info log...');
Logg.w('HelloWorldTAG', 'warn log...');
Logg.e('HelloWorldTAG', 'error log...');
Enter fullscreen mode Exit fullscreen mode
Retrieve Log Files

Logs are stored in the app's sandbox:
Log Storage
Log Storage

Logs are retained for up to 10 days and auto-cleaned on app startup. Use Log.uploadLogFiles() to compress and retrieve logs. Decrypt the exported ZIP file with decod_mars.py.

Publishing Process

  1. Prepare Files in the Library Module (same level as src):

    • README.md: Describe the package and usage.
    • CHANGELOG.md: Version update history.
    • LICENSE: License file.

  2. Recompile the Library to generate a *.har file.

  3. Generate SSH Keys:

   ssh-keygen -m PEM -t RSA -b 4096 -f ~/.ssh_ohpm/mykey
Enter fullscreen mode Exit fullscreen mode
  • Private key: mykey (specify path).
  • Public key: mykey.pub (auto-generated in the same directory).
  • Note: ohpm requires encrypted keys with a password.

  1. Add Public Key to OpenHarmony Center:

  2. Configure .ohpmrc:

    • Set the private key path: 
     ohpm config set key_path ~/.ssh_ohpm/mykey

  • Get the Publish Code from the website and configure it:

     ohpm config set publish_id your_publish_id
  1. Publish the HAR File: 
   ohpm publish <HAR路径>
Enter fullscreen mode Exit fullscreen mode

Wait for Review:
Review Status

After approval, the package will appear in the repository:
Package Listing

Common Issues

1. oh-package.json5 Configuration

Example:

{
  "name": "@qing/qlog",
  "version": "1.0.0",
  "description": "Persistent log utility for HarmonyOS Next.",
  "main": "Index.ets",
  "author": "qingkouwei",
  "license": "MIT",
  "homepage": "https://gitcode.com/wodekouwei/qlog",
  "repository": "https://gitcode.com/wodekouwei/qlog",
  "dependencies": {},
  "compatibleSdkVersion": "12",
  "compatibleSdkType": "HarmonyOS",
  "obfuscated": false
}
Enter fullscreen mode Exit fullscreen mode
  • Fields Displayed in Repository: Repository Details
  • Ensure license matches the LICENSE file.
  • If using a namespace (e.g., @group/name), register it in Organization Management: Namespace Registration

2. Private Key Password Requirement

Always set a password when generating keys:

ssh-keygen -m PEM -t RSA -b 4096 -f ~/.ssh_ohpm/mykey
Enter fullscreen mode Exit fullscreen mode

3. Publishing to Both Private and Central Repositories

To avoid overwriting .ohpmrc, specify central repo settings during publish:

ohpm publish --publish_registry https://ohpm.openharmony.cn/ohpm --publish_id xxx --key_path ~/.ssh_ohpm/mykey qloglib/build/default/outputs/default/qloglib.har
Enter fullscreen mode Exit fullscreen mode

For command details, see ohpm Publish Docs.

Summary

This guide outlines the steps to publish a HAR file to the OpenHarmony central repository using ohpm, including key generation, configuration, and submission. Key takeaways:

  • Security: Always set passwords for SSH keys.
  • Metadata: Ensure oh-package.json5 and LICENSE are accurate.
  • Review: Double-check parameters to avoid submission failures.

By following these practices, developers can efficiently manage and share SDKs within the OpenHarmony ecosystem.

Top comments (0)