From 6a0f7f0852cf049ddf52628bd1e402ee182ae7cb Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Mon, 19 Jul 2021 17:47:56 +0300 Subject: [PATCH] internal: explain why we avoid serializing everything --- crates/base_db/src/input.rs | 5 ++++- docs/dev/architecture.md | 14 ++++++++++++++ docs/dev/style.md | 2 +- 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/crates/base_db/src/input.rs b/crates/base_db/src/input.rs index 5f746ec5a5..c20eefd7b9 100644 --- a/crates/base_db/src/input.rs +++ b/crates/base_db/src/input.rs @@ -67,7 +67,10 @@ impl SourceRoot { /// Note that `CrateGraph` is build-system agnostic: it's a concept of the Rust /// language proper, not a concept of the build system. In practice, we get /// `CrateGraph` by lowering `cargo metadata` output. -#[derive(Debug, Clone, Default)] +/// +/// `CrateGraph` is `!Serialize` by design, see +/// +#[derive(Debug, Clone, Default /* Serialize, Deserialize */)] pub struct CrateGraph { arena: FxHashMap, } diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index db42a30c6b..d817a74eca 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -457,3 +457,17 @@ It is not cheap enough to enable in prod, and this is a bug which should be fixe rust-analyzer strives to be as configurable as possible while offering reasonable defaults where no configuration exists yet. There will always be features that some people find more annoying than helpful, so giving the users the ability to tweak or disable these is a big part of offering a good user experience. Mind the code--architecture gap: at the moment, we are using fewer feature flags than we really should. + +### Serialization + +In Rust, it is easy (often too easy) to add serialization to any type by adding `#[derive(Serialize)]`. +This easiness is misleading -- serializable types impose significant backwards compatability constraints. +If a type is serializable, then it is a part of some IPC boundary. +You often don't have control over the over side of this boundary, so changing serializable types are hard. + +For this reason, the types in `ide`, `base_db` and bellow are not serializable by design. +If such types need to cross an IPC boundary, then the client of rust-analyzer needs to provide custom, client-specific serialization format. +This isolates backwards compatibility and migration concerns to a specific client. + +For example, `rust-project.json` is it's own format -- it doesn't include `CrateGraph` as is. +Instead, it creates a `CrateGraph` by calling appropriate constructing functions. diff --git a/docs/dev/style.md b/docs/dev/style.md index 7e8e41a417..01daf948ce 100644 --- a/docs/dev/style.md +++ b/docs/dev/style.md @@ -292,7 +292,7 @@ impl Person { **Rationale:** we don't provide public API, it's cheaper to refactor than to pay getters rent. Non-local code properties degrade under change, privacy makes invariant local. -Borrowed own data discloses irrelevant details about origin of data. +Borrowed owned types (`&String`) disclose irrelevant details about internal representation. Irrelevant (neither right nor wrong) things obscure correctness. ## Useless Types