@lakutata/ffi 0.0.0-stage → 3.1.2

package/dist/cjs/lib/generator/Generator.d.ts

@@ -0,0 +1,136 @@
+import { type Platform } from '../declarations/Platform.js';
+import { type PreprocessedHeader, type PreprocessOptions } from './Preprocessor.js';
+/**
+ * How a library is generated from its header
+ */
+export interface GenerateOptions extends PreprocessOptions {
+    /**
+     * The library its functions are checked against: a name, as `@Library` takes it, or a file. The name of the header
+     * by default (`sqlite3.h`: `sqlite3`): give it when that library cannot be loaded (the report tells why the
+     * functions were not checked).
+     */
+    readonly library?: string;
+    /**
+     * The name of the class. The name of the header in PascalCase by default (`sqlite3.h`: `Sqlite3`).
+     */
+    readonly className?: string;
+    /**
+     * More directories whose headers are the ones of the library: the header is, and so are the headers of its
+     * directory when it is not a directory of the system.
+     */
+    readonly own?: readonly string[];
+    /**
+     * Whether the functions and the variables are checked against the library, the ones it cannot give left out.
+     * @default true
+     */
+    readonly check?: boolean;
+}
+/**
+ * A declaration of the header that was left out, and why
+ */
+export interface SkippedDeclaration {
+    /**
+     * Its name, or the start of its text
+     */
+    readonly name: string;
+    /**
+     * The file it comes from
+     */
+    readonly file?: string;
+    /**
+     * Its line in that file
+     */
+    readonly line?: number;
+    /**
+     * Why it was left out
+     */
+    readonly reason: string;
+}
+/**
+ * What the generation did
+ */
+export interface GenerationReport {
+    /**
+     * The command that ran the preprocessor
+     */
+    readonly command: string;
+    /**
+     * The platform the library was generated for (`darwin-arm64`)
+     */
+    readonly platform: string;
+    /**
+     * The file of the library the functions were checked against
+     */
+    readonly library?: string;
+    /**
+     * Why they were not checked
+     */
+    readonly unchecked?: string;
+    /**
+     * The functions of the class
+     */
+    readonly functions: number;
+    /**
+     * The variables of the class
+     */
+    readonly variables: number;
+    /**
+     * The interfaces of the structs and unions
+     */
+    readonly interfaces: number;
+    /**
+     * The constants of the declarations: the integer macros, the values of the enums, the static constants
+     */
+    readonly constants: number;
+    /**
+     * The declarations of the library left out: the ones that cannot be read, the functions and variables the library
+     * cannot give
+     */
+    readonly skipped: readonly SkippedDeclaration[];
+}
+/**
+ * A library generated from its header
+ */
+export interface GeneratedLibrary {
+    /**
+     * The name of its class
+     */
+    readonly className: string;
+    /**
+     * The TypeScript code of its class
+     */
+    readonly code: string;
+    /**
+     * Its C declarations, as the class gives them to `@Library`
+     */
+    readonly declarations: string;
+    /**
+     * What was generated, and what was left out
+     */
+    readonly report: GenerationReport;
+}
+/**
+ * Generate the class of a library from a header already run through the preprocessor (see generateNativeLibrary).
+ * @param preprocessed The output of the preprocessor, the header, the directories of the system.
+ * @param options The library, the class, the directories of the library.
+ * @param platform The platform the header was preprocessed for.
+ * @returns The code of the class and the report.
+ */
+export declare function generateFromPreprocessed(preprocessed: PreprocessedHeader, options?: Omit<GenerateOptions, 'header'>, platform?: Platform): Promise<GeneratedLibrary>;
+/**
+ * Generate the class of a native library from its header: the header is run through the preprocessor of the C compiler,
+ * its declarations are read, the functions and the variables the library cannot give are left out, and the class gets a
+ * property by function (named as the function) with its TypeScript type.
+ * @param options The header, the library, the class, the compiler and its options.
+ * @returns The code of the class, and what was generated and left out.
+ * @example
+ * ```typescript
+ * import {writeFileSync} from 'node:fs'
+ * import {generateNativeLibrary} from '@lakutata/ffi/generator'
+ *
+ * const {code, report} = await generateNativeLibrary({header: 'vendor/include/vendor.h', library: 'vendor/lib/libvendor.so'})
+ * writeFileSync('src/native/Vendor.ts', code)
+ * for (const skipped of report.skipped) console.log(`${skipped.name}: ${skipped.reason}`)
+ * ```
+ */
+export declare function generateNativeLibrary(options: GenerateOptions): Promise<GeneratedLibrary>;

