IDLize Developer Guide

This guide is for tool developers who maintain the IDLize generators and pipeline. After reading it, readers should be able to determine:

• What IDLize owns in the ArkUI code generation flow.
• Which stages a standard generation run goes through.
• Which workspace to start from for different kinds of changes.
• How to locate the pipeline stage where generated output diverged.
• Which verification steps are needed after code changes.

If you only need to use IDLize to generate code, start with the Tool User Guide. For deeper design details, see Architecture Design.

1. Project Role

IDLize is a compile-time generator tool for OpenHarmony ArkUI. It reads .d.ets, .idl, and .d.ts declarations that are still supported by the pipeline, converts them to the IDL intermediate representation and AST, then generates:

• ArkTS-layer Peer / Component classes.
• C++-layer Modifiers.
• Type conversion, callback, and Serializer code between the ArkTS layer and the C++ layer.
• Multilanguage interfaces and glue code consumed by the Arkoala runtime.

The main pipeline is:

SDK declarations / handwritten IDL
  -> etsgen converts declarations to .idl
  -> core parses .idl to IDL AST
  -> arkgen and libohos print target code
  -> runner installs generated output

2. First-Time Setup

Run the base installation from the repository root:

npm i --no-save /path/to/ace_ets2bundle/libarkts.tgz

The libarkts archive must be supplied by ace_ets2bundle; the remaining npm dependencies are installed from the configured registry.

Compile the main generation pipeline and download the SDK:

cd runner
npm run compile
cd ..
npm run download:sdk

The repository no longer requires git submodules for installation or bundling. In an OpenHarmony component build, the idlize_bundle GN target obtains both libarkts and the Panda SDK from ace_ets2bundle; it does not place either dependency in the source tree.

Run the standard generation flow:

bash generate.sh

Installed output is written to ./out; intermediate artifacts are written under runner/out.

3. Directories and Change Entry Points

Directory	Main responsibility	Common changes
core/	IDL AST, parser, LanguageWriter, shared peer model.	Add IDL syntax, type nodes, diagnostics, or target-language writer behavior.
etsgen/	.d.ts / .d.ets to .idl conversion.	Fix declaration-to-IDL mapping, generics, unions, or optional type conversion.
arkgen/	ArkUI component code generation.	Change Peer, Component, Modifier, or Arkoala interface output.
arkgen/generation-config/	Component materialization, hooks, type conversion configuration.	Adjust generation scope or special component generation strategy.
libohos/	Shared printers, serializers, peer infrastructure.	Shared generation logic, serialization, and native module bindings.
runner/	runner m3, SDK preparation, output installation, CLI.	Adjust pipeline stages, options, output directories, or install rules.
sdk-patched/	Upstream TypeScript SDK declaration patches.	Patch .d.ts input; do not edit interface_sdk-js/ directly.
sdk-patched-arkts/	Upstream ArkTS SDK declaration patches.	Patch .d.ets input.
interfaces/	Additional handwritten IDL definitions.	Add supplementary components or handwritten interfaces.
linter/ / idlinter/	Declaration and IDL lint rules.	Add or change lint rules.
dtsgen/	Reverse generation from IDL to .d.ts.	Maintain reverse generation capability.
scraper/	SDK fetching, caching, and normalization.	Adjust external SDK content handling.

Do not hand-edit generated artifacts: out/, runner/out/, build/, bundled/, *.tgz, or lib/ when it is adjacent to src/.

4. Core Concepts

IDL IDLize's intermediate interface language. etsgen converts SDK declarations to .idl, and core parses .idl into AST. Downstream generators should depend on the AST instead of reinterpreting TypeScript or ArkTS declarations.

AST The tree-shaped data model defined in core/src/idl/node.ts. Common nodes include IDLFile, IDLInterface, IDLMethod, IDLProperty, IDLCallback, IDLTypedef, and the IDLType variants.

FrameNode An ArkUI C++-layer component node representing one component instance in the UI tree. Generated C++ Modifiers ultimately apply property changes to the corresponding FrameNode.

Peer An ArkTS-layer class generated by IDLize. It exposes component attributes and methods, then forwards calls to the C++ side.

