cargo-telar 0.2.0

Cargo subcommand for Telar apps: dev server with hot reload, and packaging into native installers.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
//! The subcommands: dev, check, fmt, preview, test, build, package and migrate.

use std::process::Command;

use clap::Parser;

mod android;
mod bake;
mod check;
mod cli;
mod config;
mod diagnostics;
mod doctor;
mod fmt;
mod migrate;
mod new;
mod package;
mod transpile;
mod watch;
mod web_dev;

use android::build_android_package;
use bake::bake_workspace;
use check::run_check_cmd;
use cli::{
    BuildArgs, BuildFormat, Cli, CommonArgs, DevArgs, DevtoolsArg, HotArgs, PreviewArgs, Target,
    TelarCommand, TestArgs, WebRenderer,
};
use config::{TelarSection, load_config, resolve_package};
use doctor::run_doctor_cmd;
use fmt::run_fmt_cmd;
use migrate::run_migrate_cmd;
use new::run_new_cmd;
use package::{build_appimage, build_deb, build_desktop_dir, build_dmg, build_nsis, build_web};
use transpile::transpile_workspace;
use watch::{HotLoopOpts, HotMode, run_hot_loop};
use web_dev::run_web_dev;

/// Dispatches a `cargo telar` invocation to its subcommand.
pub fn run(args: Vec<String>) {
    let cli = Cli::parse_from(std::iter::once("cargo-telar".to_string()).chain(args));
    let command = cli.command.unwrap_or_else(default_dev_command);
    // The one place `cargo telar` prepares a build, rather than at each of the nine sites that spawn `cargo`; the five excluded here compile nothing. Bake first: a `src:"…"` transpiles against the artifact the bake writes.
    if !matches!(
        command,
        TelarCommand::New(_)
            | TelarCommand::Doctor
            | TelarCommand::Fmt(_)
            | TelarCommand::Migrate(_)
            | TelarCommand::Bake
            | TelarCommand::Transpile
    ) {
        bake_workspace();
        transpile_workspace();
    }
    match command {
        TelarCommand::New(args) => run_new_cmd(args),
        TelarCommand::Dev(args) => run_dev_cmd(args),
        TelarCommand::Preview(args) => run_preview_cmd(args),
        TelarCommand::Build(args) => run_build_cmd(args),
        TelarCommand::Test(args) => run_test_cmd(args),
        TelarCommand::Check(args) => run_check_cmd(args),
        TelarCommand::Bake => bake_workspace(),
        TelarCommand::Transpile => {
            bake_workspace();
            transpile_workspace()
        }
        TelarCommand::Doctor => run_doctor_cmd(),
        TelarCommand::Fmt(args) => run_fmt_cmd(args),
        TelarCommand::Migrate(args) => run_migrate_cmd(args),
    }
}

// No subcommand behaves like `cargo telar dev` with default flags.
fn default_dev_command() -> TelarCommand {
    TelarCommand::Dev(DevArgs {
        hot: HotArgs {
            common: CommonArgs {
                package: None,
                features: None,
                target: None,
                backend: None,
                renderer: None,
                cargo_args: vec![],
            },
            release: false,
            no_hot_reload: false,
        },
        devtools: None,
    })
}

/// What every compiling subcommand works out before it does anything of its own: the cargo invocation, the resolved configuration, and whether this run ends up in the terminal.
///
/// It was written out four times. `cargo telar test` is the one that legitimately does not want it — it drops `--backend` and `--renderer` on purpose, because the value is read through `option_env!` and setting it would change the build fingerprint for nothing — so it keeps its own preamble and says why.
struct BuildPlan {
    cargo_args: Vec<String>,
    config: TelarSection,
    target: Target,
    renderer: Option<WebRenderer>,
    /// Whether the application will run in the terminal this command was launched from, which only `--target tui` makes true.
    terminal: bool,
}

impl BuildPlan {
    /// `select_frontend` is what names the feature the target needs and points the binary at it, so it runs for every command rather than the two that remembered.
    fn new(common: CommonArgs, release: bool) -> Self {
        let CommonArgs {
            package,
            features,
            target,
            backend,
            renderer,
            cargo_args: extra,
        } = common;
        let mut cargo_args = build_cargo_args(&package, release, &features);
        cargo_args.extend(extra);
        if matches!(target, Some(Target::Android)) {
            cargo_args.push("--android".to_string());
        }
        let terminal = select_frontend(target, renderer, &mut cargo_args);
        let mut config = load_config(&cargo_args);
        if let Some(backend) = backend {
            config.backend = Some(backend.into());
        }
        Self {
            cargo_args,
            config,
            target: target.unwrap_or(Target::Desktop),
            renderer,
            terminal,
        }
    }
}

