Struct Project 

pub struct Project {
    pub root: PathBuf,
    pub manifest: PathBuf,
    pub lockfile: PathBuf,
    pub pkgs_dir: PathBuf,
    pub vendored: PathBuf,
    pub target_dirs: Vec<PathBuf>,
    pub vendored_copies: Vec<PathBuf>,
    pub patches: Vec<Patched>,
}

An mlua-pkg.toml project: where the manifest, lockfile and installed deps live.

Installed deps go under pkgs_dir — <root>/.htl/modules, beside the check cache and regenerated the same way: from the manifest and the lockfile rather than from the project’s own sources. Deps that are committed are the other thing, and they are declared: target_dirs.

Fields

root: PathBuf

manifest: PathBuf

lockfile: PathBuf

pkgs_dir: PathBuf

vendored: PathBuf

pkgs_dir/vendored: one entry per installed dep, pointing at what mlua-pkg fetched. The name is mlua-pkg’s own and describes its layout, not htl’s — what is in there is installed and regenerated, while a copy that is committed to the repo is a target_dir dep below.

target_dirs: Vec<PathBuf>

Parent directories of target_dir deps (physically vendored copies declared in the manifest, e.g. target_dir = "lua/lshape" -> <root>/lua), so require("lshape") resolves to <root>/lua/lshape/init.* like a vendored dep.

vendored_copies: Vec<PathBuf>

The target_dir copies themselves (<root>/lua/lshape), as against the parents above.

A copy is a dependency’s source that happens to sit in the repo, and mlua-pkg install rewrites it every time it runs — so it is not the project’s to check, format or take tests from, and editing one there does not survive the next install. What that means for the walkers is in crate::project_skip_dirs.

patches: Vec<Patched>

The patch_dir deps: a dependency’s source taken into the tree, and what the manifest calls it. Unlike a target_dir copy, which install rewrites, this one is the project’s own code — Project::patch wrote it once and the project edits it from then on. What that means for the walkers is in crate::patched_dirs.

Implementations

impl Project

pub fn find(start: &Path) -> Option<Self>

Walk up from start (a file or directory) looking for mlua-pkg.toml.

pub fn at(root: &Path) -> Self

Project rooted at root (must contain mlua-pkg.toml; not checked here).

pub fn patch_dirs(&self) -> Vec<PathBuf>

Where the patched deps are, for a walker that only asks whether it may enter.

pub fn installed(&self) -> bool

true once mlua-pkg install has produced the lockfile.

pub fn teal_resolver(&self) -> Result<TealResolver, InitError>

Resolver for .tl / .d.tl inside vendored deps (symlink-aware, like VendoredResolver). Creates the vendored dir if it does not exist yet.

pub fn vendored_resolver(&self) -> Result<VendoredResolver>

mlua-pkg’s own resolver for plain .lua inside vendored deps.

pub fn registry(&self) -> Result<Registry>

Registry with the project’s deps: Teal first, then plain Lua. Add your NativeResolvers before calling install if Teal code declares them in .d.tl.

pub fn sync_types(&self) -> Result<TypesSync>

Bring the declarations a dep publishes into the project’s own types/.

A dep that follows htl’s own convention keeps its .d.tl under types/ at its package root, and that is outside the entry directory vendored/<name> points at — so the checker never sees it, and the depending project writes the declaration again by hand. Copying rather than widening the search path is what makes the result survive a fresh clone: pkgs_dir is machine-local and empty until someone installs, while types/ is committed.

A name types/ already has is left alone and reported. Two libraries publishing a module of the same name is a real situation, and there is no registry to arbitrate it with, so the project decides rather than the last install winning.

pub fn add_types(&self, library: &str, force: bool) -> Result<TypesSync>

Copy one library’s declarations out of teal-types into types/.

teal-types is where the Teal ecosystem collects declarations for libraries that ship none of their own, laid out as types/<library>/<module>.d.tl. Nothing there ties a declaration to a version of the library it describes: the rocks are versioned on their own count, declare no dependency on the library, and name no revision of it. So the .src note beside each file is the whole of the record — what was taken, and from which commit of the collection.

pub fn add_types_from( &self, checkout: &Path, library: &str, sha: &str, force: bool, ) -> Result<TypesSync>

The same from a checkout already on disk, recording sha as the revision it is at.

pub fn install(&self) -> Result<InstallReport>

Fetch every dependency the manifest declares, and write the lockfile.

The report says what each one resolved to and where it was placed, including whether it came from a patch_dir; nothing is printed here. Declarations a dependency publishes are a separate step (Project::sync_types) because they are copied into the project rather than installed.

pub fn add(&self, spec: AddSpec) -> Result<AddDone>

Write a dependency into the manifest. install is what fetches it.

mlua-pkg replaces the whole [deps.<name>] entry and AddSpec carries no patch_dir, so adding a dependency that is already patched would drop the key that binds patches/<dep> to it — the project would keep building, against upstream, with the copy sitting unread in the tree. What the entry declared about its patch is carried across and reported.

pub fn update(&self, opts: UpdateOpts) -> Result<UpdateReport>

Refresh dependencies, bump the pins that follow releases, and install what changed.

pub fn clean(&self, all: bool) -> Result<CleanReport>

Remove cached packages the lockfile no longer refers to (all: the whole cache).

Never touches what install placed under vendored/: a dangling link there is repaired by the next install.

pub fn patch(&self, name: &str, force: bool) -> Result<PatchReport>

Take a dependency’s source into patches/<dep>/, where the project owns it.

The whole package root is copied, so the dep’s types/ comes with it, and patch_dir on that dependency in the manifest says which dependency the directory stands in for. There is no patch file and nothing is applied: from here the directory is the project’s code, edited and committed with git like the rest of the tree, and install resolves the dependency from it for as long as the pin still resolves to the revision the copy was taken from (patch_base in the lockfile). When the pin moves on, install uses the new revision, leaves the copy alone and says so on every install until the patch is refreshed or removed.

On a dependency that is already patched this refreshes the copy from the revision the pin now resolves to and records that as the new base. The copy is overwritten rather than merged — carrying the project’s own change forward onto it is a merge git performs, and it can only do that if the change is committed — so a directory with uncommitted changes is refused unless force.

pub fn patch_status(&self) -> Vec<PatchStatus>

Where each patched dependency stands, read back from the manifest and the lockfile.

A patch is bound to the revision it was taken from. Install compares the two itself and falls back to upstream when they differ; this reads the same two values afterwards so htl can say what happened in its own verbs — mlua-pkg’s warning names mlua-pkg patch --force, which skips the question htl asks git and leaves the dependency’s .git in the copy.

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.