Bundle

Bundle names the one directory a program’s resources live in — a shader, a font, a template, a dictionary, a set of fixtures — and resolves a resource name inside it. “The directory I was started from” is not an answer to that question: a launcher, a desktop icon and a test harness each start a program somewhere else.

#import "Bundle.xc"

Overview

Bundle.main() is the directory of the running executable (argv[0]), which is where an installed program’s resources sit. When the layout is different, $XCC_BUNDLE_ROOT overrides it, and Bundle.withRoot names any directory outright — which is what a test wants.

Bundle* b = Bundle.main();
String* t = b.textForResource(String.withCString("greeting"), String.withCString("txt"));
if (t == 0) { /* there is no such resource */ }

resourcePath is <root>/Resources when such a directory exists and <root> otherwise, so the same source works for an app that has a Resources folder and for one that keeps everything flat.

A missing resource is 0, not an empty string, so “there is no such resource” and “the resource is empty” stay different answers.

Availability

Bundle is a generic/lib/ class and is cross-platform: arm64, arm9, m68k, x86_64 and win64 read resources; wasm32 reads them through its loader. On xt6502 there is no filesystem and no argv, so a bundle can be named — root, directoryOf and the path builders all work — but textForResource and its siblings always answer 0.

Topics

Construction · withRoot · main · mainFrom · directoryOf

Paths · root · resourcePath · pathFor · pathForResource

Contents · resourceExists · textForResource · dataForResource

---

Construction

withRoot

static Bundle* withRoot(String* root)

A bundle whose resources live under root. A null or empty root becomes ., so the path builders always produce something usable.

main

static Bundle* main(void)

The bundle of the running program: $XCC_BUNDLE_ROOT when that is set and non-empty, otherwise the directory part of argv[0], otherwise ..

mainFrom

static Bundle* mainFrom(String* envName)

The same, reading envName instead of $XCC_BUNDLE_ROOT — for a program with several bundles, or one that already has a variable of its own. A null or empty envName is main.

directoryOf

static String* directoryOf(String* path)

The directory part of path: everything before the last / or \. A path with no separator yields .; a leading separator yields /. Public because the same question comes up outside a bundle.

↑ Topics

Paths

root

String* root(void)

The directory the bundle was built with.

resourcePath

String* resourcePath(void)

<root>/Resources when that directory exists, <root> otherwise. Every resource lookup goes through here, which is what makes the flat and the Resources layouts interchangeable.

pathFor

String* pathFor(String* relative)

A path inside the resources, whether or not the file is there. An empty relative is resourcePath itself.

pathForResource

String* pathForResource(String* name, String* ext)
String* pathForResource(String* name, String* ext, String* subdir)

<resourcePath>/<subdir>/<name>.<ext>. An empty ext drops the dot, so an extensionless resource is nameable; an empty subdir is the resources themselves. The path is built whether or not the file is there, so a caller can name where a resource would be.

↑ Topics

Contents

resourceExists

bool resourceExists(String* name, String* ext)

true when the resource is there.

textForResource

String* textForResource(String* name, String* ext)

The resource’s bytes as a String, or 0 when it is missing.

dataForResource

Data* dataForResource(String* name, String* ext)

The resource’s bytes as Data, or 0 when it is missing.

↑ Topics

See also

• Settings: where a program’s values are kept, as opposed to where its files live.
• String: the type a resource path and a text resource come back as.