From 80a0fea0253dd972c30353a073df507063005fdb Mon Sep 17 00:00:00 2001 From: Marc Durdin Date: Mon, 4 Mar 2024 19:15:37 +0700 Subject: [PATCH] docs(developer): kmc-package api documentation Note: WindowsPackageInstallerSources fields are not yet documented. --- developer/docs/api/etc/kmc-package.api.md | 68 ++++++++++++------- .../kmc-package/src/compiler/kmp-compiler.ts | 67 ++++++++++++++++++ .../src/compiler/package-compiler-messages.ts | 3 + .../src/compiler/package-validation.ts | 3 + .../windows-package-installer-compiler.ts | 64 +++++++++++++++++ developer/src/kmc-package/src/main.ts | 10 ++- 6 files changed, 187 insertions(+), 28 deletions(-) diff --git a/developer/docs/api/etc/kmc-package.api.md b/developer/docs/api/etc/kmc-package.api.md index 2601e38f3bd..1215057dfea 100644 --- a/developer/docs/api/etc/kmc-package.api.md +++ b/developer/docs/api/etc/kmc-package.api.md @@ -14,30 +14,38 @@ import { KeymanCompilerResult } from '@keymanapp/common-types'; import { KmpJsonFile } from '@keymanapp/common-types'; import { KpsFile } from '@keymanapp/common-types'; -// @public (undocumented) +// @public export class KmpCompiler implements KeymanCompiler { + // @internal buildKmpFile(kpsFilename: string, kmpJsonData: KmpJsonFile.KmpJsonFile): Promise; - // Warning: (ae-forgotten-export) The symbol "KmpCompilerOptions" needs to be exported by the entry point main.d.ts - // - // (undocumented) init(callbacks: CompilerCallbacks, options: KmpCompilerOptions): Promise; - // (undocumented) + // @internal (undocumented) loadKpsFile(kpsFilename: string): KpsFile.KpsFile; - // Warning: (ae-forgotten-export) The symbol "KmpCompilerResult" needs to be exported by the entry point main.d.ts - // - // (undocumented) run(inputFilename: string, outputFilename?: string): Promise; - // (undocumented) + // @internal (undocumented) transformKpsFileToKmpObject(kpsFilename: string, kps: KpsFile.KpsFile): KmpJsonFile.KmpJsonFile; - // (undocumented) + // @internal (undocumented) transformKpsToKmpObject(kpsFilename: string): KmpJsonFile.KmpJsonFile; - // Warning: (ae-forgotten-export) The symbol "KmpCompilerArtifacts" needs to be exported by the entry point main.d.ts - // - // (undocumented) write(artifacts: KmpCompilerArtifacts): Promise; } -// @public (undocumented) +// @public +export interface KmpCompilerArtifacts extends KeymanCompilerArtifacts { + kmp: KeymanCompilerArtifact; +} + +// @public +export interface KmpCompilerOptions extends CompilerOptions { +} + +// @public +export interface KmpCompilerResult extends KeymanCompilerResult { + artifacts: KmpCompilerArtifacts; +} + +// Warning: (ae-internal-missing-underscore) The name "PackageCompilerMessages" should be prefixed with an underscore because the declaration is marked as @internal +// +// @internal (undocumented) export class PackageCompilerMessages { // (undocumented) static ERROR_FileCouldNotBeRead: number; @@ -220,30 +228,38 @@ export class PackageCompilerMessages { }) => CompilerEvent; } -// @public (undocumented) +// Warning: (ae-internal-missing-underscore) The name "PackageValidation" should be prefixed with an underscore because the declaration is marked as @internal +// +// @internal (undocumented) export class PackageValidation { constructor(callbacks: CompilerCallbacks, options: CompilerOptions); // (undocumented) validate(filename: string, kmpJson: KmpJsonFile.KmpJsonFile): boolean; } -// @public (undocumented) +// @public export class WindowsPackageInstallerCompiler implements KeymanCompiler { - // Warning: (ae-forgotten-export) The symbol "WindowsPackageInstallerCompilerOptions" needs to be exported by the entry point main.d.ts - // - // (undocumented) init(callbacks: CompilerCallbacks, options: WindowsPackageInstallerCompilerOptions): Promise; - // Warning: (ae-forgotten-export) The symbol "WindowsPackageInstallerCompilerResult" needs to be exported by the entry point main.d.ts - // - // (undocumented) run(inputFilename: string, outputFilename?: string): Promise; - // Warning: (ae-forgotten-export) The symbol "WindowsPackageInstallerCompilerArtifacts" needs to be exported by the entry point main.d.ts - // - // (undocumented) write(artifacts: WindowsPackageInstallerCompilerArtifacts): Promise; } -// @public (undocumented) +// @public +export interface WindowsPackageInstallerCompilerArtifacts extends KeymanCompilerArtifacts { + exe: KeymanCompilerArtifact; +} + +// @public +export interface WindowsPackageInstallerCompilerOptions extends KmpCompilerOptions { + sources: WindowsPackageInstallerSources; +} + +// @public +export interface WindowsPackageInstallerCompilerResult extends KeymanCompilerResult { + artifacts: WindowsPackageInstallerCompilerArtifacts; +} + +// @public export interface WindowsPackageInstallerSources { // (undocumented) appName?: string; diff --git a/developer/src/kmc-package/src/compiler/kmp-compiler.ts b/developer/src/kmc-package/src/compiler/kmp-compiler.ts index c21adf61925..4665bc5d603 100644 --- a/developer/src/kmc-package/src/compiler/kmp-compiler.ts +++ b/developer/src/kmc-package/src/compiler/kmp-compiler.ts @@ -21,29 +21,76 @@ const KMP_INF_FILENAME = 'kmp.inf'; // this filename for existing keyboard packages. const WELCOME_HTM_FILENAME = 'welcome.htm'; +/** + * @public + * Options for the .kps compiler + */ export interface KmpCompilerOptions extends CompilerOptions { // Note: WindowsPackageInstallerCompilerOptions extends KmpCompilerOptions, so // be careful when modifying this interface }; +/** + * @public + * Internal in-memory build artifacts from a successful compilation + */ export interface KmpCompilerArtifacts extends KeymanCompilerArtifacts { + /** + * Binary keyboard package filedata and filename - installable into Keyman + * desktop and mobile projects + */ kmp: KeymanCompilerArtifact; }; +/** + * @public + * Build artifacts from the .kps compiler + */ export interface KmpCompilerResult extends KeymanCompilerResult { + /** + * Internal in-memory build artifacts from a successful compilation. Caller + * can write these to disk with {@link KmpCompiler.write} + */ artifacts: KmpCompilerArtifacts; }; +/** + * @public + * Compiles a .kps file to a .kmp archive. The compiler does not read or write + * from filesystem or network directly, but relies on callbacks for all external + * IO. + */ export class KmpCompiler implements KeymanCompiler { private callbacks: CompilerCallbacks; private options: KmpCompilerOptions; + /** + * Initialize the compiler. + * Copies options. + * @param callbacks - Callbacks for external interfaces, including message + * reporting and file io + * @param options - Compiler options + * @returns false if initialization fails + */ public async init(callbacks: CompilerCallbacks, options: KmpCompilerOptions): Promise { this.callbacks = callbacks; this.options = options ? {...options} : {}; return true; } + /** + * Compiles a .kps file to .kmp file. Returns an object containing binary + * artifacts on success. The files are passed in by name, and the compiler + * will use callbacks as passed to the {@link KmpCompiler.init} function + * to read any input files by disk. + * @param infile - Path to source file. Path will be parsed to find relative + * references in the .kmn file, such as icon or On Screen + * Keyboard file + * @param outfile - Path to output file. The file will not be written to, but + * will be included in the result for use by + * {@link KmpCompiler.write}. + * @returns Binary artifacts on success, null on failure. + */ public async run(inputFilename: string, outputFilename?: string): Promise { const kmpJsonData = this.transformKpsToKmpObject(inputFilename); if(!kmpJsonData) { @@ -80,11 +127,24 @@ export class KmpCompiler implements KeymanCompiler { return result; } + /** + * Write artifacts from a successful compile to disk, via callbacks methods. + * The artifacts written may include: + * + * - .kmp file - binary keyboard package used by Keyman on desktop and touch + * platforms + * + * @param artifacts - object containing artifact binary data to write out + * @returns true on success + */ public async write(artifacts: KmpCompilerArtifacts): Promise { this.callbacks.fs.writeFileSync(artifacts.kmp.filename, artifacts.kmp.data); return true; } + /** + * @internal + */ public transformKpsToKmpObject(kpsFilename: string): KmpJsonFile.KmpJsonFile { const kps = this.loadKpsFile(kpsFilename); if(!kps) { @@ -105,6 +165,9 @@ export class KmpCompiler implements KeymanCompiler { return kmp; } + /** + * @internal + */ public loadKpsFile(kpsFilename: string): KpsFile.KpsFile { // Load the KPS data from XML as JS structured data. const buffer = this.callbacks.loadFile(kpsFilename); @@ -136,6 +199,9 @@ export class KmpCompiler implements KeymanCompiler { return kps; } + /** + * @internal + */ public transformKpsFileToKmpObject(kpsFilename: string, kps: KpsFile.KpsFile): KmpJsonFile.KmpJsonFile { // @@ -401,6 +467,7 @@ export class KmpCompiler implements KeymanCompiler { } /** + * @internal * Returns a Promise to the serialized data which can then be written to a .kmp file. * * @param kpsFilename - Filename of the kps, not read, used only for calculating relative paths diff --git a/developer/src/kmc-package/src/compiler/package-compiler-messages.ts b/developer/src/kmc-package/src/compiler/package-compiler-messages.ts index 2f522889167..7e0ab61865d 100644 --- a/developer/src/kmc-package/src/compiler/package-compiler-messages.ts +++ b/developer/src/kmc-package/src/compiler/package-compiler-messages.ts @@ -7,6 +7,9 @@ const SevWarn = CompilerErrorSeverity.Warn | Namespace; const SevError = CompilerErrorSeverity.Error | Namespace; const SevFatal = CompilerErrorSeverity.Fatal | Namespace; +/** + * @internal + */ export class CompilerMessages { static FATAL_UnexpectedException = SevFatal | 0x0001; static Fatal_UnexpectedException = (o:{e: any}) => CompilerMessageSpecWithException(this.FATAL_UnexpectedException, null, o.e ?? 'unknown error'); diff --git a/developer/src/kmc-package/src/compiler/package-validation.ts b/developer/src/kmc-package/src/compiler/package-validation.ts index 58b2546b556..ce919d4a64c 100644 --- a/developer/src/kmc-package/src/compiler/package-validation.ts +++ b/developer/src/kmc-package/src/compiler/package-validation.ts @@ -16,6 +16,9 @@ const MODEL_ID_PATTERN_PACKAGE = /^[a-z_][a-z0-9_]*\.[a-z_][a-z0-9_-]*\.[a-z_][a const CONTENT_FILE_BASENAME_PATTERN = /^[a-z0-9_+.-]+$/i; // base names can be case insensitive const CONTENT_FILE_EXTENSION_PATTERN = /^(\.[a-z0-9_-]+)?$/; // extensions should be lower-case or empty +/** + * @internal + */ export class PackageValidation { constructor(private callbacks: CompilerCallbacks, private options: CompilerOptions) { diff --git a/developer/src/kmc-package/src/compiler/windows-package-installer-compiler.ts b/developer/src/kmc-package/src/compiler/windows-package-installer-compiler.ts index 031fdd2dd27..49e0ca25f9a 100644 --- a/developer/src/kmc-package/src/compiler/windows-package-installer-compiler.ts +++ b/developer/src/kmc-package/src/compiler/windows-package-installer-compiler.ts @@ -19,6 +19,10 @@ import { CompilerMessages } from "./package-compiler-messages.js"; const SETUP_INF_FILENAME = 'setup.inf'; const PRODUCT_NAME = 'Keyman'; +/** + * @public + * Sources and metadata for the Windows package installer compiler + */ export interface WindowsPackageInstallerSources { msiFilename: string; setupExeFilename: string; @@ -30,23 +34,60 @@ export interface WindowsPackageInstallerSources { startWithConfiguration: boolean; }; +/** + * @public + * Options for the .kps Windows package installer compiler + */ export interface WindowsPackageInstallerCompilerOptions extends KmpCompilerOptions { + /** + * Sources and metadata for the Windows package installer compiler + */ sources: WindowsPackageInstallerSources; } +/** + * @public + * Internal in-memory build artifacts from a successful compilation + */ export interface WindowsPackageInstallerCompilerArtifacts extends KeymanCompilerArtifacts { + /** + * Binary package installer filedata and filename - installable into Keyman + * desktop and mobile projects + */ exe: KeymanCompilerArtifact; }; +/** + * @public + * Build artifacts from the .kps Windows package installer compiler + */ export interface WindowsPackageInstallerCompilerResult extends KeymanCompilerResult { + /** + * Internal in-memory build artifacts from a successful compilation. Caller + * can write these to disk with {@link WindowsPackageInstallerCompiler.write} + */ artifacts: WindowsPackageInstallerCompilerArtifacts; }; +/** + * @public + * Compiles a .kps file to a .exe installer. The compiler does not read or write + * from filesystem or network directly, but relies on callbacks for all external + * IO. + */ export class WindowsPackageInstallerCompiler implements KeymanCompiler { private kmpCompiler: KmpCompiler; private callbacks: CompilerCallbacks; private options: WindowsPackageInstallerCompilerOptions; + /** + * Initialize the compiler. + * Copies options. + * @param callbacks - Callbacks for external interfaces, including message + * reporting and file io + * @param options - Compiler options + * @returns false if initialization fails + */ async init(callbacks: CompilerCallbacks, options: WindowsPackageInstallerCompilerOptions): Promise { this.callbacks = callbacks; this.options = {...options}; @@ -54,6 +95,20 @@ export class WindowsPackageInstallerCompiler implements KeymanCompiler { return await this.kmpCompiler.init(callbacks, options); } + /** + * Compiles a .kps file to .exe Windows package installer file. Returns an + * object containing binary artifacts on success. The files are passed in by + * name, and the compiler will use callbacks as passed to the + * {@link WindowsPackageInstallerCompiler.init} function to read any input + * files by disk. + * @param infile - Path to source file. Path will be parsed to find relative + * references in the .kmn file, such as icon or On Screen + * Keyboard file + * @param outfile - Path to output file. The file will not be written to, but + * will be included in the result for use by + * {@link WindowsPackageInstallerCompiler.write}. + * @returns Binary artifacts on success, null on failure. + */ public async run(inputFilename: string, outputFilename?: string): Promise { const sources = this.options.sources; const kps = this.kmpCompiler.loadKpsFile(inputFilename); @@ -103,6 +158,15 @@ export class WindowsPackageInstallerCompiler implements KeymanCompiler { return result; } + /** + * Write artifacts from a successful compile to disk, via callbacks methods. + * The artifacts written may include: + * + * - .exe file - binary Windows package installer executable file + * + * @param artifacts - object containing artifact binary data to write out + * @returns true on success + */ public async write(artifacts: WindowsPackageInstallerCompilerArtifacts): Promise { this.callbacks.fs.writeFileSync(artifacts.exe.filename, artifacts.exe.data); return true; diff --git a/developer/src/kmc-package/src/main.ts b/developer/src/kmc-package/src/main.ts index 636f4d0b417..e8979d3d8e0 100644 --- a/developer/src/kmc-package/src/main.ts +++ b/developer/src/kmc-package/src/main.ts @@ -1,4 +1,10 @@ -export { KmpCompiler } from "./compiler/kmp-compiler.js"; +export { KmpCompiler, KmpCompilerOptions, KmpCompilerResult, KmpCompilerArtifacts } from "./compiler/kmp-compiler.js"; export { PackageValidation } from "./compiler/package-validation.js"; -export { WindowsPackageInstallerSources, WindowsPackageInstallerCompiler } from "./compiler/windows-package-installer-compiler.js"; +export { + WindowsPackageInstallerSources, + WindowsPackageInstallerCompiler, + WindowsPackageInstallerCompilerOptions, + WindowsPackageInstallerCompilerResult, + WindowsPackageInstallerCompilerArtifacts, +} from "./compiler/windows-package-installer-compiler.js"; export { CompilerMessages as PackageCompilerMessages } from './compiler/package-compiler-messages.js'; \ No newline at end of file