Modifier A C++-layer struct / object generated by IDLize to pass property changes to a FrameNode.

Serializer Generated encode/decode logic for ArkTS/C++ parameters, callbacks, and type conversion. When adding a type or changing a cross-language parameter shape, confirm that serializers and type conversion stay aligned.

materialized A component or interface with fully generated Peer / Component / Modifier code. Materialization is mainly controlled by arkgen/generation-config/config.json.

hook A configuration mechanism for injecting custom logic into generation phases. Hooks are useful when one component or attribute needs special generated code but a broad printer rewrite is not appropriate.

5. Standard Generation Flow

generate.sh invokes:

node runner m3 sdk-patched-arkts ./interfaces/interfaces/arkui-extra/ \
    --sdk-stage prepared \
    --arkgen-options-file ./arkgen/generation-config/config.json \
    --etsgen-options-file ./etsgen/generator-config.json \
    --arkgen-interop-types ./runner/interop-types/src/cpp/interop-types.h \
    --scraper-options-file ./runner/configs/scraper-config.json \
    --arkgen "node arkgen" --etsgen "node etsgen" \
    --target all \
    --no-arkgen-dummy-impl \
    --output "./out"

Main stages:

1. The m3 command in runner/src/main.ts cleans and creates runner/out.
2. With sdkStage=prepared, etsgen converts sdk-patched-arkts/ to .idl.
3. scraper processes IDL input and extra IDL according to runner/configs/scraper-config.json.
4. arkgen reads IDL, builds ArkoalaPeerLibrary, and runs printers.
5. runner installs generated output into ./out.

When debugging generated output, trace backwards through the artifact chain:

Question	Where to look
Is the installed final output correct?	out/
What did the printers actually emit?	runner/out/peers/sig/, runner/out/peers/libace/
What IDL did the parser receive?	runner/out/idl/
Was SDK input prepared correctly?	runner/out/patched-sdk-arkts/, runner/out/patched-sdk-ts/
Do output directory constants match expectations?	runner/src/shared.ts

6. Core Code Entry Points

6.1 runner/: Pipeline Orchestration

File	Purpose
runner/src/main.ts	Defines m3, complete, sdk, m3-sdk, and related commands.
runner/src/shared.ts	Defines stage output directories under runner/out.
runner/src/commands/ets2idl.ts	Invokes etsgen to generate IDL.
runner/src/commands/idl2peer.ts	Invokes arkgen to generate peers and modifiers.
runner/src/commands/sdk.ts	Prepares the patched SDK.
runner/src/commands/scrape.ts	Processes and merges IDL input.
runner/src/commands/install.ts	Installs generated output into the target directory.

6.2 etsgen/: Declarations to IDL

File	Purpose
etsgen/src/app.ts	CLI entry point for --ets2idl, input directories, and config files.
etsgen/src/generate.ts	Core declaration conversion logic.
etsgen/src/config.ts	etsgen configuration loading.
etsgen/generator-config.json	Conversion config used by the standard pipeline.

If the IDL in runner/out/idl/ is already wrong, check etsgen and SDK patches first.

6.3 core/: IDL AST and Language Abstractions

File	Purpose
core/src/from-idl/parser.ts	Parses .idl text into AST.
core/src/idl/node.ts	Defines AST nodes and extended attributes.
core/src/idl/builders.ts	Factory functions for AST nodes.
core/src/idl/discriminators.ts	AST type guards.
core/src/idl/utils.ts	AST query and helper functions.
core/src/LanguageWriters/LanguageWriter.ts	Target-language-neutral code writing abstraction.
core/src/LanguageWriters/writers/	Writers for TS, ArkTS, C++, CangJie, and more target languages.
core/src/LanguageWriters/convertors/	Converters from IDL types to target-language types.
core/src/peer-generation/	Shared peer model, reference resolution, and layout infrastructure.

When adding IDL syntax or an AST node, usually check the parser, builders, visitors, discriminators, and all downstream generators.

6.4 arkgen/: ArkUI Code Generation