fn run_dev_cmd(args: DevArgs) {
    let DevArgs { hot, devtools } = args;
    let HotArgs {
        common,
        release,
        no_hot_reload,
    } = hot;
    let mut plan = BuildPlan::new(common, release);
    // CLI `--devtools off` overrides any config-file setting.
    if let Some(devtools) = devtools {
        plan.config.dev.devtools = Some(matches!(devtools, DevtoolsArg::On));
    }
    if plan.target == Target::Web {
        run_web_dev(plan.cargo_args, plan.config, WEB_DEV_PORT, plan.renderer);
    }
    let terminal = plan.terminal;
    run_hot_loop(
        HotMode::Dev,
        HotLoopOpts {
            args: plan.cargo_args,
            config: plan.config,
            // The hot-reload host opens a window of its own, so an app running in the terminal restarts on a change instead. Reloading in place is the only thing lost: the rebuild is the same one.
            no_hot_reload: no_hot_reload || terminal,
        },
    );
}

fn run_preview_cmd(args: PreviewArgs) {
    let PreviewArgs {
        hot,
        component,
        list,
        png,
    } = args;
    // The preview host process inherits our env; it filters PreviewEntries by this when set.
    if let Some(component) = &component {
        // SAFETY: single-threaded at this point (set before any threads/spawns are created).
        unsafe { std::env::set_var("TELAR_PREVIEW_COMPONENT", component) };
    }
    let HotArgs {
        common,
        release,
        no_hot_reload,
    } = hot;
    // Makes the generated entrypoint print "component\tpreview" lines and exit instead of opening a window.
    if list {
        run_preview_once(&common, release, "previews", "TELAR_PREVIEW_LIST", "1");
    }
    // The only answer for a shell with no display, and what a golden-image run compares.
    if let Some(dir) = &png {
        run_preview_once(
            &common,
            release,
            "preview-headless",
            "TELAR_PREVIEW_PNG",
            &dir.display().to_string(),
        );
    }
    // A preview renders one component in a window of its own; there is no page to draw it as a document, so the plan's `renderer` goes unread here.
    let plan = BuildPlan::new(common, release);
    run_hot_loop(
        HotMode::Preview,
        HotLoopOpts {
            args: plan.cargo_args,
            config: plan.config,
            no_hot_reload,
        },
    );
}

/// Runs the app binary once with `var` set, under the `telar` feature that makes it answer, and exits with its code.
///
/// The feature is the half that was missing. These entry points are reached through an environment variable the generated `run()` reads, and that `run()` only reads one in a build carrying previews — so without naming a feature here the binary starts the application instead, which is what `--png` would have done for as long as the feature behind it existed.
fn run_preview_once(
    common: &CommonArgs,
    release: bool,
    feature: &str,
    var: &str,
    value: &str,
) -> ! {
    let mut cargo_args = vec!["run".to_string()];
    cargo_args.extend(build_cargo_args(&common.package, release, &common.features));
    cargo_args.extend(common.cargo_args.clone());
    // A host binary either way, so a browser target names nothing here; the rest keep the terminal listing and the PNG render off the frontend the project does not build.
    if let Some(target) = common.target.filter(|target| *target != Target::Web) {
        let selected = frontend_args(target, common.renderer, &cargo_args);
        cargo_args.extend(selected);
    }
    cargo_args.push("--features".to_string());
    cargo_args.push(format!("telar/{feature}"));
    let status = Command::new("cargo")
        .args(&cargo_args)
        .env(var, value)
        .status()
        .expect("[cargo-telar] failed to invoke cargo");
    std::process::exit(status.code().unwrap_or(1));
}

fn run_test_cmd(args: TestArgs) -> ! {
    let TestArgs { common, release } = args;
    let CommonArgs {
        package,
        features,
        target,
        backend,
        renderer,
        cargo_args: extra,
    } = common;
    if let Some(target @ (Target::Android | Target::Web)) = target {
        let name = match target {
            Target::Android => "android",
            _ => "web",
        };
        eprintln!(
            "[cargo-telar] `cargo telar test` renders on the host; --target {name} is not supported."
        );
        std::process::exit(2);
    }
    // `TELAR_TEST` makes the generated entrypoint render every preview headlessly and exit non-zero on failure.
    let mut cargo_args = vec!["run".to_string()];
    cargo_args.extend(build_cargo_args(&package, release, &features));
    cargo_args.extend(extra);
    // The frontend the target named, so a terminal project's tests are not a desktop build — and so `--target tui` reaches this command too, rather than every command but this one.
    if let Some(target) = target {
        let selected = frontend_args(target, None, &cargo_args);
        cargo_args.extend(selected);
    }
    // What emits the `[preview]` blocks and the entry point that runs them. Without it the binary has neither, and `TELAR_TEST` below reaches nothing — which is the point: it reaches nothing in a shipped build either.
    cargo_args.push("--features".to_string());
    cargo_args.push("telar/previews".to_string());
    // The test host never instantiates a renderer, and the value is read via `option_env!`, so setting it would change the build fingerprint and force a needless recompile.
    let _ = (backend, renderer);
    eprintln!("[cargo-telar] Running component render tests...");
    let status = Command::new("cargo")
        .args(&cargo_args)
        .env("TELAR_TEST", "1")
        .status()
        .expect("[cargo-telar] failed to invoke cargo");
    std::process::exit(status.code().unwrap_or(1));
}

