Rust code organizaiton 101 - breaking down dbt-oss repo

rust
cargo
tooling
Author

Ran Li

Published

October 30, 2026

Rambling/understanding

  • New to rust and its a little confusing - breaking down the DBT-OSS codebase
  • So cargo is a apckage managemtn and devlopement tool
  • Workspace: A repositoy can be cargo workspacewoud cna containe many crates
    • the dbt-oss is a cargo workspace wih ahas 91 crates (we add the python cate) totla binir ghte loom-datwarhesou to 92 crates
    • cargo automatically determines the dependencies between crates so it can resolve it when jsut runw ithotus epcificla defualt cargo build; libraries are compiled first. whihc ar ehten packaged into programs.
    • the workspace is specified in the root cargo.toml whcihd efines the workspace
  • Crate: rust cosde is bundled in to units called crates
    • each crate has a cargo.toml that incldue pseicicasl for waht the crate produces
    • it has several secitons
      • a [[bin]] section indicate sthat it sohuld built into an exe file wiht configaiotns liek name and starting path; this optional jsut emtdata or conifsg about the exe
      • [package] metdatat of the crate liek name .. etc
      • [dependencies]` crate dpendicneins
      • [feuaters] optio extracts
    • a crate either outputs either a program  (.exe) file (as configure by bin) or it by deufalit it outputs via compilation intoa library (.rlib)
    • so a crate can ahve two tpyes either a program crate that genreates a exe or lirbary crate that genresates a rlib file
    • each crate has its own src folder 
    • In general: if a crates src fodler has a special file called src/main.rs then it is a program crate that will generate a exe. if it doenst hav the file then it is a regaulr crate that only genreates a library rlibs.
      • the excpeitons ita ht bin config can point the start file sonewehres. but dbt-oss follwos the default file naming and bin configs
  • Module: modules are sectiosn fo code inside one crate (usiually one file each)
    • they organize the code
    • e.g .dbt_features::cli means the cli module inside the dbt-features
  • Functions: are the smaller peices of code. funcitons live isnide modules 
    • fucntions have differen scoeps of sharing or reuse there are three scopes of sharing
    • No marking (dfeault) a funiton can be only use within its own module and the moduels nest within the module it is contained within
    • pub(crate) any where within the same crate it is deinfeint in 
    • pub can be reussea acorss other crates - e.g.g creating crate level depdnencies..
      • note for this tow orkt he path of pub dpendncens but also all be pub for this chaining to work.