This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit e8c7153233a8234d0dab66152f9872c46a9085c3 Author: chaokunyang <[email protected]> AuthorDate: Fri Jun 5 11:00:25 2026 +0000 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/' --- docs/compiler/compiler-guide.md | 8 ++++---- docs/compiler/flatbuffers-idl.md | 16 ++++++++-------- docs/compiler/generated-code.md | 28 ++++++++++++++-------------- docs/compiler/index.md | 5 ++--- docs/compiler/protobuf-idl.md | 4 ++-- docs/compiler/schema-idl.md | 34 +++++++++++++++++----------------- 6 files changed, 47 insertions(+), 48 deletions(-) diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md index 654ea5236f..7204116f14 100644 --- a/docs/compiler/compiler-guide.md +++ b/docs/compiler/compiler-guide.md @@ -156,8 +156,8 @@ foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./g The generated gRPC service code uses Fory to serialize request and response payloads. Java output imports grpc-java APIs and Python output imports `grpc`; applications that compile or run those generated service files must provide -their own gRPC dependencies. Fory's Java and Python runtime packages do not add a -hard gRPC dependency for this feature. +their own gRPC dependencies. Fory's Java and Python packages do not add a hard +gRPC dependency for this feature. **Use import search paths:** @@ -453,7 +453,7 @@ cd integration_tests/idl_tests ./run_csharp_tests.sh ``` -This runner executes schema-consistent and compatible roundtrips across: +This runner executes same-schema and compatible roundtrips across: - `addressbook`, `auto_id`, `complex_pb` primitives - `collection` and union/list variants @@ -475,7 +475,7 @@ cd integration_tests/idl_tests This runs: -- local Swift IDL roundtrip tests in both compatible and schema-consistent modes +- local Swift IDL roundtrip tests in both compatible and same-schema modes - Java-driven peer roundtrip validation with `IDL_PEER_LANG=swift` The script also sets `DATA_FILE*` variables so file-based roundtrip paths are exercised. diff --git a/docs/compiler/flatbuffers-idl.md b/docs/compiler/flatbuffers-idl.md index f7aa298c24..2744ba6ae7 100644 --- a/docs/compiler/flatbuffers-idl.md +++ b/docs/compiler/flatbuffers-idl.md @@ -49,9 +49,9 @@ translates them into Fory IR for code generation. | Situation | Recommended Path | | ------------------------------------------------------------------ | ---------------------- | -| You already have `.fbs` schemas and want Fory runtime/codegen | Use FlatBuffers input | +| You already have `.fbs` schemas and want Fory APIs/codegen | Use FlatBuffers input | | You are starting new schema work and want full Fory syntax control | Use native Fory IDL | -| You need FlatBuffers wire compatibility at runtime | Keep FlatBuffers stack | +| You need FlatBuffers wire compatibility | Keep FlatBuffers stack | | You need Fory object-graph semantics (`ref`, weak refs, etc.) | Use Fory | ## FlatBuffers to Fory Mapping @@ -62,7 +62,7 @@ translates them into Fory IR for code generation. - `include` entries map to Fory imports. - `table` is translated as `evolving=true`. - `struct` is translated as `evolving=false`. -- `root_type` is parsed but ignored by Fory runtime/codegen. +- `root_type` is parsed but ignored by Fory codegen. - `file_identifier` and `file_extension` are parsed but not used by Fory codegen. ### Field Numbering @@ -140,12 +140,12 @@ foryc api.fbs --java_out=./generated/java --python_out=./generated/python --grpc ``` Generated service code imports grpc APIs, so applications must provide grpc-java -or `grpcio` dependencies when they compile or run those files. The Fory runtime -packages do not add gRPC as a hard dependency. +or `grpcio` dependencies when they compile or run those files. Fory packages do +not add gRPC as a hard dependency. ### Defaults and Metadata -- FlatBuffers default values are parsed but not applied as Fory runtime defaults. +- FlatBuffers default values are parsed but not applied as Fory defaults. - Non-Fory metadata attributes are preserved as generic options in IR and may be consumed by downstream tooling. @@ -221,5 +221,5 @@ foryc schema.fbs --emit-fdl --emit-fdl-path ./translated ## Summary FlatBuffers input lets you reuse existing `.fbs` schemas while moving to Fory's -runtime and code generation model. This is useful for incremental adoption while -preserving schema investment and using Fory-native object APIs. +serialization and code generation model. This is useful for incremental adoption +while preserving schema investment and using Fory-native object APIs. diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md index 7ea245b481..567b9c57ff 100644 --- a/docs/compiler/generated-code.md +++ b/docs/compiler/generated-code.md @@ -186,7 +186,7 @@ public final class Animal extends Union { ### Schema Module Each JVM schema generates a `ForyModule`. Imported schema modules are installed -through `fory.register(...)`, so shared imports are deduplicated by the runtime. +through `fory.register(...)`, so shared imports are deduplicated by the Fory instance. ```java public final class AddressbookForyModule implements org.apache.fory.ForyModule { @@ -264,7 +264,7 @@ public final class AddressBookServiceGrpc { The generated marshaller serializes each request or response with the schema module's `ThreadSafeFory`. It uses grpc-java's `MethodDescriptor.Marshaller` API, so applications compiling these files must provide grpc-java dependencies. -Those dependencies are not added to Fory Java runtime artifacts. +Those dependencies are not added to Fory Java artifacts. ## Python @@ -407,7 +407,7 @@ Rust output is one module file per schema, for example: ### Type Generation Unions map to Rust enums with `#[fory(id = ...)]` schema case attributes. -`#[fory(unknown)] Unknown(::fory::UnknownCase)` marks the runtime +`#[fory(unknown)] Unknown(::fory::UnknownCase)` marks the Fory-provided forward-compatibility carrier. The marker only selects the carrier and does not add an entry to the schema case table; schema cases still use the full `0..N` ID range. A generated typed union must have at least one non-`Unknown` case. The @@ -803,7 +803,7 @@ public sealed partial class Person ``` Unions generate `[ForyUnion]` ADTs. `Unknown(UnknownCase)` is the -runtime-owned forward-compatibility carrier marked with `[ForyUnknownCase]`. +Fory-provided forward-compatibility carrier marked with `[ForyUnknownCase]`. The marker only selects the carrier and does not add an entry to the schema case table. Schema-defined cases use non-negative `[ForyCase]` IDs. If a case needs non-default schema encoding, the generated `[ForyCase]` carries `Type`. Known @@ -908,7 +908,7 @@ Swift output is one `.swift` file per schema, for example: The generator creates Swift models with split model macros and stable field/case IDs. A typed union must include `@ForyUnknownCase case unknown(UnknownCase)` and at least one non-`unknown` case; `unknown(UnknownCase)` is only the -runtime-owned forward-compatibility carrier. The marker only selects the carrier +Fory-provided forward-compatibility carrier. The marker only selects the carrier and does not add an entry to the schema case table. When package/namespace is non-empty, namespace shaping is controlled by `swift_namespace_style`: @@ -1221,7 +1221,7 @@ Generated Kotlin IDL sources express nullability with Kotlin `?`, not Fory construction cycles. Enums generate Kotlin enum classes with stable Fory enum IDs. Unions generate -sealed classes with `@ForyUnion`; the runtime-owned `Unknown(UnknownCase)` +sealed classes with `@ForyUnion`; the Fory-provided `Unknown(UnknownCase)` carrier is marked with `@ForyUnknownCase`. The marker only selects the carrier and does not add an entry to the schema case table. Schema-defined cases may use case IDs `0..N` and hold a single `value` property. A typed union must have at @@ -1262,9 +1262,9 @@ including nested positions. ### Schema Module Generated schema modules register schema types and resolve KSP-generated -serializers from the target class name. The package-owned helper runtime uses +serializers from the target class name. The package-owned helper Fory instance uses `ForyKotlin.builder().withXlang(true)` with the schema module installed, so message -`toBytes`/`fromBytes` helpers work without caller-managed runtime setup. For +`toBytes`/`fromBytes` helpers work without caller-managed Fory setup. For `addressbook.fdl`: ```kotlin @@ -1292,9 +1292,9 @@ not pass a serializer instance. ## Scala -The Scala target emits Scala 3 source only. The `fory-scala` runtime artifact -still supports Scala 2.13 and Scala 3, but generated IDL source and macro -derivation require Scala 3. +The Scala target emits Scala 3 source only. The `fory-scala` artifact still +supports Scala 2.13 and Scala 3, but generated IDL source and macro derivation +require Scala 3. ### Output Layout @@ -1369,7 +1369,7 @@ enum PhoneType { } ``` -Unions generate Scala 3 ADT enums. `Unknown(UnknownCase)` is the runtime-owned +Unions generate Scala 3 ADT enums. `Unknown(UnknownCase)` is the Fory-provided forward-compatibility carrier marked with `@ForyUnknownCase`. It is omitted from the schema case table because the marker only selects the carrier and does not add a schema entry. Schema-defined cases use non-negative `@ForyCase` IDs. @@ -1408,9 +1408,9 @@ use type-use annotations such as `List[Node @Ref]`. ### Schema Module Generated schema modules register schema serializers, enums, structs, and -unions. The package-owned helper runtime uses +unions. The package-owned helper Fory instance uses `ForyScala.builder().withXlang(true)` with the schema module installed, so -message `toBytes`/`fromBytes` helpers work without caller-managed runtime setup: +message `toBytes`/`fromBytes` helpers work without caller-managed Fory setup: ```scala object AddressbookForyModule extends org.apache.fory.ForyModule { diff --git a/docs/compiler/index.md b/docs/compiler/index.md index 5d97bb2d91..be9990e012 100644 --- a/docs/compiler/index.md +++ b/docs/compiler/index.md @@ -96,8 +96,7 @@ foryc animals.fdl --java_out=./generated/java --python_out=./generated/python -- The generated service code uses normal gRPC APIs, but request and response objects are serialized with Fory. Applications provide their own grpc-java or -`grpcio` dependencies; Fory runtime packages do not add gRPC as a hard -dependency. +`grpcio` dependencies; Fory packages do not add gRPC as a hard dependency. ## Why Fory IDL? @@ -105,7 +104,7 @@ dependency. Define your data model once in Fory IDL and generate consistent, type-safe code across all languages. This ensures: -- **Type Safety**: Catch type errors at compile time, not runtime +- **Type Safety**: Catch type errors at compile time, not when the code runs - **Consistency**: All languages use the same field names, types, and structures - **Documentation**: Schema serves as living documentation - **Evolution**: Managed schema changes across all implementations diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md index 59f4c63a77..a683f8cd23 100644 --- a/docs/compiler/protobuf-idl.md +++ b/docs/compiler/protobuf-idl.md @@ -319,8 +319,8 @@ foryc api.proto --java_out=./generated/java --python_out=./generated/python --gr Generated Java service files compile against grpc-java, and generated Python service modules import `grpc`. Add those dependencies in your application build; -Fory runtime packages do not add gRPC as a hard dependency. Protobuf `oneof` -fields are translated to Fory union fields inside request and response messages. +Fory packages do not add gRPC as a hard dependency. Protobuf `oneof` fields are +translated to Fory union fields inside request and response messages. Direct union RPC request or response types are not part of normal protobuf RPC syntax. diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md index 89705883b0..1823ee6cdd 100644 --- a/docs/compiler/schema-idl.md +++ b/docs/compiler/schema-idl.md @@ -888,8 +888,8 @@ message Person [id=100] { ### Rules - Case IDs must be non-negative and unique within the union -- Runtime unknown-case markers only select the carrier and do not add entries to - the schema case table +- Language-specific unknown-case markers only select the carrier and do not add + entries to the schema case table - Cases cannot be `optional` or `ref` - Union cases support field options for payload metadata, such as scalar encoding and collection element metadata @@ -1054,9 +1054,9 @@ message Node { | Go | `Parent Node` | `Parent *Node` with `fory:"ref"` | | Rust | `parent: Node` | `parent: Arc<Node>` | | C++ | `Node parent` | `std::shared_ptr<Node> parent` | -| C# | `Node parent` | `Node? parent` with runtime ref tracking | +| C# | `Node parent` | `Node? parent` with reference tracking | | JavaScript/TypeScript | `parent: Node` | `parent: Node` (no ref distinction) | -| Swift | `Node parent` | class reference with runtime ref tracking | +| Swift | `Node parent` | class reference with reference tracking | | Dart | `Node parent` | `Node parent` with `@ForyField(ref: true)` | | Scala | `parent: Node` | `@Ref parent: Node` | | Kotlin | `parent: Node` | `@Ref parent: Node?` | @@ -1161,7 +1161,7 @@ reference tracking, while `list<T>` and `array<T>` choose collection schema kind (see [Field Modifiers](#field-modifiers)). The compact tables in this section show common generated carriers. For the -complete 1.0 runtime surface, including C#, Swift, Dart, Scala, and Kotlin, see +complete 1.0 language support surface, including C#, Swift, Dart, Scala, and Kotlin, see the [xlang type-mapping specification](../specification/xlang_type_mapping.md). ### Primitive Types @@ -1187,7 +1187,7 @@ the [xlang type-mapping specification](../specification/xlang_type_mapping.md). | `timestamp` | Date and time with timezone | Variable | | `duration` | Duration | Variable | | `decimal` | Decimal value | Variable | -| `any` | Dynamic value (runtime type) | Variable | +| `any` | Dynamic value (concrete type) | Variable | #### Boolean @@ -1340,15 +1340,15 @@ Underscore spellings for integer encoding are not FDL type names. #### Any -| Language | Type | Notes | -| --------------------- | ---------------------------- | -------------------- | -| Java | `Object` | Runtime type written | -| Python | `Any` | Runtime type written | -| Go | `any` | Runtime type written | -| Rust | `Arc<dyn Any + Send + Sync>` | Runtime type written | -| C++ | `std::any` | Runtime type written | -| JavaScript/TypeScript | `any` | Runtime type written | -| Dart | `Object?` | Runtime type written | +| Language | Type | Notes | +| --------------------- | ---------------------------- | ------------------------------------ | +| Java | `Object` | Concrete value type metadata written | +| Python | `Any` | Concrete value type metadata written | +| Go | `any` | Concrete value type metadata written | +| Rust | `Arc<dyn Any + Send + Sync>` | Concrete value type metadata written | +| C++ | `std::any` | Concrete value type metadata written | +| JavaScript/TypeScript | `any` | Concrete value type metadata written | +| Dart | `Object?` | Concrete value type metadata written | **Example:** @@ -1383,12 +1383,12 @@ message Envelope [id=122] { **Notes:** - `any` always writes a null flag (same as `nullable`) because values may be empty. -- Allowed runtime values are limited to `bool`, `string`, `enum`, `message`, and `union`. +- Allowed dynamic values are limited to `bool`, `string`, `enum`, `message`, and `union`. Other primitives (numeric, bytes, date/time) and list/map are not supported; wrap them in a message or use explicit fields instead. - `ref` is not allowed on `any` fields (including list/map values). Wrap `any` in a message if you need reference tracking. -- The runtime type must be registered in the target language schema/IDL registration; unknown +- The concrete type must be registered in the target language schema/IDL registration; unknown types fail to deserialize. ### Named Types --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