File	Purpose
arkgen/src/app.ts	CLI entry point; parses --idl2peer and loads config and IDL.
arkgen/src/arkoala.ts	Orchestrates Arkoala and libace outputs.
arkgen/src/ArkoalaPeerLibrary.ts	Peer library used by ArkUI generation.
arkgen/src/printers/ComponentsPrinter.ts	Generates component classes and attribute setters.
arkgen/src/printers/PeersPrinter.ts	Generates Peer classes.
arkgen/src/printers/ModifierPrinter.ts	Generates C++ Modifiers.
arkgen/src/printers/ArkoalaInterfacePrinter.ts	Generates Arkoala interface declarations.
arkgen/generation-config/config.json	Standard generation configuration.
arkgen/generation-config/schema.json	Generation configuration schema.

If the generated file shape is correct but one component method is wrong, start with the related printer and generation-config/config.json.

6.5 libohos/: Shared Generation Infrastructure

File or directory	Purpose
libohos/src/peer-generation/printers/	Shared printers for interfaces, declarations, peers, native modules, serializers, and more.
libohos/src/peer-generation/ComponentsCollector.ts	Collects component declarations.
libohos/src/peer-generation/PeersCollector.ts	Collects and organizes Peer classes.
libohos/src/peer-generation/ImportsCollector.ts	Manages imports in generated files.
libohos/src/peer-generation/LayoutManager.ts	Decides where generated files are placed.
libohos/src/peer-generation/NativeModule.ts	Describes native module bindings.
libohos/src/ost/, libohos/src/ostgen/	Object serialization template and generation helpers.

If several targets have similar issues, do not patch only arkgen; first decide whether the fix belongs in a shared libohos printer, collector, or serializer.

7. Common Development Tasks

Task	Starting point	Verification
Change ArkUI component Peer / Component generation	arkgen/src/printers/ComponentsPrinter.ts, PeersPrinter.ts	npm run -C arkgen test, then run bash generate.sh and compare runner/out/peers/.
Change C++ Modifier generation	arkgen/src/printers/ModifierPrinter.ts or libohos/src/peer-generation/printers/ModifierPrinter.ts	Generate --target libace or run standard generate.sh.
Change .d.ets / .d.ts to IDL conversion	etsgen/src/generate.ts	npm run -C etsgen test, then inspect runner/out/idl/.
Add IDL syntax or a type node	core/src/idl/node.ts, core/src/from-idl/parser.ts	npm run -C core test, then run downstream generation.
Change a generation config field	arkgen/generation-config/schema.json, arkgen/src/config.ts	npm run -C arkgen generate-schema, then run standard generation.
Change main pipeline options or directories	runner/src/main.ts, runner/src/shared.ts	npm run -C runner compile, then bash generate.sh.
Patch upstream SDK declarations	sdk-patched/ or sdk-patched-arkts/	npm run download:sdk or bash generate.sh, then inspect IDL differences.

8. Compile and Verify

Common compile commands:

npm run -C core compile
npm run -C etsgen compile
npm run -C arkgen compile
npm run -C libohos compile
npm run -C runner compile

Common tests and checks:

npm run -C core test
npm run -C etsgen test
npm run -C arkgen test
npm run sanity

Standard end-to-end generation:

bash generate.sh

Bundle artifacts:

npm run bundle

This writes six idlizer packages to ./bundled. In an OpenHarmony build, build //foundation/arkui/idlize:idlize_bundle; its isolated work tree is under target_gen_dir, and the verified output is written to $root_out_dir/arkui_idlize.

9. Pre-Submit Checklist

• Code generation logic changed: rerun bash generate.sh and inspect runner/out/peers/.
• IDL parsing or AST changed: run npm run -C core test and confirm downstream generation is not broken.
• etsgen changed: inspect runner/out/idl/ changes.
• arkgen or libohos changed: inspect ArkTS / C++ output and Serializer changes.
• SDK declarations changed: do not edit interface_sdk-js/ directly; change patch directories instead.
• README or documentation changed: keep Chinese and English entries synchronized.
• Do not submit generated directories, bundles, tgz files, or direct changes inside the vendored SDK directory.