hare::module — Hare documentation

hare::module+x86_64 +linux

hare::module provides an interface to the module system used by this Hare implementation, as well as to the Hare cache. Note that these interfaces may not be portable to other Hare implementations.

Note that much of this module's design is an implementation detail of the Hare toolchain, and is not subject to any future compatibility guarantees.

Index

Types

type context = struct {
	harepath: str,
	harecache: str,
	tags: []str,
};
type location = (*path::buffer | ast::ident);
type module = struct {
	name: str,
	ns: ast::ident,
	path: str,
	srcs: srcset,
	// [](Index to the module, Identifier of of the module)
	deps: [](size, ast::ident),
};
type srcset = struct {
	// The last time the list of source files changed. Note that this is not
	// the last time that the source files themselves changed.
	mtime: time::instant,
	// Source directories traversed while finding these source files.
	dirs: []str,
	// The list of tags that were actually encountered while finding these
	// source files. These are sorted alphabetically, and are the set of
	// tags that should be used to find this module in the cache.
	seentags: []str,
	// hare source files (.ha)
	ha: []str,
	// assembly source files (.s)
	s: []str,
	// object source files (.o)
	o: []str,
	// linker scripts (.sc)
	sc: []str,
};
type tag = struct {
	// The name of the tag.
	name: str,
	// Whether the tag is inclusive (+tag) or not (-tag).
	include: bool,
};

Errors

type dep_cycle = ![]str;
type errcontext = !(str, *error);
type error = !(fs::error | io::error | path::error | parse::error | utf8::invalid | file_conflict | not_found | dep_cycle | tag_has_dot | tag_bad_format | errcontext);
type file_conflict = ![]str;
type not_found = !void;
type tag_bad_format = !void;
type tag_has_dot = !void;

Functions

fn find(ctx: *context, loc: location) ((str, srcset) | error);
fn finish(mod: *module) void;
fn finish_error(e: error) void;
fn finish_srcset(srcs: *srcset) void;
fn format(out: io::handle, mod: *module) (size | io::error);
fn format_srcset(out: io::handle, srcs: *srcset) (size | io::error);
fn format_tags(out: io::handle, tags: ([]str | []tag)) (size | io::error);
fn free_slice(mods: []module) void;
fn gather(ctx: *context, out: *[]module, mod: location) (size | error);
fn get_cache(harecache: str, modpath: str) (str | error);
fn locstr(loc: location) str;
fn next(it: *fs::iterator) (fs::dirent | done | fs::error);
fn outdated(target: str, deps: []str, mtime: time::instant) bool;
fn parse_deps(files: str...) ([]ast::ident | error);
fn parse_tags(s: str) ([]tag | error);
fn strerror(e: error) str;
fn tags_compat(have: []str, want: []tag) bool;

Types

type context[link]

type context = struct {
	harepath: str,
	harecache: str,
	tags: []str,
};

A container struct for context, used by gather.

type location[link]

type location = (*path::buffer | ast::ident);

The location of a module

type module[link]

type module = struct {
	name: str,
	ns: ast::ident,
	path: str,
	srcs: srcset,
	// [](Index to the module, Identifier of of the module)
	deps: [](size, ast::ident),
};

A hare module.

type srcset[link]

type srcset = struct {
	// The last time the list of source files changed. Note that this is not
	// the last time that the source files themselves changed.
	mtime: time::instant,
	// Source directories traversed while finding these source files.
	dirs: []str,
	// The list of tags that were actually encountered while finding these
	// source files. These are sorted alphabetically, and are the set of
	// tags that should be used to find this module in the cache.
	seentags: []str,
	// hare source files (.ha)
	ha: []str,
	// assembly source files (.s)
	s: []str,
	// object source files (.o)
	o: []str,
	// linker scripts (.sc)
	sc: []str,
};

A set of sources for a module, filtered by a set of tags.

type tag[link]

type tag = struct {
	// The name of the tag.
	name: str,
	// Whether the tag is inclusive (+tag) or not (-tag).
	include: bool,
};

A file tag, e.g. +x86_64, or -libc.

Errors

type dep_cycle[link]

type dep_cycle = ![]str;

A dependency cycle error.

type errcontext[link]

type errcontext = !(str, *error);

Context for another error.

type error[link]

type error = !(fs::error | io::error | path::error | parse::error | utf8::invalid | file_conflict | not_found | dep_cycle | tag_has_dot | tag_bad_format | errcontext);

Tagged union of all possible error types. Must be freed with finish_error unless it's passed to strerror.

type file_conflict[link]

type file_conflict = ![]str;

Two files in a module have the same basename and extension, and the same number of compatible tags with the input tagset, so it is unknown which should be used.

type not_found[link]

type not_found = !void;

A module was not found.

type tag_bad_format[link]

type tag_bad_format = !void;

Generic badly formatted tag error.

type tag_has_dot[link]

type tag_has_dot = !void;

A tag contains a dot.

Functions

fn find[link]

fn find(ctx: *context, loc: location) ((str, srcset) | error);

Find the on-disk path and set of source files for a given module. The path is statically allocated and may be overwritten on subsequent calls.

fn finish[link]

fn finish(mod: *module) void;

Free the resources associated with a module.

fn finish_error[link]

fn finish_error(e: error) void;

Free the resources associated with an error.

fn finish_srcset[link]

fn finish_srcset(srcs: *srcset) void;

Frees the resources associated with a srcset.

fn format[link]

fn format(out: io::handle, mod: *module) (size | io::error);

Formats a module to an io::handle.

fn format_srcset[link]

fn format_srcset(out: io::handle, srcs: *srcset) (size | io::error);

Formats a srcset to an io::handle.

fn format_tags[link]

fn format_tags(out: io::handle, tags: ([]str | []tag)) (size | io::error);

Formats a set of tags to an io::handle in "+tag1-tag2" format.

fn free_slice[link]

fn free_slice(mods: []module) void;

Free all the modules in a slice of modules, and then the slice itself.

fn gather[link]

fn gather(ctx: *context, out: *[]module, mod: location) (size | error);

Gather a module and all its dependencies, appending them to an existing slice, deduplicated, in reverse topological order, returning the index of the input module within the slice. Dependencies will also be written to the cache.

fn get_cache[link]

fn get_cache(harecache: str, modpath: str) (str | error);

Gets the cache directory for a given module, given the value of 'harecache'. The result is statically allocated and will be overwritten on subsequent calls. An error is returned if the resulting path would be longer than path::MAX.

fn locstr[link]

fn locstr(loc: location) str;

Returns a string representation of a location. The result must be freed by the caller.

fn next[link]

fn next(it: *fs::iterator) (fs::dirent | done | fs::error);

Wrapper for fs::next that only returns valid submodule directories.

fn outdated[link]

fn outdated(target: str, deps: []str, mtime: time::instant) bool;

Checks if the file at 'target' is out-of-date, given a list of dependency files, and the last time the deps list changed. If "target" doesn't exist, returns true. If any of the deps don't exist, they are skipped.

fn parse_deps[link]

fn parse_deps(files: str...) ([]ast::ident | error);

Get the list of dependencies referred to by a set of source files. The list will be sorted alphabetically and deduplicated.

fn parse_tags[link]

fn parse_tags(s: str) ([]tag | error);

Parses tags from a string. The tag themselves are borrowed from the input, but the caller must free the slice returned.

fn strerror[link]

fn strerror(e: error) str;

Turns an error into a human-readable string. The result is statically allocated. Consumes the error.

fn tags_compat[link]

fn tags_compat(have: []str, want: []tag) bool;

Checks if a set of tags are compatible with a tag requirement.