pkg

Documentation

Overview

pkg implements MX Script's package manager. The model is deliberately Go-flavoured: dependency identifiers are full URLs (`github.com/owner/repo`), there's a tiny human-readable manifest (`mxpkg.json`), and downloaded sources live under `./mx_modules` in the project root. There is no central registry — packages are fetched directly from their git origin via `git clone`.

Today the manifest tracks: dependency URL, locked commit SHA, and optional entry-point file (defaults to `main.mx`). Future versions will add semver / tag support, a lockfile separate from the manifest, and `mx pkg vendor` for offline builds.

Index

• Constants
• func CloneURL(importPath string) string
• func EntryFile(dir string, dep Dependency, importPath string) string
• func Init(dir, name string) (bool, error)
• func Install(dir string) error
• func LocalPath(dir, importPath string) string
• func NormalizeImportPath(raw string) string
• func Remove(dir, rawPath string) error
• func ResolveImportFile(dir, importPath string) string
• func SaveManifest(dir string, m *Manifest) error
• func Update(dir, rawPath string) error
• type Dependency
  • func Add(dir, rawPath string) (Dependency, error)
• type Manifest
  • func LoadManifest(dir string) (*Manifest, error)

Constants

const (
	ManifestFile = "mxpkg.json"
	ModulesDir   = "mx_modules"
)

Functions

func CloneURL

func CloneURL(importPath string) string

CloneURL builds the HTTPS clone URL for an import path so the package manager can shell out to `git clone` without baking in any assumptions about a specific host beyond "https works".

func EntryFile

func EntryFile(dir string, dep Dependency, importPath string) string

EntryFile returns the absolute path to the entry .mx file for a dependency. Defaults to main.mx if the manifest doesn't override.

func Init

func Init(dir, name string) (bool, error)

Init creates a fresh manifest if one doesn't exist. Returns true if it created the file, false if it already existed.

func Install

func Install(dir string) error

Install ensures every manifest dependency is present on disk. Used by collaborators after `git clone`-ing a project. Skips packages that are already installed at the locked SHA.

func LocalPath

func LocalPath(dir, importPath string) string

LocalPath returns where a dependency lives on disk, relative to the project root.

github.com/foo/bar -> mx_modules/foo/bar  (host stripped — repos are namespaced
                                            by owner/name, not by host, today)

The host segment is omitted intentionally so paths in source code stay short. If multi-host support becomes a problem we'll reverse this — for now the design matches Go's "repo by owner/name" mental model.

func NormalizeImportPath

func NormalizeImportPath(raw string) string

NormalizeImportPath turns user-friendly forms into the canonical host/owner/repo path used as the manifest key. Accepts:

github.com/foo/bar
https://github.com/foo/bar
https://github.com/foo/bar.git
git@github.com:foo/bar.git

func Remove

func Remove(dir, rawPath string) error

Remove deletes the on-disk module directory and the manifest entry. Doesn't `git rm` because mx_modules is expected to be in .gitignore.

func ResolveImportFile

func ResolveImportFile(dir, importPath string) string

ResolveImportFile, given an import path that looks like a package reference (`github.com/foo/bar`), returns the on-disk .mx file the MX runtime should read. Returns "" when the path doesn't look like a package reference (so callers can fall back to plain file paths).

func SaveManifest

func SaveManifest(dir string, m *Manifest) error

SaveManifest writes the manifest with stable key ordering and two-space indentation so diffs stay readable across versions.

func Update

func Update(dir, rawPath string) error

Update pulls the latest commit for a single dependency and updates its locked Ref. With empty path, updates every dependency.

Types

type Dependency

type Dependency struct {
	URL   string `json:"url"`
	Ref   string `json:"ref"`
	Entry string `json:"entry,omitempty"` // defaults to main.mx
}

Dependency is one entry in the manifest's `dependencies` map. The key is the import path (e.g. `github.com/foo/bar`); the value captures everything we need to reproduce an install: the locked commit SHA, and the entry file the import statement resolves to.

func Add

func Add(dir, rawPath string) (Dependency, error)

Add clones (or reuses) a dependency, locks it to the current HEAD commit, and updates the manifest. If the dependency already exists in mx_modules we don't re-clone — the caller can `mx pkg update` for that.

type Manifest

type Manifest struct {
	Name         string                `json:"name"`
	Version      string                `json:"version"`
	Description  string                `json:"description,omitempty"`
	Dependencies map[string]Dependency `json:"dependencies,omitempty"`
}

Manifest is the JSON shape persisted at the project root. Keep fields stable — third-party tools (CI, registries) read it.

func LoadManifest

func LoadManifest(dir string) (*Manifest, error)

LoadManifest reads mxpkg.json from `dir` (or `.` if dir is empty). Returns nil + nil if the file doesn't exist — callers decide whether that's an error in their context.