Struct Project 

pub struct Project { /* private fields */ }

Represents a WaterUI project with its manifest and crate information.

Implementations

impl Project

pub async fn select_channel( path: impl AsRef<Path>, channel: FrameworkChannel, ) -> Result<Self>

Select or update a framework channel and persist its exact dependency selection.

Errors

Returns an error when resolution, native-project merging, or dependency verification fails.

pub async fn run<B: Backend, D: Device>( &self, backend: &B, platform: TargetPlatform, device: D, ) -> Result<Running, FailToRun>

Run the WaterUI project on the specified device.

This method handles building, packaging, and running the project.

Arguments

• backend: The backend to use for building and packaging
• platform: The target platform to build for
• device: The device to run on

Errors

• If any step in the build, package, or run process fails.

pub async fn run_with_options<B: Backend, D: Device>( &self, backend: &B, platform: TargetPlatform, device: D, run_options: RunOptions, progress: Option<BuildProgress>, ) -> Result<Running, FailToRun>

Run the WaterUI project with explicit run options.

This allows callers (like preview) to inject extra environment variables. progress, when given, receives cargo compile events from both the library build and the packaging pass’s asset-manifest compile.

Errors

Returns an error if building, packaging, or launching the app fails.

pub async fn run_android_with_options<D: Device + AndroidAbiProvider>( &self, _backend: &AndroidBackend, device: D, run_options: RunOptions, build_options: BuildOptions, progress: Option<BuildProgress>, ) -> Result<Running, FailToRun>

Run the Android backend for the specific target ABI of the device.

This is required because Android packaging is ABI-dependent (e.g., x86_64 emulator vs arm64-v8a physical device).

build_options decides the Rust runtime linkage: a support app that dlopens WaterUI modules (the preview app) must pass BuildOptions::with_dynamic_module_loading so the shared runtime is built and packaged; a standalone app links it in.

Errors

Returns an error if building, packaging, or launching the Android app fails.

pub fn root(&self) -> &Path

Get the root path of the project.

Same as the directory containing Water.toml.

pub async fn target_dir(&self) -> Result<PathBuf>

Get the target directory for Rust build artifacts.

Errors

Returns an error when Cargo metadata cannot resolve the target directory.

pub async fn lockfile_path(&self) -> Result<PathBuf>

The lockfile the application builds against.

The workspace Cargo.lock when the project is a workspace member, otherwise the project’s own. It need not exist yet: a project that has never been resolved has none.

Errors

Returns an error when Cargo metadata cannot resolve the workspace.

pub async fn water_target_dir(&self, linkage: RustLinkage) -> Result<PathBuf>

Resolve the Cargo target directory every generated backend crate builds into.

The directory is shared by every project on the machine — one ~/.water/build_cache/target subtree — because Cargo already keys each compiled unit by target triple, resolved features, and profile: a second project’s build reuses the dependency graph the first one compiled instead of cold-building it, the way sccache-equipped machines behave. The shared root sits beside the per-project managed containers rather than inside one: generated backend sources are deleted and regenerated whenever the CLI’s scaffold templates change, while compiled artifacts do not become stale for that reason — keeping them together meant one CLI upgrade discarded the compiled dependency graph of every project on the machine.

One directory serves every backend, platform, and feature set of a linkage: switching backends only rebuilds the units the two graphs do not share — measured on an example app, over 80% of the Apple FFI graph resolves identically to the Hydrolysis graph and is reused as-is. Builds must therefore agree on everything Cargo hashes into every unit — pass an explicit --target and keep final-artifact link flags out of RUSTFLAGS (see RustBuild::with_final_rustc_arg) — or two variants sharing this directory re-fingerprint each other’s entire dependency graph on every switch.

Linkage is the one axis Cargo cannot separate: shared-runtime development builds carry -Cprefer-dynamic -Crpath in RUSTFLAGS and static packaging builds carry none, so each linkage keeps its own directory instead of the two variants invalidating each other whenever a developer alternates water run and water package.

Errors

Returns an error when the shared build-cache directory cannot be resolved.

pub async fn toolchain_target_dir(&self, toolchain: &str) -> Result<PathBuf>

Resolve an isolated target directory for a backend built by a different Rust toolchain.

Cargo hashes the compiler into every unit fingerprint, so a backend that pins its own toolchain (ESP32’s Espressif Rust fork) would invalidate the host units of Self::water_target_dir on every switch if it shared the directory.

Errors

Returns an error when the shared build-cache directory cannot be resolved.

pub async fn host_target_dir(&self) -> Result<PathBuf>

