diff --git a/README.md b/README.md index 7e0adbb..75a0e41 100644 --- a/README.md +++ b/README.md @@ -42,83 +42,7 @@ bare-make test ## API -#### `await generate([options])` - -Options include: - -```js -options = { - source: '.', - build: 'build', - platform: os.platform(), - arch: os.arch(), - simulator: false, - environment, - cache: true, - preset, - sanitize, - fuzz, - debug, - withDebugSymbols, - withMinimalSize, - define, - cwd: path.resolve('.'), - color: false, - verbose: false, - stdio -} -``` - -#### `await build([options])` - -Options include: - -```js -options = { - build: 'build', - target, - clean: false, - parallel, - preset, - cwd: path.resolve('.'), - verbose: false, - stdio -} -``` - -#### `await install([options])` - -Options include: - -```js -options = { - build: 'build', - prefix: 'prebuilds', - component, - link: false, - strip: false, - parallel, - cwd: path.resolve('.'), - verbose: false, - stdio -} -``` - -#### `await test([options])` - -Options include: - -```js -options = { - build: 'build', - timeout: 30, - parallel, - preset, - cwd: path.resolve('.'), - verbose: false, - stdio -} -``` +See the [`bare-make` reference](https://docs.pears.com/reference/bare/modules/bare-make). ## CLI diff --git a/lib/build.d.ts b/lib/build.d.ts index 37ce7e4..d706897 100644 --- a/lib/build.d.ts +++ b/lib/build.d.ts @@ -1,16 +1,30 @@ import Pipe from 'bare-pipe' +/** Options for `build()`. */ declare interface BuildOptions { + /** Path to the build tree (default `'build'`, unset when `preset` is given). */ build?: string + /** Clean before building (default `false`). */ clean?: boolean + /** Working directory the build runs in (default the process working directory). */ cwd?: string + /** Number of parallel jobs; `0` lets the build system decide (default `0`). */ parallel?: number + /** CMake preset to use (default none). */ preset?: string + /** Standard I/O configuration passed to the CMake subprocess. */ stdio?: Pipe + /** The target to build (default all targets). */ target?: string + /** Enable verbose output (default `false`). */ verbose?: boolean } +/** + * @param opts - Options; `build` defaults to `'build'` (unset when `preset` is set), `parallel` to + * `0`, and `clean` and `verbose` to `false`. + * @throws {BUILD_FAILED} the build exits with a non-zero status. + */ declare function build(opts?: BuildOptions): Promise declare namespace build { diff --git a/lib/errors.d.ts b/lib/errors.d.ts index 2f4d9f8..4cf9312 100644 --- a/lib/errors.d.ts +++ b/lib/errors.d.ts @@ -1,10 +1,37 @@ declare class MakeError extends Error { + /** + * Construct a `MakeError` with the given message and `code`. + * @param msg - Human-readable error message. + * @param code - The error code, assigned to `err.code`. + * @param fn - The function to omit from the captured stack trace (default the `MakeError` + * constructor). + */ constructor(msg: string, code: string, fn?: MakeError) + /** + * Create a `MakeError` with code `'UNKNOWN_TOOLCHAIN'`. + * @param msg - Human-readable error message. + */ static UNKNOWN_TOOLCHAIN(msg: string): MakeError + /** + * Create a `MakeError` with code `'GENERATE_FAILED'`. + * @param msg - Human-readable error message. + */ static GENERATE_FAILED(msg: string): MakeError + /** + * Create a `MakeError` with code `'BUILD_FAILED'`. + * @param msg - Human-readable error message. + */ static BUILD_FAILED(msg: string): MakeError + /** + * Create a `MakeError` with code `'INSTALL_FAILED'`. + * @param msg - Human-readable error message. + */ static INSTALL_FAILED(msg: string): MakeError + /** + * Create a `MakeError` with code `'TEST_FAILED'`. + * @param msg - Human-readable error message. + */ static TEST_FAILED(msg: string): MakeError } diff --git a/lib/generate.d.ts b/lib/generate.d.ts index c956417..caa646b 100644 --- a/lib/generate.d.ts +++ b/lib/generate.d.ts @@ -1,25 +1,53 @@ import Pipe from 'bare-pipe' +/** Options for `generate()`. */ declare interface GenerateOptions { + /** Architecture to build for (default the host architecture). */ arch?: string + /** Path to the build tree (default `'build'`, unset when `preset` is given). */ build?: string + /** Reuse the build variable cache; set to `false` to configure fresh (default `true`). */ cache?: boolean + /** Working directory the generation runs in (default the process working directory). */ cwd?: string + /** Configure a debug build (default `false`). */ debug?: boolean + /** + * Build variable cache entries to create or update, as `[:]=` strings (default + * `[]`). + */ define?: string[] + /** The environment to build for (default none). */ environment?: string + /** Configure for fuzzing (default `false`). */ fuzz?: boolean + /** Operating system platform to build for (default the host platform). */ platform?: string + /** CMake preset to use (default none). */ preset?: string + /** Sanitizer to enable (default none). */ sanitize?: string + /** Build for a simulator (default `false`). */ simulator?: boolean + /** Path to the source tree (default `'.'`). */ source?: string + /** Standard I/O configuration passed to the CMake subprocess. */ stdio?: Pipe + /** Enable verbose output (default `false`). */ verbose?: boolean + /** Configure a release build with debug symbols (default `false`). */ withDebugSymbols?: boolean + /** Configure a release build with minimal size (default `false`). */ withMinimalSize?: boolean } +/** + * @param opts - Options; `source` defaults to `'.'`, `build` to `'build'`, `platform` and `arch` to + * the host, `cache` to `true`, and the build-type flags (`debug`, `fuzz`, `withDebugSymbols`, + * `withMinimalSize`, `verbose`) to `false`. + * @throws {UNKNOWN_TOOLCHAIN} no toolchain is available for the resolved `platform`-`arch` target. + * @throws {GENERATE_FAILED} build system generation exits with a non-zero status. + */ declare function generate(opts?: GenerateOptions): Promise declare namespace generate { diff --git a/lib/install.d.ts b/lib/install.d.ts index 31d6b21..b7e7c70 100644 --- a/lib/install.d.ts +++ b/lib/install.d.ts @@ -1,17 +1,32 @@ import Pipe from 'bare-pipe' +/** Options for `install()`. */ declare interface InstallOptions { + /** Path to the build tree (default `'build'`). */ build?: string + /** The component to install (default all components). */ component?: string + /** Working directory the install runs in (default the process working directory). */ cwd?: string + /** Symlink rather than copy the installed files (default `false`). */ link?: boolean + /** Whether to install in parallel (default `false`). */ parallel?: boolean + /** The prefix to install to (default `'prebuilds'`). */ prefix?: string + /** Standard I/O configuration passed to the CMake subprocess. */ stdio?: Pipe + /** Strip symbols before installing (default `false`). */ strip?: boolean + /** Enable verbose output (default `false`). */ verbose?: boolean } +/** + * @param opts - Options; `build` defaults to `'build'`, `prefix` to `'prebuilds'`, and `link`, + * `strip`, and `verbose` to `false`. + * @throws {INSTALL_FAILED} the install exits with a non-zero status. + */ declare function install(opts?: InstallOptions): Promise declare namespace install { diff --git a/lib/test.d.ts b/lib/test.d.ts index b207442..c698e05 100644 --- a/lib/test.d.ts +++ b/lib/test.d.ts @@ -1,15 +1,28 @@ import Pipe from 'bare-pipe' +/** Options for `test()`. */ declare interface TestOptions { + /** Path to the build tree (default `'build'`). */ build?: string + /** Working directory the tests run in (default the process working directory). */ cwd?: string + /** Number of parallel jobs; a negative value lets the runner decide (default `-1`). */ parallel?: number + /** CMake preset to use (default none). */ preset?: string + /** Standard I/O configuration passed to the CMake subprocess. */ stdio?: Pipe + /** Default per-test timeout in seconds (default `30`). */ timeout?: number + /** Enable verbose output (default `false`). */ verbose?: boolean } +/** + * @param opts - Options; `build` defaults to `'build'`, `timeout` to `30` seconds, `parallel` to + * `-1`, and `verbose` to `false`. + * @throws {TEST_FAILED} one or more tests fail. + */ declare function test(opts?: TestOptions): Promise declare namespace test {