hare::module +linux +x86_64

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.



type filetype;
type input;
type manifest;
type tag;
type tag_mode;
type version;

// Undocumented types:
type context;


type ambiguous;
type error;
type notfound;


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;


type filetype[link]

type filetype = enum {


The filetype of a file within a module.

type input[link]

type input = struct {
	hash: []u8,
	path: str,
	ft: filetype,
	stat: fs::filestat,
	// Name without any tags
basename: str, // Tags applicable to input
tags: []tag, };

An input to a module, generally a source file.

type manifest[link]

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[link]

type tag = struct {
	name: str,
	mode: tag_mode,

A build tag, e.g. +x86_64.

type tag_mode[link]

type tag_mode = enum {


The inclusive/exclusive state for a build tag.

type version[link]

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[link]

Show undocumented member
type context = struct {
	// Filesystem to use for the cache and source files.
fs: *fs::fs, // List of paths to search, generally populated from HAREPATH plus some
// baked-in defaults.
paths: []str, // Path to the Hare cache, generally populated from HARECACHE and
// defaulting to $XDG_CACHE_HOME/hare.
cache: str, // Build tags to apply to this context.
tags: []tag, // List of -D arguments passed to harec
defines: []str, };


type ambiguous[link]

type ambiguous = !(str, str);

We are unable to select from two ambiguous options for an input file.

type error[link]

type error = !(fs::error | io::error | parse::error | notfound | ambiguous);

All possible error types.

type notfound[link]

type notfound = !void;

The requested module could not be found.


fn context_finish[link]

fn context_finish(ctx: *context) void;

Frees resources associated with this context.

fn context_init[link]

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[link]

fn current(man: *manifest, ver: *version) bool;

Returns true if the desired module version is present and current in this manifest.

fn identpath[link]

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[link]

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[link]

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[link]

fn manifest_finish(m: *manifest) void;

Frees resources associated with this manifest.

fn manifest_load[link]

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[link]

fn manifest_write(ctx: *context, man: *manifest) (void | error);

Writes a module manifest to the build cache.

fn parsename[link]

fn parsename(name: str) (str, str, []tag);

Given a file or directory name, parses it into the basename, extension, and tag set.

fn parsetags[link]

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[link]

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[link]

fn strerror(err: error) const str;

Returns a human-friendly representation of an error.

fn tagcompat[link]

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

Compares two tag sets and tells you if they are compatible.

fn tags_dup[link]

fn tags_dup(tags: []tag) []tag;

Duplicates a set of tags.

fn tags_free[link]

fn tags_free(tags: []tag) void;

Frees a set of tags.

fn walk[link]

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[link]

fn walk_free(items: []ast::ident) void;

Frees resources associated with the return value of walk.