This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch update_docs in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 023972638cd190feecd50f5a54c71bc5c535e8e6 Author: chaokunyang <[email protected]> AuthorDate: Tue Aug 4 10:47:02 2026 +0800 docs: consolidate overview guides --- .../object-serialization/xlang/swift/README.md | 4 +- docs/community/how_to_release.md | 2 +- docs/development/building.md | 135 --------------------- docs/development/index.md | 120 +++++++++++++++++- docs/grpc/architecture.md | 41 ------- docs/grpc/index.md | 47 ++++++- docs/grpc/interoperability.md | 41 ------- docs/introduction/choose-a-format.md | 25 +++- docs/introduction/product-model.md | 47 ------- docs/introduction/support-matrix.md | 6 +- docs/object-serialization/java/index.md | 2 +- docs/object-serialization/runtimes.md | 2 +- docs/start/index.md | 2 +- docs/start/swift.md | 2 +- .../current/community/how_to_release.md | 2 +- .../current/development/building.md | 134 -------------------- .../current/development/index.md | 119 +++++++++++++++++- .../current/grpc/architecture.md | 35 ------ .../current/grpc/index.md | 38 +++++- .../current/grpc/interoperability.md | 39 ------ .../current/introduction/choose-a-format.md | 22 +++- .../current/introduction/support-matrix.md | 4 +- .../current/object-serialization/java/index.md | 2 +- .../current/object-serialization/runtimes.md | 2 +- .../current/start/index.md | 18 +-- .../current/start/swift.md | 2 +- 26 files changed, 371 insertions(+), 522 deletions(-) diff --git a/docs/benchmarks/object-serialization/xlang/swift/README.md b/docs/benchmarks/object-serialization/xlang/swift/README.md index f3322f902b..91d4568221 100644 --- a/docs/benchmarks/object-serialization/xlang/swift/README.md +++ b/docs/benchmarks/object-serialization/xlang/swift/README.md @@ -2,11 +2,11 @@ This benchmark compares serialization and deserialization throughput for Apache Fory, Protocol Buffers, and JSON in Swift. -## Benchmark Products +## Benchmark Executables The ordinary/xlang cases are built by `swift-benchmark`. External-type and carrier comparisons are built by the separate `swift-external-benchmark` -product, so building the ordinary product does not compile those models or +executable, so building the ordinary executable does not compile those models or serializer specializations. ## Throughput Plot diff --git a/docs/community/how_to_release.md b/docs/community/how_to_release.md index ddefad8b1a..6b34c3e13b 100644 --- a/docs/community/how_to_release.md +++ b/docs/community/how_to_release.md @@ -446,7 +446,7 @@ To learn more about Fory, please see https://fory.apache.org/ [ ] No compiled archives bundled in source archive. [ ] Can compile from source. -How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/development/building.md +How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/development/index.md Thanks, diff --git a/docs/development/building.md b/docs/development/building.md deleted file mode 100644 index 4e6bb13846..0000000000 --- a/docs/development/building.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Development -sidebar_position: 20 -id: building -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---- - -## How to build Apache Fory™ - -Clone the source tree from https://github.com/apache/fory. - -### Build Apache Fory™ Java - -```bash -cd java -mvn -T16 package -``` - -#### Environment Requirements - -- JDK 17+ -- Maven 3.6.3+ - -### Build Apache Fory™ Python - -```bash -cd python -pip install -v -e . - -# Optional: build Cython extension (replace X.Y with your Python version) -bazel build //:cp_fory_so --@rules_python//python/config_settings:python_version=X.Y -``` - -#### Environment Requirements - -- CPython 3.8+ -- Bazel 8+ (required when building Cython extensions) - -### Build Apache Fory™ C++ - -```bash -cd cpp -bazel build //cpp/... -``` - -#### Environment Requirements - -- C++17 compiler -- Bazel 8+ - -### Build Apache Fory™ Go - -```bash -cd go/fory -go test -v ./... -``` - -Run Go xlang tests from Java test module: - -```bash -cd java -mvn -T16 install -DskipTests -cd fory-core -FORY_GO_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn test -Dtest=org.apache.fory.xlang.GoXlangTest -``` - -#### Environment Requirements - -- Go 1.24+ - -### Build Apache Fory™ Rust - -```bash -cd rust -cargo build -cargo test --features tests - -# Debug a specific test -RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 ENABLE_FORY_DEBUG_OUTPUT=1 \ - cargo test --test mod $dir$::$test_file::$test_method -- --nocapture -``` - -#### Environment Requirements - -- Rust toolchain via rustup -- `cargo-expand` (optional, for macro expansion debugging) - -### Build Apache Fory™ JavaScript - -```bash -cd javascript -npm install - -npm run build -node ./node_modules/.bin/jest --ci --reporters=default --reporters=jest-junit -``` - -#### Environment Requirements - -- Node.js (LTS) -- npm - -### Lint Markdown Docs - -```bash -cd docs -npx prettier --write "**/*.md" -``` - -#### Environment Requirements - -- Node.js (LTS) -- npm - -## Contributing - -For contribution details, see [How to contribute to Apache Fory™](https://github.com/apache/fory/blob/main/CONTRIBUTING.md). -For AI-assisted contributions, follow the -[AI Contribution Policy](https://github.com/apache/fory/blob/main/AI_POLICY.md), including the -required self-review, two-reviewer AI review loop, disclosure, and verification evidence for -substantial AI assistance. diff --git a/docs/development/index.md b/docs/development/index.md index 7044b921de..aea0a3e778 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -22,11 +22,123 @@ license: | Contributor documentation covers repository setup, builds, tests, debugging, and release-oriented workflows. It is separate from the user guides for released artifacts. -## Start here +## Build and Test -- [Build and test the repository](building.md) -- [Debug the C++ implementation](cpp-debugging.md) -- [Contributing guide](https://github.com/apache/fory/blob/main/CONTRIBUTING.md) +Clone the source tree from https://github.com/apache/fory. + +### Java + +```bash +cd java +mvn -T16 package +``` + +Requirements: + +- JDK 17+ +- Maven 3.6.3+ + +### Python + +```bash +cd python +pip install -v -e . + +# Optional: build Cython extension (replace X.Y with your Python version) +bazel build //:cp_fory_so --@rules_python//python/config_settings:python_version=X.Y +``` + +Requirements: + +- CPython 3.8+ +- Bazel 8+ (required when building Cython extensions) + +### C++ + +```bash +cd cpp +bazel build //cpp/... +``` + +Requirements: + +- C++17 compiler +- Bazel 8+ + +### Go + +```bash +cd go/fory +go test -v ./... +``` + +Run Go xlang tests from the Java test module: + +```bash +cd java +mvn -T16 install -DskipTests +cd fory-core +FORY_GO_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn test -Dtest=org.apache.fory.xlang.GoXlangTest +``` + +Requirement: Go 1.24+. + +### Rust + +```bash +cd rust +cargo build +cargo test --features tests + +# Debug a specific test +RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 ENABLE_FORY_DEBUG_OUTPUT=1 \ + cargo test --test mod $dir$::$test_file::$test_method -- --nocapture +``` + +Requirements: + +- Rust toolchain via rustup +- `cargo-expand` (optional, for macro expansion debugging) + +### JavaScript + +```bash +cd javascript +npm install + +npm run build +node ./node_modules/.bin/jest --ci --reporters=default --reporters=jest-junit +``` + +Requirements: + +- Node.js (LTS) +- npm + +### Markdown + +```bash +cd docs +npx prettier --write "**/*.md" +``` + +Requirements: + +- Node.js (LTS) +- npm + +## Debugging + +See [Debugging C++](cpp-debugging.md) for the repository's VS Code, Bazel, LLDB, and GDB setup. Runtime-specific contributor instructions remain in each runtime's source tree and contributor README when they are not part of the shared repository build. + +## Contributing + +For contribution details, see +[How to contribute to Apache Fory™](https://github.com/apache/fory/blob/main/CONTRIBUTING.md). +For AI-assisted contributions, follow the +[AI Contribution Policy](https://github.com/apache/fory/blob/main/AI_POLICY.md), including the +required self-review, two-reviewer AI review loop, disclosure, and verification evidence for +substantial AI assistance. diff --git a/docs/grpc/architecture.md b/docs/grpc/architecture.md deleted file mode 100644 index ffe4c30162..0000000000 --- a/docs/grpc/architecture.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Architecture -sidebar_position: 2 -id: architecture -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---- - -Generated service companions use normal gRPC servers, channels, method descriptors, deadlines, -status codes, interceptors, and streaming APIs. Fory-generated marshallers encode and decode the -generated request and response models. - -## Ownership boundary - -Fory can generate service companions for application-provided gRPC runtimes. -Those companions provide Fory serialization for request and response objects; -the application and gRPC stack still own listeners, channels, credentials, -authentication, authorization, deadlines, retries, and transport lifecycle. - -Fory packages do not add a gRPC implementation as a hard dependency. The application selects and -configures the runtime's gRPC libraries. - -## Generated service surface - -The compiler emits runtime-idiomatic service bases, clients or stubs, method metadata, and Fory -marshallers. Model generation is documented under -[Generated Code](../compiler/generated-code/index.md); the runtime pages document server and client -integration. diff --git a/docs/grpc/index.md b/docs/grpc/index.md index 5e019a79ff..6fef383aee 100644 --- a/docs/grpc/index.md +++ b/docs/grpc/index.md @@ -54,8 +54,52 @@ generation with `--grpc-python-mode=sync`. JavaScript uses `@grpc/grpc-js` for Node.js; browser clients are generated separately with `--grpc-web` and use `grpc-web`. +## Architecture + +Generated service companions use normal gRPC servers, channels, method descriptors, deadlines, +status codes, interceptors, and streaming APIs. Fory-generated marshallers encode and decode the +generated request and response models. + +### Ownership Boundary + +Fory can generate service companions for application-provided gRPC runtimes. Those companions +provide Fory serialization for request and response objects; the application and gRPC stack still +own listeners, channels, credentials, authentication, authorization, deadlines, retries, and +transport lifecycle. + +Fory packages do not add a gRPC implementation as a hard dependency. The application selects and +configures the runtime's gRPC libraries. + +### Generated Service Surface + +The compiler emits runtime-idiomatic service bases, clients or stubs, method metadata, and Fory +marshallers. Model generation is documented under +[Generated Code](../compiler/generated-code/index.md); the runtime pages document server and client +integration. + +## Interoperability + +Fory gRPC peers interoperate only when they use the same generated service contract, matching Fory +type identities, and compatible generated model schemas. + +### Protocol Boundary + +The transport is gRPC, but the message bytes are Fory payloads. Generic protobuf clients and server +reflection tools cannot decode those payloads as protobuf messages. Generate every peer through a +supported Fory compiler frontend. + +### Verification + +Test at least one unary call and every streaming shape used by the service. A protobuf +`UNIMPLEMENTED` or decode failure usually means the peer used an ordinary protobuf stub or a +different generated service contract. + ## Runtime Guides +Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Dart, Scala, and Kotlin have documented gRPC +companions. Use the [support matrix](../introduction/support-matrix.md) and the selected runtime page +for current dependencies and streaming support. + | Runtime | Guide | | --------------------- | ------------------------------------- | | Java | [Java](java.md) | @@ -68,6 +112,3 @@ Node.js; browser clients are generated separately with `--grpc-web` and use | Dart | [Dart](dart.md) | | Scala | [Scala](scala.md) | | Kotlin | [Kotlin](kotlin.md) | - -See [Architecture](architecture.md) for payload and transport ownership and -[Interoperability](interoperability.md) for peer compatibility. diff --git a/docs/grpc/interoperability.md b/docs/grpc/interoperability.md deleted file mode 100644 index 1de36c4885..0000000000 --- a/docs/grpc/interoperability.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Interoperability -sidebar_position: 3 -id: interoperability -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---- - -Fory gRPC peers interoperate only when they use the same generated service contract, matching Fory -type identities, and compatible generated model schemas. - -## Protocol boundary - -The transport is gRPC, but the message bytes are Fory payloads. Generic protobuf clients and server -reflection tools cannot decode those payloads as protobuf messages. Generate every peer through a -supported Fory compiler frontend. - -## Supported generated companions - -Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Dart, Scala, and Kotlin have documented gRPC -companions. Use the [support matrix](../introduction/support-matrix.md) and the selected runtime page -for current dependencies and streaming support. - -## Verification - -Test at least one unary call and every streaming shape used by the service. A protobuf -`UNIMPLEMENTED` or decode failure usually means the peer used an ordinary protobuf stub or a -different generated service contract. diff --git a/docs/introduction/choose-a-format.md b/docs/introduction/choose-a-format.md index 0d7225c6a4..75cee3efce 100644 --- a/docs/introduction/choose-a-format.md +++ b/docs/introduction/choose-a-format.md @@ -19,12 +19,16 @@ license: | limitations under the License. --- -| Format | Use it when | Start here | -| ------------- | ------------------------------------------------------------- | -------------------------------------------------------------- | -| Xlang binary | Data crosses language boundaries | [Cross-language guide](../object-serialization/xlang/index.md) | -| Native binary | Producer and consumer are in the same language | Language guide | -| Row format | You need random field access or analytics-style partial reads | [Row format spec](../row-format/index.md) | -| Fory JSON | Java applications need high-performance standard JSON | [Fory JSON guide](../json/index.md) | +| Format or mode | Data model | Use it when | Interoperability | Start here | +| -------------- | ------------------------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------- | +| Xlang binary | Portable object graphs | Data crosses language boundaries | Shared wire format across supported runtimes | [Cross-language guide](../object-serialization/xlang/index.md) | +| Native binary | Runtime-native object graphs | Producer and consumer use the same language | Same runtime family only | [Object Serialization](../object-serialization/index.md) | +| Row Format | Random-access binary rows | You need random field access or analytics-style partial reads | Standard Row is shared by Java, Python, C++, and Rust; Compact is Java-only | [Row Format guide](../row-format/index.md) | +| Fory JSON | Standard JSON mapped to Java objects | Java applications need high-performance standard JSON | Standard JSON text | [Fory JSON guide](../json/index.md) | + +Xlang and native are sibling modes of Object Serialization. Use them when the receiver needs to +reconstruct an object graph. Row Format and Fory JSON are separate formats, not additional Object +Serialization modes. For Java, Scala, Kotlin, Python, C++, Go, and Rust, use native mode for same-language traffic. It avoids xlang's cross-language type mapping and @@ -59,3 +63,12 @@ Choose xlang or native mode when you need to reconstruct object graphs. Choose R trusted analytical data that benefits from random field access. Choose Fory JSON for standard JSON in Java applications. Use Fory IDL and the compiler when multiple teams need one schema-first contract; it generates models that use the relevant Fory capability. + +## Related capabilities + +[Fory IDL and the compiler](../compiler/index.md) generate native models for supported runtimes. +Service definitions can also generate [Fory gRPC](../grpc/index.md) code. Neither capability defines +another serialization format. + +Protocol implementers should follow the normative format documentation under +[Specifications](../specification/xlang_serialization_spec.md). diff --git a/docs/introduction/product-model.md b/docs/introduction/product-model.md deleted file mode 100644 index 3379dd6b52..0000000000 --- a/docs/introduction/product-model.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Product Model -sidebar_position: 3 -id: product-model -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---- - -Apache Fory exposes three serialization products and one schema toolchain. Start from the data -contract you need, then choose a runtime API. - -## Serialization products - -| Product | Data model | Interoperability boundary | -| ---------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------- | -| Binary Object Serialization: xlang mode | Portable object graphs | Shared wire format across supported runtimes | -| Binary Object Serialization: native mode | Runtime-native object graphs | Same runtime family only | -| Row Format | Random-access binary rows | Standard Row is shared by Java, Python, C++, and Rust; Compact Row is Java-only | -| Fory JSON | Standard JSON mapped to Java objects | Java API with text interoperability | - -Xlang and native are sibling modes of Binary Object Serialization. Row Format and Fory JSON are -separate products; neither is a third object-serialization mode. - -## Schema and services - -[Fory IDL and the compiler](../compiler/index.md) generate native models for supported runtimes. -Service definitions can also generate [Fory gRPC](../grpc/index.md) companions. The compiler and -gRPC integration do not define additional serialization formats. - -## Normative formats - -Protocol implementers should use the unchanged [Specification](../specification/xlang_serialization_spec.md) -surface. User guides explain tasks and link to the exact specification instead of duplicating its -wire-level rules. diff --git a/docs/introduction/support-matrix.md b/docs/introduction/support-matrix.md index 5127bd48fb..7fee55a395 100644 --- a/docs/introduction/support-matrix.md +++ b/docs/introduction/support-matrix.md @@ -20,7 +20,7 @@ license: | --- Use this matrix to confirm the documented API surface before choosing a capability. A runtime page -does not imply support for every Fory product. +does not imply support for every Fory capability. | Capability | Documented runtimes | Interoperability | | --------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------- | @@ -33,5 +33,5 @@ does not imply support for every Fory product. | Fory gRPC | Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Dart, Scala, Kotlin | Peers must use matching generated Fory service contracts | Platform constraints such as [Android](../object-serialization/java/android.md) and -[GraalVM Native Image](../object-serialization/java/graalvm.md) are documented by the owning Java -object-serialization and Fory JSON products. +[GraalVM Native Image](../object-serialization/java/graalvm.md) are documented in the Java Object +Serialization and Fory JSON guides. diff --git a/docs/object-serialization/java/index.md b/docs/object-serialization/java/index.md index 88a69b87ef..ea3a0f3d9a 100644 --- a/docs/object-serialization/java/index.md +++ b/docs/object-serialization/java/index.md @@ -22,7 +22,7 @@ license: | Apache Fory Java provides high-performance binary object serialization. Use xlang mode for payloads shared with other supported runtimes and native mode for Java/JVM-only object graphs. -This runtime guide is scoped to Binary Object Serialization. For other Java products, use +This runtime guide is scoped to Binary Object Serialization. For other Java capabilities, use [Row Format](../../row-format/java.md), [Fory JSON](../../json/index.md), [Fory IDL and compiler](../../compiler/index.md), or [Fory gRPC](../../grpc/java.md). diff --git a/docs/object-serialization/runtimes.md b/docs/object-serialization/runtimes.md index c820c929d9..491608e543 100644 --- a/docs/object-serialization/runtimes.md +++ b/docs/object-serialization/runtimes.md @@ -21,7 +21,7 @@ license: | Choose the runtime whose API your application uses. Runtime documentation is scoped to binary object serialization; Row Format, Fory JSON, compiler, and gRPC pages remain with -their product owners. +their respective capability guides. | Runtime | Modes | Documentation | | --------------------- | -------------------- | ------------------------------------------------------ | diff --git a/docs/start/index.md b/docs/start/index.md index 3575ff456a..898a0e86a7 100644 --- a/docs/start/index.md +++ b/docs/start/index.md @@ -68,4 +68,4 @@ round trip for an application project, and the next capability-specific steps: Object Serialization uses xlang mode for portable cross-language data. Java, Python, C++, Go, Rust, Scala, and Kotlin also offer native mode for same-runtime data. Use [Choose a Format](../introduction/choose-a-format.md) -when the product choice is not yet clear. +when you have not yet chosen a format. diff --git a/docs/start/swift.md b/docs/start/swift.md index 7118e7d9c7..4c086bdd89 100644 --- a/docs/start/swift.md +++ b/docs/start/swift.md @@ -37,7 +37,7 @@ Create an executable package: swift package init --type executable --name ForyExample ``` -Add the released package and `Fory` product to the generated `Package.swift`: +Add the released package and depend on its `Fory` library in the generated `Package.swift`: ```swift title="Package.swift" dependencies: [ diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/community/how_to_release.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/community/how_to_release.md index 4c4acc258c..227d59f5f5 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/community/how_to_release.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/community/how_to_release.md @@ -428,7 +428,7 @@ To learn more about Fory, please see https://fory.apache.org/ [ ] No compiled archives bundled in source archive. [ ] Can compile from source. -How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/development/building.md +How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/development/index.md Thanks, diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/building.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/building.md deleted file mode 100644 index b7e336c288..0000000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/building.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: 开发 -sidebar_position: 20 -id: building -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---- - -## 如何构建 Apache Fory™ - -从 https://github.com/apache/fory 克隆源代码树。 - -### 构建 Apache Fory™ Java - -```bash -cd java -mvn -T16 package -``` - -#### 环境要求 - -- JDK 17+ -- Maven 3.6.3+ - -### 构建 Apache Fory™ Python - -```bash -cd python -pip install -v -e . - -# Optional: build Cython extension (replace X.Y with your Python version) -bazel build //:cp_fory_so --@rules_python//python/config_settings:python_version=X.Y -``` - -#### 环境要求 - -- CPython 3.8+ -- Bazel 8+(构建 Cython 扩展时必需) - -### 构建 Apache Fory™ C++ - -```bash -cd cpp -bazel build //cpp/... -``` - -#### 环境要求 - -- C++17 编译器 -- Bazel 8+ - -### 构建 Apache Fory™ Go - -```bash -cd go/fory -go test -v ./... -``` - -从 Java 测试模块运行 Go xlang 测试: - -```bash -cd java -mvn -T16 install -DskipTests -cd fory-core -FORY_GO_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn test -Dtest=org.apache.fory.xlang.GoXlangTest -``` - -#### 环境要求 - -- Go 1.24+ - -### 构建 Apache Fory™ Rust - -```bash -cd rust -cargo build -cargo test --features tests - -# Debug a specific test -RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 ENABLE_FORY_DEBUG_OUTPUT=1 \ - cargo test --test mod $dir$::$test_file::$test_method -- --nocapture -``` - -#### 环境要求 - -- 通过 rustup 安装的 Rust 工具链 -- `cargo-expand`(可选,用于调试宏展开) - -### 构建 Apache Fory™ JavaScript - -```bash -cd javascript -npm install - -npm run build -node ./node_modules/.bin/jest --ci --reporters=default --reporters=jest-junit -``` - -#### 环境要求 - -- Node.js (LTS) -- npm - -### 检查 Markdown 文档 - -```bash -cd docs -npx prettier --write "**/*.md" -``` - -#### 环境要求 - -- Node.js (LTS) -- npm - -## 参与贡献 - -有关贡献的详细信息,请参阅[如何为 Apache Fory™ 做贡献](https://github.com/apache/fory/blob/main/CONTRIBUTING.md)。 -对于 AI 辅助的贡献,请遵循 -[AI 贡献政策](https://github.com/apache/fory/blob/main/AI_POLICY.md),包括大量使用 AI 辅助时 -所需的自我审查、双审查者 AI 审查流程、披露和验证证据。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/index.md index 9e547b6e14..70933815a9 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/development/index.md @@ -22,11 +22,122 @@ license: | 贡献者文档涵盖仓库设置、构建、测试、调试和面向发布的工作流程。 这部分文档与已发布构件的用户指南相互独立。 -## 从这里开始 +## 构建与测试 -- [构建并测试仓库](building.md) -- [调试 C++ 实现](cpp-debugging.md) -- [贡献指南](https://github.com/apache/fory/blob/main/CONTRIBUTING.md) +从 https://github.com/apache/fory 克隆源代码树。 + +### Java + +```bash +cd java +mvn -T16 package +``` + +环境要求: + +- JDK 17+ +- Maven 3.6.3+ + +### Python + +```bash +cd python +pip install -v -e . + +# Optional: build Cython extension (replace X.Y with your Python version) +bazel build //:cp_fory_so --@rules_python//python/config_settings:python_version=X.Y +``` + +环境要求: + +- CPython 3.8+ +- Bazel 8+(构建 Cython 扩展时必需) + +### C++ + +```bash +cd cpp +bazel build //cpp/... +``` + +环境要求: + +- C++17 编译器 +- Bazel 8+ + +### Go + +```bash +cd go/fory +go test -v ./... +``` + +从 Java 测试模块运行 Go xlang 测试: + +```bash +cd java +mvn -T16 install -DskipTests +cd fory-core +FORY_GO_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn test -Dtest=org.apache.fory.xlang.GoXlangTest +``` + +环境要求:Go 1.24+。 + +### Rust + +```bash +cd rust +cargo build +cargo test --features tests + +# Debug a specific test +RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 ENABLE_FORY_DEBUG_OUTPUT=1 \ + cargo test --test mod $dir$::$test_file::$test_method -- --nocapture +``` + +环境要求: + +- 通过 rustup 安装的 Rust 工具链 +- `cargo-expand`(可选,用于调试宏展开) + +### JavaScript + +```bash +cd javascript +npm install + +npm run build +node ./node_modules/.bin/jest --ci --reporters=default --reporters=jest-junit +``` + +环境要求: + +- Node.js (LTS) +- npm + +### Markdown + +```bash +cd docs +npx prettier --write "**/*.md" +``` + +环境要求: + +- Node.js (LTS) +- npm + +## 调试 + +仓库中的 VS Code、Bazel、LLDB 和 GDB 配置请参阅[调试 C++](cpp-debugging.md)。 不属于共享仓库构建的运行时特定贡献者说明,仍保留在各运行时的源代码树和贡献者 README 中。 + +## 参与贡献 + +有关贡献的详细信息,请参阅 +[如何为 Apache Fory™ 做贡献](https://github.com/apache/fory/blob/main/CONTRIBUTING.md)。 +对于 AI 辅助的贡献,请遵循 +[AI 贡献政策](https://github.com/apache/fory/blob/main/AI_POLICY.md),包括大量使用 AI 辅助时 +所需的自我审查、双审查者 AI 审查流程、披露和验证证据。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/architecture.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/architecture.md deleted file mode 100644 index 9e2b817e1e..0000000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/architecture.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: 架构 -sidebar_position: 2 -id: architecture -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---- - -生成的服务配套代码使用标准 gRPC server、channel、方法描述符、deadline、状态码、interceptor -和流式 API。Fory 生成的 marshaller 负责对生成的请求和响应模型进行编码和解码。 - -## 职责边界 - -Fory 可以为应用提供的 gRPC 运行时生成服务配套代码。这些代码为请求和响应对象提供 Fory 序列化; -listener、channel、credential、身份认证、授权、deadline、重试和传输生命周期仍由应用和 gRPC 技术栈负责。 - -Fory 软件包不会将某个 gRPC 实现作为强制依赖。应用负责选择和配置运行时的 gRPC 库。 - -## 生成的服务接口 - -编译器会生成符合运行时习惯的 service base、client 或 stub、方法元数据和 Fory marshaller。 -模型生成详见[生成代码](../compiler/generated-code/index.md);各运行时页面介绍 server 与 client 集成。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/index.md index 0d7538b872..9b76910dd0 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/index.md @@ -51,8 +51,44 @@ Python 默认生成异步 `grpc.aio` 配套代码,并支持通过 `--grpc-pyth JavaScript 在 Node.js 中使用 `@grpc/grpc-js`;浏览器客户端通过 `--grpc-web` 单独生成, 并使用 `grpc-web`。 +## 架构 + +生成的服务配套代码使用标准 gRPC server、channel、方法描述符、deadline、状态码、interceptor +和流式 API。Fory 生成的 marshaller 负责对生成的请求和响应模型进行编码和解码。 + +### 职责边界 + +Fory 可以为应用提供的 gRPC 运行时生成服务配套代码。这些代码为请求和响应对象提供 Fory 序列化; +listener、channel、credential、身份认证、授权、deadline、重试和传输生命周期仍由应用和 gRPC 技术栈负责。 + +Fory 软件包不会将某个 gRPC 实现作为强制依赖。应用负责选择和配置运行时的 gRPC 库。 + +### 生成的服务接口 + +编译器会生成符合运行时习惯的 service base、client 或 stub、方法元数据和 Fory marshaller。 +模型生成详见[生成代码](../compiler/generated-code/index.md);各运行时页面介绍 server 与 client 集成。 + +## 互操作性 + +只有使用同一份生成服务契约、匹配的 Fory 类型标识以及兼容的生成模型 Schema,Fory gRPC 对端 +才能互操作。 + +### 协议边界 + +传输协议是 gRPC,但消息字节是 Fory 载荷。通用 protobuf 客户端和 server reflection 工具无法将 +这些载荷解码为 protobuf 消息。每个对端都必须通过受支持的 Fory 编译器前端生成。 + +### 验证 + +至少测试一个一元调用,以及服务使用的每种流式调用形式。protobuf `UNIMPLEMENTED` 或解码失败 +通常表示对端使用了普通 protobuf stub,或使用了不同的生成服务契约。 + ## 运行时指南 +Java、Python、C++、Go、Rust、JavaScript/TypeScript、C#、Dart、Scala 和 Kotlin 均有相应的 +gRPC 配套代码文档。当前依赖和流式调用支持请参阅[支持矩阵](../introduction/support-matrix.md) +以及所选运行时页面。 + | 运行时 | 指南 | | --------------------- | ------------------------------------ | | Java | [Java](java.md) | @@ -65,5 +101,3 @@ JavaScript 在 Node.js 中使用 `@grpc/grpc-js`;浏览器客户端通过 `--g | Dart | [Dart](dart.md) | | Scala | [Scala](scala.md) | | Kotlin | [Kotlin](kotlin.md) | - -载荷和传输的职责边界请参阅[架构](architecture.md),对端兼容性请参阅[互操作性](interoperability.md)。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/interoperability.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/interoperability.md deleted file mode 100644 index 5d1f4d9300..0000000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/grpc/interoperability.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: 互操作性 -sidebar_position: 3 -id: interoperability -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---- - -只有使用同一份生成服务契约、匹配的 Fory 类型标识以及兼容的生成模型 Schema,Fory gRPC 对端 -才能互操作。 - -## 协议边界 - -传输协议是 gRPC,但消息字节是 Fory 载荷。通用 protobuf 客户端和 server reflection 工具无法将 -这些载荷解码为 protobuf 消息。每个对端都必须通过受支持的 Fory 编译器前端生成。 - -## 支持的生成配套代码 - -Java、Python、C++、Go、Rust、JavaScript/TypeScript、C#、Dart、Scala 和 Kotlin 均有相应的 -gRPC 配套代码文档。当前依赖和流式调用支持请参阅[支持矩阵](../introduction/support-matrix.md) -以及所选运行时页面。 - -## 验证 - -至少测试一个一元调用,以及服务使用的每种流式调用形式。protobuf `UNIMPLEMENTED` 或解码失败 -通常表示对端使用了普通 protobuf stub,或使用了不同的生成服务契约。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/choose-a-format.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/choose-a-format.md index 30f64384f5..b27548b2d6 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/choose-a-format.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/choose-a-format.md @@ -19,12 +19,15 @@ license: | limitations under the License. --- -| 格式 | 适用场景 | 入门文档 | -| ------------- | ------------------------------------ | ---------------------------------------------------- | -| Xlang 二进制 | 数据需要跨语言传输 | [跨语言指南](../object-serialization/xlang/index.md) | -| Native 二进制 | 生产端和消费端使用同一种语言 | 相应语言指南 | -| Row Format | 需要随机字段访问或分析场景的部分读取 | [Row Format 规范](../row-format/index.md) | -| Fory JSON | Java 应用需要高性能标准 JSON | [Fory JSON 指南](../json/index.md) | +| 格式或模式 | 数据模型 | 适用场景 | 互操作范围 | 入门文档 | +| ------------- | --------------------------- | ------------------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------- | +| Xlang 二进制 | 可移植对象图 | 数据需要跨语言传输 | 支持的运行时共享同一种线格式 | [跨语言指南](../object-serialization/xlang/index.md) | +| Native 二进制 | 运行时原生对象图 | 生产端和消费端使用同一种语言 | 仅限同一运行时家族 | [对象序列化](../object-serialization/index.md) | +| Row Format | 可随机访问的二进制行 | 需要随机字段访问或分析场景的部分读取 | Standard Row 由 Java、Python、C++ 和 Rust 共享;Compact 仅支持 Java | [Row Format 指南](../row-format/index.md) | +| Fory JSON | 映射到 Java 对象的标准 JSON | Java 应用需要高性能标准 JSON | 标准 JSON 文本 | [Fory JSON 指南](../json/index.md) | + +Xlang 和 native 是对象序列化的两种并列模式,适用于接收端需要重建对象图的场景。Row Format +和 Fory JSON 是独立格式,不是额外的对象序列化模式。 对于 Java、Scala、Kotlin、Python、C++、Go 和 Rust,同语言通信应使用 native 模式。它避开 xlang 的跨语言类型映射和元数据限制,更贴近各语言的原生类型系统,并支持更丰富的语言特定 @@ -51,3 +54,10 @@ pickle 和 cloudpickle。 需要重建对象图时选择 xlang 或 native 模式。对于可信的分析数据,如果随机字段访问能带来 收益,请选择 Row Format。Java 应用需要标准 JSON 时选择 Fory JSON。多个团队需要统一的 Schema 优先契约时,请使用 Fory IDL 和编译器;它会生成使用相应 Fory 能力的模型。 + +## 相关能力 + +[Fory IDL 和编译器](../compiler/index.md)可以为支持的运行时生成原生模型。服务定义还可以生成 +[Fory gRPC](../grpc/index.md)代码。这两项能力都不会定义新的序列化格式。 + +协议实现者应遵循 [Specifications](../specification/xlang_serialization_spec.md) 中的规范性格式文档。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/support-matrix.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/support-matrix.md index d2245f59cd..91c44820b7 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/support-matrix.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/support-matrix.md @@ -20,7 +20,7 @@ license: | --- 选择能力前,请使用此矩阵确认文档所覆盖的 API。存在某个运行时页面,并不表示该运行时 -支持所有 Fory 产品。 +支持所有 Fory 能力。 | 能力 | 已有文档的运行时 | 互操作能力 | | ------------------- | ---------------------------------------------------------------------------------- | -------------------------------------- | @@ -34,4 +34,4 @@ license: | [Android](../object-serialization/java/android.md) 和 [GraalVM Native Image](../object-serialization/java/graalvm.md) 等平台限制,由相应的 Java -对象序列化和 Fory JSON 产品文档说明。 +对象序列化和 Fory JSON 指南说明。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/java/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/java/index.md index b474077a51..106aadf403 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/java/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/java/index.md @@ -21,7 +21,7 @@ license: | Apache Fory Java 提供高性能二进制对象序列化。与其他受支持运行时共享的载荷使用跨语言模式,仅供 Java/JVM 使用的对象图则使用原生模式。 -本运行时指南仅介绍二进制对象序列化。其他 Java 产品参见 [Row Format](../../row-format/java.md)、[Fory JSON](../../json/index.md)、[Fory IDL 与编译器](../../compiler/index.md)或 [Fory gRPC](../../grpc/java.md)。 +本运行时指南仅介绍二进制对象序列化。其他 Java 能力参见 [Row Format](../../row-format/java.md)、[Fory JSON](../../json/index.md)、[Fory IDL 与编译器](../../compiler/index.md)或 [Fory gRPC](../../grpc/java.md)。 ## 二进制对象序列化 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/runtimes.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/runtimes.md index bdb850cfa7..19e4bed27e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/runtimes.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/object-serialization/runtimes.md @@ -20,7 +20,7 @@ license: | --- 请选择应用所使用 API 对应的运行时。运行时文档仅涵盖二进制对象序列化;Row Format、 -Fory JSON、编译器和 gRPC 页面仍归属于各自的产品功能。 +Fory JSON、编译器和 gRPC 分别由各自的能力指南说明。 | 运行时 | 模式 | 文档 | | --------------------- | ----------------- | ----------------------------------------------------- | diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/index.md index 62737cd51b..832666ad9d 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/index.md @@ -51,12 +51,12 @@ Apache Fory™ 以源代码制品和各语言专用软件包的形式发布。 ## 可以构建什么 -| 能力 | 用途 | 可用运行时 | 详细指南 | -| ---------- | ----------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------- | -| 对象序列化 | 重建对象图,包括共享引用和 Schema 变更 | 所有运行时 | [对象序列化](../object-serialization/index.md) | -| Row Format | 对可信分析数据进行零拷贝、随机或部分字段访问 | Java、Python、C++、Rust | [Row Format](../row-format/index.md) | -| Fory JSON | 高性能标准 JSON 映射 | Java | [Fory JSON](../json/index.md) | -| Fory IDL | 从 Fory、protobuf 或 FlatBuffers IDL 生成原生模型和序列化器 | 所有运行时 | [Fory IDL 与编译器](../compiler/index.md) | -| Fory gRPC | 通过常规 gRPC 传输使用生成的模型和 Fory 编码的消息 | Java、Python、C++、Go、Rust、JavaScript、C#、Dart、Scala、Kotlin | [Fory gRPC](../grpc/index.md) | - -对象序列化使用 xlang 模式生成可移植的跨语言数据。Java、Python、C++、Go、Rust、Scala 和 Kotlin 还提供 native 模式,用于同一运行时内的数据。如果尚未明确产品应选择哪种格式,请参阅[选择格式](../introduction/choose-a-format.md)。 +| 能力 | 用途 | 可用运行时 | 详细指南 | +| ---------- | ----------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- | +| 对象序列化 | 重建对象图,包括共享引用和 Schema 变更 | 所有运行时 | [对象序列化](../object-serialization/index.md) | +| Row Format | 对可信分析数据进行零拷贝、随机或部分字段访问 | Java、Python、C++、Rust | [Row Format](../row-format/index.md) | +| Fory JSON | 高性能标准 JSON 映射 | Java | [Fory JSON](../json/index.md) | +| Fory IDL | 从 Fory、protobuf 或 FlatBuffers IDL 生成原生模型和序列化器 | 所有运行时 | [Fory IDL 与编译器](../compiler/index.md) | +| Fory gRPC | 通过常规 gRPC 传输使用生成的模型和 Fory 编码的消息 | Java、Python、C++、Go、Rust、JavaScript、C#、Dart、Scala、Kotlin | [Fory gRPC](../grpc/index.md) | + +对象序列化使用 xlang 模式生成可移植的跨语言数据。Java、Python、C++、Go、Rust、Scala 和 Kotlin 还提供 native 模式,用于同一运行时内的数据。如果尚未确定使用哪种格式,请参阅[选择格式](../introduction/choose-a-format.md)。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/swift.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/swift.md index 96653fe49e..f4e97bd76b 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/swift.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/start/swift.md @@ -35,7 +35,7 @@ swift --version swift package init --type executable --name ForyExample ``` -在生成的 `Package.swift` 中添加已发布的软件包和 `Fory` 产品: +在生成的 `Package.swift` 中添加已发布的软件包,并依赖其中的 `Fory` 库: ```swift title="Package.swift" dependencies: [ --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
