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 460cf357b11125a31c5ead42320bbaf3f6e3414a Author: chaokunyang <[email protected]> AuthorDate: Sat Feb 28 08:01:07 2026 +0000 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/' --- docs/compiler/compiler-guide.md | 39 +++++++++++++++++++-- docs/compiler/generated-code.md | 76 +++++++++++++++++++++++++++++++++++++++++ docs/compiler/index.md | 15 ++++---- docs/compiler/protobuf-idl.md | 15 ++++---- docs/compiler/schema-idl.md | 44 ++++++++++++++++++++++++ 5 files changed, 173 insertions(+), 16 deletions(-) diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md index 0457751d24..f58eaee0ca 100644 --- a/docs/compiler/compiler-guide.md +++ b/docs/compiler/compiler-guide.md @@ -64,10 +64,14 @@ Compile options: | `--go_out=DST_DIR` | Generate Go code in DST_DIR | (none) | | `--rust_out=DST_DIR` | Generate Rust code in DST_DIR | (none) | | `--csharp_out=DST_DIR` | Generate C# code in DST_DIR | (none) | +| `--swift_out=DST_DIR` | Generate Swift code in DST_DIR | (none) | | `--go_nested_type_style` | Go nested type naming: `camelcase` or `underscore` | `underscore` | +| `--swift_namespace_style` | Swift namespace style: `enum` or `flatten` | `enum` | | `--emit-fdl` | Emit translated FDL (for non-FDL inputs) | `false` | | `--emit-fdl-path` | Write translated FDL to this path (file or directory) | (stdout) | +For both `go_nested_type_style` and `swift_namespace_style`, schema-level file options are supported (`option ... = ...;`) and the CLI flag overrides the schema option when both are present. + Scan options (with `--scan-generated`): | Option | Description | Default | @@ -111,7 +115,7 @@ foryc schema.fdl **Compile for specific languages:** ```bash -foryc schema.fdl --lang java,python,csharp +foryc schema.fdl --lang java,python,csharp,swift ``` **Specify output directory:** @@ -158,7 +162,7 @@ foryc src/main.fdl -I libs/common,libs/types --proto_path third_party/ foryc schema.fdl --java_out=./src/main/java # Generate multiple languages to different directories -foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen --csharp_out=./csharp/gen +foryc schema.fdl --java_out=./java/gen --python_out=./python/src --go_out=./go/gen --csharp_out=./csharp/gen --swift_out=./swift/gen # Combine with import paths foryc schema.fdl --java_out=./gen/java -I proto/ -I common/ @@ -235,6 +239,7 @@ Compiling src/main.fdl... | Rust | `rust` | `.rs` | Structs with derive macros | | C++ | `cpp` | `.h` | Structs with FORY macros | | C# | `csharp` | `.cs` | Classes with Fory attributes | +| Swift | `swift` | `.swift` | `@ForyObject` Swift models | ## Output Structure @@ -319,6 +324,22 @@ generated/ - Imported schemas are registered transitively (for example `root.idl` importing `addressbook.fdl` and `tree.fdl`) +### Swift + +``` +generated/ +└── swift/ + └── addressbook/ + └── addressbook.swift +``` + +- Single `.swift` file per schema +- Package segments are mapped to nested Swift enums (for example `addressbook.*` -> `Addressbook.*`) +- Generated messages/unions/enums use `@ForyObject` and `@ForyField(id: ...)` +- Union types are generated as tagged enums with associated payload values +- Each schema includes `ForyRegistration` and `toBytes`/`fromBytes` helpers +- Imported schemas are registered transitively by generated registration helpers + ### C# IDL Matrix Verification Run the end-to-end C# IDL matrix (FDL/IDL/Proto/FBS generation plus roundtrip tests): @@ -339,6 +360,20 @@ This runner executes schema-consistent and compatible roundtrips across: - `root.idl` cross-package import coverage - evolving schema compatibility cases +### Swift IDL Matrix Verification + +Run the end-to-end Swift IDL matrix (FDL/IDL/Proto/FBS generation plus roundtrip tests): + +```bash +cd integration_tests/idl_tests +./run_swift_tests.sh +``` + +This runs: + +- local Swift IDL roundtrip tests in both compatible and schema-consistent 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. ## Build Integration diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md index 72225f4fdc..dcf9bce3b1 100644 --- a/docs/compiler/generated-code.md +++ b/docs/compiler/generated-code.md @@ -667,6 +667,8 @@ if err := f.RegisterNamedUnion(Holder{}, "myapp.models.Holder", fory.NewUnionSer option go_nested_type_style = "camelcase"; ``` +The CLI flag `--go_nested_type_style` overrides this schema option when both are set. + ### Usage ```go @@ -742,6 +744,78 @@ public static class AddressbookForyRegistration When explicit type IDs are not provided, generated registration uses computed numeric IDs (same behavior as other targets). +## Swift + +### Output Layout + +Swift output is one `.swift` file per schema, for example: + +- `<swift_out>/addressbook/addressbook.swift` + +### Type Generation + +The generator creates Swift models with `@ForyObject` and field IDs. + +When package/namespace is non-empty, namespace shaping is controlled by `swift_namespace_style`: + +- `enum` (default): nested enum namespace wrappers. +- `flatten`: package-derived prefix on top-level type names (for example `Demo_Foo_User`). + +When package/namespace is empty, no enum wrapper or flatten prefix is applied. + +For non-empty package with default `enum` style: + +```swift +public enum Addressbook { + @ForyObject + public enum Animal: Equatable { + @ForyField(id: 1) + case dog(Addressbook.Dog) + @ForyField(id: 2) + case cat(Addressbook.Cat) + } + + @ForyObject + public struct Person: Equatable { + @ForyField(id: 1) + public var name: String = "" + @ForyField(id: 8) + public var pet: Addressbook.Animal = .foryDefault() + } +} +``` + +For non-empty package with `flatten` style: + +```swift +@ForyObject +public struct Addressbook_Person: Equatable { ... } +``` + +The CLI flag `--swift_namespace_style` overrides schema option `swift_namespace_style` when both are set. + +Unions are generated as tagged Swift enums with associated payload values. +Messages with `ref`/`weak_ref` fields are generated as `final class` models to preserve reference semantics. + +### Registration + +Each schema includes a registration helper with transitive import registration: + +```swift +public enum ForyRegistration { + public static func register(_ fory: Fory) throws { + try ComplexPb.ForyRegistration.register(fory) + fory.register(Addressbook.Person.self, id: 100) + fory.register(Addressbook.Animal.self, id: 106) + } +} +``` + +With non-empty package and `flatten` style, the helper is prefixed too (for example `Addressbook_ForyRegistration`). + +For schemas without explicit `[id=...]`, registration uses computed numeric IDs. +If `option enable_auto_type_id = false;` is set, generated code uses name-based registration APIs. + ## Cross-Language Notes ### Type ID Behavior @@ -760,6 +834,7 @@ numeric IDs (same behavior as other targets). | C++ | `Person::PhoneNumber` | | Go | `Person_PhoneNumber` (default) | | C# | `Person.PhoneNumber` | +| Swift | `Person.PhoneNumber` | ### Byte Helper Naming @@ -771,3 +846,4 @@ numeric IDs (same behavior as other targets). | C++ | `to_bytes` / `from_bytes` | | Go | `ToBytes` / `FromBytes` | | C# | `ToBytes` / `FromBytes` | +| Swift | `toBytes` / `fromBytes` | diff --git a/docs/compiler/index.md b/docs/compiler/index.md index d6e8bb99be..63c0a0659d 100644 --- a/docs/compiler/index.md +++ b/docs/compiler/index.md @@ -21,7 +21,7 @@ license: | Fory IDL is a schema definition language for Apache Fory that enables type-safe cross-language serialization. Define your data structures once and generate -native data structure code for Java, Python, Go, Rust, C++, and C#. +native data structure code for Java, Python, Go, Rust, C++, C#, and Swift. ## Example Schema @@ -101,6 +101,7 @@ Generated code uses native language constructs: - Rust: Structs with `#[derive(ForyObject)]` - C++: Structs with `FORY_STRUCT` macros - C#: Classes with `[ForyObject]` and registration helpers +- Swift: `@ForyObject` models with `@ForyField` metadata and registration helpers ## Quick Start @@ -138,7 +139,7 @@ message Person { foryc example.fdl --output ./generated # Generate for specific languages -foryc example.fdl --lang java,python,csharp --output ./generated +foryc example.fdl --lang java,python,csharp,swift --output ./generated ``` ### 4. Use Generated Code @@ -193,11 +194,11 @@ message Example { Fory IDL types map to native types in each language: -| Fory IDL Type | Java | Python | Go | Rust | C++ | C# | -| ------------- | --------- | -------------- | -------- | -------- | ------------- | -------- | -| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` | `int` | -| `string` | `String` | `str` | `string` | `String` | `std::string` | `string` | -| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` | `bool` | +| Fory IDL Type | Java | Python | Go | Rust | C++ | C# | Swift | +| ------------- | --------- | -------------- | -------- | -------- | ------------- | -------- | -------- | +| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` | `int` | `Int32` | +| `string` | `String` | `str` | `string` | `String` | `std::string` | `string` | `String` | +| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool` | `bool` | `Bool` | See [Type System](schema-idl.md#type-system) for complete mappings. diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md index 8292a00f5e..f0dc62971b 100644 --- a/docs/compiler/protobuf-idl.md +++ b/docs/compiler/protobuf-idl.md @@ -207,13 +207,14 @@ message TreeNode { ### File-Level Options -| Option | Type | Description | -| ------------------------------------ | ------ | -------------------------------------------------------------- | -| `(fory).use_record_for_java_message` | bool | Generate Java records for all messages in this file | -| `(fory).polymorphism` | bool | Enable polymorphic serialization metadata by default | -| `(fory).enable_auto_type_id` | bool | Auto-generate type IDs when omitted (compiler default is true) | -| `(fory).evolving` | bool | Default schema-evolution behavior for messages | -| `(fory).go_nested_type_style` | string | Go nested naming style: `underscore` (default) or `camelcase` | +| Option | Type | Description | +| ------------------------------------ | ------ | -------------------------------------------------------------------------------------------- | +| `(fory).use_record_for_java_message` | bool | Generate Java records for all messages in this file | +| `(fory).polymorphism` | bool | Enable polymorphic serialization metadata by default | +| `(fory).enable_auto_type_id` | bool | Auto-generate type IDs when omitted (compiler default is true) | +| `(fory).evolving` | bool | Default schema-evolution behavior for messages | +| `(fory).go_nested_type_style` | string | Go nested naming style: `underscore` (default) or `camelcase` | +| `(fory).swift_namespace_style` | string | Swift namespace style: `enum` (default) or `flatten`; applies only when package is non-empty | ### Message and Enum Options diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md index eb9a96dc43..c66803be6b 100644 --- a/docs/compiler/schema-idl.md +++ b/docs/compiler/schema-idl.md @@ -171,6 +171,50 @@ message Payment { - Output path follows namespace segments (`MyCorp/Payment/V1/` under `--csharp_out`) - Type registration still uses the Fory IDL package (`payment`) for cross-language compatibility +### Go Nested Type Style Option + +Control Go naming for nested message/enum/union types: + +```protobuf +package payment; +option go_nested_type_style = "camelcase"; + +message Envelope { + message Payload { + string id = 1; + } +} +``` + +**Values:** + +- `underscore` (default): `Envelope_Payload` +- `camelcase`: `EnvelopePayload` + +The CLI flag `--go_nested_type_style` overrides this schema option when both are set. + +### Swift Namespace Style Option + +Control how package namespace is reflected in Swift generated type names: + +```protobuf +package payment.v1; +option swift_namespace_style = "flatten"; + +message Payment { + string id = 1; +} +``` + +**Values:** + +- `enum` (default): namespace wrappers (for example `Payment.V1.Payment`) +- `flatten`: package prefix on top-level types (for example `Payment_V1_Payment`) + +**Important:** namespace wrapper/prefixing is only applied when package is non-empty. If package is empty, Swift emits top-level types directly for both styles. + +The CLI flag `--swift_namespace_style` overrides this schema option when both are set. + ### Java Outer Classname Option Generate all types as inner classes of a single outer wrapper class: --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
