project_model/
project_json.rs

1//! `rust-project.json` file format.
2//!
3//! This format is spiritually a serialization of [`base_db::CrateGraph`]. The
4//! idea here is that people who do not use Cargo, can instead teach their build
5//! system to generate `rust-project.json` which can be ingested by
6//! rust-analyzer.
7//!
8//! This short file is a somewhat big conceptual piece of the architecture of
9//! rust-analyzer, so it's worth elaborating on the underlying ideas and
10//! motivation.
11//!
12//! For rust-analyzer to function, it needs some information about the project.
13//! Specifically, it maintains an in-memory data structure which lists all the
14//! crates (compilation units) and dependencies between them. This is necessary
15//! a global singleton, as we do want, eg, find usages to always search across
16//! the whole project, rather than just in the "current" crate.
17//!
18//! Normally, we get this "crate graph" by calling `cargo metadata
19//! --message-format=json` for each cargo workspace and merging results. This
20//! works for your typical cargo project, but breaks down for large folks who
21//! have a monorepo with an infinite amount of Rust code which is built with bazel or
22//! some such.
23//!
24//! To support this use case, we need to make _something_ configurable. To avoid
25//! a [midlayer mistake](https://lwn.net/Articles/336262/), we allow configuring
26//! the lowest possible layer. `ProjectJson` is essentially a hook to just set
27//! that global singleton in-memory data structure. It is optimized for power,
28//! not for convenience (you'd be using cargo anyway if you wanted nice things,
29//! right? :)
30//!
31//! `rust-project.json` also isn't necessary a file. Architecturally, we support
32//! any convenient way to specify this data, which today is:
33//!
34//! * file on disk
35//! * a field in the config (ie, you can send a JSON request with the contents
36//!   of `rust-project.json` to rust-analyzer, no need to write anything to disk)
37//!
38//! Another possible thing we don't do today, but which would be totally valid,
39//! is to add an extension point to VS Code extension to register custom
40//! project.
41//!
42//! In general, it is assumed that if you are going to use `rust-project.json`,
43//! you'd write a fair bit of custom code gluing your build system to ra through
44//! this JSON format. This logic can take form of a VS Code extension, or a
45//! proxy process which injects data into "configure" LSP request, or maybe just
46//! a simple build system rule to generate the file.
47//!
48//! In particular, the logic for lazily loading parts of the monorepo as the
49//! user explores them belongs to that extension (it's totally valid to change
50//! rust-project.json over time via configuration request!)
51
52use base_db::{CrateDisplayName, CrateName};
53use cfg::CfgAtom;
54use paths::{AbsPath, AbsPathBuf, Utf8PathBuf};
55use rustc_hash::{FxHashMap, FxHashSet};
56use serde::{Deserialize, Serialize, de};
57use span::Edition;
58
59use crate::{ManifestPath, TargetKind};
60
61/// Roots and crates that compose this Rust project.
62#[derive(Clone, Debug, Eq, PartialEq)]
63pub struct ProjectJson {
64    /// e.g. `path/to/sysroot`
65    pub(crate) sysroot: Option<AbsPathBuf>,
66    /// e.g. `path/to/sysroot/lib/rustlib/src/rust/library`
67    pub(crate) sysroot_src: Option<AbsPathBuf>,
68    /// A nested project describing the layout of the sysroot
69    pub(crate) sysroot_project: Option<Box<ProjectJson>>,
70    project_root: AbsPathBuf,
71    /// The path to the rust-project.json file. May be None if this
72    /// data was generated by the discoverConfig command.
73    manifest: Option<ManifestPath>,
74    crates: Vec<Crate>,
75    /// Configuration for CLI commands.
76    ///
77    /// Examples include a check build or a test run.
78    runnables: Vec<Runnable>,
79}
80
81impl ProjectJson {
82    /// Create a new ProjectJson instance.
83    ///
84    /// # Arguments
85    ///
86    /// * `manifest` - The path to the `rust-project.json`.
87    /// * `base` - The path to the workspace root (i.e. the folder containing `rust-project.json`)
88    /// * `data` - The parsed contents of `rust-project.json`, or project json that's passed via configuration.
89    pub fn new(
90        manifest: Option<ManifestPath>,
91        base: &AbsPath,
92        data: ProjectJsonData,
93    ) -> ProjectJson {
94        let absolutize_on_base = |p| base.absolutize(p);
95        let sysroot_src = data.sysroot_src.map(absolutize_on_base);
96        let sysroot_project =
97            data.sysroot_project.zip(sysroot_src.clone()).map(|(sysroot_data, sysroot_src)| {
98                Box::new(ProjectJson::new(None, &sysroot_src, *sysroot_data))
99            });
100
101        ProjectJson {
102            sysroot: data.sysroot.map(absolutize_on_base),
103            sysroot_src,
104            sysroot_project,
105            project_root: base.to_path_buf(),
106            manifest,
107            runnables: data.runnables.into_iter().map(Runnable::from).collect(),
108            crates: data
109                .crates
110                .into_iter()
111                .map(|crate_data| {
112                    let root_module = absolutize_on_base(crate_data.root_module);
113                    let is_workspace_member = crate_data
114                        .is_workspace_member
115                        .unwrap_or_else(|| root_module.starts_with(base));
116                    let (include, exclude) = match crate_data.source {
117                        Some(src) => {
118                            let absolutize = |dirs: Vec<Utf8PathBuf>| {
119                                dirs.into_iter().map(absolutize_on_base).collect::<Vec<_>>()
120                            };
121                            (absolutize(src.include_dirs), absolutize(src.exclude_dirs))
122                        }
123                        None => (vec![root_module.parent().unwrap().to_path_buf()], Vec::new()),
124                    };
125
126                    let build = match crate_data.build {
127                        Some(build) => Some(Build {
128                            label: build.label,
129                            build_file: build.build_file,
130                            target_kind: build.target_kind.into(),
131                        }),
132                        None => None,
133                    };
134
135                    let cfg = crate_data
136                        .cfg_groups
137                        .iter()
138                        .flat_map(|cfg_extend| {
139                            let cfg_group = data.cfg_groups.get(cfg_extend);
140                            match cfg_group {
141                                Some(cfg_group) => cfg_group.0.iter().cloned(),
142                                None => {
143                                    tracing::error!(
144                                        "Unknown cfg group `{cfg_extend}` in crate `{}`",
145                                        crate_data.display_name.as_deref().unwrap_or("<unknown>"),
146                                    );
147                                    [].iter().cloned()
148                                }
149                            }
150                        })
151                        .chain(crate_data.cfg.0)
152                        .collect();
153
154                    Crate {
155                        display_name: crate_data
156                            .display_name
157                            .as_deref()
158                            .map(CrateDisplayName::from_canonical_name),
159                        root_module,
160                        edition: crate_data.edition.into(),
161                        version: crate_data.version.as_ref().map(ToString::to_string),
162                        deps: crate_data.deps,
163                        cfg,
164                        target: crate_data.target,
165                        env: crate_data.env,
166                        proc_macro_dylib_path: crate_data
167                            .proc_macro_dylib_path
168                            .map(absolutize_on_base),
169                        is_workspace_member,
170                        include,
171                        exclude,
172                        is_proc_macro: crate_data.is_proc_macro,
173                        repository: crate_data.repository,
174                        build,
175                        proc_macro_cwd: crate_data.proc_macro_cwd.map(absolutize_on_base),
176                    }
177                })
178                .collect(),
179        }
180    }
181
182    /// Returns the number of crates in the project.
183    pub fn n_crates(&self) -> usize {
184        self.crates.len()
185    }
186
187    /// Returns an iterator over the crates in the project.
188    pub fn crates(&self) -> impl Iterator<Item = (CrateArrayIdx, &Crate)> {
189        self.crates.iter().enumerate().map(|(idx, krate)| (CrateArrayIdx(idx), krate))
190    }
191
192    /// Returns the path to the project's root folder.
193    pub fn path(&self) -> &AbsPath {
194        &self.project_root
195    }
196
197    pub fn crate_by_root(&self, root: &AbsPath) -> Option<Crate> {
198        self.crates
199            .iter()
200            .filter(|krate| krate.is_workspace_member)
201            .find(|krate| krate.root_module == root)
202            .cloned()
203    }
204
205    /// Returns the path to the project's manifest, if it exists.
206    pub fn manifest(&self) -> Option<&ManifestPath> {
207        self.manifest.as_ref()
208    }
209
210    pub fn crate_by_buildfile(&self, path: &AbsPath) -> Option<Build> {
211        // this is fast enough for now, but it's unfortunate that this is O(crates).
212        let path: &std::path::Path = path.as_ref();
213        self.crates
214            .iter()
215            .filter(|krate| krate.is_workspace_member)
216            .filter_map(|krate| krate.build.clone())
217            .find(|build| build.build_file.as_std_path() == path)
218    }
219
220    /// Returns the path to the project's manifest or root folder, if no manifest exists.
221    pub fn manifest_or_root(&self) -> &AbsPath {
222        self.manifest.as_ref().map_or(&self.project_root, |manifest| manifest.as_ref())
223    }
224
225    /// Returns the path to the project's root folder.
226    pub fn project_root(&self) -> &AbsPath {
227        &self.project_root
228    }
229
230    pub fn runnables(&self) -> &[Runnable] {
231        &self.runnables
232    }
233}
234
235/// A crate points to the root module of a crate and lists the dependencies of the crate. This is
236/// useful in creating the crate graph.
237#[derive(Clone, Debug, Eq, PartialEq)]
238pub struct Crate {
239    pub(crate) display_name: Option<CrateDisplayName>,
240    pub root_module: AbsPathBuf,
241    pub(crate) edition: Edition,
242    pub(crate) version: Option<String>,
243    pub(crate) deps: Vec<Dep>,
244    pub(crate) cfg: Vec<CfgAtom>,
245    pub(crate) target: Option<String>,
246    pub(crate) env: FxHashMap<String, String>,
247    pub(crate) proc_macro_dylib_path: Option<AbsPathBuf>,
248    pub(crate) is_workspace_member: bool,
249    pub(crate) include: Vec<AbsPathBuf>,
250    pub(crate) exclude: Vec<AbsPathBuf>,
251    pub(crate) is_proc_macro: bool,
252    /// The working directory to run proc-macros in. This is usually the workspace root of cargo workspaces.
253    pub(crate) proc_macro_cwd: Option<AbsPathBuf>,
254    pub(crate) repository: Option<String>,
255    pub build: Option<Build>,
256}
257
258/// Additional, build-specific data about a crate.
259#[derive(Clone, Debug, Eq, PartialEq)]
260pub struct Build {
261    /// The name associated with this crate.
262    ///
263    /// This is determined by the build system that produced
264    /// the `rust-project.json` in question. For instance, if buck were used,
265    /// the label might be something like `//ide/rust/rust-analyzer:rust-analyzer`.
266    ///
267    /// Do not attempt to parse the contents of this string; it is a build system-specific
268    /// identifier similar to [`Crate::display_name`].
269    pub label: String,
270    /// Path corresponding to the build system-specific file defining the crate.
271    ///
272    /// It is roughly analogous to [`ManifestPath`], but it should *not* be used with
273    /// [`crate::ProjectManifest::from_manifest_file`], as the build file may not be
274    /// be in the `rust-project.json`.
275    pub build_file: Utf8PathBuf,
276    /// The kind of target.
277    ///
278    /// Examples (non-exhaustively) include [`TargetKind::Bin`], [`TargetKind::Lib`],
279    /// and [`TargetKind::Test`]. This information is used to determine what sort
280    /// of runnable codelens to provide, if any.
281    pub target_kind: TargetKind,
282}
283
284/// A template-like structure for describing runnables.
285///
286/// These are used for running and debugging binaries and tests without encoding
287/// build system-specific knowledge into rust-analyzer.
288///
289/// # Example
290///
291/// Below is an example of a test runnable. `{label}` and `{test_id}`
292/// are explained in [`Runnable::args`]'s documentation.
293///
294/// ```json
295/// {
296///     "program": "buck",
297///     "args": [
298///         "test",
299///          "{label}",
300///          "--",
301///          "{test_id}",
302///          "--print-passing-details"
303///     ],
304///     "cwd": "/home/user/repo-root/",
305///     "kind": "testOne"
306/// }
307/// ```
308#[derive(Debug, Clone, PartialEq, Eq)]
309pub struct Runnable {
310    /// The program invoked by the runnable.
311    ///
312    /// For example, this might be `cargo`, `buck`, or `bazel`.
313    pub program: String,
314    /// The arguments passed to [`Runnable::program`].
315    ///
316    /// The args can contain two template strings: `{label}` and `{test_id}`.
317    /// rust-analyzer will find and replace `{label}` with [`Build::label`] and
318    /// `{test_id}` with the test name.
319    pub args: Vec<String>,
320    /// The current working directory of the runnable.
321    pub cwd: Utf8PathBuf,
322    pub kind: RunnableKind,
323}
324
325/// The kind of runnable.
326#[derive(Debug, Clone, PartialEq, Eq)]
327pub enum RunnableKind {
328    Check,
329
330    /// Can run a binary.
331    Run,
332
333    /// Run a single test.
334    TestOne,
335}
336
337#[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq)]
338pub struct ProjectJsonData {
339    sysroot: Option<Utf8PathBuf>,
340    sysroot_src: Option<Utf8PathBuf>,
341    sysroot_project: Option<Box<ProjectJsonData>>,
342    #[serde(default)]
343    cfg_groups: FxHashMap<String, CfgList>,
344    crates: Vec<CrateData>,
345    #[serde(default)]
346    runnables: Vec<RunnableData>,
347}
348
349#[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq, Default)]
350#[serde(transparent)]
351struct CfgList(#[serde(with = "cfg_")] Vec<CfgAtom>);
352
353#[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq)]
354struct CrateData {
355    display_name: Option<String>,
356    root_module: Utf8PathBuf,
357    edition: EditionData,
358    #[serde(default)]
359    version: Option<semver::Version>,
360    deps: Vec<Dep>,
361    #[serde(default)]
362    cfg_groups: FxHashSet<String>,
363    #[serde(default)]
364    cfg: CfgList,
365    target: Option<String>,
366    #[serde(default)]
367    env: FxHashMap<String, String>,
368    proc_macro_dylib_path: Option<Utf8PathBuf>,
369    is_workspace_member: Option<bool>,
370    source: Option<CrateSource>,
371    #[serde(default)]
372    is_proc_macro: bool,
373    #[serde(default)]
374    repository: Option<String>,
375    #[serde(default)]
376    build: Option<BuildData>,
377    #[serde(default)]
378    proc_macro_cwd: Option<Utf8PathBuf>,
379}
380
381mod cfg_ {
382    use cfg::CfgAtom;
383    use serde::{Deserialize, Serialize};
384
385    pub(super) fn deserialize<'de, D>(deserializer: D) -> Result<Vec<CfgAtom>, D::Error>
386    where
387        D: serde::Deserializer<'de>,
388    {
389        let cfg: Vec<String> = Vec::deserialize(deserializer)?;
390        cfg.into_iter().map(|it| crate::parse_cfg(&it).map_err(serde::de::Error::custom)).collect()
391    }
392    pub(super) fn serialize<S>(cfg: &[CfgAtom], serializer: S) -> Result<S::Ok, S::Error>
393    where
394        S: serde::Serializer,
395    {
396        cfg.iter()
397            .map(|cfg| match cfg {
398                CfgAtom::Flag(flag) => flag.as_str().to_owned(),
399                CfgAtom::KeyValue { key, value } => {
400                    format!("{}=\"{}\"", key.as_str(), value.as_str())
401                }
402            })
403            .collect::<Vec<String>>()
404            .serialize(serializer)
405    }
406}
407
408#[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq)]
409#[serde(rename = "edition")]
410enum EditionData {
411    #[serde(rename = "2015")]
412    Edition2015,
413    #[serde(rename = "2018")]
414    Edition2018,
415    #[serde(rename = "2021")]
416    Edition2021,
417    #[serde(rename = "2024")]
418    Edition2024,
419}
420
421#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq)]
422pub struct BuildData {
423    label: String,
424    build_file: Utf8PathBuf,
425    target_kind: TargetKindData,
426}
427
428#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
429pub struct RunnableData {
430    pub program: String,
431    pub args: Vec<String>,
432    pub cwd: Utf8PathBuf,
433    pub kind: RunnableKindData,
434}
435
436#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
437#[serde(rename_all = "camelCase")]
438pub enum RunnableKindData {
439    Check,
440    Run,
441    TestOne,
442}
443
444#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
445#[serde(rename_all = "camelCase")]
446pub enum TargetKindData {
447    Bin,
448    /// Any kind of Cargo lib crate-type (dylib, rlib, proc-macro, ...).
449    Lib,
450    Test,
451}
452/// Identifies a crate by position in the crates array.
453///
454/// This will differ from `Crate` when multiple `ProjectJson`
455/// workspaces are loaded.
456#[derive(Serialize, Deserialize, Debug, Clone, Copy, Eq, PartialEq, Hash)]
457#[serde(transparent)]
458pub struct CrateArrayIdx(pub usize);
459
460#[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq)]
461pub(crate) struct Dep {
462    /// Identifies a crate by position in the crates array.
463    #[serde(rename = "crate")]
464    pub(crate) krate: CrateArrayIdx,
465    #[serde(serialize_with = "serialize_crate_name")]
466    #[serde(deserialize_with = "deserialize_crate_name")]
467    pub(crate) name: CrateName,
468}
469
470#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
471struct CrateSource {
472    include_dirs: Vec<Utf8PathBuf>,
473    exclude_dirs: Vec<Utf8PathBuf>,
474}
475
476impl From<TargetKindData> for TargetKind {
477    fn from(data: TargetKindData) -> Self {
478        match data {
479            TargetKindData::Bin => TargetKind::Bin,
480            TargetKindData::Lib => TargetKind::Lib { is_proc_macro: false },
481            TargetKindData::Test => TargetKind::Test,
482        }
483    }
484}
485
486impl From<EditionData> for Edition {
487    fn from(data: EditionData) -> Self {
488        match data {
489            EditionData::Edition2015 => Edition::Edition2015,
490            EditionData::Edition2018 => Edition::Edition2018,
491            EditionData::Edition2021 => Edition::Edition2021,
492            EditionData::Edition2024 => Edition::Edition2024,
493        }
494    }
495}
496
497impl From<RunnableData> for Runnable {
498    fn from(data: RunnableData) -> Self {
499        Runnable { program: data.program, args: data.args, cwd: data.cwd, kind: data.kind.into() }
500    }
501}
502
503impl From<RunnableKindData> for RunnableKind {
504    fn from(data: RunnableKindData) -> Self {
505        match data {
506            RunnableKindData::Check => RunnableKind::Check,
507            RunnableKindData::Run => RunnableKind::Run,
508            RunnableKindData::TestOne => RunnableKind::TestOne,
509        }
510    }
511}
512
513fn deserialize_crate_name<'de, D>(de: D) -> std::result::Result<CrateName, D::Error>
514where
515    D: de::Deserializer<'de>,
516{
517    let name = String::deserialize(de)?;
518    CrateName::new(&name).map_err(|err| de::Error::custom(format!("invalid crate name: {err:?}")))
519}
520
521fn serialize_crate_name<S>(name: &CrateName, se: S) -> Result<S::Ok, S::Error>
522where
523    S: serde::Serializer,
524{
525    se.serialize_str(name.as_str())
526}
project_model/project_json.rs

project_model/
project_json.rs