package/dist/cjs/lib/generator/Generator.js

@@ -0,0 +1,395 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateFromPreprocessed = generateFromPreprocessed;
+exports.generateNativeLibrary = generateNativeLibrary;
+const node_path_1 = __importDefault(require("node:path"));
+const NativeLibrary_js_1 = require("../../components/NativeLibrary.js");
+const Builtins_js_1 = require("../declarations/Builtins.js");
+const Parser_js_1 = require("../declarations/Parser.js");
+const Platform_js_1 = require("../declarations/Platform.js");
+const NativeLibraryHandle_js_1 = require("../library/NativeLibraryHandle.js");
+const CText_js_1 = require("./CText.js");
+const Preprocessor_js_1 = require("./Preprocessor.js");
+const TypeScriptTypes_js_1 = require("./TypeScriptTypes.js");
+/**
+ * The tokens that are not names of types or constants
+ */
+const KEYWORDS = new Set(['struct', 'union', 'enum', 'typedef', 'extern', 'static', 'const', 'volatile', 'signed', 'unsigned', 'inline']);
+/**
+ * The names the generated file imports or uses: not names of interfaces
+ */
+const TAKEN = new Set(['Library', 'Native', 'NativeLibrary', 'NativeVariable', 'Pointer', 'Out', 'Buffer', 'ArrayBufferView', 'Array', 'Object', 'Function', 'String', 'Number', 'Date', 'Error', 'Map', 'Set', 'Promise']);
+/**
+ * The options of the configuration of the component of a library: not names of properties
+ */
+const CONFIGURATION = ['path', 'search', 'keepLoaded', 'drainTimeout', 'threads'];
+/**
+ * The names of the members of a NativeLibrary: a function named as one of them gets another property
+ */
+function memberNames() {
+    const names = new Set(CONFIGURATION);
+    for (let prototype = NativeLibrary_js_1.NativeLibrary.prototype; prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+        for (const name of Object.getOwnPropertyNames(prototype))
+            names.add(name);
+    }
+    return names;
+}
+/**
+ * A path as the paths of the line markers are compared (case-insensitive on Windows)
+ * @param file
+ */
+function comparable(file) {
+    const resolved = node_path_1.default.resolve(file);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * Whether a file is inside a directory
+ * @param file
+ * @param directory
+ */
+function inside(file, directory) {
+    const relative = node_path_1.default.relative(directory, file);
+    return !!relative && !relative.startsWith('..') && !node_path_1.default.isAbsolute(relative);
+}
+/**
+ * Which files are the ones of the library: the header, the headers of its directory when it is not a directory of the
+ * system, the ones of the directories given
+ * @param header
+ * @param systemDirectories
+ * @param own
+ */
+function ownFiles(header, systemDirectories, own) {
+    const main = comparable(header);
+    const system = systemDirectories.map(comparable);
+    const directory = node_path_1.default.dirname(main);
+    const directories = [...system.includes(directory) ? [] : [directory], ...own.map(comparable)];
+    const known = new Map();
+    return (file) => {
+        if (!file || file.startsWith('<'))
+            return false;
+        let result = known.get(file);
+        if (result === undefined) {
+            const candidate = comparable(file);
+            result = candidate === main || directories.some((dir) => inside(candidate, dir) && !system.some((sys) => sys !== dir && inside(candidate, sys) && inside(sys, dir)));
+            known.set(file, result);
+        }
+        return result;
+    };
+}
+/**
+ * The names a declaration uses: of types (\`type x\`, \`struct x\`) and of constants
+ * @param tokens
+ */
+function referencesOf(tokens) {
+    const references = [];
+    tokens.forEach((token, index) => {
+        if (token.kind !== 'identifier' || KEYWORDS.has(token.text))
+            return;
+        const before = tokens[index - 1];
+        if (before?.kind === 'identifier' && (before.text === 'struct' || before.text === 'union' || before.text === 'enum'))
+            references.push(`${before.text} ${token.text}`);
+        else
+            references.push(`type ${token.text}`, `constant ${token.text}`);
+    });
+    return references;
+}
+/**
+ * A name in PascalCase (\`sqlite3\`: \`Sqlite3\`, \`vendor_sdk\`: \`VendorSdk\`)
+ * @param name
+ */
+function pascalCase(name) {
+    const words = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const joined = words.map((word) => word[0].toUpperCase() + word.slice(1)).join('') || 'Library';
+    return /^[0-9]/.test(joined) ? `Library${joined}` : joined;
+}
+/**
+ * The name \`@Library\` gets for a library given as a name or a file: \`libsqlite3.dylib\`, \`libsqlite3.so\`, \`sqlite3.dll\`
+ * give \`sqlite3\` (completed on each platform); a file with a version is kept as it is
+ * @param library
+ */
+function libraryName(library) {
+    const file = node_path_1.default.basename(library);
+    const plain = file.match(/^(?:lib)?(.+?)\.(?:dylib|so|dll)$/i);
+    if (plain && !/\.(?:dylib|so|dll)/i.test(plain[1]))
+        return plain[1];
+    return file;
+}
+/**
+ * A text as the lines of a comment of TypeScript, wrapped at 120 characters
+ * @param text
+ */
+function commentLines(text) {
+    const lines = [];
+    let line = '//';
+    for (const word of text.split(' ')) {
+        if (line.length > 2 && line.length + 1 + word.length > 120) {
+            lines.push(line);
+            line = '//';
+        }
+        line += line.length > 2 ? ` ${word}` : word;
+    }
+    lines.push(line);
+    return lines;
+}
+/**
+ * Text put in a template literal of TypeScript
+ * @param text
+ */
+function templateText(text) {
+    return text.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+/**
+ * The first line of the message of an error
+ * @param error
+ */
+function reasonOf(error) {
+    return (error instanceof Error ? error.message : String(error)).split('\n')[0].replace(/ \(line \d+, column \d+\)$/, '');
+}
+/**
+ * Generate the class of a library from a header already run through the preprocessor (see generateNativeLibrary).
+ * @param preprocessed The output of the preprocessor, the header, the directories of the system.
+ * @param options The library, the class, the directories of the library.
+ * @param platform The platform the header was preprocessed for.
+ * @returns The code of the class and the report.
+ */
+async function generateFromPreprocessed(preprocessed, options = {}, platform = Platform_js_1.CURRENT_PLATFORM) {
+    const header = preprocessed.header;
+    const headerName = node_path_1.default.basename(header).replace(/\.[^.]+$/, '');
+    const source = new Parser_js_1.DeclarationParser(platform).readSource(preprocessed.text);
+    const items = source.items;
+    const isOwn = ownFiles(header, preprocessed.systemDirectories, options.own ?? []);
+    const builtins = (0, Builtins_js_1.builtinTypes)(platform);
+    const skipped = [];
+    const where = (item) => ({ ...item.file !== undefined ? { file: item.file } : {}, ...item.line !== undefined ? { line: item.line } : {} });
+    //The declarations of the library, and the ones of the system they use
+    const definers = new Map();
+    items.forEach((item, index) => {
+        if (item.error)
+            return;
+        for (const name of item.names)
+            definers.set(name, [...definers.get(name) ?? [], index]);
+    });
+    const selected = new Set();
+    const queue = [];
+    items.forEach((item, index) => {
+        if (!isOwn(item.file))
+            return;
+        if (item.error) {
+            skipped.push({ name: (0, CText_js_1.declarationText)((0, CText_js_1.prunedTokens)(item.tokens.slice(0, 16)), '').join(' ').slice(0, 80), ...where(item), reason: item.error });
+            return;
+        }
+        if (!item.names.length)
+            return;
+        selected.add(index);
+        queue.push(index);
+    });
+    while (queue.length) {
+        const index = queue.pop();
+        const item = items[index];
+        for (const reference of referencesOf(item.tokens)) {
+            if (item.names.includes(reference))
+                continue;
+            if (reference.startsWith('type ') && builtins.has(reference.slice(5)))
+                continue;
+            //The definition seen at that point: the last one before it
+            const candidates = definers.get(reference) ?? [];
+            const definer = candidates.filter((candidate) => candidate < index).pop() ?? candidates[0];
+            if (definer === undefined || selected.has(definer))
+                continue;
+            //A typedef of the system redefining a type the package knows is not needed
+            if (!isOwn(items[definer].file) && items[definer].names.every((name) => name.startsWith('type ') && builtins.has(name.slice(5))))
+                continue;
+            selected.add(definer);
+            queue.push(definer);
+        }
+    }
+    //The macros of the library whose value is an integer, written with their values
+    const itemConstants = new Set(items.flatMap((item) => [...item.names]).filter((name) => name.startsWith('constant ')).map((name) => name.slice(9)));
+    const macroConstants = [...source.macros]
+        .filter(([name, origin]) => isOwn(origin.file) && source.declarations.constants.has(name) && !itemConstants.has(name))
+        .map(([name]) => [name, source.declarations.constants.get(name)]);
+    //The declarations written again, each one checked: read alone, after the ones before it
+    const checker = new Parser_js_1.DeclarationParser(platform);
+    const chunks = [];
+    for (const index of [...selected].sort((a, b) => a - b)) {
+        const item = items[index];
+        const body = (0, CText_js_1.declarationText)((0, CText_js_1.prunedTokens)(item.tokens));
+        const lines = item.pack !== undefined && item.names.some((name) => name.startsWith('struct ') || name.startsWith('union ') || name.startsWith('type '))
+            ? [`#pragma pack(push, ${item.pack})`, ...body, '#pragma pack(pop)']
+            : body;
+        try {
+            checker.parse(lines.join('\n'));
+            chunks.push({ index: index, lines: lines });
+        }
+        catch (error) {
+            selected.delete(index);
+            if (isOwn(item.file))
+                skipped.push({ name: item.names.join(', '), ...where(item), reason: `its declaration cannot be read again: ${reasonOf(error)}` });
+        }
+    }
+    const constantLines = macroConstants.map(([name, value]) => `#define ${name} ${value}`);
+    const declarations = [...chunks.flatMap((chunk) => chunk.lines), ...constantLines].join('\n');
+    //The functions and the variables of the library, as the declarations written are read (the types the package knows
+    //replace the ones of the system of the same name: DWORD, LPCWSTR)
+    const emitted = checker.declarations;
+    let functions = [];
+    let variables = [];
+    const prototypes = new Map();
+    for (const chunk of chunks) {
+        const item = items[chunk.index];
+        if (!isOwn(item.file))
+            continue;
+        for (const name of item.names) {
+            if (name.startsWith('function ')) {
+                const fn = emitted.functions.get(name.slice(9));
+                if (fn)
+                    functions.push(fn);
+                prototypes.set(name.slice(9), (0, CText_js_1.declarationText)((0, CText_js_1.prunedTokens)(item.tokens), '').join(' '));
+            }
+            else if (name.startsWith('variable ')) {
+                const variable = emitted.variables.get(name.slice(9));
+                if (variable)
+                    variables.push(variable);
+            }
+        }
+    }
+    const ownConstants = macroConstants.length + chunks.filter((chunk) => isOwn(items[chunk.index].file)).flatMap((chunk) => items[chunk.index].names).filter((name) => name.startsWith('constant ')).length;
+    //Checked against the library: the functions and the variables it cannot give left out
+    let libraryFile;
+    let unchecked;
+    const library = options.library ?? headerName;
+    if (options.check === false) {
+        unchecked = 'not asked';
+    }
+    else {
+        let handle;
+        try {
+            handle = (0, NativeLibraryHandle_js_1.loadNativeLibrary)(library, declarations);
+        }
+        catch (error) {
+            unchecked = reasonOf(error).replace(/:$/, '').replace(/^The /, 'the ');
+        }
+        if (handle) {
+            libraryFile = handle.file;
+            const usable = (declared, bind) => declared.filter((declaration) => {
+                try {
+                    bind(declaration.name);
+                    return true;
+                }
+                catch (error) {
+                    skipped.push({ name: declaration.name, reason: reasonOf(error) });
+                    return false;
+                }
+            });
+            functions = usable(functions, (name) => handle.function(name));
+            variables = usable(variables, (name) => handle.variable(name));
+            await handle.close();
+        }
+    }
+    //The interfaces of the structs and unions of the library
+    const records = [];
+    const names = new Map();
+    const used = new Set([...TAKEN]);
+    const className = options.className ?? pascalCase(headerName);
+    used.add(className);
+    const nameRecord = (record, preferred) => {
+        if (names.has(record))
+            return;
+        let name = preferred;
+        while (used.has(name))
+            name = `${name}_`;
+        used.add(name);
+        names.set(record, name);
+        records.push({ name: name, record: record });
+    };
+    for (const chunk of chunks) {
+        const item = items[chunk.index];
+        if (!isOwn(item.file))
+            continue;
+        for (const name of item.names) {
+            const type = name.startsWith('type ') ? emitted.types.get(name.slice(5)) : name.startsWith('struct ') || name.startsWith('union ') ? emitted.tags.get(name) : undefined;
+            if ((type?.kind === 'struct' || type?.kind === 'union') && type.members)
+                nameRecord(type, name.startsWith('type ') ? name.slice(5) : name.split(' ')[1]);
+        }
+    }
+    const types = new TypeScriptTypes_js_1.TypeScriptTypes(names);
+    //The class: a property by function and variable, named as it (another name when the component has a member of that name)
+    const reserved = memberNames();
+    const property = (name) => {
+        if (!reserved.has(name))
+            return { name: name, argument: '' };
+        let renamed = `${name}_`;
+        while (reserved.has(renamed))
+            renamed = `${renamed}_`;
+        return { name: renamed, argument: `'${name}'` };
+    };
+    const members = [];
+    for (const fn of functions) {
+        const prototype = prototypes.get(fn.name);
+        const { name, argument } = property(fn.name);
+        members.push([...prototype ? [`    //${prototype}`] : [], `    @Native(${argument})`, `    public readonly ${name}: ${types.functionType(fn.type)}`].join('\n'));
+    }
+    for (const variable of variables) {
+        const { name, argument } = property(variable.name);
+        members.push([`    @NativeVariable(${argument})`, `    public readonly ${name}: ${types.type(variable.type, 'received')}`].join('\n'));
+    }
+    const interfaces = records.map(({ name, record }) => [`export interface ${name} {`, ...types.members(record, '    '), '}'].join('\n'));
+    const body = [...interfaces, ...members].join('\n');
+    const imports = ['Library', 'Native', 'NativeLibrary', ...variables.length ? ['NativeVariable'] : [], ...body.includes('Out<') ? ['type Out'] : [], ...body.includes('Pointer') ? ['type Pointer'] : []];
+    const platformName = `${platform.os}-${platform.arch}`;
+    const code = [
+        ...commentLines(`Generated from ${node_path_1.default.basename(header)} by the generator of @lakutata/ffi (lakutata ffi generate), for ${platformName}${libraryFile ? `; checked against ${libraryFile}` : ''}: ${functions.length} functions, ${variables.length} variables, ${ownConstants} constants.`),
+        ...commentLines('The functions are synchronous, and their pointer parameters are inputs: where needed, mark the output parameters _Out_ in the declarations and the functions that block {async: true} (see the guide of @lakutata/ffi). Another build of the library may lack some of these functions: the component then refuses to start, naming the function.'),
+        `import {${imports.join(', ')}} from '@lakutata/ffi'`,
+        '',
+        ...interfaces.flatMap((text) => [text, '']),
+        '@Library({',
+        `    names: ${JSON.stringify(libraryName(library)).replace(/^"|"$/g, '\'')},`,
+        '    declarations: `',
+        ...templateText(declarations).split('\n').map((line) => `        ${line}`),
+        '    `',
+        '})',
+        `export class ${className} extends NativeLibrary {`,
+        members.join('\n\n'),
+        '}',
+        ''
+    ].join('\n');
+    return {
+        className: className,
+        code: code,
+        declarations: declarations,
+        report: {
+            command: preprocessed.command,
+            platform: platformName,
+            ...libraryFile ? { library: libraryFile } : {},
+            ...unchecked ? { unchecked: unchecked } : {},
+            functions: functions.length,
+            variables: variables.length,
+            interfaces: records.length,
+            constants: ownConstants,
+            skipped: skipped
+        }
+    };
+}
+/**
+ * Generate the class of a native library from its header: the header is run through the preprocessor of the C compiler,
+ * its declarations are read, the functions and the variables the library cannot give are left out, and the class gets a
+ * property by function (named as the function) with its TypeScript type.
+ * @param options The header, the library, the class, the compiler and its options.
+ * @returns The code of the class, and what was generated and left out.
+ * @example
+ * ```typescript
+ * import {writeFileSync} from 'node:fs'
+ * import {generateNativeLibrary} from '@lakutata/ffi/generator'
+ *
+ * const {code, report} = await generateNativeLibrary({header: 'vendor/include/vendor.h', library: 'vendor/lib/libvendor.so'})
+ * writeFileSync('src/native/Vendor.ts', code)
+ * for (const skipped of report.skipped) console.log(`${skipped.name}: ${skipped.reason}`)
+ * ```
+ */
+async function generateNativeLibrary(options) {
+    return await generateFromPreprocessed((0, Preprocessor_js_1.preprocessHeader)(options), options);
+}

package/dist/cjs/lib/generator/Preprocessor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * How a header is run through the preprocessor
+ */
+export interface PreprocessOptions {
+    /**
+     * The header
+     */
+    readonly header: string;
+    /**
+     * The compiler whose preprocessor is run: cc, gcc, clang (their -E -dD), or cl, clang-cl (cl /P /d1PP)
+     */
+    readonly compiler?: string;
+    /**
+     * The directories of the headers it includes
+     */
+    readonly include?: readonly string[];
+    /**
+     * The macros defined before it: NAME, or NAME=VALUE
+     */
+    readonly define?: readonly string[];
+}
+/**
+ * A header run through the preprocessor
+ */
+export interface PreprocessedHeader {
+    /**
+     * The output of the preprocessor: the declarations, the #define kept, the line markers naming the files
+     */
+    readonly text: string;
+    /**
+     * The header, as the line markers name it
+     */
+    readonly header: string;
+    /**
+     * The directories of the headers of the system: their headers are not the ones of the library
+     */
+    readonly systemDirectories: readonly string[];
+    /**
+     * The command run
+     */
+    readonly command: string;
+}
+/**
+ * The C compiler whose preprocessor reads the headers by default: the one of the CC variable, else cl on Windows (run
+ * in the Developer Command Prompt of Visual Studio), cc elsewhere.
+ * @returns The command of the compiler.
+ * @example
+ * ```typescript
+ * import {defaultCompiler} from '@lakutata/ffi/generator'
+ *
+ * console.log(defaultCompiler())
+ * ```
+ */
+export declare function defaultCompiler(): string;
+/**
+ * Run a header through the preprocessor of a compiler, keeping its #define and the line markers naming the files.
+ * @param options The header, the compiler, the directories and the macros.
+ * @returns The output, the header as the line markers name it, the directories of the system.
+ */
+export declare function preprocessHeader(options: PreprocessOptions): PreprocessedHeader;

package/dist/cjs/lib/generator/Preprocessor.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultCompiler = defaultCompiler;
+exports.preprocessHeader = preprocessHeader;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const NativeDeclarationException_js_1 = require("../../exceptions/NativeDeclarationException.js");
+/**
+ * The C compiler whose preprocessor reads the headers by default: the one of the CC variable, else cl on Windows (run
+ * in the Developer Command Prompt of Visual Studio), cc elsewhere.
+ * @returns The command of the compiler.
+ * @example
+ * ```typescript
+ * import {defaultCompiler} from '@lakutata/ffi/generator'
+ *
+ * console.log(defaultCompiler())
+ * ```
+ */
+function defaultCompiler() {
+    return process.env.CC?.trim() || (process.platform === 'win32' ? 'cl' : 'cc');
+}
+/**
+ * Whether a compiler takes the options of Microsoft (cl, clang-cl)
+ * @param compiler
+ */
+function microsoft(compiler) {
+    return /^(?:cl|clang-cl)(?:\.exe)?$/i.test(node_path_1.default.basename(compiler));
+}
+/**
+ * Run a compiler: its output, its errors
+ * @param compiler
+ * @param args
+ */
+function run(compiler, args) {
+    const result = (0, node_child_process_1.spawnSync)(compiler, args, { encoding: 'latin1', maxBuffer: 1 << 30, windowsHide: true });
+    if (result.error?.code === 'ENOENT') {
+        throw new NativeDeclarationException_js_1.NativeDeclarationException(microsoft(compiler)
+            ? `The compiler ${compiler} is not found: run in the Developer Command Prompt (or PowerShell) of Visual Studio, or give another compiler`
+            : `The compiler ${compiler} is not found: install a C compiler (the Command Line Tools of Xcode, gcc, clang), or give another one`);
+    }
+    if (result.error)
+        throw result.error;
+    return { stdout: result.stdout, stderr: result.stderr, status: result.status };
+}
+/**
+ * The directories of the headers of the system of GCC and Clang, as -v lists them (without the ones given by -I)
+ * @param compiler
+ */
+function systemDirectoriesOf(compiler) {
+    const { stdout, stderr } = run(compiler, ['-E', '-v', '-x', 'c', node_os_1.devNull]);
+    const lines = `${stdout}\n${stderr}`.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.startsWith('#include <...> search starts here'));
+    const end = lines.findIndex((line, index) => index > start && line.startsWith('End of search list'));
+    if (start < 0 || end < 0)
+        return [];
+    return lines.slice(start + 1, end).map((line) => node_path_1.default.resolve(line.replace(/\(framework directory\)$/, '').trim()));
+}
+/**
+ * Run a header through the preprocessor of a compiler, keeping its #define and the line markers naming the files.
+ * @param options The header, the compiler, the directories and the macros.
+ * @returns The output, the header as the line markers name it, the directories of the system.
+ */
+function preprocessHeader(options) {
+    const header = node_path_1.default.resolve(options.header);
+    const compiler = options.compiler ?? defaultCompiler();
+    const include = (options.include ?? []).map((directory) => node_path_1.default.resolve(directory));
+    const define = options.define ?? [];
+    if (microsoft(compiler)) {
+        //cl /P writes a file; /d1PP keeps the #define in it
+        const directory = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), 'lakutata-ffi-preprocess-'));
+        const output = node_path_1.default.join(directory, 'header.i');
+        const args = ['/nologo', '/P', '/TC', '/d1PP', `/Fi${output}`, ...include.map((dir) => `/I${dir}`), ...define.map((macro) => `/D${macro}`), header];
+        try {
+            const { stderr, status } = run(compiler, args);
+            if (status !== 0)
+                throw new NativeDeclarationException_js_1.NativeDeclarationException(`The preprocessor failed (${compiler} ${args.join(' ')}): ${stderr.trim()}`);
+            const systemDirectories = (process.env.INCLUDE ?? '').split(';').filter(Boolean).map((dir) => node_path_1.default.resolve(dir));
+            return { text: (0, node_fs_1.readFileSync)(output, 'latin1'), header: header, systemDirectories: systemDirectories, command: [compiler, ...args.filter((arg) => !arg.startsWith('/Fi'))].join(' ') };
+        }
+        finally {
+            (0, node_fs_1.rmSync)(directory, { recursive: true, force: true });
+        }
+    }
+    const args = ['-E', '-dD', '-x', 'c', ...include.map((dir) => `-I${dir}`), ...define.map((macro) => `-D${macro}`), header];
+    const { stdout, stderr, status } = run(compiler, args);
+    if (status !== 0)
+        throw new NativeDeclarationException_js_1.NativeDeclarationException(`The preprocessor failed (${compiler} ${args.join(' ')}): ${stderr.trim()}`);
+    return { text: stdout, header: header, systemDirectories: systemDirectoriesOf(compiler), command: [compiler, ...args].join(' ') };
+}