hare::module
hare::module implements the module resolution algorithm used by Hare. Given that
it is run within a Hare environment (i.e. with HAREPATH et al filled in), this
module will resolve module references from their identifiers, producing a list
of the source files which are necessary, including any necessary considerations
for build tags. This interface is stable, but specific to this Hare
implementation, and may not be portable to other Hare implementations.
This module also provides access to the Hare cache via manifests and their
related functions, but this is not considered stable, and may be changed if we
overhaul the cache format to implement better caching strategies.
Index
Types
type filetype;
type input;
type manifest;
type tag;
type tag_mode;
type version;
type context;
Errors
type ambiguous;
type error;
type notfound;
Functions
fn context_finish(*context) void;
fn context_init([]tag, []str, str) context;
fn current(*manifest, *version) bool;
fn identpath(ast::ident) str;
fn identuscore(ast::ident) str;
fn lookup(*context, ast::ident) (version | error);
fn manifest_finish(*manifest) void;
fn manifest_load(*context, ast::ident) (manifest | error);
fn manifest_write(*context, *manifest) (void | error);
fn parsename(str) (str, str, []tag);
fn parsetags(str) ([]tag | void);
fn scan(*context, str) (version | error);
fn strerror(error) const str;
fn tagcompat([]tag, []tag) bool;
fn tags_dup([]tag) []tag;
fn tags_free([]tag) void;
fn walk(*context, str) ([]ast::ident | error);
fn walk_free([]ast::ident) void;
Types
type filetype
type filetype = enum {
HARE,
ASSEMBLY,
};
The filetype of a file within a module.
type input = struct {
hash: []u8,
path: str,
ft: filetype,
stat: fs::filestat,
basename: str,
tags: []tag,
};
An input to a module, generally a source file.
type manifest
type manifest = struct {
ident: ast::ident,
inputs: []input,
versions: []version,
};
The manifest for a particular module, with some number of inputs, and
versions.
type tag
type tag = struct {
name: str,
mode: tag_mode,
};
A build tag, e.g. +x86_64.
type tag_mode
type tag_mode = enum {
INCLUSIVE,
EXCLUSIVE,
};
The inclusive/exclusive state for a build tag.
type version
type version = struct {
hash: []u8,
basedir: str,
depends: []ast::ident,
inputs: []input,
subdirs: []str,
tags: []tag,
};
A module version: a set of possible input files for that module.
type context
Show undocumented member
type context = struct {
fs: *fs::fs,
paths: []str,
cache: str,
tags: []tag,
defines: []str,
};
Errors
type ambiguous
type ambiguous = !(str, str);
We are unable to select from two ambiguous options for an input file.
type error
type error = !(fs::error | io::error | parse::error | notfound | ambiguous);
All possible error types.
type notfound
type notfound = !void;
The requested module could not be found.
Functions
fn context_finish
fn context_finish(ctx: *context) void;
Frees resources associated with this context.
fn context_init
fn context_init(tags: []tag, defs: []str, harepath: str) context;
Initializes a new context with the system default configuration. The tag list
and list of defines (arguments passed with harec -D) is borrowed from the
caller. The harepath parameter is not borrowed, but it is ignored if HAREPATH
is set in the process environment.
fn current
fn current(man: *manifest, ver: *version) bool;
Returns true if the desired module version is present and current in this
manifest.
fn identpath
fn identpath(name: ast::ident) str;
Converts an identifier to a partial path (e.g. foo::bar becomes foo/bar). The
return value must be freed by the caller.
fn identuscore
fn identuscore(ident: ast::ident) str;
Joins an ident string with underscores instead of double colons. The return
value must be freed by the caller.
This is used for module names in environment variables and some file names.
fn lookup
fn lookup(ctx: *context, name: ast::ident) (version | error);
Looks up a module by its identifier from HAREPATH, and returns a version
which includes all eligible build inputs.
fn manifest_finish
fn manifest_finish(m: *manifest) void;
Frees resources associated with this manifest.
fn manifest_load
fn manifest_load(ctx: *context, ident: ast::ident) (manifest | error);
Loads the module manifest from the build cache for the given ident. The
return value borrows the ident parameter. If the module is not found, an
empty manifest is returned.
fn manifest_write
fn manifest_write(ctx: *context, man: *manifest) (void | error);
Writes a module manifest to the build cache.
fn parsename
fn parsename(name: str) (str, str, []tag);
Given a file or directory name, parses it into the basename, extension, and
tag set.
fn parsetags(in: str) ([]tag | void);
Parses a set of build tags, returning void if the string is an invalid tag
set. The caller must free the return value with tags_free.
fn scan
fn scan(ctx: *context, path: str) (version | error);
Scans the files in a directory for eligible build inputs and returns a
version which includes all applicable files and their dependencies.
fn strerror
fn strerror(err: error) const str;
Returns a human-friendly representation of an error.
fn tagcompat
fn tagcompat(have: []tag, want: []tag) bool;
Compares two tag sets and tells you if they are compatible.
fn tags_dup(tags: []tag) []tag;
Duplicates a set of tags.
fn tags_free(tags: []tag) void;
Frees a set of tags.
fn walk
fn walk(ctx: *context, path: str) ([]ast::ident | error);
Recursively scans the filesystem to find valid Hare modules for the given
context, given the path to the entry point. The caller must free the
return value with walk_free.
fn walk_free
fn walk_free(items: []ast::ident) void;
Frees resources associated with the return value of walk.