Resolve the target directory the project’s host-side rlib builds into.

build_host_rlib compiles the user crate for the host to read its waterui_meta_* symbols. That compile shares the dependency graph with every other project’s host build, so it lives beside the backend variants in the shared target root rather than in the project’s own target/.

Errors

Returns an error when the shared build-cache directory cannot be resolved.

pub const fn backends(&self) -> &Backends

Get the backends configured for the project.

pub const fn crate_name(&self) -> &CrateName

Get the crate name of the project.

pub fn ffi_crate_name(&self) -> CrateName

Get configured or default FFI crate name for app mode.

The default is tagged with this project’s root — see generated_crate_name; an explicit [crates] override is verbatim.

pub fn preview_ffi_crate_name(&self) -> CrateName

Get configured preview wrapper crate name for preview dylib builds.

pub fn preview_dylib_crate_path(&self, workspace_root: &Path) -> PathBuf

Get the crate root path used to build preview dylibs.

pub fn preview_dylib_crate_name(&self) -> CrateName

Get the crate name used to build preview dylibs.

pub fn gtk_backend_crate_name(&self) -> CrateName

Get configured or default GTK backend crate name for app mode.

pub fn hydrolysis_backend_crate_name(&self) -> CrateName

Get configured or default hydrolysis backend crate name for app mode.

pub fn winui_backend_crate_name(&self) -> CrateName

Get configured or default WinUI backend crate name for app mode.

pub fn esp32_backend_crate_name(&self) -> CrateName

Get the generated ESP32 firmware harness crate name.

pub fn tui_backend_crate_name(&self) -> CrateName

Get the crate name of the generated experimental TUI launcher.

pub fn gtk4_binary_name(&self) -> CrateName

The executable name the packaged GTK4 binary ships under.

pub fn hydrolysis_binary_name(&self) -> CrateName

The executable name the packaged hydrolysis binary ships under.

pub fn winui_binary_name(&self) -> CrateName

The executable name the packaged WinUI binary ships under.

pub fn esp32_binary_name(&self) -> CrateName

The name the packaged ESP32 firmware image ships under.

pub const fn package_type(&self) -> PackageType

Get package type declared in Water.toml.

pub fn is_playground(&self) -> bool

Returns true when this project is a playground project.

pub const fn apple_backend(&self) -> Option<&AppleBackend>

Get the Apple backend configuration if available.

pub fn backend_path<B: Backend>(&self) -> PathBuf

Get the full path to a backend directory.

Returns project.root() / backends.path / B::DEFAULT_PATH.

pub fn backend_relative_path<B: Backend>(&self) -> PathBuf

Get the relative path to a backend directory from project root.

Returns backends.path / B::DEFAULT_PATH.

pub fn ffi_crate_path(&self) -> PathBuf

Get the full path to the managed native FFI companion crate.

pub fn preview_module_member_path(&self) -> PathBuf

Directory name this project’s preview module occupies inside a workspace.

pub fn preview_ffi_crate_path(&self, workspace_root: &Path) -> PathBuf

Get the full path to the managed preview-only companion crate.

The crate lives inside the support runtime’s workspace rather than this project’s build cache, because a preview module and the runtime it is loaded into must come out of one Cargo resolution to agree on the -C metadata hash mangled into every symbol.

pub fn ffi_crate_relative_path(&self) -> PathBuf

Get the relative path to the managed native FFI companion crate from project root.

pub const fn android_backend(&self) -> Option<&AndroidBackend>

Get the Android backend configuration if available.

pub const fn gtk4_backend(&self) -> Option<&Gtk4Backend>

Get the GTK4 backend configuration if available.

pub const fn hydrolysis_backend(&self) -> Option<&HydrolysisBackend>

Get the hydrolysis backend configuration if available.

pub const fn winui_backend(&self) -> Option<&WinUiBackend>

Get the WinUI backend configuration if available.

pub const fn esp32_backend(&self) -> Option<&Esp32Backend>

Get the ESP32 backend configuration if available.

pub const fn manifest(&self) -> &Manifest

Get the manifest of the project.

pub async fn resolved_framework(&self) -> Result<ResolvedFramework>

The framework this project resolves generated code against — the channel selection Water.toml records, or the checkout waterui_path names.

Errors

Returns an error when the manifest records no framework source, or the local checkout’s framework facts cannot be read.

pub async fn links_runtime_package(&self, package_name: &str) -> Result<bool>

Returns whether the packaged application links package_name.

Development-only and build-only dependencies are excluded because they do not become part of the packaged application. The resolved graph is cached so backend regeneration and scaffolding share one Cargo metadata resolution.

