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
The following commit(s) were added to refs/heads/main by this push:
new c1ae5fe25 ๐ synced local 'docs/guide/' with remote 'docs/guide/'
c1ae5fe25 is described below
commit c1ae5fe2550a919b591150ce04b595158033d767
Author: chaokunyang <[email protected]>
AuthorDate: Sun Oct 19 18:56:22 2025 +0000
๐ synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/DEVELOPMENT.md | 2 ++
docs/guide/rust_guide.md | 9 +++++++++
2 files changed, 11 insertions(+)
diff --git a/docs/guide/DEVELOPMENT.md b/docs/guide/DEVELOPMENT.md
index dc08f8a00..921143aaa 100644
--- a/docs/guide/DEVELOPMENT.md
+++ b/docs/guide/DEVELOPMENT.md
@@ -100,6 +100,8 @@ cargo test
cargo test -p fory-tests --test $test_file $test_method
# run specific test under subdirectory
cargo test --test mod $dir$::$test_file::$test_method
+# debug specific test under subdirectory and get backtrace
+RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 cargo test --test mod
$dir$::$test_file::$test_method
# inspect generated code by fory derive macro
cargo expand --test mod $mod$::$file$ > expanded.rs
```
diff --git a/docs/guide/rust_guide.md b/docs/guide/rust_guide.md
index 5279ad835..b543f5207 100644
--- a/docs/guide/rust_guide.md
+++ b/docs/guide/rust_guide.md
@@ -940,6 +940,15 @@ let fory = Fory::default().max_dyn_depth(10); // Allow up
to 10 levels
Note: Static data types (non-dynamic types) are secure by nature and not
subject to depth limits, as their structure is known at compile time.
+## ๐งช Troubleshooting
+
+- **Type registry errors**: An error like `TypeId ... not found in type_info
registry` means the type was never registered with the current `Fory` instance.
Confirm that every serializable struct or trait implementation calls
`fory.register::<T>(type_id)` before serialization and that the same IDs are
reused on the deserialize side.
+- **Quick error lookup**: Prefer the static constructors on
`fory_core::error::Error` (`Error::type_mismatch`, `Error::invalid_data`,
`Error::unknown`, etc.) rather than instantiating variants manually. This keeps
diagnostics consistent and makes opt-in panics work.
+- **Panic on error for backtraces**: Toggle `FORY_PANIC_ON_ERROR=1` (or
`true`) alongside `RUST_BACKTRACE=1` when running tests or binaries to panic at
the exact site an error is constructed. Reset the variable afterwards to avoid
aborting user-facing code paths.
+- **Struct field tracing**: Add the `#[fory_debug]` attribute alongside
`#[derive(ForyObject)]` to tell the macro to emit hook invocations for that
type. Once compiled with debug hooks, call `set_before_write_field_func`,
`set_after_write_field_func`, `set_before_read_field_func`, or
`set_after_read_field_func` (from `fory-core/src/serializer/struct_.rs`) to
plug in custom callbacks, and use `reset_struct_debug_hooks()` when you want
the defaults back.
+- **Lightweight logging**: Without custom hooks, enable
`ENABLE_FORY_DEBUG_OUTPUT=1` to print field-level read/write events emitted by
the default hook functions. This is especially useful when investigating
alignment or cursor mismatches.
+- **Test-time hygiene**: Some integration tests expect `FORY_PANIC_ON_ERROR`
to remain unset. Export it only for focused debugging sessions, and prefer
`cargo test --features tests -p fory-tests --test <case>` when isolating
failing scenarios.
+
## ๐ ๏ธ Development
### Building
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
