/* * Parcel's native plugin ABI. A plugin is a shared library that defines the * parcel_plugin_* entry points declared at the end of this file, and calls back * into Parcel through the ParcelApi table it receives in parcel_plugin_init2(). * * Threading: Parcel calls a plugin from many threads, and calls overlap. Every * call for one .parcelrc entry receives the same `state`, so anything in it that * changes needs synchronizing. Today, transforms and resolves run in parallel * with each other, as do optimizers and custom content packaging, and log * events reach parcel_plugin_report() on whichever thread logged them, alongside * everything else. parcel_plugin_init2() may run concurrently for different * entries; parcel_plugin_deinit() runs once no other call for its entry is * running. Custom content callbacks run on any thread, possibly in a later * build, and possibly after parcel_plugin_deinit(). * * Lifetimes: a handle is valid only until the call that received or obtained it * returns, unless its documentation says otherwise. Never keep one in plugin * state or custom content. * * Memory: what Parcel reads during a call, it only borrows. Strings and bytes a * plugin passes into a call, as a pointer and length, whether as arguments or in * an options struct, may point at the plugin's own memory, and Parcel copies * what it keeps before returning. What Parcel reads after a call returns, it * owns: an entry point's output, such as its `DiagnosticOptions` or * `ResolveResult`, holds `Buffer`s the plugin allocated with * parcel_buffer_alloc(), which Parcel frees. And a `Buffer` Parcel fills in for * the plugin, such as a getter's, is the plugin's to free with * parcel_buffer_free(). */ #ifndef PARCEL_PLUGIN_H #define PARCEL_PLUGIN_H #include #include #include /** * The plugin ABI implemented by this build of Parcel. * * Bumped whenever a change would make an existing plugin binary unsafe to load: * a changed or removed [`ParcelApi`] field, or a changed plugin entry point * signature. Appending to `ParcelApi` is compatible in both directions and does * not bump it — plugins check `size` before calling an appended function. * * Bumping this invalidates every plugin ever built, so prefer appending. To give * a host function a different signature, append a new field and leave the old one * pointing at a shim: `abi` stays put and existing plugins keep working across * the upgrade. That leaves plugin entry point signatures, which are not in this * table, as about the only thing a bump is genuinely needed for. * * Structs passed by pointer do not need a bump either: each starts with its own * `size`, so fields can be appended to them too. * * # Evolving the entry points * * The entry points a plugin exports (`parcel_plugin_transform()` and so on, see * the `entry_points` module) are the one part of the ABI a host can't extend by * appending, so they change only like this: * * - New per-call state reaches plugins through the `Options` handle every entry * point already receives: Parcel adds it to its `OptionsContext` and exposes * it through new host functions taking `Options`. Most needs end here. * - New output goes in a size-prefixed struct the entry point already fills * (`ResolveResult`, `OptimizeResult`, `DiagnosticOptions`), by appending a * field. * - An entry point whose arguments must change ships as a new symbol, such as * `parcel_plugin_optimize2()`. Parcel looks for the new symbol first and * falls back to the old one, so plugins built either way keep loading. An SDK * exports whichever it was built for. * - A new entry point, numbered or not, takes its inputs as one size-prefixed * args struct, so later inputs are appended rather than needing another * symbol. * * None of these needs a bump, which is why one should never be necessary. * * A published plugin repeats this in its package.json as `parcel.abi`, which * lets Parcel reject a mismatch before opening the library. That copy is * human-written metadata; the authoritative check is the one the plugin makes * against this field. */ #define PARCEL_ABI_VERSION 1 enum BundleBehavior #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_BUNDLE_BEHAVIOR_NONE = 0, PARCEL_BUNDLE_BEHAVIOR_INLINE = 1, PARCEL_BUNDLE_BEHAVIOR_ISOLATED = 2, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum BundleBehavior BundleBehavior; #else typedef uint8_t BundleBehavior; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum BundleGraphResolutionType #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_BUNDLE_GRAPH_RESOLUTION_INVALID = 0, PARCEL_BUNDLE_GRAPH_RESOLUTION_NONE = 1, PARCEL_BUNDLE_GRAPH_RESOLUTION_DEFERRED = 2, PARCEL_BUNDLE_GRAPH_RESOLUTION_EXTERNAL = 3, PARCEL_BUNDLE_GRAPH_RESOLUTION_EXCLUDED = 4, PARCEL_BUNDLE_GRAPH_RESOLUTION_ASSET = 5, PARCEL_BUNDLE_GRAPH_RESOLUTION_BUNDLE = 6, PARCEL_BUNDLE_GRAPH_RESOLUTION_INTERNALIZED = 7, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum BundleGraphResolutionType BundleGraphResolutionType; #else typedef uint8_t BundleGraphResolutionType; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum SpecifierType #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_SPECIFIER_ESM = 0, PARCEL_SPECIFIER_COMMONJS = 1, PARCEL_SPECIFIER_URL = 2, PARCEL_SPECIFIER_CUSTOM = 3, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum SpecifierType SpecifierType; #else typedef uint8_t SpecifierType; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum Priority #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_PRIORITY_SYNC = 0, PARCEL_PRIORITY_PARALLEL = 1, PARCEL_PRIORITY_LAZY = 2, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum Priority Priority; #else typedef uint8_t Priority; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum ImportType #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { /** * The module's exports. A file imported this way must have a transformer that turns it into * JavaScript, or it is an error. */ PARCEL_IMPORT_TYPE_JAVASCRIPT = 0, /** * A `CSSStyleSheet`. */ PARCEL_IMPORT_TYPE_STYLESHEET = 1, /** * The URL of the file. Any file can be referenced this way, transformed or not. */ PARCEL_IMPORT_TYPE_URL = 2, /** * The bundle's contents as a string. */ PARCEL_IMPORT_TYPE_TEXT = 3, /** * The bundle's contents as bytes. */ PARCEL_IMPORT_TYPE_BYTES = 4, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum ImportType ImportType; #else typedef uint8_t ImportType; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus /** * The level of a log event, and of a message passed to `parcel_options_log()`. */ enum LogLevel #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_LOG_NONE = 0, PARCEL_LOG_ERROR = 1, PARCEL_LOG_WARN = 2, PARCEL_LOG_INFO = 3, PARCEL_LOG_VERBOSE = 4, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum LogLevel LogLevel; #else typedef uint8_t LogLevel; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum Environment #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_ENV_BROWSER = 0, PARCEL_ENV_WEB_WORKER = 1, PARCEL_ENV_SERVICE_WORKER = 2, PARCEL_ENV_WORKLET = 3, PARCEL_ENV_NODE = 4, PARCEL_ENV_ELECTRON_MAIN = 5, PARCEL_ENV_ELECTRON_RENDERER = 6, PARCEL_ENV_REACT_CLIENT = 7, PARCEL_ENV_REACT_SERVER = 8, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum Environment Environment; #else typedef uint8_t Environment; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum OutputFormat #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_OUTPUT_FORMAT_GLOBAL = 0, PARCEL_OUTPUT_FORMAT_COMMONJS = 1, PARCEL_OUTPUT_FORMAT_ESMODULE = 2, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum OutputFormat OutputFormat; #else typedef uint8_t OutputFormat; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum SourceType #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_SOURCE_TYPE_MODULE = 0, PARCEL_SOURCE_TYPE_SCRIPT = 1, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum SourceType SourceType; #else typedef uint8_t SourceType; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum DiagnosticSeverity #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_SEVERITY_ERROR = 0, PARCEL_SEVERITY_WARNING = 1, PARCEL_SEVERITY_SOURCE_ERROR = 2, PARCEL_SEVERITY_INFO = 3, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum DiagnosticSeverity DiagnosticSeverity; #else typedef uint8_t DiagnosticSeverity; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus /** * Outcome of a file system call. */ enum IoStatus #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { /** * The call succeeded and its result is in the output buffer. */ PARCEL_IO_OK = 0, /** * The path does not exist. The output buffer is left empty. */ PARCEL_IO_NOT_FOUND = 1, /** * Any other failure. The output buffer holds a UTF-8 description of it. */ PARCEL_IO_ERROR = 2, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum IoStatus IoStatus; #else typedef uint8_t IoStatus; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus /** * Result of a plugin's `parcel_plugin_init2()` (or `parcel_plugin_init()`). * * A plugin that cannot use the `ParcelApi` table it was * handed returns `PARCEL_INIT_INCOMPATIBLE` without writing a diagnostic — it * has no way to allocate one, since allocating goes through the very table it * just rejected. Parcel writes that diagnostic instead. */ enum InitStatus #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { /** * The plugin initialized. Its state, if any, is in the `state` out param. */ PARCEL_INIT_OK = 0, /** * The plugin failed and wrote a diagnostic describing why. */ PARCEL_INIT_ERROR = 1, /** * The plugin cannot run against this build of Parcel. No diagnostic was * written; Parcel reports the mismatch. */ PARCEL_INIT_INCOMPATIBLE = 2, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum InitStatus InitStatus; #else typedef uint8_t InitStatus; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum ResolutionType #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_RESOLUTION_NONE = 0, PARCEL_RESOLUTION_FILE_PATH = 1, PARCEL_RESOLUTION_EXTERNAL = 2, PARCEL_RESOLUTION_EXCLUDED = 3, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum ResolutionType ResolutionType; #else typedef uint8_t ResolutionType; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus /** * The kind of event passed to `parcel_plugin_report()`. */ enum ReportEventType #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_EVENT_BUILD_START = 0, PARCEL_EVENT_BUILD_SUCCESS = 1, PARCEL_EVENT_BUILD_FAILURE = 2, PARCEL_EVENT_LOG = 3, }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum ReportEventType ReportEventType; #else typedef uint8_t ReportEventType; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum DependencyFlags #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint16_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_DEP_ENTRY = (1 << 0), PARCEL_DEP_OPTIONAL = (1 << 1), PARCEL_DEP_NEEDS_STABLE_NAME = (1 << 2), PARCEL_DEP_IS_WEBWORKER = (1 << 3), PARCEL_DEP_SIDE_EFFECTS = (1 << 4), PARCEL_DEP_MACRO = (1 << 5), }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum DependencyFlags DependencyFlags; #else typedef uint16_t DependencyFlags; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus /** * Conditions used when resolving package `exports` and `imports` fields. */ enum ExportsConditions #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint32_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_EXPORTS_CONDITION_IMPORT = (1 << 0), PARCEL_EXPORTS_CONDITION_REQUIRE = (1 << 1), PARCEL_EXPORTS_CONDITION_MODULE = (1 << 2), PARCEL_EXPORTS_CONDITION_NODE = (1 << 3), PARCEL_EXPORTS_CONDITION_BROWSER = (1 << 4), PARCEL_EXPORTS_CONDITION_WORKER = (1 << 5), PARCEL_EXPORTS_CONDITION_WORKLET = (1 << 6), PARCEL_EXPORTS_CONDITION_ELECTRON = (1 << 7), PARCEL_EXPORTS_CONDITION_DEVELOPMENT = (1 << 8), PARCEL_EXPORTS_CONDITION_PRODUCTION = (1 << 9), PARCEL_EXPORTS_CONDITION_TYPES = (1 << 10), PARCEL_EXPORTS_CONDITION_DEFAULT = (1 << 11), PARCEL_EXPORTS_CONDITION_STYLE = (1 << 12), PARCEL_EXPORTS_CONDITION_SASS = (1 << 13), PARCEL_EXPORTS_CONDITION_LESS = (1 << 14), PARCEL_EXPORTS_CONDITION_STYLUS = (1 << 15), PARCEL_EXPORTS_CONDITION_REACT_SERVER = (1 << 16), PARCEL_EXPORTS_CONDITION_SOURCE = (1 << 17), }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum ExportsConditions ExportsConditions; #else typedef uint32_t ExportsConditions; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum AssetFlags #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint32_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_ASSET_IS_SOURCE = (1 << 0), PARCEL_ASSET_SIDE_EFFECTS = (1 << 1), PARCEL_ASSET_IS_BUNDLE_SPLITTABLE = (1 << 2), PARCEL_ASSET_LARGE_BLOB = (1 << 3), PARCEL_ASSET_HAS_CJS_EXPORTS = (1 << 4), PARCEL_ASSET_STATIC_EXPORTS = (1 << 5), PARCEL_ASSET_SHOULD_WRAP = (1 << 6), PARCEL_ASSET_IS_CONSTANT_MODULE = (1 << 7), PARCEL_ASSET_HAS_NODE_REPLACEMENTS = (1 << 8), PARCEL_ASSET_HAS_SYMBOLS = (1 << 9), PARCEL_ASSET_IS_HTML_ATTR = (1 << 10), PARCEL_ASSET_IS_HTML_TAG = (1 << 11), PARCEL_ASSET_IS_ESM = (1 << 12), }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum AssetFlags AssetFlags; #else typedef uint32_t AssetFlags; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum EnvironmentFlags #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_ENV_FLAG_IS_LIBRARY = (1 << 0), PARCEL_ENV_FLAG_SHOULD_OPTIMIZE = (1 << 1), PARCEL_ENV_FLAG_SHOULD_SCOPE_HOIST = (1 << 2), PARCEL_ENV_FLAG_MODULE_TYPE_EXTENSION = (1 << 3), }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum EnvironmentFlags EnvironmentFlags; #else typedef uint8_t EnvironmentFlags; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus enum BundleFlags #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_BUNDLE_FLAG_NEEDS_STABLE_NAME = (1 << 0), PARCEL_BUNDLE_FLAG_IS_SPLITTABLE = (1 << 1), PARCEL_BUNDLE_FLAG_IS_PLACEHOLDER = (1 << 2), PARCEL_BUNDLE_FLAG_ENTRY = (1 << 3), }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum BundleFlags BundleFlags; #else typedef uint8_t BundleFlags; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus /** * What a path refers to. Empty when it does not exist. */ enum FileKind #if defined(__cplusplus) || __STDC_VERSION__ >= 202311L : uint8_t #endif // defined(__cplusplus) || __STDC_VERSION__ >= 202311L { PARCEL_FILE_KIND_FILE = (1 << 0), PARCEL_FILE_KIND_DIR = (1 << 1), PARCEL_FILE_KIND_SYMLINK = (1 << 2), }; #ifndef __cplusplus #if __STDC_VERSION__ >= 202311L typedef enum FileKind FileKind; #else typedef uint8_t FileKind; #endif // __STDC_VERSION__ >= 202311L #endif // __cplusplus /** * Index of an asset within the bundle graph. */ typedef uint32_t AssetIndex; /** * Index of a bundle within the bundle graph. */ typedef uintptr_t BundleIndex; typedef struct ParcelApiHeader { /** * `size_of::()` as the host was built. Always the first member. */ uintptr_t size; /** * [`PARCEL_ABI_VERSION`] as the host was built. */ uint32_t abi; /** * Room for a minor version, should appended functions ever need to be * detectable by something more readable than `size`. */ uint32_t _reserved; } ParcelApiHeader; /** * Bytes in memory Parcel allocated, which change hands with the buffer: Parcel * fills one in for the plugin to free with `parcel_buffer_free()`, and an entry * point returns one, from `parcel_buffer_alloc()`, for Parcel to free. Inputs to * a call are passed as a pointer and length instead, since Parcel only borrows * them. * Use `parcel_buffer_write` or `parcel_buffer_write_utf8` to copy data into an existing Buffer, * replacing and dropping the existing content if any. Do not set the fields in this struct manually. * * `is_utf8` is a promise that `data` is valid UTF-8. Parcel relies on it without checking, so a * buffer a plugin returns with it set (via `parcel_buffer_write_utf8()`) must hold valid UTF-8, * and returning one that does not is undefined behavior. */ typedef struct Buffer { uint8_t *data; uintptr_t len; uintptr_t cap; bool is_utf8; } Buffer; /** * Opaque handle to an asset that may only be read, such as one from * `parcel_bundle_graph_get_asset()`. Pass to the `parcel_asset_get_*` functions. * Passing one where an `Asset` is expected, to a function that changes the * asset, is undefined behavior: other threads may be reading it. */ typedef uint64_t AssetRef; /** * Opaque handle to the context of the current call into the plugin: the build's * options, and whatever the call may do, such as reading files. Every entry * point receives one. It is valid only until that call returns, so never store * it, in plugin state or custom content. */ typedef uint64_t Options; /** * Opaque handle to a list of diagnostics Parcel handed the plugin during the * current call, such as those a failed read reports. Readable anywhere a * `DiagnosticsRef` is expected, and reported as they were by setting * `DiagnosticOptions.diagnostics` to it. Parcel frees it when the call returns. */ typedef uint64_t Diagnostics; /** * Opaque handle to the asset a transformer is transforming, which it may change. * Only `parcel_plugin_transform()` hands one out, and it is valid until that call * returns. It can be passed anywhere an `AssetRef` is expected. */ typedef uint64_t Asset; /** * Describes a diagnostic a plugin reports: the error an entry point fails with, * or a warning it logs with `parcel_options_log_diagnostic()`. * * Parcel allocates the one each entry point receives, zeroed apart from `size` * and `diagnostics`, and frees every `Buffer` in it once the call returns; fill * them with `parcel_buffer_alloc()`. The call fails when `message` is set, or * `diagnostics` holds any. To log one, initialize it as * `DiagnosticOptions d = {.size = sizeof(DiagnosticOptions)};`, and free its * buffers after the call: Parcel copies what it needs. * * Its own fields describe one diagnostic with at most one code frame, * highlight and hint. Anything more is built in a list instead: * `parcel_diagnostics_push()` a diagnostic to it, then add to it with * `parcel_diagnostics_add_code_frame()`, `parcel_diagnostics_add_code_highlight()` * and `parcel_diagnostics_add_hint()`, which take their strings as a pointer * and length, so nothing needs allocating. The list to fail an entry point with * is already in the `diagnostics` field of the one it received; to log one, * create a list with `parcel_diagnostics_create()` and set `diagnostics` to it. * Where Parcel provides these, building every diagnostic this way, leaving the * struct's own fields empty, is simplest. * * To report diagnostics Parcel handed the plugin, such as those of a failed read, * set `diagnostics` to their list instead. Either way, Parcel reports the list's * diagnostics after the one `message` describes, if it is set too. * * Only write fields that fit within `size`, which an older Parcel sets lower than * `sizeof(DiagnosticOptions)`; `PARCEL_HAS_FIELD()` checks. Parcel ignores fields it * does not know, since the rest is still worth showing. */ typedef struct DiagnosticOptions { /** * `sizeof(DiagnosticOptions)` as whoever allocated it was built. Always the first member. */ uintptr_t size; struct Buffer message; /** * Absolute path of the file the diagnostic's code frame shows, if it has one. */ struct Buffer file_path; /** * 1-based line and column of the first highlighted character in `file_path`, or 0 for no * highlight. */ uint32_t line; uint32_t column; struct Buffer hint; /** * `PARCEL_SEVERITY_*` */ DiagnosticSeverity severity; /** * A message shown at the highlight. */ struct Buffer highlight_message; /** * 1-based line and column of the last highlighted character, or 0 to highlight just the one at * `line` and `column`. */ uint32_t end_line; uint32_t end_column; /** * A URL to documentation about the diagnostic. */ struct Buffer documentation_url; /** * Diagnostics to report as well, or 0: a list the plugin built or Parcel handed it during this * call. A list from any other call is ignored. In the one an entry point receives, Parcel sets * it to an empty list for the plugin to push to; an older Parcel leaves it 0. */ Diagnostics diagnostics; } DiagnosticOptions; /** * Opaque handle to Parcel bundle graph. */ typedef uint64_t BundleGraph; /** * Opaque handle to Parcel bundle. */ typedef uint64_t Bundle; /** * Opaque handle to a Parcel target. Obtained via `parcel_asset_get_target()`. */ typedef uint64_t Target; /** * The resolution of a dependency in the bundle graph, written by * `parcel_bundle_graph_get_dependency_resolution()`. * * Initialize it as `BundleGraphDependencyResolution resolution = {.size = sizeof(resolution)};`. */ typedef struct BundleGraphDependencyResolution { /** * `sizeof(BundleGraphDependencyResolution)`, set by the caller. Always the first member. */ uintptr_t size; /** * `PARCEL_BUNDLE_GRAPH_RESOLUTION_*` */ BundleGraphResolutionType resolution_type; /** * The asset the dependency resolved to, when `resolution_type` is * `PARCEL_BUNDLE_GRAPH_RESOLUTION_ASSET` (an asset in the same bundle), * `PARCEL_BUNDLE_GRAPH_RESOLUTION_BUNDLE` (an asset in another bundle) or * `PARCEL_BUNDLE_GRAPH_RESOLUTION_INTERNALIZED` (an asset in a bundle inlined * into this one). `PARCEL_INVALID_ASSET_INDEX` otherwise. */ AssetIndex asset; /** * The bundle the dependency resolved to, only when `resolution_type` is * `PARCEL_BUNDLE_GRAPH_RESOLUTION_BUNDLE`. `PARCEL_INVALID_BUNDLE_INDEX` * otherwise. */ BundleIndex bundle; } BundleGraphDependencyResolution; /** * Opaque, read-only handle to a Parcel dependency. Passed to * `parcel_plugin_resolve()`, and returned by `parcel_asset_get_dependency()`, * in which case it is valid until the next `parcel_asset_add_dependency()` on * the same asset, or until the call that obtained it returns. */ typedef uint64_t Dependency; /** * Dependency descriptor passed to `parcel_asset_add_dependency()` and `parcel_asset_resolve()`. * * Initialize it as `DependencyOptions dep = {.size = sizeof(DependencyOptions)};`, which zeroes the rest: * `PARCEL_SPECIFIER_ESM` / `PARCEL_PRIORITY_SYNC` / `PARCEL_BUNDLE_BEHAVIOR_NONE` / * `PARCEL_IMPORT_TYPE_JAVASCRIPT` and no flags are the defaults. Zero any padding too, e.g. with * `memset`, if you fill it in some other way: a field a newer header adds lands where an older * Parcel sees only bytes it expects to be zero, and it rejects a dependency that sets anything it * does not understand rather than silently ignoring it. */ typedef struct DependencyOptions { /** * `sizeof(DependencyOptions)`. Always the first member. */ uintptr_t size; /** * Module specifier bytes (e.g. `"./foo.js"`). Required. */ const uint8_t *specifier; /** * Byte length of `specifier`. */ uintptr_t specifier_len; /** * `PARCEL_SPECIFIER_*` */ SpecifierType specifier_type; /** * `PARCEL_PRIORITY_*` */ Priority priority; /** * `PARCEL_BUNDLE_BEHAVIOR_*` */ BundleBehavior bundle_behavior; /** * `PARCEL_DEP_*` bits */ DependencyFlags flags; /** * `PARCEL_EXPORTS_CONDITION_*` bits */ ExportsConditions conditions; /** * `PARCEL_IMPORT_TYPE_*` */ ImportType import_type; } DependencyOptions; /** * The minimum engine versions a target supports, written by * `parcel_target_get_engines()`. * * Each version is `major << 8 | minor`, so versions compare as integers, and * zero means the target does not specify that engine. * * Initialize it as `Engines engines = {.size = sizeof(engines)};`. */ typedef struct Engines { /** * `sizeof(Engines)`, set by the caller. Always the first member. */ uintptr_t size; uint16_t android; uint16_t chrome; uint16_t edge; uint16_t firefox; uint16_t ie; uint16_t ios_saf; uint16_t opera; uint16_t safari; uint16_t samsung; uint16_t electron; uint16_t node; uint16_t parcel; } Engines; /** * Opaque, read-only handle to a list of diagnostics: those a reporter event * carries, or a `Diagnostics` list. Pass to the `parcel_diagnostics_*` and * `parcel_diagnostic_*` getters. Valid until the call that received it returns. */ typedef uint64_t DiagnosticsRef; /** * Result filled by a resolver plugin's `parcel_plugin_resolve()`, or by Parcel in * `parcel_asset_resolve()`. * * Whoever allocates it zero-initializes it and sets `size`: Parcel before calling * `parcel_plugin_resolve()`, so a resolver only writes fields that fit within * `size` (`PARCEL_HAS_FIELD()` checks), and the plugin before calling * `parcel_asset_resolve()`, as `ResolveResult result = {.size = sizeof(ResolveResult)};`. * * When type == PARCEL_RESOLUTION_FILE_PATH, fill `file_path` (and optionally `pipeline`) via `parcel_buffer_alloc()`. */ typedef struct ResolveResult { /** * `sizeof(ResolveResult)` as whoever allocated it was built. Always the first member. */ uintptr_t size; /** * `PARCEL_RESOLUTION_*` */ ResolutionType resolution_type; struct Buffer file_path; struct Buffer pipeline; } ResolveResult; /** * One of a diagnostic's code frames, filled in by * `parcel_diagnostic_get_code_frame()`. * * Set `size` before the call, as `CodeFrameInfo info = {.size = sizeof(CodeFrameInfo)};`; * Parcel writes only the fields that fit. Free each buffer after. */ typedef struct CodeFrameInfo { /** * `sizeof(CodeFrameInfo)` as the caller was built. Always the first member. */ uintptr_t size; /** * The absolute path of the file, when the frame is about one on disk. */ struct Buffer file_path; /** * The URL of the file, e.g. a `file:` URL, when the frame names one. */ struct Buffer url; /** * The code to show, when it differs from the file's contents. Empty to read the file. */ struct Buffer code; /** * The code's language, as a file extension, for syntax highlighting. Empty when unknown. */ struct Buffer language; /** * How many highlights the frame has, for `parcel_diagnostic_get_code_highlight()`. */ uintptr_t highlight_count; } CodeFrameInfo; /** * One highlighted range in a code frame, filled in by * `parcel_diagnostic_get_code_highlight()`. Lines and columns are 1-based, and * the end is the last highlighted character. * * Set `size` before the call, as `CodeHighlightInfo info = {.size = sizeof(CodeHighlightInfo)};`; * Parcel writes only the fields that fit. Free `message` after. */ typedef struct CodeHighlightInfo { /** * `sizeof(CodeHighlightInfo)` as the caller was built. Always the first member. */ uintptr_t size; uint32_t start_line; uint32_t start_column; uint32_t end_line; uint32_t end_column; /** * A message shown at the highlight. Empty when it has none. */ struct Buffer message; } CodeHighlightInfo; /** * A diagnostic to append to a list with `parcel_diagnostics_push()`. Add its * code frames and hints with the calls that follow. * * Initialize it as `DiagnosticEntryOptions d = {.size = sizeof(DiagnosticEntryOptions)};`. * Like every input to a call, Parcel only reads it during the call: its * strings may point at the plugin's own memory, which the plugin still owns. * None of them is NUL-terminated. */ typedef struct DiagnosticEntryOptions { /** * `sizeof(DiagnosticEntryOptions)` as the plugin was built. Always the first member. */ uintptr_t size; DiagnosticSeverity severity; /** * What went wrong. Required. */ const uint8_t *message; uintptr_t message_len; /** * A URL to documentation about the diagnostic. Empty when it has none. */ const uint8_t *documentation_url; uintptr_t documentation_url_len; } DiagnosticEntryOptions; /** * A code frame to add with `parcel_diagnostics_add_code_frame()`: an excerpt of * a file the diagnostic is about. Add its highlights with * `parcel_diagnostics_add_code_highlight()`. * * Initialize it as `CodeFrameOptions f = {.size = sizeof(CodeFrameOptions)};`. * Parcel only reads it during the call. None of its strings is NUL-terminated. */ typedef struct CodeFrameOptions { /** * `sizeof(CodeFrameOptions)` as the plugin was built. Always the first member. */ uintptr_t size; /** * The absolute path of the file, for one on disk. Empty to name it with `url`. */ const uint8_t *file_path; uintptr_t file_path_len; /** * The URL of the file, for one that is not on disk. Ignored when `file_path` is set. */ const uint8_t *url; uintptr_t url_len; /** * The code to show. Empty to show the file's contents. */ const uint8_t *code; uintptr_t code_len; /** * The code's language, as a file extension, for syntax highlighting. Empty when unknown. */ const uint8_t *language; uintptr_t language_len; } CodeFrameOptions; /** * A highlight to add with `parcel_diagnostics_add_code_highlight()`. Lines and * columns are 1-based, and the end is the last highlighted character. * * Initialize it as `CodeHighlightOptions h = {.size = sizeof(CodeHighlightOptions)};`. * Parcel only reads it during the call. `message` is not NUL-terminated. */ typedef struct CodeHighlightOptions { /** * `sizeof(CodeHighlightOptions)` as the plugin was built. Always the first member. */ uintptr_t size; /** * Required. */ uint32_t start_line; uint32_t start_column; /** * 0 to highlight just the character at the start. */ uint32_t end_line; uint32_t end_column; /** * A message shown at the highlight. Empty when it has none. */ const uint8_t *message; uintptr_t message_len; } CodeHighlightOptions; /** * The host functions available to a plugin. */ typedef struct ParcelApi { /** * Size and abi version. Always the first member. */ struct ParcelApiHeader header; bool (*asset_get_content)(struct Buffer *buf, AssetRef asset, Options options, Diagnostics *diagnostics); bool (*asset_get_content_utf8)(struct Buffer *buf, AssetRef asset, Options options, Diagnostics *diagnostics); void (*asset_set_content)(Asset asset, const uint8_t *data, uintptr_t len, const uint8_t *map, uintptr_t map_len); void (*asset_set_content_utf8)(Asset asset, const uint8_t *data, uintptr_t len, const uint8_t *map, uintptr_t map_len); void (*asset_set_custom_content)(Asset asset, const uint8_t (*ty)[16], void *content, void (*read)(const void *content, struct Buffer *buf, struct DiagnosticOptions *diagnostic), void (*package)(const void *content, BundleGraph bundle_graph, Bundle bundle, Options options, struct Buffer *buf, struct DiagnosticOptions *diagnostic), void (*free)(void *content)); bool (*asset_get_custom_content)(uint8_t (*ty)[16], void **content, AssetRef asset); void (*asset_get_type)(struct Buffer *buf, AssetRef asset); void (*asset_set_type)(Asset asset, const uint8_t *ty, uintptr_t ty_len); void (*asset_get_file_path)(struct Buffer *buf, AssetRef asset, Options options); void (*asset_get_pipeline)(struct Buffer *buf, AssetRef asset); void (*asset_set_pipeline)(Asset asset, const uint8_t *pipeline, uintptr_t pipeline_len); BundleBehavior (*asset_get_bundle_behavior)(AssetRef asset); void (*asset_set_bundle_behavior)(Asset asset, BundleBehavior behavior); AssetFlags (*asset_get_flags)(AssetRef asset); void (*asset_set_flags)(Asset asset, AssetFlags flags); void (*asset_get_unique_key)(struct Buffer *buf, AssetRef asset); void (*asset_set_unique_key)(Asset asset, const uint8_t *key, uintptr_t key_len); void (*asset_add_export_symbol)(Asset asset, const uint8_t *name, uintptr_t name_len); void (*buffer_free)(struct Buffer *buf); struct Buffer (*buffer_alloc)(const uint8_t *data, uintptr_t len); void (*buffer_write)(struct Buffer *buf, const uint8_t *data, uintptr_t len); void (*buffer_write_utf8)(struct Buffer *buf, const uint8_t *data, uintptr_t len); void (*bundle_get_type)(struct Buffer *buf, Bundle bundle); Target (*bundle_get_target)(Bundle bundle); BundleBehavior (*bundle_get_bundle_behavior)(Bundle bundle); BundleFlags (*bundle_get_flags)(Bundle bundle); void (*bundle_get_dist_path)(struct Buffer *buf, Bundle bundle); uintptr_t (*bundle_get_asset_count)(Bundle bundle); AssetIndex (*bundle_get_asset)(Bundle bundle, uintptr_t index); uintptr_t (*bundle_get_entry_asset_count)(Bundle bundle); AssetIndex (*bundle_get_entry_asset)(Bundle bundle, uintptr_t index); AssetIndex (*bundle_get_main_entry_asset)(Bundle bundle); void (*bundle_get_name)(struct Buffer *buf, Bundle bundle); void (*bundle_get_absolute_url)(struct Buffer *buf, Bundle bundle); void (*bundle_get_relative_url)(struct Buffer *buf, Bundle bundle, Bundle from); void (*bundle_get_relative_specifier)(struct Buffer *buf, Bundle bundle, Bundle from); uintptr_t (*bundle_graph_get_asset_count)(BundleGraph bundle_graph); AssetRef (*bundle_graph_get_asset)(BundleGraph bundle_graph, AssetIndex index); uintptr_t (*bundle_graph_get_bundle_count)(BundleGraph bundle_graph); Bundle (*bundle_graph_get_bundle)(BundleGraph bundle_graph, BundleIndex index); void (*bundle_graph_get_dependency_resolution)(struct BundleGraphDependencyResolution *resolution, BundleGraph bundle_graph, AssetIndex asset, uintptr_t dependency_index); uintptr_t (*asset_get_dependency_count)(AssetRef asset); Dependency (*asset_get_dependency)(AssetRef asset, uintptr_t index); bool (*asset_add_dependency)(Asset asset, const struct DependencyOptions *dep); void (*dep_get_specifier)(struct Buffer *buf, Dependency dep); SpecifierType (*dep_get_specifier_type)(Dependency dep); Priority (*dep_get_priority)(Dependency dep); BundleBehavior (*dep_get_bundle_behavior)(Dependency dep); DependencyFlags (*dep_get_flags)(Dependency dep); ExportsConditions (*dep_get_conditions)(Dependency dep); ImportType (*dep_get_import_type)(Dependency dep); void (*dep_get_source_path)(struct Buffer *buf, Dependency dep, Options options); void (*dep_get_resolve_from)(struct Buffer *buf, Dependency dep, Options options); Target (*dep_get_target)(Dependency dep); void (*options_get_project_root)(struct Buffer *buf, Options options); void (*options_get_env)(struct Buffer *buf, Options options, const uint8_t *key, uintptr_t key_len); void (*options_get_mode)(struct Buffer *buf, Options options); bool (*options_get_hmr)(Options options); LogLevel (*options_get_log_level)(Options options); Target (*asset_get_target)(AssetRef asset); Environment (*target_get_environment)(Target target); OutputFormat (*target_get_output_format)(Target target); SourceType (*target_get_source_type)(Target target); EnvironmentFlags (*target_get_env_flags)(Target target); void (*target_get_public_url)(struct Buffer *buf, Target target); void (*target_get_dist_dir)(struct Buffer *buf, Target target, Options options); void (*target_get_engines)(struct Engines *engines, Target target); void (*asset_get_query)(struct Buffer *buf, AssetRef asset); uintptr_t (*diagnostics_get_count)(DiagnosticsRef diagnostics); void (*diagnostic_get_message)(struct Buffer *buf, DiagnosticsRef diagnostics, uintptr_t index); DiagnosticSeverity (*diagnostic_get_severity)(DiagnosticsRef diagnostics, uintptr_t index); void (*diagnostic_get_origin)(struct Buffer *buf, DiagnosticsRef diagnostics, uintptr_t index); uintptr_t (*diagnostic_get_hint_count)(DiagnosticsRef diagnostics, uintptr_t index); void (*diagnostic_get_hint)(struct Buffer *buf, DiagnosticsRef diagnostics, uintptr_t index, uintptr_t hint); void (*options_log)(Options options, LogLevel level, const uint8_t *message, uintptr_t message_len); void (*options_log_diagnostic)(Options options, const struct DiagnosticOptions *diagnostic); void (*bundle_get_stable_key)(struct Buffer *buf, Bundle bundle); void (*bundle_get_hash_reference)(struct Buffer *buf, Bundle bundle); IoStatus (*fs_read_file)(struct Buffer *buf, Options options, const uint8_t *path, uintptr_t path_len); FileKind (*fs_get_kind)(Options options, const uint8_t *path, uintptr_t path_len); IoStatus (*fs_canonicalize)(struct Buffer *buf, Options options, const uint8_t *path, uintptr_t path_len); bool (*asset_resolve)(Asset asset, Options options, const struct DependencyOptions *dep, const uint8_t *from, uintptr_t from_len, struct ResolveResult *result, Diagnostics *diagnostics); void (*asset_get_map)(struct Buffer *buf, AssetRef asset); void (*diagnostic_get_documentation_url)(struct Buffer *buf, DiagnosticsRef diagnostics, uintptr_t index); uintptr_t (*diagnostic_get_code_frame_count)(DiagnosticsRef diagnostics, uintptr_t index); bool (*diagnostic_get_code_frame)(struct CodeFrameInfo *out, DiagnosticsRef diagnostics, uintptr_t index, uintptr_t frame); bool (*diagnostic_get_code_highlight)(struct CodeHighlightInfo *out, DiagnosticsRef diagnostics, uintptr_t index, uintptr_t frame, uintptr_t highlight); Diagnostics (*diagnostics_create)(Options options); bool (*diagnostics_push)(Diagnostics diagnostics, const struct DiagnosticEntryOptions *diagnostic); bool (*diagnostics_add_code_frame)(Diagnostics diagnostics, const struct CodeFrameOptions *frame); bool (*diagnostics_add_code_highlight)(Diagnostics diagnostics, const struct CodeHighlightOptions *highlight); bool (*diagnostics_add_hint)(Diagnostics diagnostics, const uint8_t *hint, uintptr_t hint_len); } ParcelApi; /** * Result filled by an optimizer plugin's `parcel_plugin_optimize()`. * The struct is zero-initialised by the host before the call, apart from `size`. * Fill `contents` and optionally `source_map` using `parcel_buffer_write()` or * `parcel_buffer_write_utf8()`, and only write fields that fit within `size` * (`PARCEL_HAS_FIELD()` checks). */ typedef struct OptimizeResult { /** * `sizeof(OptimizeResult)` as Parcel was built. Always the first member. */ uintptr_t size; struct Buffer contents; /** * Leave empty to remove the source map from the optimized output. */ struct Buffer source_map; } OptimizeResult; /** * An event passed to a reporter plugin's `parcel_plugin_report()`. * * Which fields are filled in depends on `event_type`; the rest are zeroed. * Every handle and pointer here is valid only for the duration of the call. * * Check `size` with `PARCEL_HAS_FIELD()` before reading a field this header * declares but an older Parcel may not have written. Unlike `ParcelApi`, whose * `size` a plugin verifies once at startup, this struct is filled in per call * and carries its own. */ typedef struct ReportEvent { /** * `sizeof(struct ReportEvent)` as the host was built. */ uintptr_t size; ReportEventType event_type; /** * `PARCEL_EVENT_LOG` only. */ LogLevel level; /** * `PARCEL_EVENT_LOG` only, and NULL when the event carries diagnostics * instead of a message. Not NUL-terminated; use `message_len`. */ const uint8_t *message; uintptr_t message_len; /** * `PARCEL_EVENT_BUILD_FAILURE` and `PARCEL_EVENT_LOG`. 0 when the event * carries no diagnostics. */ DiagnosticsRef diagnostics; /** * `PARCEL_EVENT_BUILD_SUCCESS` only; 0 otherwise. */ BundleGraph bundle_graph; /** * `PARCEL_EVENT_BUILD_SUCCESS` only. How long the build took. */ uint64_t build_time_ms; /** * `PARCEL_EVENT_BUILD_SUCCESS` only. The assets transformed by this build: * on a full build, every asset. NULL when `changed_asset_count` is 0. */ const AssetIndex *changed_assets; uintptr_t changed_asset_count; } ReportEvent; /** * The inputs to `parcel_plugin_init2()`. * * Parcel allocates it and sets `size` to `sizeof(InitArgs)` as Parcel was * built. Fields may be appended in later versions: check one with * `PARCEL_HAS_FIELD()` before reading it, unless it is in the first layout * (through `options`), which every Parcel calling `parcel_plugin_init2()` fills * in. Everything it points to is valid only until `parcel_plugin_init2()` * returns: copy what you need into your state. */ typedef struct InitArgs { /** * `sizeof(InitArgs)` as Parcel was built. Always the first member. */ uintptr_t size; /** * The host functions. Check `parcel_api_compatible(&args->api->header)` * before using it, or anything else Parcel passed. */ const struct ParcelApi *api; /** * The .parcelrc entry's options, as JSON. Not NUL-terminated. Empty when the * entry has none. */ const uint8_t *config; uintptr_t config_len; /** * The absolute path of the .parcelrc file whose entry named the plugin: the * file itself, not its directory. When the entry comes from a config that * file `extends`, this is that config's path. Resolve relative paths in * `config` against its directory. Not NUL-terminated. */ const uint8_t *config_path; uintptr_t config_path_len; /** * The build's options, for the duration of this call, as every other entry * point receives them. Files read through it with `parcel_fs_read_file()` * and friends are tracked: a change to any of them reinitializes every * plugin. Never store it; `parcel_asset_resolve()` is not available. */ Options options; } InitArgs; /** * `parcel_plugin_init()`: the original form of `parcel_plugin_init2()`, which * Parcel calls instead when a plugin exports both. It receives only the entry's * options as JSON in `config`: no `Options`, so it cannot read files or the * project root, and no path to the .parcelrc that configured it. Kept so that * plugins built before `parcel_plugin_init2()` keep loading; new plugins should * define `parcel_plugin_init2()` instead. * * Check `parcel_api_compatible(&api->header)` first, and return * `PARCEL_INIT_INCOMPATIBLE` without touching `api` if it fails. Store anything * the other entry points need in `*state`, which every later call for this * entry receives. On failure, return `PARCEL_INIT_ERROR` and fill in * `diagnostic`. */ typedef InitStatus (*ParcelPluginInitFn)(const struct ParcelApi *api, const uint8_t *config, uintptr_t config_len, void **state, struct DiagnosticOptions *diagnostic); /** * `parcel_plugin_init2()`: called once for each .parcelrc entry naming the * plugin, before any other entry point. It may be called concurrently, and * always with the same `args->api` table. * * Check `parcel_api_compatible(&args->api->header)` first, and return * `PARCEL_INIT_INCOMPATIBLE` without touching anything else if it fails. Store * anything the other entry points need in `*state`, which every later call for * this entry receives. On failure, return `PARCEL_INIT_ERROR` and fill in * `diagnostic`. */ typedef InitStatus (*ParcelPluginInit2Fn)(const struct InitArgs *args, void **state, struct DiagnosticOptions *diagnostic); /** * `parcel_plugin_deinit()`: releases `state` once Parcel is done with the * entry and none of its other calls is still running. Not called when `state` * is NULL. Custom content the plugin created can outlive it, so content * callbacks must not rely on `state`. */ typedef void (*ParcelPluginDeinitFn)(void *state); /** * `parcel_plugin_transform()`: transforms `asset` in place. The only entry * point that receives a mutable `Asset`, valid until it returns. Fill in * `diagnostic` to fail. */ typedef void (*ParcelPluginTransformFn)(Asset asset, Options options, void *state, struct DiagnosticOptions *diagnostic); /** * `parcel_plugin_resolve()`: resolves `specifier` (not NUL-terminated), as * imported by `dependency`. `pipeline` is the named pipeline from the * specifier, or NULL when it has none. Write the result into `*result`, whose * `size` Parcel set, or leave it as `PARCEL_RESOLUTION_NONE` to let the next * resolver try. Fill in `diagnostic` to fail. */ typedef void (*ParcelPluginResolveFn)(Dependency dependency, const uint8_t *specifier, uintptr_t specifier_len, const uint8_t *pipeline, uintptr_t pipeline_len, Options options, struct ResolveResult *result, void *state, struct DiagnosticOptions *diagnostic); /** * `parcel_plugin_name()`: writes `bundle`'s name, relative to its target's dist * directory, into `*name`. Leave `*name` empty to let the next namer try. Fill * in `diagnostic` to fail. */ typedef void (*ParcelPluginNameFn)(BundleGraph bundle_graph, Bundle bundle, Options options, struct Buffer *name, void *state, struct DiagnosticOptions *diagnostic); /** * `parcel_plugin_optimize()`: optimizes `bundle`'s packaged `contents`, along * with its JSON source map, which is NULL when it has none. Write the output * into `*result`, whose `size` Parcel set. Fill in `diagnostic` to fail. */ typedef void (*ParcelPluginOptimizeFn)(BundleGraph bundle_graph, Bundle bundle, const uint8_t *contents, uintptr_t contents_len, const uint8_t *source_map, uintptr_t source_map_len, Options options, struct OptimizeResult *result, void *state, struct DiagnosticOptions *diagnostic); /** * `parcel_plugin_report()`: handles a build event. Log events can arrive from * any thread while a build runs, concurrently with each other. A diagnostic is * printed rather than failing the build. */ typedef void (*ParcelPluginReportFn)(const struct ReportEvent *event, Options options, void *state, struct DiagnosticOptions *diagnostic); /** * An asset index no asset has, returned by getters for a missing asset. */ #define PARCEL_INVALID_ASSET_INDEX 4294967295 /** * The host functions Parcel passed to `parcel_plugin_init2()`. Plugins define this * once and assign it before calling anything below. */ extern const struct ParcelApi *parcel_api; /** * The end of the last function in the table's first published layout, and so the * smallest table any Parcel implementing this ABI passes. Functions declared after * `diagnostic_get_code_highlight` were appended later, and an older Parcel's table ends before them. */ #define PARCEL_API_MIN_SIZE \ (offsetof(struct ParcelApi, diagnostic_get_code_highlight) + sizeof(((struct ParcelApi *)0)->diagnostic_get_code_highlight)) /** * Whether `api` is usable by a plugin built against this header. Check it in * `parcel_plugin_init2()` before anything else. * * The ABI version must match: appending never changes the size of an existing * field, so a changed signature is invisible to `size`. The table may be smaller * than the one declared here, when Parcel predates functions this header appends; * their wrappers check for them on each call, so a plugin only needs a newer * Parcel if it actually calls one. */ static inline bool parcel_api_compatible(const struct ParcelApiHeader *api) { return api && api->abi == PARCEL_ABI_VERSION && api->size >= PARCEL_API_MIN_SIZE; } /** * Whether the table in `parcel_api` has the function `field`. Always true for * functions in the first layout. For one appended later, check it before calling, * or just call the wrapper, which does nothing and returns zero when Parcel is too * old to have it. */ #define PARCEL_API_HAS(field) \ (parcel_api->header.size >= offsetof(struct ParcelApi, field) + sizeof(parcel_api->field)) /** * Whether `ptr`, a struct of type `type` that starts with `size`, has room for * `field` according to that `size`. * * Whoever allocates such a struct sets `size` to the size it was built with. Check * this before writing a field to one Parcel allocated, such as a `Diagnostic` or * `ResolveResult` out-param, and before reading a field from one Parcel filled in, * such as a `ReportEvent`, when an older Parcel might not have that field. Fields * in the struct's first layout are always there. */ #define PARCEL_HAS_FIELD(ptr, type, field) \ ((ptr)->size >= offsetof(type, field) + sizeof(((type *)0)->field)) static inline bool parcel_asset_get_content(struct Buffer *buf, AssetRef asset, Options options, Diagnostics *diagnostics) { return parcel_api->asset_get_content(buf, asset, options, diagnostics); } static inline bool parcel_asset_get_content_utf8(struct Buffer *buf, AssetRef asset, Options options, Diagnostics *diagnostics) { return parcel_api->asset_get_content_utf8(buf, asset, options, diagnostics); } static inline void parcel_asset_set_content(Asset asset, const uint8_t *data, uintptr_t len, const uint8_t *map, uintptr_t map_len) { parcel_api->asset_set_content(asset, data, len, map, map_len); } static inline void parcel_asset_set_content_utf8(Asset asset, const uint8_t *data, uintptr_t len, const uint8_t *map, uintptr_t map_len) { parcel_api->asset_set_content_utf8(asset, data, len, map, map_len); } static inline void parcel_asset_set_custom_content(Asset asset, const uint8_t (*ty)[16], void *content, void (*read)(const void *content, struct Buffer *buf, struct DiagnosticOptions *diagnostic), void (*package)(const void *content, BundleGraph bundle_graph, Bundle bundle, Options options, struct Buffer *buf, struct DiagnosticOptions *diagnostic), void (*free)(void *content)) { parcel_api->asset_set_custom_content(asset, ty, content, read, package, free); } static inline bool parcel_asset_get_custom_content(uint8_t (*ty)[16], void **content, AssetRef asset) { return parcel_api->asset_get_custom_content(ty, content, asset); } static inline void parcel_asset_get_type(struct Buffer *buf, AssetRef asset) { parcel_api->asset_get_type(buf, asset); } static inline void parcel_asset_set_type(Asset asset, const uint8_t *ty, uintptr_t ty_len) { parcel_api->asset_set_type(asset, ty, ty_len); } static inline void parcel_asset_get_file_path(struct Buffer *buf, AssetRef asset, Options options) { parcel_api->asset_get_file_path(buf, asset, options); } static inline void parcel_asset_get_pipeline(struct Buffer *buf, AssetRef asset) { parcel_api->asset_get_pipeline(buf, asset); } static inline void parcel_asset_set_pipeline(Asset asset, const uint8_t *pipeline, uintptr_t pipeline_len) { parcel_api->asset_set_pipeline(asset, pipeline, pipeline_len); } static inline BundleBehavior parcel_asset_get_bundle_behavior(AssetRef asset) { return parcel_api->asset_get_bundle_behavior(asset); } static inline void parcel_asset_set_bundle_behavior(Asset asset, BundleBehavior behavior) { parcel_api->asset_set_bundle_behavior(asset, behavior); } static inline AssetFlags parcel_asset_get_flags(AssetRef asset) { return parcel_api->asset_get_flags(asset); } static inline void parcel_asset_set_flags(Asset asset, AssetFlags flags) { parcel_api->asset_set_flags(asset, flags); } static inline void parcel_asset_get_unique_key(struct Buffer *buf, AssetRef asset) { parcel_api->asset_get_unique_key(buf, asset); } static inline void parcel_asset_set_unique_key(Asset asset, const uint8_t *key, uintptr_t key_len) { parcel_api->asset_set_unique_key(asset, key, key_len); } static inline void parcel_asset_add_export_symbol(Asset asset, const uint8_t *name, uintptr_t name_len) { parcel_api->asset_add_export_symbol(asset, name, name_len); } static inline void parcel_buffer_free(struct Buffer *buf) { parcel_api->buffer_free(buf); } static inline struct Buffer parcel_buffer_alloc(const uint8_t *data, uintptr_t len) { return parcel_api->buffer_alloc(data, len); } static inline void parcel_buffer_write(struct Buffer *buf, const uint8_t *data, uintptr_t len) { parcel_api->buffer_write(buf, data, len); } static inline void parcel_buffer_write_utf8(struct Buffer *buf, const uint8_t *data, uintptr_t len) { parcel_api->buffer_write_utf8(buf, data, len); } static inline void parcel_bundle_get_type(struct Buffer *buf, Bundle bundle) { parcel_api->bundle_get_type(buf, bundle); } static inline Target parcel_bundle_get_target(Bundle bundle) { return parcel_api->bundle_get_target(bundle); } static inline BundleBehavior parcel_bundle_get_bundle_behavior(Bundle bundle) { return parcel_api->bundle_get_bundle_behavior(bundle); } static inline BundleFlags parcel_bundle_get_flags(Bundle bundle) { return parcel_api->bundle_get_flags(bundle); } static inline void parcel_bundle_get_dist_path(struct Buffer *buf, Bundle bundle) { parcel_api->bundle_get_dist_path(buf, bundle); } static inline uintptr_t parcel_bundle_get_asset_count(Bundle bundle) { return parcel_api->bundle_get_asset_count(bundle); } static inline AssetIndex parcel_bundle_get_asset(Bundle bundle, uintptr_t index) { return parcel_api->bundle_get_asset(bundle, index); } static inline uintptr_t parcel_bundle_get_entry_asset_count(Bundle bundle) { return parcel_api->bundle_get_entry_asset_count(bundle); } static inline AssetIndex parcel_bundle_get_entry_asset(Bundle bundle, uintptr_t index) { return parcel_api->bundle_get_entry_asset(bundle, index); } static inline AssetIndex parcel_bundle_get_main_entry_asset(Bundle bundle) { return parcel_api->bundle_get_main_entry_asset(bundle); } static inline void parcel_bundle_get_name(struct Buffer *buf, Bundle bundle) { parcel_api->bundle_get_name(buf, bundle); } static inline void parcel_bundle_get_absolute_url(struct Buffer *buf, Bundle bundle) { parcel_api->bundle_get_absolute_url(buf, bundle); } static inline void parcel_bundle_get_relative_url(struct Buffer *buf, Bundle bundle, Bundle from) { parcel_api->bundle_get_relative_url(buf, bundle, from); } static inline void parcel_bundle_get_relative_specifier(struct Buffer *buf, Bundle bundle, Bundle from) { parcel_api->bundle_get_relative_specifier(buf, bundle, from); } static inline uintptr_t parcel_bundle_graph_get_asset_count(BundleGraph bundle_graph) { return parcel_api->bundle_graph_get_asset_count(bundle_graph); } static inline AssetRef parcel_bundle_graph_get_asset(BundleGraph bundle_graph, AssetIndex index) { return parcel_api->bundle_graph_get_asset(bundle_graph, index); } static inline uintptr_t parcel_bundle_graph_get_bundle_count(BundleGraph bundle_graph) { return parcel_api->bundle_graph_get_bundle_count(bundle_graph); } static inline Bundle parcel_bundle_graph_get_bundle(BundleGraph bundle_graph, BundleIndex index) { return parcel_api->bundle_graph_get_bundle(bundle_graph, index); } static inline void parcel_bundle_graph_get_dependency_resolution(struct BundleGraphDependencyResolution *resolution, BundleGraph bundle_graph, AssetIndex asset, uintptr_t dependency_index) { parcel_api->bundle_graph_get_dependency_resolution(resolution, bundle_graph, asset, dependency_index); } static inline uintptr_t parcel_asset_get_dependency_count(AssetRef asset) { return parcel_api->asset_get_dependency_count(asset); } static inline Dependency parcel_asset_get_dependency(AssetRef asset, uintptr_t index) { return parcel_api->asset_get_dependency(asset, index); } static inline bool parcel_asset_add_dependency(Asset asset, const struct DependencyOptions *dep) { return parcel_api->asset_add_dependency(asset, dep); } static inline void parcel_dep_get_specifier(struct Buffer *buf, Dependency dep) { parcel_api->dep_get_specifier(buf, dep); } static inline SpecifierType parcel_dep_get_specifier_type(Dependency dep) { return parcel_api->dep_get_specifier_type(dep); } static inline Priority parcel_dep_get_priority(Dependency dep) { return parcel_api->dep_get_priority(dep); } static inline BundleBehavior parcel_dep_get_bundle_behavior(Dependency dep) { return parcel_api->dep_get_bundle_behavior(dep); } static inline DependencyFlags parcel_dep_get_flags(Dependency dep) { return parcel_api->dep_get_flags(dep); } static inline ExportsConditions parcel_dep_get_conditions(Dependency dep) { return parcel_api->dep_get_conditions(dep); } static inline ImportType parcel_dep_get_import_type(Dependency dep) { return parcel_api->dep_get_import_type(dep); } static inline void parcel_dep_get_source_path(struct Buffer *buf, Dependency dep, Options options) { parcel_api->dep_get_source_path(buf, dep, options); } static inline void parcel_dep_get_resolve_from(struct Buffer *buf, Dependency dep, Options options) { parcel_api->dep_get_resolve_from(buf, dep, options); } static inline Target parcel_dep_get_target(Dependency dep) { return parcel_api->dep_get_target(dep); } static inline void parcel_options_get_project_root(struct Buffer *buf, Options options) { parcel_api->options_get_project_root(buf, options); } static inline void parcel_options_get_env(struct Buffer *buf, Options options, const uint8_t *key, uintptr_t key_len) { parcel_api->options_get_env(buf, options, key, key_len); } static inline void parcel_options_get_mode(struct Buffer *buf, Options options) { parcel_api->options_get_mode(buf, options); } static inline bool parcel_options_get_hmr(Options options) { return parcel_api->options_get_hmr(options); } static inline LogLevel parcel_options_get_log_level(Options options) { return parcel_api->options_get_log_level(options); } static inline Target parcel_asset_get_target(AssetRef asset) { return parcel_api->asset_get_target(asset); } static inline Environment parcel_target_get_environment(Target target) { return parcel_api->target_get_environment(target); } static inline OutputFormat parcel_target_get_output_format(Target target) { return parcel_api->target_get_output_format(target); } static inline SourceType parcel_target_get_source_type(Target target) { return parcel_api->target_get_source_type(target); } static inline EnvironmentFlags parcel_target_get_env_flags(Target target) { return parcel_api->target_get_env_flags(target); } static inline void parcel_target_get_public_url(struct Buffer *buf, Target target) { parcel_api->target_get_public_url(buf, target); } static inline void parcel_target_get_dist_dir(struct Buffer *buf, Target target, Options options) { parcel_api->target_get_dist_dir(buf, target, options); } static inline void parcel_target_get_engines(struct Engines *engines, Target target) { parcel_api->target_get_engines(engines, target); } static inline void parcel_asset_get_query(struct Buffer *buf, AssetRef asset) { parcel_api->asset_get_query(buf, asset); } static inline uintptr_t parcel_diagnostics_get_count(DiagnosticsRef diagnostics) { return parcel_api->diagnostics_get_count(diagnostics); } static inline void parcel_diagnostic_get_message(struct Buffer *buf, DiagnosticsRef diagnostics, uintptr_t index) { parcel_api->diagnostic_get_message(buf, diagnostics, index); } static inline DiagnosticSeverity parcel_diagnostic_get_severity(DiagnosticsRef diagnostics, uintptr_t index) { return parcel_api->diagnostic_get_severity(diagnostics, index); } static inline void parcel_diagnostic_get_origin(struct Buffer *buf, DiagnosticsRef diagnostics, uintptr_t index) { parcel_api->diagnostic_get_origin(buf, diagnostics, index); } static inline uintptr_t parcel_diagnostic_get_hint_count(DiagnosticsRef diagnostics, uintptr_t index) { return parcel_api->diagnostic_get_hint_count(diagnostics, index); } static inline void parcel_diagnostic_get_hint(struct Buffer *buf, DiagnosticsRef diagnostics, uintptr_t index, uintptr_t hint) { parcel_api->diagnostic_get_hint(buf, diagnostics, index, hint); } static inline void parcel_options_log(Options options, LogLevel level, const uint8_t *message, uintptr_t message_len) { parcel_api->options_log(options, level, message, message_len); } static inline void parcel_options_log_diagnostic(Options options, const struct DiagnosticOptions *diagnostic) { parcel_api->options_log_diagnostic(options, diagnostic); } static inline void parcel_bundle_get_stable_key(struct Buffer *buf, Bundle bundle) { parcel_api->bundle_get_stable_key(buf, bundle); } static inline void parcel_bundle_get_hash_reference(struct Buffer *buf, Bundle bundle) { parcel_api->bundle_get_hash_reference(buf, bundle); } static inline IoStatus parcel_fs_read_file(struct Buffer *buf, Options options, const uint8_t *path, uintptr_t path_len) { return parcel_api->fs_read_file(buf, options, path, path_len); } static inline FileKind parcel_fs_get_kind(Options options, const uint8_t *path, uintptr_t path_len) { return parcel_api->fs_get_kind(options, path, path_len); } static inline IoStatus parcel_fs_canonicalize(struct Buffer *buf, Options options, const uint8_t *path, uintptr_t path_len) { return parcel_api->fs_canonicalize(buf, options, path, path_len); } static inline bool parcel_asset_resolve(Asset asset, Options options, const struct DependencyOptions *dep, const uint8_t *from, uintptr_t from_len, struct ResolveResult *result, Diagnostics *diagnostics) { return parcel_api->asset_resolve(asset, options, dep, from, from_len, result, diagnostics); } static inline void parcel_asset_get_map(struct Buffer *buf, AssetRef asset) { parcel_api->asset_get_map(buf, asset); } static inline void parcel_diagnostic_get_documentation_url(struct Buffer *buf, DiagnosticsRef diagnostics, uintptr_t index) { parcel_api->diagnostic_get_documentation_url(buf, diagnostics, index); } static inline uintptr_t parcel_diagnostic_get_code_frame_count(DiagnosticsRef diagnostics, uintptr_t index) { return parcel_api->diagnostic_get_code_frame_count(diagnostics, index); } static inline bool parcel_diagnostic_get_code_frame(struct CodeFrameInfo *out, DiagnosticsRef diagnostics, uintptr_t index, uintptr_t frame) { return parcel_api->diagnostic_get_code_frame(out, diagnostics, index, frame); } static inline bool parcel_diagnostic_get_code_highlight(struct CodeHighlightInfo *out, DiagnosticsRef diagnostics, uintptr_t index, uintptr_t frame, uintptr_t highlight) { return parcel_api->diagnostic_get_code_highlight(out, diagnostics, index, frame, highlight); } /** Appended after the first layout: check `parcel_api_has_diagnostics_create()`. */ static inline bool parcel_api_has_diagnostics_create(void) { return PARCEL_API_HAS(diagnostics_create); } /** Does nothing and returns zero when Parcel is too old to provide it. */ static inline Diagnostics parcel_diagnostics_create(Options options) { if (!PARCEL_API_HAS(diagnostics_create)) { Diagnostics zero = {0}; return zero; } return parcel_api->diagnostics_create(options); } /** Appended after the first layout: check `parcel_api_has_diagnostics_push()`. */ static inline bool parcel_api_has_diagnostics_push(void) { return PARCEL_API_HAS(diagnostics_push); } /** Does nothing and returns zero when Parcel is too old to provide it. */ static inline bool parcel_diagnostics_push(Diagnostics diagnostics, const struct DiagnosticEntryOptions *diagnostic) { if (!PARCEL_API_HAS(diagnostics_push)) { bool zero = {0}; return zero; } return parcel_api->diagnostics_push(diagnostics, diagnostic); } /** Appended after the first layout: check `parcel_api_has_diagnostics_add_code_frame()`. */ static inline bool parcel_api_has_diagnostics_add_code_frame(void) { return PARCEL_API_HAS(diagnostics_add_code_frame); } /** Does nothing and returns zero when Parcel is too old to provide it. */ static inline bool parcel_diagnostics_add_code_frame(Diagnostics diagnostics, const struct CodeFrameOptions *frame) { if (!PARCEL_API_HAS(diagnostics_add_code_frame)) { bool zero = {0}; return zero; } return parcel_api->diagnostics_add_code_frame(diagnostics, frame); } /** Appended after the first layout: check `parcel_api_has_diagnostics_add_code_highlight()`. */ static inline bool parcel_api_has_diagnostics_add_code_highlight(void) { return PARCEL_API_HAS(diagnostics_add_code_highlight); } /** Does nothing and returns zero when Parcel is too old to provide it. */ static inline bool parcel_diagnostics_add_code_highlight(Diagnostics diagnostics, const struct CodeHighlightOptions *highlight) { if (!PARCEL_API_HAS(diagnostics_add_code_highlight)) { bool zero = {0}; return zero; } return parcel_api->diagnostics_add_code_highlight(diagnostics, highlight); } /** Appended after the first layout: check `parcel_api_has_diagnostics_add_hint()`. */ static inline bool parcel_api_has_diagnostics_add_hint(void) { return PARCEL_API_HAS(diagnostics_add_hint); } /** Does nothing and returns zero when Parcel is too old to provide it. */ static inline bool parcel_diagnostics_add_hint(Diagnostics diagnostics, const uint8_t *hint, uintptr_t hint_len) { if (!PARCEL_API_HAS(diagnostics_add_hint)) { bool zero = {0}; return zero; } return parcel_api->diagnostics_add_hint(diagnostics, hint, hint_len); } /** * The entry points a plugin defines, matching the `ParcelPlugin*Fn` types Parcel loads * them as. Define those your plugin implements: `parcel_plugin_init2()` always, and the * rest for each kind of plugin it is used as. * * Define `PARCEL_NO_ENTRY_POINT_PROTOTYPES` before including this header when the * toolchain declares them itself, as cgo does for exported Go functions, with types it * cannot spell the same way. */ #ifndef PARCEL_NO_ENTRY_POINT_PROTOTYPES InitStatus parcel_plugin_init(const struct ParcelApi *api, const uint8_t *config, uintptr_t config_len, void **state, struct DiagnosticOptions *diagnostic); InitStatus parcel_plugin_init2(const struct InitArgs *args, void **state, struct DiagnosticOptions *diagnostic); void parcel_plugin_deinit(void *state); void parcel_plugin_transform(Asset asset, Options options, void *state, struct DiagnosticOptions *diagnostic); void parcel_plugin_resolve(Dependency dependency, const uint8_t *specifier, uintptr_t specifier_len, const uint8_t *pipeline, uintptr_t pipeline_len, Options options, struct ResolveResult *result, void *state, struct DiagnosticOptions *diagnostic); void parcel_plugin_name(BundleGraph bundle_graph, Bundle bundle, Options options, struct Buffer *name, void *state, struct DiagnosticOptions *diagnostic); void parcel_plugin_optimize(BundleGraph bundle_graph, Bundle bundle, const uint8_t *contents, uintptr_t contents_len, const uint8_t *source_map, uintptr_t source_map_len, Options options, struct OptimizeResult *result, void *state, struct DiagnosticOptions *diagnostic); void parcel_plugin_report(const struct ReportEvent *event, Options options, void *state, struct DiagnosticOptions *diagnostic); #endif #endif /* PARCEL_PLUGIN_H */