ferroui_build_scan/
lib.rs

1//! ferroui-build-scan
2//!
3//! The build-time type model of a crate, the source scanner that fills it and
4//! the export of the model through the build script of the crate
5//! (docs/porting/xaml.md, 9.5.1, 9.5.13 and 9.6.3). No counterpart upstream:
6//! upstream's compiler reads the types of a referenced assembly from its
7//! metadata; a Rust crate has none, so a crate writes what its declarations
8//! state into its `.xamlmeta` and hands the file to the crates that depend on
9//! it.
10//!
11//! The crate depends on the standard library and on the three crates the
12//! scanner reads Rust source with, and on nothing of the framework: the base
13//! crate, the controls and the XAML runtime library take it as a build
14//! dependency to export their own models, which a crate that depends on the
15//! compiler (`ferroui-build`, which links the three) could not be.
16//!
17//! ```ignore
18//! // build.rs of a crate that declares types and has no documents
19//! fn main() {
20//!     ferroui_build_scan::export::Export::from_env().run();
21//! }
22//! ```
23//!
24//! ```toml
25//! # Cargo.toml of that crate
26//! [package]
27//! build = "build.rs"
28//! links = "<crate>_xaml"
29//!
30//! [build-dependencies]
31//! ferroui-build-scan = { workspace = true }
32//! ```
33//!
34//! What is here:
35//!
36//! - [`model`]: the type model of a crate (`AssemblyModel`, `TypeModel`,
37//!   `MemberModel`, `RegisteredModel`) and its file, the `.xamlmeta` of format
38//!   2, which keeps the documents of format 1 where the compiler reads them;
39//! - [`xaml_metadata`]: the part of the file the compiler of a crate reads of
40//!   another crate, its compiled documents (format 1);
41//! - [`scanner`]: the source scanner, which fills the model from the
42//!   declaration macros of the sources of a crate (`scan_crate`), linking
43//!   nothing;
44//! - [`model_set`]: the models of several crates read together, so that a
45//!   type or a property of one crate is found by the path another crate names
46//!   it by;
47//! - [`call_forms`]: how generated code calls each member a declaration states
48//!   by a callable (xaml.md 9.5.3), chosen at the end of a scan and written
49//!   into the model;
50//! - [`export`]: the scan of the crate whose build script is running, with the
51//!   models of its dependencies, written into its `.xamlmeta`.
52//!
53//! The compiler over the models (`ModelTypeSystem`, `ModelEmitTypes`,
54//! `Build::compile_xaml`) is in `ferroui-build`, which exports every module of
55//! this crate under its own name.
56//!
57//! # The host and the target
58//!
59//! A build script runs on the host whatever the target of the build is, and
60//! the scan reads the sources as text: a `cfg` condition is recorded with the
61//! declaration it guards and never evaluated, so the model of a crate is the
62//! same text for every target and every set of features. A cross build (the
63//! browser build of the framework for `wasm32`) builds this crate and the
64//! three it depends on for the host once and exports the same files.
65
66#![forbid(unsafe_code)]
67
68pub mod call_forms;
69pub mod export;
70mod json;
71pub mod model;
72pub mod model_set;
73pub mod scanner;
74pub mod xaml_metadata;
75
76/// The XML namespace of the framework, as the base crate states it
77/// (`ferroui_base::metadata::FERRO_XML_NAMESPACE`). The scanner reads the
78/// `MarkupAssembly` of a crate that names the constant; this crate cannot link the
79/// base crate (the base crate scans itself with it), so the text is stated here, and a
80/// test of `ferroui-build`, which links both, compares the two.
81pub const FERRO_XML_NAMESPACE: &str = "https://github.com/ferroui";
82
83/// The key of the assembly metadata that turns source information on
84/// (`ferroui_base::metadata::MarkupAssembly::CREATE_SOURCE_INFO`), stated here for the
85/// reason [`FERRO_XML_NAMESPACE`] is.
86pub const CREATE_SOURCE_INFO: &str = "FerroXamlCreateSourceInfo";
87
88/// The key of the assembly metadata that makes `{Binding}` a compiled binding by default
89/// (`ferroui_base::metadata::MarkupAssembly::USE_COMPILED_BINDINGS_BY_DEFAULT`), stated here
90/// for the reason [`FERRO_XML_NAMESPACE`] is.
91pub const USE_COMPILED_BINDINGS_BY_DEFAULT: &str = "FerroUseCompiledBindingsByDefault";
ferroui_build_scan/lib.rs

ferroui_build_scan/
lib.rs