fn build_format_name(format: &BuildFormat) -> &'static str {
    match format {
        BuildFormat::Appimage => "appimage",
        BuildFormat::Deb => "deb",
        BuildFormat::Dmg => "dmg",
        BuildFormat::Nsis => "nsis",
        BuildFormat::Apk => "apk",
        BuildFormat::Dir => "dir",
    }
}

fn run_build_cmd(args: BuildArgs) -> ! {
    let BuildArgs { mut common, format } = args;

    // All desktop formats reject `--target android`, and `--format apk` implies Android. Resolved before the plan is built, because the format can move the target and the plan is what the target decides.
    match &format {
        Some(
            fmt @ (BuildFormat::Deb | BuildFormat::Appimage | BuildFormat::Dmg | BuildFormat::Nsis),
        ) if common.target == Some(Target::Android) => {
            eprintln!(
                "[cargo-telar] `--format {}` is desktop-only; drop `--target android` (use `--format apk` for Android).",
                build_format_name(fmt)
            );
            std::process::exit(2);
        }
        Some(BuildFormat::Apk) => common.target = Some(Target::Android),
        Some(BuildFormat::Dir) if common.target == Some(Target::Android) => {
            eprintln!(
                "[cargo-telar] `--format dir` is desktop-only; use `--target android` (or `--format apk`) for Android."
            );
            std::process::exit(2);
        }
        _ => {}
    }
    if common.target == Some(Target::Web) && format.is_some() {
        eprintln!(
            "[cargo-telar] `--format` is for native installers; a web build is a directory of files."
        );
        std::process::exit(2);
    }

    // Build always implies --release.
    let plan = BuildPlan::new(common, true);
    if plan.target == Target::Web {
        build_web(plan.cargo_args, plan.config, true, plan.renderer);
    }
    if plan.target == Target::Android {
        build_android_package(plan.cargo_args, plan.config)
    } else {
        match format {
            Some(BuildFormat::Deb) => build_deb(plan.cargo_args, plan.config),
            Some(BuildFormat::Appimage) => build_appimage(plan.cargo_args, plan.config),
            Some(BuildFormat::Dmg) => build_dmg(plan.cargo_args, plan.config),
            Some(BuildFormat::Nsis) => build_nsis(plan.cargo_args, plan.config),
            _ => build_desktop_dir(plan.cargo_args, plan.config),
        }
    }
}

fn build_cargo_args(
    package: &Option<String>,
    release: bool,
    features: &Option<String>,
) -> Vec<String> {
    let mut args = Vec::new();
    if let Some(pkg) = package {
        args.push("-p".to_string());
        args.push(pkg.clone());
    }
    if release {
        args.push("--release".to_string());
    }
    if let Some(features) = features {
        args.push("--features".to_string());
        args.push(features.clone());
    }
    args
}

/// The flags that build exactly the frontend `target` names, for the invocation `cargo_args` is becoming.
///
/// A package that declares a feature for the target gets it named on its own, with `--no-default-features` and the rest of its defaults re-named alongside: `default` is where a project says which frontend it builds, so asking for another one has to turn that one off. Adding it on top instead is what made `--target tui` compile a desktop stack beside the terminal one — build time nobody asked for on a desktop, and the whole of the failure under Termux, where `platform-desktop` is `cfg`'d out of the graph and the window it pays for cannot exist.
///
/// A package that declares no such feature reaches the frontend through `telar/` and keeps its defaults, so any project builds for a target without first declaring one.
fn frontend_args(
    target: Target,
    renderer: Option<WebRenderer>,
    cargo_args: &[String],
) -> Vec<String> {
    let mut args = Vec::new();
    resolve_package(cargo_args)
        .frontend_feature(target.feature(renderer))
        .push_to(&mut args);
    args
}

/// Turns on the frontend a `--target` named and tells the app to start on it, returning whether the app will run in this terminal.
///
/// No target is a project left to say it in its manifest, which is where it says everything else about the build: nothing is named here, and the terminal is still answered for, because a package whose `default` is the terminal and no window runs in one whether or not anybody passed a flag.
///
/// The environment variable is what picks between the frontends a build ends up with, which is only still a question in the case where the package declared no feature for the target: there it kept a windowed default and the terminal rides along beside it.
fn select_frontend(
    target: Option<Target>,
    renderer: Option<WebRenderer>,
    cargo_args: &mut Vec<String>,
) -> bool {
    // A browser build names its own frontend in `build_web_bundle`, which is also where the wasm target and the profile that go with it are decided.
    if let Some(target) = target.filter(|target| *target != Target::Web) {
        let selected = frontend_args(target, renderer, cargo_args);
        cargo_args.extend(selected);
    }
    let terminal = match target {
        Some(target) => target == Target::Tui,
        None => resolve_package(cargo_args).defaults_to_terminal(),
    };
    if terminal {
        // SAFETY: single-threaded at this point — set before any child is spawned or any thread started.
        unsafe { std::env::set_var("TELAR_TARGET", "tui") };
    }
    terminal
}

/// Where `cargo telar dev --target web` serves from. Fixed rather than chosen: a page reloaded by hand, a bookmark and a second terminal all have to name the same address.
const WEB_DEV_PORT: u16 = 8080;

#[cfg(test)]
#[path = "mod_test.rs"]
mod tests;