Errors

Returns an error when Cargo cannot resolve the application graph or omits a package referenced by that graph.

pub async fn uses_standard_webview(&self) -> Result<bool>

Whether the application’s graph turns on the standard WebView component.

The signal is a webview feature enabled inside the application’s own subtree — the facade’s webview feature, or an engine crate’s webview hookup — resolved by cargo tree --edges features. The waterui-webview package cannot be the signal: engines link it for the shared asset-server types a ChromiumPage answers over CDP (#586), so its presence no longer means the component is used.

Errors

Returns an error when Cargo cannot resolve the application graph or omits a package referenced by that graph.

pub async fn resolved_webview_backend( &self, platform: TargetPlatform, backend: TargetBackend, ) -> Result<Option<ResolvedWebViewBackend>>

Resolve and validate the standard WebView engine for a build.

The application’s own dependency graph is the selection: linking waterui-browser-cef or waterui-browser-wpe picks that engine, and an app that links neither uses whatever web engine the target platform bridges. Nothing in Water.toml names an engine, because nothing else could keep the packaged runtime and the code that loads it in step.

Returns None when no webview feature is enabled in the application’s graph, so an engine crate reaching the graph through some other component never adds a WebView runtime to the package on its own.

Errors

Returns an error when Cargo metadata cannot be resolved, when the application links two engines at once, or when the selected engine is unsupported for the requested platform and backend.

pub async fn linked_browser_engine( &self, ) -> Result<Option<ResolvedWebViewBackend>>

The browser engine crate the application links, if any.

Errors

Returns an error when Cargo metadata cannot be resolved, or when the application links more than one engine — two engines cannot both draw one WebView, and the second install would fail at startup.

pub async fn declares_cef_helper(&self) -> Result<bool>

Whether the generated backend manifests declare the CEF subprocess helper [[bin]].

This is the manifest’s own predicate: the helper exists only when the application links the CEF engine crate, while a waterui-chromium link alone does not declare it. Builds and packaging that touch the helper must gate on this rather than BrowserRuntimePlan::requires_cef, which is wider — it also turns on for chromium — and would request a bin target Cargo never received.

Errors

Returns an error when Cargo metadata cannot be resolved or the application links two engines at once.

pub async fn browser_runtime_plan( &self, platform: TargetPlatform, backend: TargetBackend, ) -> Result<BrowserRuntimePlan>

Resolves and validates every embedded browser runtime linked by the application.

Errors

Returns an error when standard WebView or Chromium is unsupported for the requested platform and backend.

pub const fn bundle_identifier(&self) -> &BundleIdentifier

Get the bundle identifier of the project.

pub fn assets_path(&self) -> &str

Get the assets directory path relative to project root.

pub fn assets_dir(&self) -> PathBuf

Get the full path to the assets directory.

pub async fn clean<B: Backend>( &self, backend: &B, platform: TargetPlatform, ) -> Result<(), Report>

Clean build artifacts for the project using the specified backend.

Errors

Returns an error if cleaning fails.

pub async fn clean_all(&self) -> Result<(), Report>

Clean all build artifacts for the project.

This cleans:

• Rust target directory
• Apple build artifacts (if backend configured)
• Android build artifacts (if backend configured)
• GTK4 build artifacts (if backend configured)

Errors

Returns an error if any cleaning operation fails.

pub async fn package<B: Backend>( &self, backend: &B, platform: TargetPlatform, options: PackageOptions, ) -> Result<Artifact, Report>

Package the project for the specified platform.

Errors

Returns an error if packaging fails.

impl Project

pub async fn scaffold_preview_ffi_companion( &self, workspace_root: &Path, ) -> Result<PathBuf, FailToInitBackend>

Scaffold this project’s preview module inside workspace_root.

Errors

Returns an error when the generated crate cannot be written.

pub async fn create( path: impl AsRef<Path>, options: CreateOptions, ) -> Result<Self, FailToCreateProject>

Create a new WaterUI project at the specified path.

This creates the project directory, scaffolds root files (Cargo.toml, src/lib.rs), and saves the Water.toml manifest. Use init_apple_backend() and init_android_backend() to scaffold platform backends after creation.

Errors

• FailToCreateProject::DirectoryExists: If the directory already exists.
• FailToCreateProject::CreateDir: If creating the directory fails.
• FailToCreateProject::Scaffold: If scaffolding files fails.
• FailToCreateProject::SaveManifest: If saving the manifest fails.

pub async fn init( path: impl AsRef<Path>, options: CreateOptions, ) -> Result<Self, FailToCreateProject>

Initialize a WaterUI project inside an existing directory (water init): the same scaffold as Project::create without the directory-creation step.

Errors

• FailToCreateProject::AlreadyProject: If Water.toml already exists.
• FailToCreateProject::CargoManifestExists: If Cargo.toml already exists and would be overwritten.
• the Project::create scaffold errors.

pub async fn init_apple_backend(&mut self) -> Result<(), FailToInitBackend>

Initialize the Apple backend for this project.

This scaffolds the Apple backend files and updates the manifest.

Errors

Returns an error if scaffolding fails.

pub async fn init_android_backend(&mut self) -> Result<(), FailToInitBackend>

Initialize the Android backend for this project.

This scaffolds the Android backend files and updates the manifest.

Errors

Returns an error if scaffolding fails.

pub async fn init_gtk4_backend(&mut self) -> Result<(), FailToInitBackend>

Initialize the GTK4 backend for an existing project.

Creates necessary files/folders for the GTK4 backend under backend_path::<Gtk4Backend>().

Errors

Returns an error if scaffolding fails.

pub async fn init_hydrolysis_backend(&mut self) -> Result<(), FailToInitBackend>

Initialize the hydrolysis backend for an existing project.

Creates necessary files/folders for the hydrolysis backend under backend_path::<HydrolysisBackend>().

Errors

Returns an error if scaffolding fails.

pub async fn init_winui_backend(&mut self) -> Result<(), FailToInitBackend>

Initialize the WinUI backend for an existing project.

Creates necessary files/folders for the WinUI backend under backend_path::<WinUiBackend>().

Errors

Returns an error if scaffolding fails.

pub async fn init_esp32_backend(&mut self) -> Result<(), FailToInitBackend>

Initialize the ESP32 backend for an existing project.

Creates necessary files/folders for the ESP32 firmware harness under backend_path::<Esp32Backend>().

Errors

Returns an error if scaffolding fails.

pub async fn set_esp32_chip(&mut self, chip: Esp32Chip) -> Result<()>

Select the ESP32 target chip, persisting it to Water.toml.

The chip is the single source of truth for the ESP32 backend’s target triple, QEMU model, and firmware parameters. Selecting a platform such as esp32c3 calls this so the generated harness and build target follow the platform. No-ops (and skips the manifest write) when the configured chip already matches.

Errors

Returns an error if saving the manifest fails.

pub async fn remove_apple_backend(&mut self) -> Result<()>

Remove Apple backend configuration and generated files.

Errors

Returns an error if deleting files or saving manifest fails.

pub async fn remove_android_backend(&mut self) -> Result<()>

Remove Android backend configuration and generated files.

Errors

Returns an error if deleting files or saving manifest fails.

pub async fn remove_gtk4_backend(&mut self) -> Result<()>

Remove GTK4 backend configuration and generated files.

Errors

Returns an error if deleting files or saving manifest fails.

pub async fn remove_winui_backend(&mut self) -> Result<()>

Remove WinUI backend configuration and generated files.

Errors

Returns an error if deleting files or saving manifest fails.

pub async fn remove_hydrolysis_backend(&mut self) -> Result<()>

Remove hydrolysis backend configuration and generated files.

Errors

Returns an error if deleting files or saving manifest fails.

pub async fn remove_esp32_backend(&mut self) -> Result<()>

Remove ESP32 backend configuration and generated files.

Errors

Returns an error if deleting files or saving manifest fails.

pub async fn open(path: impl AsRef<Path>) -> Result<Self, FailToOpenProject>

Open a WaterUI project located at the specified path.

This loads both the Water.toml manifest and the Cargo.toml file. For playground projects, backends are automatically initialized if not configured.

Errors

• FailToOpenProject::Manifest: If there was an error opening the Water.toml manifest.
• FailToOpenProject::CargoManifest: If there was an error reading the Cargo.toml file.
• FailToOpenProject::MissingCrateName: If the crate name is missing in Cargo.toml.

pub async fn open_for_preview_build( path: impl AsRef<Path>, ) -> Result<Self, FailToOpenProject>

Open a project for preview dylib builds without initializing native app backends.

Playground preview dylib builds only need the managed preview wrapper crate. Native backend initialization is reserved for support app projects that actually launch apps.

Errors

• FailToOpenProject::Manifest: If there was an error opening the Water.toml manifest.
• FailToOpenProject::CargoManifest: If there was an error reading the Cargo.toml file.
• FailToOpenProject::MissingCrateName: If the crate name is missing in Cargo.toml.

Trait Implementations

impl Clone for Project

fn clone(&self) -> Project

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Project

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.