chandeliers_san/lib.rs
1//! Perform verification of a Candle AST all the way down to code generation.
2//!
3//! The entry point for this entire crate is in constructing an AST
4//! in `ast::Prog`, and then you should do the following in exactly that order
5//! (some steps assume that the previous is completed without errors)
6//!
7//! 0. From a parsed result, construct an `ast::Prog`.
8//!
9//! 1. Resolving causality.
10//! by `causality::Causality`
11//!
12//! (will perform rearrangements of the declarations so
13//! that there are no cycles)
14//!
15//! 2. Typechecking
16//! by `typecheck::TypeCheckStmt`
17//!
18//! (if any causality errors remain they may or may not
19//! appear as "unknown variable" errors at this stage,
20//! but these errors are both less reliable and less
21//! understandable than the ones triggered in `causality`)
22//!
23//! 3. Clockchecking
24//! by `clockcheck::ClockCheckDecl`
25//!
26//! 4. Depth resolution
27//! by `positivity::MakePositive`
28//!
29//! 5. Codegen
30//! by `quote::ToTokens` in `codegen`
31//!
32//! (errors remaining at this stage will almost always
33//! become hard compilation errors by Rustc, which will
34//! invariably be an order of magnitude harder to debug)
35//!
36//! All of the above steps are optional from the point of view of the
37//! type system because at the end of step 0 you already have an AST
38//! that you could do codegen on, but skipping them will very likely
39//! result in at the best compilation errors that are harder to understand
40//! (e.g. failure to uphold causality might result in Rustc complaining
41//! that some type has a size unknown at compile-time and that you should
42//! insert a Box, this is a symptom and clearly not a cause of the issue)
43//! and at the worst code that compiles but may produce a `Nil` ouput,
44//! which will then be a runtime issue.
45//!
46//! ...or you could just use a proc macro from a parent crate that will
47//! automatically perform all these steps in the correct order and collect
48//! errors.
49//!
50//! Be careful that some steps take `&mut ast::Prog` and return
51//! `Result<(), TokenStream>`, while some steps instead take `ast::Prog`
52//! and return `Result<ast::Prog, TokenStream>`.
53//! There are internal implementation details that make these things difficult
54//! to implement in other ways, but you should be careful not to drop your
55//! AST because you thought it was changed in-place.
56
57#![feature(lint_reasons)]
58#![warn(
59 missing_docs,
60 unused_crate_dependencies,
61 unused_macro_rules,
62 variant_size_differences,
63 clippy::allow_attributes,
64 clippy::allow_attributes_without_reason,
65 clippy::expect_used,
66 clippy::indexing_slicing,
67 clippy::missing_docs_in_private_items,
68 clippy::multiple_inherent_impl,
69 clippy::panic,
70 clippy::pedantic,
71 clippy::str_to_string,
72 clippy::unreachable,
73 clippy::unwrap_used,
74 clippy::use_debug
75)]
76
77pub mod ast;
78pub mod candle;
79pub mod causality;
80pub mod clockcheck;
81pub mod codegen;
82pub mod positivity;
83pub mod sp;
84pub mod typecheck;