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// It would be nice to keep the compiler free of unsafe code
7#![deny(unsafe_code)]
8
9#[cfg(feature = "proc_macro_span")]
10extern crate proc_macro;
11
12use core::future::Future;
13use core::pin::Pin;
14use std::cell::RefCell;
15use std::collections::HashMap;
16use std::rc::Rc;
17#[cfg(feature = "software-renderer")]
18use std::sync::Arc;
19
20pub mod builtin_macros;
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 it 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#[derive(Clone, Debug, Eq, PartialEq, Default)]
64#[non_exhaustive]
65pub enum ComponentSelection {
66    /// All components that inherit from Window.
67    ///
68    /// Note: Components marked for export but lacking Window inheritance are not selected (this will produce a warning),
69    /// For compatibility reason, the last exported component is still selected even if it doesn't inherit Window,
70    /// and if no component is exported, the last component is selected
71    #[default]
72    ExportedWindows,
73
74    /// The Last component (legacy for the viewer / interpreter)
75    ///
76    /// Only the last exported component is generated, regardless if this is a Window or not,
77    /// (and it will be transformed in a Window)
78    LastExported,
79
80    /// The component with the given name is generated
81    Named(String),
82}
83
84#[cfg(feature = "software-renderer")]
85pub type FontCache = Rc<
86    RefCell<
87        std::collections::HashMap<
88            i_slint_common::sharedfontdb::fontdb::ID,
89            fontdue::FontResult<(Arc<fontdue::Font>, Arc<dyn AsRef<[u8]> + Send + Sync>, u32)>,
90        >,
91    >,
92>;
93
94pub type OpenImportFallback =
95    Rc<dyn Fn(String) -> Pin<Box<dyn Future<Output = Option<std::io::Result<String>>>>>>;
96pub type ResourceUrlMapper = Rc<dyn Fn(&str) -> Pin<Box<dyn Future<Output = Option<String>>>>>;
97
98/// CompilationConfiguration allows configuring different aspects of the compiler.
99#[derive(Clone)]
100pub struct CompilerConfiguration {
101    /// Indicate whether to embed resources such as images in the generated output or whether
102    /// to retain references to the resources on the file system.
103    pub embed_resources: EmbedResourcesKind,
104    /// Whether to use SDF when pre-rendering fonts.
105    #[cfg(all(feature = "software-renderer", feature = "sdf-fonts"))]
106    pub use_sdf_fonts: bool,
107    /// The compiler will look in these paths for components used in the file to compile.
108    pub include_paths: Vec<std::path::PathBuf>,
109    /// The compiler will look in these paths for library imports.
110    pub library_paths: HashMap<String, std::path::PathBuf>,
111    /// the name of the style. (eg: "native")
112    pub style: Option<String>,
113
114    /// Callback to load import files which is called if the file could not be found
115    ///
116    /// The callback should open the file specified by the given file name and
117    /// return an future that provides the text content of the file as output.
118    pub open_import_fallback: Option<OpenImportFallback>,
119    /// Callback to map URLs for resources
120    ///
121    /// The function takes the url and returns the mapped URL (or None if not mapped)
122    pub resource_url_mapper: Option<ResourceUrlMapper>,
123
124    /// Run the pass that inlines all the elements.
125    ///
126    /// This may help optimization to optimize the runtime resources usages,
127    /// but at the cost of much more generated code and binary size.
128    pub inline_all_elements: bool,
129
130    /// Compile time scale factor to apply to embedded resources such as images and glyphs.
131    /// If != 1.0 then the scale factor will be set on the `slint::Window`.
132    pub const_scale_factor: f64,
133
134    /// expose the accessible role and properties
135    pub accessibility: bool,
136
137    /// Add support for experimental features
138    pub enable_experimental: bool,
139
140    /// The domain used as one of the parameter to the translate function
141    pub translation_domain: Option<String>,
142    /// When Some, this is the path where the translations are looked at to bundle the translations
143    #[cfg(feature = "bundle-translations")]
144    pub translation_path_bundle: Option<std::path::PathBuf>,
145
146    /// Do not generate the hook to create native menus
147    pub no_native_menu: bool,
148
149    /// C++ namespace
150    pub cpp_namespace: Option<String>,
151
152    /// When true, fail the build when a binding loop is detected with a window layout property
153    /// (otherwise this is a compatibility warning)
154    pub error_on_binding_loop_with_window_layout: bool,
155
156    /// Generate debug information for elements (ids, type names)
157    pub debug_info: bool,
158
159    /// Generate debug hooks to inspect/override properties.
160    pub debug_hooks: Option<std::hash::RandomState>,
161
162    pub components_to_generate: ComponentSelection,
163
164    #[cfg(feature = "software-renderer")]
165    pub font_cache: FontCache,
166}
167
168impl CompilerConfiguration {
169    pub fn new(output_format: OutputFormat) -> Self {
170        let embed_resources = if std::env::var_os("SLINT_EMBED_TEXTURES").is_some()
171            || std::env::var_os("DEP_MCU_BOARD_SUPPORT_MCU_EMBED_TEXTURES").is_some()
172        {
173            #[cfg(not(feature = "software-renderer"))]
174            panic!("the software-renderer feature must be enabled in i-slint-compiler when embedding textures");
175            #[cfg(feature = "software-renderer")]
176            EmbedResourcesKind::EmbedTextures
177        } else if let Ok(var) = std::env::var("SLINT_EMBED_RESOURCES") {
178            let var = var.parse::<bool>().unwrap_or_else(|_|{
179                panic!("SLINT_EMBED_RESOURCES has incorrect value. Must be either unset, 'true' or 'false'")
180            });
181            match var {
182                true => EmbedResourcesKind::EmbedAllResources,
183                false => EmbedResourcesKind::OnlyBuiltinResources,
184            }
185        } else {
186            match output_format {
187                #[cfg(feature = "rust")]
188                OutputFormat::Rust => EmbedResourcesKind::EmbedAllResources,
189                OutputFormat::Interpreter => EmbedResourcesKind::Nothing,
190                _ => EmbedResourcesKind::OnlyBuiltinResources,
191            }
192        };
193
194        let inline_all_elements = match std::env::var("SLINT_INLINING") {
195            Ok(var) => var.parse::<bool>().unwrap_or_else(|_| {
196                panic!(
197                    "SLINT_INLINING has incorrect value. Must be either unset, 'true' or 'false'"
198                )
199            }),
200            // Currently, the interpreter needs the inlining to be on.
201            Err(_) => output_format == OutputFormat::Interpreter,
202        };
203
204        let const_scale_factor = std::env::var("SLINT_SCALE_FACTOR")
205            .ok()
206            .and_then(|x| x.parse::<f64>().ok())
207            .filter(|f| *f > 0.)
208            .unwrap_or(1.);
209
210        let enable_experimental = std::env::var_os("SLINT_ENABLE_EXPERIMENTAL_FEATURES").is_some();
211
212        let debug_info = std::env::var_os("SLINT_EMIT_DEBUG_INFO").is_some();
213
214        let cpp_namespace = match output_format {
215            #[cfg(feature = "cpp")]
216            OutputFormat::Cpp(config) => match config.namespace {
217                Some(namespace) => Some(namespace),
218                None => match std::env::var("SLINT_CPP_NAMESPACE") {
219                    Ok(namespace) => Some(namespace),
220                    Err(_) => None,
221                },
222            },
223            _ => None,
224        };
225
226        Self {
227            embed_resources,
228            include_paths: Default::default(),
229            library_paths: Default::default(),
230            style: Default::default(),
231            open_import_fallback: None,
232            resource_url_mapper: None,
233            inline_all_elements,
234            const_scale_factor,
235            accessibility: true,
236            enable_experimental,
237            translation_domain: None,
238            no_native_menu: false,
239            cpp_namespace,
240            error_on_binding_loop_with_window_layout: false,
241            debug_info,
242            debug_hooks: None,
243            components_to_generate: ComponentSelection::ExportedWindows,
244            #[cfg(feature = "software-renderer")]
245            font_cache: Default::default(),
246            #[cfg(all(feature = "software-renderer", feature = "sdf-fonts"))]
247            use_sdf_fonts: false,
248            #[cfg(feature = "bundle-translations")]
249            translation_path_bundle: std::env::var("SLINT_BUNDLE_TRANSLATIONS")
250                .ok()
251                .map(|x| x.into()),
252        }
253    }
254
255    #[cfg(feature = "software-renderer")]
256    fn load_font_by_id(
257        &self,
258        face_id: i_slint_common::sharedfontdb::fontdb::ID,
259    ) -> fontdue::FontResult<(Arc<fontdue::Font>, Arc<dyn AsRef<[u8]> + Send + Sync>, u32)> {
260        self.font_cache
261            .borrow_mut()
262            .entry(face_id)
263            .or_insert_with(|| {
264                i_slint_common::sharedfontdb::FONT_DB.with(|fontdb| {
265                    fontdb
266                        .borrow()
267                        .with_face_data(face_id, |font_data, face_index| {
268                            fontdue::Font::from_bytes(
269                                font_data,
270                                fontdue::FontSettings {
271                                    collection_index: face_index,
272                                    scale: 40.,
273                                    ..Default::default()
274                                },
275                            )
276                            .map(|fontdue_font| {
277                                (
278                                    Arc::new(fontdue_font),
279                                    Arc::new(font_data.to_vec())
280                                        as Arc<dyn AsRef<[u8]> + Send + Sync>,
281                                    face_index,
282                                )
283                            })
284                        })
285                        .unwrap_or_else(|| fontdue::FontResult::Err("internal error: corrupt font"))
286                })
287            })
288            .clone()
289    }
290}
291
292fn prepare_for_compile(
293    diagnostics: &mut diagnostics::BuildDiagnostics,
294    #[allow(unused_mut)] mut compiler_config: CompilerConfiguration,
295) -> typeloader::TypeLoader {
296    #[cfg(feature = "software-renderer")]
297    if compiler_config.embed_resources == EmbedResourcesKind::EmbedTextures {
298        // HACK: disable accessibility when compiling for the software renderer
299        // accessibility is not supported with backend that support software renderer anyway
300        compiler_config.accessibility = false;
301    }
302
303    diagnostics.enable_experimental = compiler_config.enable_experimental;
304
305    let global_type_registry = if compiler_config.enable_experimental {
306        crate::typeregister::TypeRegister::builtin_experimental()
307    } else {
308        crate::typeregister::TypeRegister::builtin()
309    };
310
311    typeloader::TypeLoader::new(global_type_registry, compiler_config, diagnostics)
312}
313
314pub async fn compile_syntax_node(
315    doc_node: parser::SyntaxNode,
316    mut diagnostics: diagnostics::BuildDiagnostics,
317    #[allow(unused_mut)] mut compiler_config: CompilerConfiguration,
318) -> (object_tree::Document, diagnostics::BuildDiagnostics, typeloader::TypeLoader) {
319    let mut loader = prepare_for_compile(&mut diagnostics, compiler_config);
320
321    let doc_node: parser::syntax_nodes::Document = doc_node.into();
322
323    let type_registry =
324        Rc::new(RefCell::new(typeregister::TypeRegister::new(&loader.global_type_registry)));
325    let (foreign_imports, reexports) =
326        loader.load_dependencies_recursively(&doc_node, &mut diagnostics, &type_registry).await;
327
328    let mut doc = crate::object_tree::Document::from_node(
329        doc_node,
330        foreign_imports,
331        reexports,
332        &mut diagnostics,
333        &type_registry,
334    );
335
336    if !diagnostics.has_errors() {
337        passes::run_passes(&mut doc, &mut loader, false, &mut diagnostics).await;
338    } else {
339        // Don't run all the passes in case of errors because because some invariants are not met.
340        passes::run_import_passes(&doc, &loader, &mut diagnostics);
341    }
342    (doc, diagnostics, loader)
343}
344
345/// Pass a file to the compiler and process it fully, applying all the
346/// necessary compilation passes.
347///
348/// This returns a `Tuple` containing the actual cleaned `path` to the file,
349/// a set of `BuildDiagnostics` and a `TypeLoader` with all compilation passes applied.
350pub async fn load_root_file(
351    path: &Path,
352    source_path: &Path,
353    source_code: String,
354    mut diagnostics: diagnostics::BuildDiagnostics,
355    #[allow(unused_mut)] mut compiler_config: CompilerConfiguration,
356) -> (std::path::PathBuf, diagnostics::BuildDiagnostics, typeloader::TypeLoader) {
357    let mut loader = prepare_for_compile(&mut diagnostics, compiler_config);
358
359    let (path, _) =
360        loader.load_root_file(path, source_path, source_code, false, &mut diagnostics).await;
361
362    (path, diagnostics, loader)
363}
364
365/// Pass a file to the compiler and process it fully, applying all the
366/// necessary compilation passes, just like `load_root_file`.
367///
368/// This returns a `Tuple` containing the actual cleaned `path` to the file,
369/// a set of `BuildDiagnostics`, a `TypeLoader` with all compilation passes
370/// applied and another `TypeLoader` with a minimal set of passes applied to it.
371pub async fn load_root_file_with_raw_type_loader(
372    path: &Path,
373    source_path: &Path,
374    source_code: String,
375    mut diagnostics: diagnostics::BuildDiagnostics,
376    #[allow(unused_mut)] mut compiler_config: CompilerConfiguration,
377) -> (
378    std::path::PathBuf,
379    diagnostics::BuildDiagnostics,
380    typeloader::TypeLoader,
381    Option<typeloader::TypeLoader>,
382) {
383    let mut loader = prepare_for_compile(&mut diagnostics, compiler_config);
384
385    let (path, raw_type_loader) =
386        loader.load_root_file(path, source_path, source_code, true, &mut diagnostics).await;
387
388    (path, diagnostics, loader, raw_type_loader)
389}
i_slint_compiler/lib.rs

i_slint_compiler/
lib.rs
