Skip to content

Partially document proc-macros #1029

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Partially document proc-macros #1029

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fca9d84
fix: use unambiguous paths for Result
axelkar Nov 21, 2025
77c0219
docs: Partially document proc-macros
axelkar Nov 21, 2025
81b2c85
docs: Document `debug` option of proc-macros
axelkar Nov 21, 2025
966078f
docs: document singleton option
axelkar Nov 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions book/src/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ The database is also used to implement interning (making a canonical version of

## Inputs

Every Salsa program begins with an **input**.
Every Salsa program begins with an **input**. See the [`#[input]` attribute macro's documentation](https://docs.rs/salsa/latest/salsa/attr.input.html) for options.
Inputs are special structs that define the starting point of your program.
Everything else in your program is ultimately a deterministic function of these inputs.

Expand Down Expand Up @@ -123,7 +123,7 @@ This gives the ability to set the [durability](./reference/durability.md) and ot

## Tracked functions

Once you've defined your inputs, the next thing to define are **tracked functions**:
Once you've defined your inputs, the next thing to define are **tracked functions**. See the [`#[tracked]` attribute macro's documentation](https://docs.rs/salsa/latest/salsa/attr.tracked.html) for options.

```rust
#[salsa::tracked]
Expand All @@ -149,7 +149,7 @@ Tracked functions can return any clone-able type. A clone is required since, whe

## Tracked structs

**Tracked structs** are intermediate structs created during your computation.
**Tracked structs** are intermediate structs created during your computation. See the [`#[tracked]` attribute macro's documentation](https://docs.rs/salsa/latest/salsa/attr.tracked.html) for options.
Like inputs, their fields are stored inside the database, and the struct itself just wraps an id.
Unlike inputs, they can only be created inside a tracked function, and their fields can never change once they are created (until the next revision, at least).
Getter methods are provided to read the fields, but there are no setter methods.
Expand Down Expand Up @@ -180,6 +180,8 @@ fn parse_file(db: &dyn crate::Db, file: ProgramFile) -> Ast {

### `#[id]` fields

<!-- FIXME: #[id] fields only currently exist on interned structs -->

When a tracked function is re-executed because its inputs have changed, the tracked structs it creates in the new execution are matched against those from the old execution, and the values of their fields are compared.
If the field values have not changed, then other tracked functions that only read those fields will not be re-executed.

Expand Down Expand Up @@ -246,6 +248,7 @@ Specifying is only possible for tracked functions that take a single tracked str
The final kind of Salsa struct are **interned structs**.
Interned structs are useful for quick equality comparison.
They are commonly used to represent strings or other primitive values.
See the [`#[interned]` attribute macro's documentation](https://docs.rs/salsa/latest/salsa/attr.interned.html) for options.

Most compilers, for example, will define a type to represent a user identifier:

Expand Down Expand Up @@ -273,7 +276,7 @@ You can access the fields of an interned struct using a getter, like `word.text(

## Accumulators

The final Salsa concept are **accumulators**. Accumulators are a way to report errors or other "side channel" information that is separate from the main return value of your function.
The final Salsa concept are **accumulators**. Accumulators are a way to report errors or other "side channel" information that is separate from the main return value of your function. See the [`#[accumulator]` attribute macro's documentation](https://docs.rs/salsa/latest/salsa/attr.accumulator.html) for options.

To create an accumulator, you declare a type as an _accumulator_:

Expand Down
8 changes: 4 additions & 4 deletions components/salsa-macro-rules/src/setup_input_struct.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ macro_rules! setup_input_struct {
fn serialize<S: $zalsa::serde::Serializer>(
fields: &Self::Fields,
serializer: S,
) -> Result<S::Ok, S::Error> {
) -> ::std::result::Result<S::Ok, S::Error> {
$zalsa::macro_if! {
if $persist {
$($serialize_fn(fields, serializer))?
Expand All @@ -135,7 +135,7 @@ macro_rules! setup_input_struct {

fn deserialize<'de, D: $zalsa::serde::Deserializer<'de>>(
deserializer: D,
) -> Result<Self::Fields, D::Error> {
) -> ::std::result::Result<Self::Fields, D::Error> {
$zalsa::macro_if! {
if $persist {
$($deserialize_fn(deserializer))?
Expand Down Expand Up @@ -241,7 +241,7 @@ macro_rules! setup_input_struct {

$zalsa::macro_if! { $persist =>
impl $zalsa::serde::Serialize for $Struct {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
fn serialize<S>(&self, serializer: S) -> ::std::result::Result<S::Ok, S::Error>
where
S: $zalsa::serde::Serializer,
{
Expand All @@ -250,7 +250,7 @@ macro_rules! setup_input_struct {
}

impl<'de> $zalsa::serde::Deserialize<'de> for $Struct {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: $zalsa::serde::Deserializer<'de>,
{
Expand Down
8 changes: 4 additions & 4 deletions components/salsa-macro-rules/src/setup_interned_struct.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ macro_rules! setup_interned_struct {
fn serialize<S: $zalsa::serde::Serializer>(
fields: &Self::Fields<'_>,
serializer: S,
) -> Result<S::Ok, S::Error> {
) -> ::std::result::Result<S::Ok, S::Error> {
$zalsa::macro_if! {
if $persist {
$($serialize_fn(fields, serializer))?
Expand All @@ -183,7 +183,7 @@ macro_rules! setup_interned_struct {

fn deserialize<'de, D: $zalsa::serde::Deserializer<'de>>(
deserializer: D,
) -> Result<Self::Fields<'static>, D::Error> {
) -> ::std::result::Result<Self::Fields<'static>, D::Error> {
$zalsa::macro_if! {
if $persist {
$($deserialize_fn(deserializer))?
Expand Down Expand Up @@ -269,7 +269,7 @@ macro_rules! setup_interned_struct {

$zalsa::macro_if! { $persist =>
impl<$($db_lt_arg)?> $zalsa::serde::Serialize for $Struct<$($db_lt_arg)?> {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
fn serialize<S>(&self, serializer: S) -> ::std::result::Result<S::Ok, S::Error>
where
S: $zalsa::serde::Serializer,
{
Expand All @@ -278,7 +278,7 @@ macro_rules! setup_interned_struct {
}

impl<'de, $($db_lt_arg)?> $zalsa::serde::Deserialize<'de> for $Struct<$($db_lt_arg)?> {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: $zalsa::serde::Deserializer<'de>,
{
Expand Down
8 changes: 4 additions & 4 deletions components/salsa-macro-rules/src/setup_tracked_fn.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ macro_rules! setup_tracked_fn {
fn serialize<S: $zalsa::serde::Serializer>(
fields: &Self::Fields<'_>,
serializer: S,
) -> Result<S::Ok, S::Error> {
) -> ::std::result::Result<S::Ok, S::Error> {
$zalsa::macro_if! {
if $persist {
$zalsa::serde::Serialize::serialize(fields, serializer)
Expand All @@ -193,7 +193,7 @@ macro_rules! setup_tracked_fn {

fn deserialize<'de, D: $zalsa::serde::Deserializer<'de>>(
deserializer: D,
) -> Result<Self::Fields<'static>, D::Error> {
) -> ::std::result::Result<Self::Fields<'static>, D::Error> {
$zalsa::macro_if! {
if $persist {
$zalsa::serde::Deserialize::deserialize(deserializer)
Expand Down Expand Up @@ -329,7 +329,7 @@ macro_rules! setup_tracked_fn {
fn serialize<S: $zalsa::serde::Serializer>(
value: &Self::Output<'_>,
serializer: S,
) -> Result<S::Ok, S::Error> {
) -> ::std::result::Result<S::Ok, S::Error> {
$zalsa::macro_if! {
if $persist {
$zalsa::serde::Serialize::serialize(value, serializer)
Expand All @@ -341,7 +341,7 @@ macro_rules! setup_tracked_fn {

fn deserialize<'de, D: $zalsa::serde::Deserializer<'de>>(
deserializer: D,
) -> Result<Self::Output<'static>, D::Error> {
) -> ::std::result::Result<Self::Output<'static>, D::Error> {
$zalsa::macro_if! {
if $persist {
$zalsa::serde::Deserialize::deserialize(deserializer)
Expand Down
8 changes: 4 additions & 4 deletions components/salsa-macro-rules/src/setup_tracked_struct.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,7 @@ macro_rules! setup_tracked_struct {
fn serialize<S: $zalsa::serde::Serializer>(
fields: &Self::Fields<'_>,
serializer: S,
) -> Result<S::Ok, S::Error> {
) -> ::std::result::Result<S::Ok, S::Error> {
$zalsa::macro_if! {
if $persist {
$($serialize_fn(fields, serializer))?
Expand All @@ -221,7 +221,7 @@ macro_rules! setup_tracked_struct {

fn deserialize<'de, D: $zalsa::serde::Deserializer<'de>>(
deserializer: D,
) -> Result<Self::Fields<'static>, D::Error> {
) -> ::std::result::Result<Self::Fields<'static>, D::Error> {
$zalsa::macro_if! {
if $persist {
$($deserialize_fn(deserializer))?
Expand Down Expand Up @@ -307,7 +307,7 @@ macro_rules! setup_tracked_struct {

$zalsa::macro_if! { $persist =>
impl $zalsa::serde::Serialize for $Struct<'_> {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
fn serialize<S>(&self, serializer: S) -> ::std::result::Result<S::Ok, S::Error>
where
S: $zalsa::serde::Serializer,
{
Expand All @@ -316,7 +316,7 @@ macro_rules! setup_tracked_struct {
}

impl<'de> $zalsa::serde::Deserialize<'de> for $Struct<'_> {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: $zalsa::serde::Deserializer<'de>,
{
Expand Down
4 changes: 4 additions & 0 deletions components/salsa-macros/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ quote = "1.0"
syn = { version = "2.0.104", features = ["full", "visit-mut"] }
synstructure = "0.13.2"

[dev-dependencies]
# For doc-tests
salsa.path = "../../"

[features]
default = []
persistence = []
7 changes: 0 additions & 7 deletions components/salsa-macros/src/db.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,6 @@ use syn::parse::Nothing;
use crate::hygiene::Hygiene;
use crate::token_stream_with_error;

// Source:
//
// #[salsa::db]
// pub struct Database {
// storage: salsa::Storage<Self>,
// }

pub(crate) fn db(
args: proc_macro::TokenStream,
input: proc_macro::TokenStream,
Expand Down
Loading
Loading