i_slint_compiler/
lib.rs

1// Copyright © SixtyFPS GmbH <info@slint.dev>
2// SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0
3
4#![doc = include_str!("README.md")]
5#![doc(html_logo_url = "https://slint.dev/logo/slint-logo-square-light.svg")]
6#![cfg_attr(docsrs, feature(doc_cfg))]
7// It would be nice to keep the compiler free of unsafe code
8#![deny(unsafe_code)]
9
10#[cfg(feature = "proc_macro_span")]
11extern crate proc_macro;
12
13use core::future::Future;
14use core::pin::Pin;
15use std::cell::RefCell;
16use std::collections::HashMap;
17use std::rc::Rc;
18
19pub mod builtin_macros;
20pub mod data_uri;
21pub mod diagnostics;
22pub mod embedded_resources;
23pub mod expression_tree;
24pub mod fileaccess;
25pub mod generator;
26pub mod langtype;
27pub mod layout;
28pub mod lexer;
29pub mod literals;
30pub mod llr;
31pub(crate) mod load_builtins;
32pub mod lookup;
33pub mod namedreference;
34pub mod object_tree;
35pub mod parser;
36pub mod pathutils;
37#[cfg(feature = "bundle-translations")]
38pub mod translations;
39pub mod typeloader;
40pub mod typeregister;
41
42pub mod passes;
43
44use crate::generator::OutputFormat;
45use std::path::Path;
46
47/// Specify how the resources are embedded by the compiler
48#[derive(Clone, Copy, Debug, Eq, PartialEq)]
49pub enum EmbedResourcesKind {
50    /// Embeds nothing (only useful for interpreter)
51    Nothing,
52    /// Only embed builtin resources
53    OnlyBuiltinResources,
54    /// Do not embed resources, but list them in the Document as if they were embedded
55    ListAllResources,
56    /// Embed all images resources (the content of their files)
57    EmbedAllResources,
58    #[cfg(feature = "software-renderer")]
59    /// Embed raw texture (process images and fonts)
60    EmbedTextures,
61}
62
63/// This enum specifies the default translation context when no context is explicitly
64/// specified in the `@tr("context" => ...)` macro.
65#[derive(Clone, Debug, Eq, PartialEq)]
66#[non_exhaustive]
67pub enum DefaultTranslationContext {
68    /// The default translation context is the component name in which the `@tr` is written.
69    ///
70    /// This is the default behavior of `slint-tr-extractor`.
71    ComponentName,
72    /// Opt out of the default translation context.
73    ///
74    /// When using this option, invoke `slint-tr-extractor` with `--no-default-translation-context`
75    /// to make sure that the translation files have no context for strings which didn't specify a context.
76    None,
77}
78
79#[derive(Clone, Debug, Eq, PartialEq, Default)]
80#[non_exhaustive]
81pub enum ComponentSelection {
82    /// All components that inherit from Window.
83    ///
84    /// Note: Components marked for export but lacking Window inheritance are not selected (this will produce a warning),
85    /// For compatibility reason, the last exported component is still selected even if it doesn't inherit Window,
86    /// and if no component is exported, the last component is selected
87    #[default]
88    ExportedWindows,
89
90    /// The Last component (legacy for the viewer / interpreter)
91    ///
92    /// Only the last exported component is generated, regardless if this is a Window or not,
93    /// (and it will be transformed in a Window)
94    LastExported,
95
96    /// The component with the given name is generated
97    Named(String),
98}
99
100/// Type alias for the callback to open files mentioned in `import` statements
101///
102/// This is a dyn-compatible version of:
103///
104/// ```ignore
105/// async fn(String) -> Option<std::io::Result<String>>
106/// ```
107///
108/// Unfortunately AsyncFn is not dyn-compatible yet.
109pub type OpenImportCallback =
110    Rc<dyn Fn(String) -> Pin<Box<dyn Future<Output = Option<std::io::Result<String>>>>>>;
111pub type ResourceUrlMapper = Rc<dyn Fn(&str) -> Pin<Box<dyn Future<Output = Option<String>>>>>;
112
113/// CompilationConfiguration allows configuring different aspects of the compiler.
114#[derive(Clone)]
115pub struct CompilerConfiguration {
116    /// Indicate whether to embed resources such as images in the generated output or whether
117    /// to retain references to the resources on the file system.
118    pub embed_resources: EmbedResourcesKind,
119    /// Whether to use SDF when pre-rendering fonts.
120    #[cfg(all(feature = "software-renderer", feature = "sdf-fonts"))]
121    pub use_sdf_fonts: bool,
122    /// The compiler will look in these paths for components used in the file to compile.
123    pub include_paths: Vec<std::path::PathBuf>,
124    /// The compiler will look in these paths for library imports.
125    pub library_paths: HashMap<String, std::path::PathBuf>,
126    /// the name of the style. (eg: "native")
127    pub style: Option<String>,
128
129    /// Callback to load import files
130    ///
131    /// The callback should open the file specified by the given file name and
132    /// return a future that provides the text content of the file as output.
133    pub open_import_callback: Option<OpenImportCallback>,
134    /// Callback to map URLs for resources
135    ///
136    /// The function takes the url and returns the mapped URL (or None if not mapped)
137    pub resource_url_mapper: Option<ResourceUrlMapper>,
138
139    /// Run the pass that inlines all the elements.
140    ///
141    /// This may help optimization to optimize the runtime resources usages,
142    /// but at the cost of much more generated code and binary size.
143    pub inline_all_elements: bool,
144
145    /// Compile time scale factor to apply to embedded resources such as images and glyphs.
146    /// It will also be set as a const scale factor on the `slint::Window`.
147    pub const_scale_factor: Option<f32>,
148
149    /// expose the accessible role and properties
150    pub accessibility: bool,
151
152    /// Add support for experimental features
153    pub enable_experimental: bool,
154
155    /// The domain used as one of the parameter to the translate function
156    pub translation_domain: Option<String>,
157    /// When Some, this is the path where the translations are looked at to bundle the translations
158    #[cfg(feature = "bundle-translations")]
159    pub translation_path_bundle: Option<std::path::PathBuf>,
160    /// Default translation context
161    pub default_translation_context: DefaultTranslationContext,
162
163    /// Do not generate the hook to create native menus
164    pub no_native_menu: bool,
165
166    /// C++ namespace
167    pub cpp_namespace: Option<String>,
168
169    /// When true, fail the build when a binding loop is detected with a window layout property
170    /// (otherwise this is a compatibility warning)
171    pub error_on_binding_loop_with_window_layout: bool,
172
173    /// Generate debug information for elements (ids, type names)
174    pub debug_info: bool,
175
176    /// Generate debug hooks to inspect/override properties.
177    pub debug_hooks: Option<std::hash::RandomState>,
178
179    pub components_to_generate: ComponentSelection,
180
181    /// The name of the library when compiling as a library.
182    pub library_name: Option<String>,
183
184    /// Specify the Rust module to place the generated code in.
185    pub rust_module: Option<String>,
186}
187
188impl CompilerConfiguration {
189    pub fn new(output_format: OutputFormat) -> Self {
190        let embed_resources = if std::env::var_os("SLINT_EMBED_TEXTURES").is_some()
191            || std::env::var_os("DEP_MCU_BOARD_SUPPORT_MCU_EMBED_TEXTURES").is_some()
192        {
193            #[cfg(not(feature = "software-renderer"))]
194            panic!(
195                "the software-renderer feature must be enabled in i-slint-compiler when embedding textures"
196            );
197            #[cfg(feature = "software-renderer")]
198            EmbedResourcesKind::EmbedTextures
199        } else if let Ok(var) = std::env::var("SLINT_EMBED_RESOURCES") {
200            let var = var.parse::<bool>().unwrap_or_else(|_|{
201                panic!("SLINT_EMBED_RESOURCES has incorrect value. Must be either unset, 'true' or 'false'")
202            });
203            match var {
204                true => EmbedResourcesKind::EmbedAllResources,
205                false => EmbedResourcesKind::OnlyBuiltinResources,
206            }
207        } else {
208            match output_format {
209                #[cfg(feature = "rust")]
210                OutputFormat::Rust => EmbedResourcesKind::EmbedAllResources,
211                OutputFormat::Interpreter => EmbedResourcesKind::Nothing,
212                _ => EmbedResourcesKind::OnlyBuiltinResources,
213            }
214        };
215
216        let inline_all_elements = match std::env::var("SLINT_INLINING") {
217            Ok(var) => var.parse::<bool>().unwrap_or_else(|_| {
218                panic!(
219                    "SLINT_INLINING has incorrect value. Must be either unset, 'true' or 'false'"
220                )
221            }),
222            // Currently, the interpreter needs the inlining to be on.
223            Err(_) => output_format == OutputFormat::Interpreter,
224        };
225
226        let const_scale_factor = std::env::var("SLINT_SCALE_FACTOR")
227            .ok()
228            .and_then(|x| x.parse::<f32>().ok())
229            .filter(|f| *f > 0.);
230
231        let enable_experimental = std::env::var_os("SLINT_ENABLE_EXPERIMENTAL_FEATURES").is_some();
232
233        let debug_info = std::env::var_os("SLINT_EMIT_DEBUG_INFO").is_some();
234
235        let cpp_namespace = match output_format {
236            #[cfg(feature = "cpp")]
237            OutputFormat::Cpp(config) => match config.namespace {
238                Some(namespace) => Some(namespace),
239                None => std::env::var("SLINT_CPP_NAMESPACE").ok(),
240            },
241            _ => None,
242        };
243
244        let style = std::env::var("SLINT_STYLE").ok();
245
246        Self {
247            embed_resources,
248            include_paths: Default::default(),
249            library_paths: Default::default(),
250            style,
251            open_import_callback: None,
252            resource_url_mapper: None,
253            inline_all_elements,
254            const_scale_factor,
255            accessibility: true,
256            enable_experimental,
257            translation_domain: None,
258            default_translation_context: DefaultTranslationContext::ComponentName,
259            no_native_menu: false,
260            cpp_namespace,
261            error_on_binding_loop_with_window_layout: false,
262            debug_info,
263            debug_hooks: None,
264            components_to_generate: ComponentSelection::ExportedWindows,
265            #[cfg(all(feature = "software-renderer", feature = "sdf-fonts"))]
266            use_sdf_fonts: false,
267            #[cfg(feature = "bundle-translations")]
268            translation_path_bundle: std::env::var("SLINT_BUNDLE_TRANSLATIONS")
269                .ok()
270                .map(|x| x.into()),
271            library_name: None,
272            rust_module: None,
273        }
274    }
275}
276
277/// Prepare for compilation of the source file
278/// - storing parser configuration
279/// - setting up the parser
280fn prepare_for_compile(
281    diagnostics: &mut diagnostics::BuildDiagnostics,
282    #[allow(unused_mut)] mut compiler_config: CompilerConfiguration,
283) -> typeloader::TypeLoader {
284    #[cfg(feature = "software-renderer")]
285    if compiler_config.embed_resources == EmbedResourcesKind::EmbedTextures {
286        // HACK: disable accessibility when compiling for the software renderer
287        // accessibility is not supported with backend that support software renderer anyway
288        compiler_config.accessibility = false;
289    }
290
291    diagnostics.enable_experimental = compiler_config.enable_experimental;
292
293    typeloader::TypeLoader::new(compiler_config, diagnostics)
294}
295
296pub async fn compile_syntax_node(
297    doc_node: parser::SyntaxNode,
298    mut diagnostics: diagnostics::BuildDiagnostics,
299    #[allow(unused_mut)] mut compiler_config: CompilerConfiguration,
300) -> (object_tree::Document, diagnostics::BuildDiagnostics, typeloader::TypeLoader) {
301    let mut loader = prepare_for_compile(&mut diagnostics, compiler_config);
302
303    let doc_node: parser::syntax_nodes::Document = doc_node.into();
304
305    let type_registry =
306        Rc::new(RefCell::new(typeregister::TypeRegister::new(&loader.global_type_registry)));
307    let (foreign_imports, reexports) =
308        loader.load_dependencies_recursively(&doc_node, &mut diagnostics, &type_registry).await;
309
310    let mut doc = crate::object_tree::Document::from_node(
311        doc_node,
312        foreign_imports,
313        reexports,
314        &mut diagnostics,
315        &type_registry,
316    );
317
318    if !diagnostics.has_errors() {
319        passes::run_passes(&mut doc, &mut loader, false, &mut diagnostics).await;
320    } else {
321        // Don't run all the passes in case of errors because because some invariants are not met.
322        passes::run_import_passes(&doc, &loader, &mut diagnostics);
323    }
324    (doc, diagnostics, loader)
325}
326
327/// Pass a file to the compiler and process it fully, applying all the
328/// necessary compilation passes.
329///
330/// This returns a `Tuple` containing the actual cleaned `path` to the file,
331/// a set of `BuildDiagnostics` and a `TypeLoader` with all compilation passes applied.
332pub async fn load_root_file(
333    path: &Path,
334    source_path: &Path,
335    source_code: String,
336    mut diagnostics: diagnostics::BuildDiagnostics,
337    #[allow(unused_mut)] mut compiler_config: CompilerConfiguration,
338) -> (std::path::PathBuf, diagnostics::BuildDiagnostics, typeloader::TypeLoader) {
339    let mut loader = prepare_for_compile(&mut diagnostics, compiler_config);
340
341    let (path, _) =
342        loader.load_root_file(path, source_path, source_code, false, &mut diagnostics).await;
343
344    (path, diagnostics, loader)
345}
346
347/// Pass a file to the compiler and process it fully, applying all the
348/// necessary compilation passes, just like `load_root_file`.
349///
350/// This returns a `Tuple` containing the actual cleaned `path` to the file,
351/// a set of `BuildDiagnostics`, a `TypeLoader` with all compilation passes
352/// applied and another `TypeLoader` with a minimal set of passes applied to it.
353pub async fn load_root_file_with_raw_type_loader(
354    path: &Path,
355    source_path: &Path,
356    source_code: String,
357    mut diagnostics: diagnostics::BuildDiagnostics,
358    #[allow(unused_mut)] mut compiler_config: CompilerConfiguration,
359) -> (
360    std::path::PathBuf,
361    diagnostics::BuildDiagnostics,
362    typeloader::TypeLoader,
363    Option<typeloader::TypeLoader>,
364) {
365    let mut loader = prepare_for_compile(&mut diagnostics, compiler_config);
366
367    let (path, raw_type_loader) =
368        loader.load_root_file(path, source_path, source_code, true, &mut diagnostics).await;
369
370    (path, diagnostics, loader, raw_type_loader)
371}
i_slint_compiler/lib.rs

i_slint_compiler/
lib.rs
