CompileOptions

Syntax

interface CompileOptions {
  readonly fileName?: string;
  readonly consoleSink?: ConsoleSink;
  readonly deprecations?: boolean;
  readonly console?: 'cpu' | 'gpu';
  readonly readDocument?: (fileName: string) => string | undefined;
  readonly resolveImport?: (fromFile: string, specifier: string) => string | undefined;
}

Description

Every field is optional, and the defaults are what compile(source) did before this interface existed.

Instance properties

fileNameoptionalread only string

The name this source is compiled under. It is the file of every SourceSpan the front end stamps on the IR, and the fileName of every diagnostic, so it is how a consumer that holds a span says which of the author’s files a statement came from.

That default is fine for a compile whose output is shader text, since nothing reads the name, but not for one whose output is stepped: a DebugBreakpoint carries the path the editor knows the file by, and matches it against span.file, so a session compiled under the placeholder silently arms no breakpoint at all. An adapter that has a path should pass it.

Nothing resolves or reads it: it is a label carried to the spans, not a path the compiler opens. An adapter does not have to care: a DebugBreakpoint’s path is normalized the same way before it is compared, so either spelling matches.

consoleSinkoptionalread only ConsoleSink

Host sink for console.* calls made by CPU/debug evaluation.

deprecationsoptionalread only boolean

Report deprecation warnings for spellings whose meaning is scheduled to change. One today: an integer-written literal in a declaration with no annotation or declared integer use still types as f32 and will type as i32 (§13).

Off by default, and off is the whole of the compiler’s behaviour: the flag adds category: 'warning' diagnostics and moves no emitted byte, so wgsl and glsl are byte-identical with it on and with it off. It is how a build finds the lines the flip will move, one release ahead of it.

consoleoptionalread only 'cpu' | 'gpu'

Where a console call is recorded. 'cpu', the default, is what compile() always did: the CPU run delivers each call to CompileOptions.consoleSink, and the WGSL and GLSL record nothing, so no emitted byte depends on a console call. 'gpu' makes the WGSL also record each call a compute or fragment entry reaches, in a _console storage buffer the compiler binds at group 0 past the module’s own bindings; CompileResult.console says where, and decodeConsole turns the buffer the host copies back into the same events. A call the WGSL cannot record is a TS8071 warning. GLSL ES 3.00 records nothing either way. Surface §66, Rule 11.9.

readDocumentoptionalread only (fileName: string) => string | undefined

Reads a file this source imports (Rule 3.9, surface §68): its text, or undefined when there is none. The source and every shader file it imports, directly or through another, are one program, compiled into one module, and a diagnostic located in an imported file carries that file’s name and offsets. It is asked for a package’s package.json too, which the default resolveImport reads to find a package in node_modules, so a readDocument that reads from disk follows a package with no change. Without it nothing is read: a source with no import compiles as it always has, and an import is TS8072. The same hook as the language service’s TypeshadeLanguageServiceHost.readDocument, so both halves read one program.

resolveImportoptionalread only (fromFile: string, specifier: string) => string | undefined

The file a specifier written in fromFile names, or undefined when it names none. The default, which the language service applies too, resolves a relative specifier against the importing file (fileName for the source), reads .js and .mjs as .ts, and appends .ts to any other path. Any other specifier names a package: the first node_modules/<name>/package.json from the importing file’s directory up, read through readDocument, and the file its exports publishes under the typeshade condition (surface §68, change 0024). A hook passed here replaces the rule for every specifier.

See also

• CompileResult
• decodeConsole

Source

src/compiler/ts/compile.ts, line 88, at commit 26de7be8