htl_core/link.rs
1//! Linking: the `require` closure of one entry file, as a [`Bundle`].
2//!
3//! Starting at the entry, every `require("<literal>")` is followed (only string
4//! literals: a `require(expr)` cannot be resolved statically, list its targets under
5//! `extra`). `.tl` modules are type-checked and generated; plain `.lua` modules (a
6//! vendored dependency, say) are taken as they are. A name that runs from no file of the
7//! project — one the host provides, one only a `.d.tl` declares — is recorded as
8//! host-provided, as is anything listed in `host`. Any other unresolved `require` is an
9//! error: the point of a bundle is that "module not found" happens here, not on the
10//! first `require` at the customer's machine.
11//!
12//! # The host's names
13//!
14//! Which names the host provides is the project model's to say
15//! (`model::Project::provided`: `#[host_module]`s in the crate around the project,
16//! `[build] host`, `std.*`), and the callers that have a model — `htl build`,
17//! `include_bundle!` — put all of them in [`LinkOptions::host`]. A name there is not
18//! walked. When a file of the model implements it as well, the model refuses the name
19//! (its resolver's `HostShadowed`): the check reports that at a checked file's
20//! `require`, and the linker reports it at a plain `.lua`'s, which nothing checks — the
21//! same split as for a name two files implement. The file is never bundled: every run
22//! with the host loads the host's module, which `package.preload` answers first.
23//!
24//! # Declared names
25//!
26//! A name the model has only a declaration for — a `.d.tl` and no `.tl` or `.lua`, like
27//! `types/socket/http.d.tl` for a LuaSocket installed on the machine — is provided by the
28//! environment at run time, and is left out of the bundle the same way. That, too, is the
29//! model's answer (`model::Provider::Declared`, from its resolver's `provides`), which the
30//! linker asks through [`Htl::model_provides`] for a name that resolves to a declaration.
31//! It does not decide it from a lookup of its own, as it did before the model answered
32//! it (#321): only for a file in no project, or a name the model has nothing under, is a
33//! declaration with no `.lua` found behind it on the search path taken to be the host's —
34//! there is no model to ask. The outcome is the same either way; what changed is which of
35//! the two says so.
36//!
37//! A `require` the generator erased is not a dependency of anything that runs. Teal's
38//! `local type x = require("x")` is a type declaration when the alias is only ever used as
39//! a type, and the generator drops the whole statement; the checked file's census marks
40//! such a site ([`RequireSite::erased`], from the generator's own flag) and the linker
41//! skips it — not bundled, not the host's, not missing — so a bundle that imports a
42//! record of types from a `.d.tl` asks the host for nothing. The same alias read as a
43//! value keeps its `require`, and is counted like any other; so is a `global type`.
44//!
45//! # The store
46//!
47//! Generating a module is the expensive part of linking — the Teal check behind it costs
48//! about a second per few thousand lines, against milliseconds for Lua's own compiler to
49//! turn the result into bytecode — and it is the part the run cache already answers for.
50//! [`link_with`] takes a [`LinkStore`]: for every typed module it asks the store for the
51//! module's `gen` entry (the one `htl test` writes and replays), and an entry whose inputs
52//! and probes still hold stands in for the check, its generated Lua for `gen_lua`. A miss
53//! generates as before and writes the entry, so `htl build`, `htl test` and the
54//! `include_bundle!` / `include_tl!` macros feed one another (#100).
55//!
56//! Bytecode is never stored: compiling it is cheap, and an entry that carried it would
57//! have to be keyed on the strip and debug flags and on the Lua the bytecode is for, for
58//! no saving. What a bundle contains — module order, fingerprint, host modules — is the
59//! same whether a module was generated or replayed.
60//!
61//! # `htl build`, and the bundle from Rust
62//!
63//! `htl build src/main.tl -o app.hb` follows `require("<literal>")` from the entry and
64//! links everything it reaches into one file; `htl run app.hb` runs it, and a host does
65//! [`Htl::run_bundle`] after registering its modules. A missing `require` is said once,
66//! and the line says where to declare the module: in an `x.d.tl`, under `[build] host`,
67//! or under `[build] extra` for a dynamic `require` (`--extra`, `--host` on the command
68//! line). The payload is stripped bytecode unless `--debug` ([`LinkOptions::debug`]) or
69//! `--source` ([`LinkOptions::source`]); `htl bundle info app.hb` prints what the file
70//! records ([`crate::bundle`]). `htl build <dir>` is the older form, every `.tl` under a
71//! directory. A second [`Htl::install_bundle`] writes nothing; a newer bundle goes into a
72//! running state with [`Htl::replace_bundle`].
73//!
74//! From Rust, `include_bundle!` does the same at `cargo build`:
75//!
76//! ```rust,ignore
77//! const BUNDLE: &[u8] = htl::include_bundle!("src/main.tl", extra = ["modkit"]);
78//! // The host's names are the project's, as for `htl build`: `Host`'s `#[host_module]`, `[build]
79//! // host` and `std.*` are not bundled. `host = [..]` is optional, for a module the project
80//! // cannot see (registered by hand, or by another crate). payload = "source" for a target
81//! // whose Lua header differs (big-endian, non-default number types; see `bundle`);
82//! // debug = true keeps line numbers. [build] extra in htl.toml is merged in.
83//! Host { .. }.htl_preload(&h)?;
84//! h.run_bundle(&htl::bundle::Bundle::decode(BUNDLE)?, &args)?;
85//! ```
86//!
87//! From a `build.rs`, [`link`] does the same: take the bundle through [`Linked::bundle`]
88//! / [`Linked::into_bundle`], and emit `cargo:rerun-if-changed=<file>` for each of
89//! [`Linked::inputs`].
90use crate::bundle::{Bundle, Kind, Module};
91use crate::cache::{self, Cache};
92use crate::{CheckInfo, Htl, RequireSite};
93use anyhow::{Context, Result};
94use std::collections::{BTreeSet, HashSet, VecDeque};
95use std::path::{Path, PathBuf};
96
97/// What a link is asked for beyond the entry file: how modules are stored, and which ones
98/// the walk would otherwise miss or must not take.
99///
100/// Owned and `Default`, and it crosses the proc-macro boundary as a value — the borrowed
101/// half of a link's inputs is [`LinkStore`].
102#[derive(Debug, Clone, Default)]
103pub struct LinkOptions {
104 /// Keep debug info (line numbers, local names) in bytecode. Off = stripped, and
105 /// stripping takes the traceback with it: every frame of a run-time failure reads `?`,
106 /// with no line. On, a frame reads `depth:8` — the module the bundle knows, since a
107 /// bundle holds modules rather than files.
108 pub debug: bool,
109 /// Store generated Lua source instead of bytecode (portable across Lua builds):
110 /// larger and readable, bound to no Lua build, and named the same way as `debug`.
111 pub source: bool,
112 /// Modules to include even if no literal `require` reaches them.
113 pub extra: Vec<String>,
114 /// Modules the host provides at run time, besides those declared only by a `.d.tl`
115 /// (which the model answers for — see the module doc).
116 /// A name here is left out of the bundle and not walked, whether or not a file on
117 /// the search path could answer it — a library that bundles its own module names it
118 /// here in the binary's bundle so the two do not carry it twice.
119 ///
120 /// A caller with the project's model puts every name the model says the host provides
121 /// here (`model::Project::provided`), as `htl build` and `include_bundle!` do; what
122 /// else it lists is added to those. A file of the model under one of them is an error
123 /// of the model's, not something this list can override (see the module doc).
124 pub host: Vec<String>,
125 /// The module name the entry is served under in the bundle. `None` derives it from
126 /// the file alone: its stem, or its directory's name for an `init.tl`.
127 ///
128 /// A caller that has the project's model (`model::Project::locate`) passes the name it
129 /// gives the file, which is the one a `require` elsewhere in the project writes —
130 /// `src/app/main.tl` is `app.main` there, and a bundle serving it as `main` would
131 /// answer a name nothing asks for. The file alone cannot say which directory the
132 /// name starts from, so the default is right only for an entry at the top of the
133 /// source root.
134 pub entry_name: Option<String>,
135}
136
137/// The run cache as the linker uses it: the store, plus what the store needs to key and
138/// to validate an entry and that only the caller knows.
139///
140/// A borrowed view rather than part of [`LinkOptions`], which is owned and `Default` and
141/// crosses the proc-macro boundary as a value; the store lives for one command or one
142/// macro expansion, the options may not.
143#[derive(Clone, Copy)]
144pub struct LinkStore<'a> {
145 /// The store itself: where a typed module's generated Lua and its check are looked up
146 /// before the checker is asked, and written back after.
147 pub cache: &'a Cache,
148 /// The lint selection in force, as [`cache::gen_key`] takes it: an entry generated
149 /// under different lints reports different lints, and must not be reused.
150 pub lint: Option<&'a str>,
151 /// The project root, for the directories a `require` could resolve in.
152 pub root: &'a Path,
153 /// The project's `htl.toml` (its path) and what it says: its `[check] paths` are
154 /// probed, and the file itself is an input of every entry, since its lint selection is.
155 pub config: Option<(&'a Path, &'a crate::config::HtlConfig)>,
156}
157
158impl LinkStore<'_> {
159 /// Files an entry depends on besides the module and what it required.
160 fn extra_inputs(&self) -> Vec<PathBuf> {
161 self.config
162 .map(|(file, _)| vec![file.to_path_buf()])
163 .unwrap_or_default()
164 }
165
166 /// Directories a `require` from `file` could resolve in, for the entry's probes when
167 /// the store has no project model ([`cache::search_dirs`]).
168 fn probe_dirs(&self, file: &Path) -> Vec<PathBuf> {
169 cache::search_dirs(file)
170 }
171}
172
173/// One linked module: where it came from and how it was stored.
174#[derive(Debug, Clone)]
175pub struct LinkedModule {
176 /// The module name a `require` reaches it by, which is the name it takes in the
177 /// bundle — not its path.
178 pub name: String,
179 /// The file it was read from, for a report that wants to name something openable.
180 pub path: PathBuf,
181 /// `true` for a `.tl` that was checked and generated, `false` for a `.lua` taken as
182 /// it was. Only the typed ones have a store entry, so this is what
183 /// [`Linked::cached`] counts against.
184 pub typed: bool,
185}
186
187/// The result of a link: the bundle, and everything a reporter wants to say about how it
188/// was arrived at.
189///
190/// The bundle is private because an incomplete one must not escape — see
191/// [`errors`](Self::errors) and [`bundle`](Self::bundle). [`link`] itself returns `Ok`
192/// with the errors inside, so a caller (a `build.rs`, the macros) can show the whole list
193/// rather than the first one; the bundle is handed out only when the list is empty.
194#[derive(Debug, Default)]
195pub struct Linked {
196 bundle: Bundle,
197 /// Every module the walk took, in the order it took them.
198 pub modules: Vec<LinkedModule>,
199 /// Names the host is expected to provide at run time, so the bundle records them as
200 /// its own requirements rather than carrying code for them.
201 pub host_modules: Vec<String>,
202 /// Type errors and unresolved requires. A module with a type error is *absent* from
203 /// the bundle, so the bundle is only handed out ([`bundle`](Self::bundle)) when this
204 /// is empty: a program missing a module dies at its first `require`, far from here.
205 ///
206 /// Each is a [`Diagnostic`](crate::Diagnostic)'s text with its path spelled as
207 /// `htl check` spells it ([`spelled`](crate::Diagnostic::spelled)), so the error a
208 /// failed `include_bundle!` or `into_bundle` shows names a file the way the report does.
209 pub errors: Vec<String>,
210 /// The part of [`errors`](Self::errors) the linker found itself — a `require` nothing
211 /// answers, an `extra` module that is not there, a name two files claim — as values.
212 /// The rest of `errors` is the modules' own checks, which [`checks`](Self::checks)
213 /// carries. A reporter says these after the checks' diagnostics; it does not have to
214 /// tell the two apart by their text.
215 pub link_errors: Vec<crate::Diagnostic>,
216 /// Lints from every module, which do not stop a bundle: whether they stop the *run*
217 /// is the caller's, and the caller is what knows about `strict`.
218 pub lints: Vec<String>,
219 /// The full check of each module, for a reader that wants more than the flattened
220 /// [`errors`](Self::errors) and [`lints`](Self::lints) — the requires, the
221 /// dependencies, the per-file verdict.
222 pub checks: Vec<(PathBuf, CheckInfo)>,
223 /// How many typed modules came from the store rather than the checker. Zero without
224 /// a store. The total to say it against is the typed count of [`modules`](Self::modules).
225 pub cached: usize,
226 /// The checks' errors a linker error says instead: a `require` the checker could not
227 /// find is its `module not found`, and the linker's error at the same place says the
228 /// same thing and where to declare the module. One `require` is said once, by the
229 /// linker; [`errors`](Self::errors) carries that line in the check's place, and
230 /// [`reported`](Self::reported) leaves the check's out.
231 superseded: Vec<(PathBuf, usize, usize)>,
232}
233
234impl Linked {
235 /// The check of `path` as a report says it: `check` without the errors a linker error
236 /// at the same place says instead ([`link_errors`](Self::link_errors)). The checks in
237 /// [`checks`](Self::checks) are left as the checker made them.
238 pub fn reported(&self, path: &Path, check: &CheckInfo) -> CheckInfo {
239 let taken = |d: &crate::Diagnostic| {
240 self.superseded
241 .iter()
242 .any(|(p, l, c)| p == path && *l == d.line && *c == d.col)
243 };
244 let mut out = check.clone();
245 if !check.error_items.iter().any(taken) {
246 return out;
247 }
248 // `errors`, `error_fixes` and `error_items` are parallel: the i-th of each is one
249 // error, so they are filtered together.
250 out.errors.clear();
251 out.error_fixes.clear();
252 out.error_items.clear();
253 for (i, d) in check.error_items.iter().enumerate() {
254 if taken(d) {
255 continue;
256 }
257 out.errors.push(check.errors[i].clone());
258 out.error_fixes
259 .push(check.error_fixes.get(i).cloned().flatten());
260 out.error_items.push(d.clone());
261 }
262 out
263 }
264
265 /// `true` when every module linked cleanly (lints are not errors here).
266 pub fn ok(&self) -> bool {
267 self.errors.is_empty()
268 }
269
270 /// The bundle, or every error that makes it incomplete.
271 pub fn bundle(&self) -> Result<&Bundle> {
272 if self.errors.is_empty() {
273 Ok(&self.bundle)
274 } else {
275 Err(self.error())
276 }
277 }
278
279 /// The bundle by value, on the same condition as [`bundle`](Self::bundle): for a
280 /// caller that writes it out and is done with the report around it.
281 pub fn into_bundle(self) -> Result<Bundle> {
282 if self.errors.is_empty() {
283 Ok(self.bundle)
284 } else {
285 Err(self.error())
286 }
287 }
288
289 fn error(&self) -> anyhow::Error {
290 anyhow::anyhow!(
291 "link failed with {} error(s):\n {}",
292 self.errors.len(),
293 self.errors.join("\n ")
294 )
295 }
296
297 /// Every file the bundle was built from (entry, modules, and what the checker read
298 /// for them, e.g. `.d.tl`s): what a build script or macro should watch for changes,
299 /// one `cargo:rerun-if-changed=<file>` each. Files, not the directory: cargo compares
300 /// the mtime of the path it is given, and editing a file inside a directory does not
301 /// change the directory's.
302 pub fn inputs(&self) -> Vec<PathBuf> {
303 let mut out: Vec<PathBuf> = self.modules.iter().map(|m| m.path.clone()).collect();
304 for (_, ci) in &self.checks {
305 out.extend(ci.deps.iter().cloned());
306 }
307 out.sort();
308 out.dedup();
309 out
310 }
311}
312
313/// Link `entry` (a `.tl` file) and everything it requires. The checker's search path
314/// must already cover the project (`add_path` / `apply_project` / `apply_config`).
315pub fn link(h: &Htl, entry: &Path, opts: &LinkOptions) -> Result<Linked> {
316 link_with(h, entry, opts, None)
317}
318
319/// [`link`], replaying from the run cache what it can (see the module doc).
320///
321/// With `store` = `None` this is `link`. With a store, a typed module whose `gen` entry
322/// still holds is taken from it — its generated Lua, and what checking it reported — and
323/// counted in [`Linked::cached`]; every other typed module is generated and its entry
324/// written. Nothing about the store can fail the link: an unreadable or stale entry is a
325/// generate, an unwritable store is a generate next time too.
326pub fn link_with(
327 h: &Htl,
328 entry: &Path,
329 opts: &LinkOptions,
330 store: Option<LinkStore<'_>>,
331) -> Result<Linked> {
332 let mut out = Linked::default();
333 let entry_name = opts
334 .entry_name
335 .clone()
336 .unwrap_or_else(|| entry_module_name(entry));
337 let host_declared: HashSet<String> = opts.host.iter().cloned().collect();
338 let mut host: BTreeSet<String> = BTreeSet::new();
339 let mut queued: HashSet<String> = HashSet::new();
340 let mut queue: VecDeque<(String, PathBuf)> = VecDeque::new();
341 queue.push_back((entry_name.clone(), entry.to_path_buf()));
342 queued.insert(entry_name.clone());
343 for name in &opts.extra {
344 match classify(h, name, None)? {
345 Target::File(p) => {
346 if queued.insert(name.clone()) {
347 queue.push_back((name.clone(), p));
348 }
349 }
350 Target::Host => {
351 host.insert(name.clone());
352 }
353 Target::Missing => out.link_error(positionless(format!(
354 "extra module '{name}' not found on the search path"
355 ))),
356 Target::Ambiguous(why) | Target::Shadowed(why) => {
357 out.link_error(positionless(format!("extra module {why}")))
358 }
359 }
360 }
361
362 while let Some((name, path)) = queue.pop_front() {
363 let typed = path.extension().is_none_or(|e| e != "lua");
364 let mut checked_errors: Option<(usize, Vec<(usize, usize)>)> = None;
365 let (code, requires) = if typed {
366 let Generated {
367 code,
368 check: ci,
369 cached,
370 } = generate(h, &path, store)?;
371 if cached {
372 out.cached += 1;
373 }
374 debug_assert_eq!(ci.error_items.len(), ci.errors.len());
375 // Where this file's errors start in `errors`, and where each sits: a linker
376 // error at one of those places says it instead (`superseded`).
377 let first = out.errors.len();
378 let at_positions: Vec<(usize, usize)> =
379 ci.error_items.iter().map(|d| (d.line, d.col)).collect();
380 checked_errors = Some((first, at_positions));
381 out.errors.extend(
382 ci.error_items
383 .iter()
384 .map(|d| d.clone().spelled().to_string()),
385 );
386 out.lints.extend(
387 ci.lint_items
388 .iter()
389 .map(|d| d.clone().spelled().to_string()),
390 );
391 let reqs = ci.requires.clone();
392 out.checks.push((path.clone(), ci));
393 (code, reqs)
394 } else {
395 let src = std::fs::read_to_string(&path)
396 .with_context(|| format!("reading {}", path.display()))?;
397 let reqs = h.lua_requires(&src, &path)?;
398 (Some(src), reqs)
399 };
400 for r in &requires {
401 // The value of a `local type` the generator erased: no `require` of the name is
402 // in the code just generated, so nothing runs it — not bundled, not the
403 // host's, not missing. The census keeps the site for the readers that want the
404 // check's dependencies (`htl unused`, the cycle lint); only the closure of what
405 // runs leaves it out.
406 if r.erased {
407 continue;
408 }
409 if queued.contains(&r.module) {
410 continue;
411 }
412 // A name the caller said the host provides is the host's before the search
413 // path is asked: a file that could answer it is not bundled and not walked.
414 // If a file of the model implements it all the same, the model refuses the
415 // name; a checked file's `require` of it is already an error of the check, a
416 // plain `.lua`'s is said here, where it would otherwise pass unseen — at every
417 // such `require`, including after a checked file has filed the name under the
418 // host's.
419 if host_declared.contains(&r.module) || host.contains(&r.module) {
420 if !typed && let Some(why) = h.host_shadowing(&r.module)? {
421 out.link_error(at(&path, r, &why));
422 continue;
423 }
424 host.insert(r.module.clone());
425 continue;
426 }
427 match classify(h, &r.module, r.path.as_deref())? {
428 Target::File(p) => {
429 queued.insert(r.module.clone());
430 queue.push_back((r.module.clone(), p));
431 }
432 Target::Host => {
433 host.insert(r.module.clone());
434 }
435 Target::Missing => {
436 let d = unresolved(&path, r);
437 // The checker's own error at this `require`, when it has one, is
438 // `module not found`: the same finding, said without where to declare
439 // the module. The linker's line takes its place.
440 let own = checked_errors.as_ref().and_then(|(first, at)| {
441 at.iter()
442 .position(|&(l, c)| l == r.line && c == r.col)
443 .map(|i| first + i)
444 });
445 match own {
446 Some(i) => {
447 let d = d.spelled();
448 out.errors[i] = d.to_string();
449 out.superseded.push((path.clone(), r.line, r.col));
450 out.link_errors.push(d);
451 }
452 None => out.link_error(d),
453 }
454 }
455 // A checked file's `require` of it is already an error of the check, at
456 // the same place; a plain `.lua` is checked by nobody, so it is said here.
457 Target::Ambiguous(why) | Target::Shadowed(why) if !typed => {
458 out.link_error(at(&path, r, &why))
459 }
460 Target::Ambiguous(_) => {}
461 // The check said it; the name is still the host's, and nothing is bundled.
462 Target::Shadowed(_) => {
463 host.insert(r.module.clone());
464 }
465 }
466 }
467 let Some(code) = code else { continue };
468 let payload = if opts.source {
469 Module {
470 name: name.clone(),
471 kind: Kind::Source,
472 payload: code.into_bytes(),
473 }
474 } else {
475 let bc = h.compile_with(&name, &code, !opts.debug)?;
476 Module {
477 name: name.clone(),
478 kind: Kind::Bytecode,
479 payload: bc,
480 }
481 };
482 out.bundle.modules.push(payload);
483 out.modules.push(LinkedModule { name, path, typed });
484 }
485
486 out.host_modules = host.iter().cloned().collect();
487 out.bundle.entry = entry_name;
488 out.bundle.htl_version = env!("CARGO_PKG_VERSION").to_string();
489 out.bundle.host_modules = out.host_modules.clone();
490 if !opts.source {
491 out.bundle.fingerprint = h.fingerprint()?;
492 }
493 Ok(out)
494}
495
496/// One typed module, generated or replayed: see [`generate`].
497#[derive(Debug)]
498pub struct Generated {
499 /// The Lua; `None` when checking produced errors (see [`CheckInfo`]).
500 pub code: Option<String>,
501 /// What checking said — carried whether or not there is code, and the half a replay
502 /// needs as much as the Lua: the lints, the requires and the dependencies come out of
503 /// here.
504 pub check: CheckInfo,
505 /// Whether it came from the store rather than the checker.
506 pub cached: bool,
507}
508
509/// One typed module's generated Lua and what checking it said: from the store when its
510/// `gen` entry still holds, else from the checker, and then into the store. What
511/// [`link_with`] does per module, and what `include_tl!` does for its one file.
512///
513/// A hit needs both halves of the entry — the Lua, and the structured check it came with —
514/// since the reader wants the lints, the requires and the dependencies out of the second.
515/// `htl test` writes both; an entry missing either is a miss rather than a partial replay.
516pub fn generate(h: &Htl, path: &Path, store: Option<LinkStore<'_>>) -> Result<Generated> {
517 let key = store.map(|s| cache::module_gen_key(path, s.lint));
518 if let (Some(s), Some(k)) = (store, &key)
519 && let Some(m) = s.cache.lookup(k)
520 && let (Some(code), Some(check)) = (&m.code, &m.check)
521 {
522 return Ok(Generated {
523 code: Some(code.clone()),
524 check: check.to_check(),
525 cached: true,
526 });
527 }
528 let (code, ci) = h.gen_lua(path)?;
529 // Only when there is code: a module that failed to check has nothing to bundle, and
530 // storing that would replay the failure as if it were a result.
531 if let (Some(s), Some(k), Some(code)) = (store, &key, &code) {
532 // `gen_lua` can come back without requires for a module the checker already holds
533 // — it serves the generated code without walking the file again — and the requires
534 // are what the next run's validation and the linker's own walk are built from. Ask
535 // the checker separately, but only when the file could have any: a leaf that never
536 // says `require` is most of a project, and a check per leaf is the wrong price.
537 let stored = if ci.requires.is_empty() && mentions_require(path) {
538 match h.check(path) {
539 Ok(c) if !c.requires.is_empty() => CheckInfo {
540 requires: c.requires,
541 ..ci.clone()
542 },
543 _ => ci.clone(),
544 }
545 } else {
546 ci.clone()
547 };
548 let m = cache::Module::generated(&stored, code.clone());
549 s.cache
550 .store_module(k, path, &s.extra_inputs(), &s.probe_dirs(path), &m);
551 }
552 Ok(Generated {
553 code,
554 check: ci,
555 cached: false,
556 })
557}
558
559/// Whether `path`'s source says `require` anywhere ([`cache::source_mentions_require`]);
560/// an unreadable file is taken to, which costs a check rather than a wrong entry.
561pub fn mentions_require(path: &Path) -> bool {
562 std::fs::read_to_string(path)
563 .map(|s| cache::source_mentions_require(&s))
564 .unwrap_or(true)
565}
566
567fn is_decl(p: &Path) -> bool {
568 p.to_string_lossy().ends_with(".d.tl")
569}
570
571fn unresolved(from: &Path, r: &RequireSite) -> crate::Diagnostic {
572 at(
573 from,
574 r,
575 &format!(
576 "require(\"{}\") is not on the search path: nothing to bundle. If the host \
577 provides it, declare it in a `{}.d.tl` or list it under `[build] host` in \
578 htl.toml; if it is reached only through a dynamic require, list it under \
579 `[build] extra`",
580 r.module,
581 r.module.replace('.', "/")
582 ),
583 )
584}
585
586enum Target {
587 /// A file to bundle (`.tl` typed, or a plain `.lua`).
588 File(PathBuf),
589 /// Runs from no file of the project: the model says the host or the environment
590 /// provides it — declared only, by a `.d.tl` with no `.lua` behind it, or named by
591 /// one of the host's sources — or, with no model to ask, it resolves to a `.d.tl` and
592 /// the search path has no `.lua` behind it.
593 Host,
594 Missing,
595 /// More than one file implements the name: the model's message saying which. Nothing
596 /// is bundled for it, since no order picks one.
597 Ambiguous(String),
598 /// The host provides the name and a file of the model implements it too: the model's
599 /// message saying so. Nothing is bundled for it — the host's module is what runs — and
600 /// it is an error wherever it is required, as `Ambiguous` is. Reached for a name the
601 /// caller did not list in [`LinkOptions::host`] (a caller without the model's list);
602 /// a listed one is checked before the walk would classify it.
603 Shadowed(String),
604}
605
606/// A linker error at a `require`: `file:line:col: why`, the shape a check's error has.
607fn at(file: &Path, r: &RequireSite, why: &str) -> crate::Diagnostic {
608 crate::Diagnostic::new(
609 crate::Severity::Error,
610 file.display().to_string(),
611 r.line,
612 r.col,
613 why,
614 None,
615 )
616}
617
618/// A linker error about no place in a file: an `extra` module named in the config.
619fn positionless(message: String) -> crate::Diagnostic {
620 crate::Diagnostic::new(crate::Severity::Error, "", 0, 0, message, None)
621}
622
623impl Linked {
624 /// Record an error the linker found itself: as a value, and in the flattened
625 /// [`errors`](Self::errors) as its text.
626 fn link_error(&mut self, d: crate::Diagnostic) {
627 let d = d.spelled();
628 self.errors.push(d.to_string());
629 self.link_errors.push(d);
630 }
631}
632
633/// The module name an entry file answers to when the project model does not name it — an
634/// entry outside every project: the naming rule ([`crate::naming`]) against the file's own
635/// directory, so its stem, except that `<dir>/init.tl` is the module `<dir>` — the name a
636/// `require` of it is written as, and so the name a bundle has to serve it under once a
637/// host has installed the bundle and a program asks for it. An entry the model names is
638/// served under that name ([`LinkOptions::entry_name`]).
639fn entry_module_name(entry: &Path) -> String {
640 // Named against its own directory — the one place a file outside every project
641 // names by itself — which leaves `<dir>/init.tl` nothing to be named by but `<dir>`.
642 let file = entry.file_name().map(PathBuf::from).unwrap_or_default();
643 let rel = match (file.to_str(), entry.parent().and_then(|d| d.file_name())) {
644 (Some("init.tl"), Some(dir)) => Path::new(dir).join(&file),
645 _ => file,
646 };
647 crate::naming::name_of("", &rel).unwrap_or_else(|| "main".into())
648}
649
650/// What a `require(name)` points at for the linker. `found` is the checker's own
651/// resolution when already known (a require site); otherwise it is looked up.
652fn classify(h: &Htl, name: &str, found: Option<&Path>) -> Result<Target> {
653 let (found, lua) = match found {
654 Some(p) => (Some(p.to_path_buf()), None),
655 None => h.resolve_module(name)?,
656 };
657 // A refused name resolves to its declaration or to nothing, never to its file; either
658 // would read as the host's or as missing, so ask the model first.
659 if found.as_deref().is_none_or(is_decl)
660 && let Some(why) = h.host_shadowing(name)?
661 {
662 return Ok(Target::Shadowed(why));
663 }
664 let Some(p) = found else {
665 return Ok(match h.ambiguity(name)? {
666 Some(why) => Target::Ambiguous(why),
667 None => Target::Missing,
668 });
669 };
670 if !is_decl(&p) {
671 return Ok(Target::File(p));
672 }
673 // A declaration. Whether anything of the project runs behind it is the model's to
674 // say: a name it has only this declaration for is the environment's, one the host
675 // provides is the host's, and neither is bundled.
676 let model = h.model_provides(name)?;
677 if let crate::Provision::Provided(_) = model {
678 return Ok(Target::Host);
679 }
680 // Otherwise a `.lua` behind the declaration (a vendored dependency typed by a `.d.tl`)
681 // is what runs, and what gets bundled: the model's own, when it has the name.
682 let lua = match lua {
683 Some(l) => Some(l),
684 None => h.resolve_module(name)?.1,
685 };
686 Ok(match (lua, model) {
687 (Some(l), _) => Target::File(l),
688 // No model to ask, or a name it has nothing under (a `.d.tl` found on the search
689 // path, outside every root of the project): a declaration with nothing behind it
690 // on the path is taken to be the host's, as it was before the model answered.
691 (None, crate::Provision::Unknown) => Target::Host,
692 // The model has the name and says a file of the project runs for it, and the
693 // lookup found none: the two disagree, which a declared name never makes them
694 // do. Filed with the host's as before rather than failing a build over it.
695 (None, _) => Target::Host,
696 })
697}