From 293aa1ae02f6678774345a34d230408aa6b5a853 Mon Sep 17 00:00:00 2001 From: Danny McCormick Date: Sun, 4 Aug 2019 09:00:04 -0400 Subject: [PATCH] Update package docs (#38) * Update README.md * Add exec guidance * Add io guidance * Add tool-cache guidance * Readability * Readability * Readability * Nit * Nit * Nit --- packages/core/README.md | 81 ++++++++++++++++++++++++++++++++++- packages/exec/README.md | 59 +++++++++++++++++++++++-- packages/io/README.md | 80 ++++++++++++++++++---------------- packages/tool-cache/README.md | 77 ++++++++++++++++++++++++++++++++- 4 files changed, 254 insertions(+), 43 deletions(-) diff --git a/packages/core/README.md b/packages/core/README.md index d5bf5bab..dd5d479b 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -4,4 +4,83 @@ ## Usage -See [src/core.ts](src/core.ts). +#### Inputs/Outputs + +You can use this library to get inputs or set outputs: + +``` +const core = require('@actions/core'); + +const myInput = core.getInput('inputName', { required: true }); + +// Do stuff + +core.setOutput('outputKey', 'outputVal'); +``` + +#### Exporting variables/secrets + +You can also export variables and secrets for future steps. Variables get set in the environment automatically, while secrets must be scoped into the environment from a workflow using `{{ secret.FOO }}`. Secrets will also be masked from the logs: + +``` +const core = require('@actions/core'); + +// Do stuff + +core.exportVariable('envVar', 'Val'); +core.exportSecret('secretVar', variableWithSecretValue); +``` + +#### PATH Manipulation + +You can explicitly add items to the path for all remaining steps in a workflow: + +``` +const core = require('@actions/core'); + +core.addPath('pathToTool'); +``` + +#### Exit codes + +You should use this library to set the exit code for your action: + +``` +const core = require('@actions/core'); + +try { + if (work to do) { + // Do work + } else { + // Set neutral indicates that the action terminated but did not fail (aka there was no work to be done) + core.setNeutral(); + } +} +catch (err) { + // setFailed logs the message and sets a failing exit code + core.setFailed(`Action failed with error ${err}`); +} + +``` + +#### Logging + +Finally, this library provides some utilities for logging: + +``` +const core = require('@actions/core'); + +const myInput = core.getInput('input'); +try { + core.debug('Inside try block'); + + if (!myInput) { + core.warning('myInput wasnt set'); + } + + // Do stuff +} +catch (err) { + core.error('Error ${err}, action may still succeed though'); +} +``` diff --git a/packages/exec/README.md b/packages/exec/README.md index 354acdcb..e76ce0b5 100644 --- a/packages/exec/README.md +++ b/packages/exec/README.md @@ -1,7 +1,60 @@ # `@actions/exec` -> Functions necessary for running tools on the command line - ## Usage -See [src/exec.ts](src/exec.ts). \ No newline at end of file +#### Basic + +You can use this package to execute your tools on the command line in a cross platform way: + +``` +const exec = require('@actions/exec'); + +await exec.exec('node index.js'); +``` + +#### Args + +You can also pass in arg arrays: + +``` +const exec = require('@actions/exec'); + +await exec.exec('node', ['index.js', 'foo=bar']); +``` + +#### Output/options + +Capture output or specify [other options](https://github.com/actions/toolkit/blob/d9347d4ab99fd507c0b9104b2cf79fb44fcc827d/packages/exec/src/interfaces.ts#L5): + +``` +const exec = require('@actions/exec'); + +const myOutput = ''; +const myError = ''; + +const options = {}; +options.listeners = { + stdout: (data: Buffer) => { + myOutput += data.toString(); + }, + stderr: (data: Buffer) => { + myError += data.toString(); + } +}; +options.cwd = './lib'; + +await exec.exec('node', ['index.js', 'foo=bar'], options); +``` + +#### Exec tools not in the PATH + +You can use it in conjunction with the `which` function from `@actions/io` to execute tools that are not in the PATH: + +``` +const exec = require('@actions/exec'); +const io = require('@actions/io'); + +const pythonPath: string = await io.which('python', true) + +await exec.exec(`"${pythonPath}"`, ['main.py']); +``` diff --git a/packages/io/README.md b/packages/io/README.md index e9b50d2f..22f0901d 100644 --- a/packages/io/README.md +++ b/packages/io/README.md @@ -4,46 +4,50 @@ ## Usage +#### mkdir -p + +Recursively make a directory. Follows rules specified in [man mkdir](https://linux.die.net/man/1/mkdir) with the `-p` option specified: + ``` -/** - * Copies a file or folder. - * - * @param source source path - * @param dest destination path - * @param options optional. See CopyOptions. - */ -export function cp(source: string, dest: string, options?: CopyOptions): Promise +const io = require('@actions/io'); -/** - * Remove a path recursively with force - * - * @param path path to remove - */ -export function rmRF(path: string): Promise +await io.mkdirP('path/to/make'); +``` -/** - * Make a directory. Creates the full path with folders in between - * - * @param p path to create - * @returns Promise - */ -export function mkdirP(p: string): Promise +#### cp/mv -/** - * Moves a path. - * - * @param source source path - * @param dest destination path - * @param options optional. See CopyOptions. - */ -export function mv(source: string, dest: string, options?: CopyOptions): Promise +Copy or move files or folders. Follows rules specified in [man cp](https://linux.die.net/man/1/cp) and [man mv](https://linux.die.net/man/1/mv): -/** - * Returns path of a tool had the tool actually been invoked. Resolves via paths. - * - * @param tool name of the tool - * @param options optional. See WhichOptions. - * @returns Promise path to tool - */ -export function which(tool: string, options?: WhichOptions): Promise -``` \ No newline at end of file +``` +const io = require('@actions/io'); + +// Recursive must be true for directories +const options = { recursive: true, force: false } + +await io.cp('path/to/directory', 'path/to/dest', options); +await io.mv('path/to/file', 'path/to/dest'); +``` + +#### rm -rf + +Remove a file or folder recursively. Follows rules specified in [man rm](https://linux.die.net/man/1/rm) with the `-r` and `-f` rules specified. + +``` +const io = require('@actions/io'); + +await io.rmRF('path/to/directory'); +await io.rmRF('path/to/file'); +``` + +#### which + +Get the path to a tool and resolves via paths. Follows the rules specified in [man which](https://linux.die.net/man/1/which). + +``` +const exec = require('@actions/exec'); +const io = require('@actions/io'); + +const pythonPath: string = await io.which('python', true) + +await exec.exec(`"${pythonPath}"`, ['main.py']); +``` diff --git a/packages/tool-cache/README.md b/packages/tool-cache/README.md index 5856b65f..56c53530 100644 --- a/packages/tool-cache/README.md +++ b/packages/tool-cache/README.md @@ -4,4 +4,79 @@ ## Usage -See [src/tool-cache.ts](src/tool-cache.ts). \ No newline at end of file +#### Download + +You can use this to download tools (or other files) from a download URL: + +``` +const tc = require('@actions/tool-cache'); + +const node12Path = await tc.downloadTool('http://nodejs.org/dist/v12.7.0/node-v12.7.0-linux-x64.tar.gz'); +``` + +#### Extract + +These can then be extracted in platform specific ways: + +``` +const tc = require('@actions/tool-cache'); + +if (process.platform === 'win32') { + tc.downloadTool('http://nodejs.org/dist/v12.7.0/node-v12.7.0-win-x64.zip'); + const node12ExtractedFolder = await tc.extractZip(node12Path, 'path/to/extract/to'); + + // Or alternately + tc.downloadTool('http://nodejs.org/dist/v12.7.0/node-v12.7.0-win-x64.7z'); + const node12ExtractedFolder = await tc.extract7z(node12Path, 'path/to/extract/to'); +} +else { + const node12Path = await tc.downloadTool('http://nodejs.org/dist/v12.7.0/node-v12.7.0-linux-x64.tar.gz'); + const node12ExtractedFolder = await tc.extractTar(node12Path, 'path/to/extract/to'); +} +``` + +#### Cache + +Finally, you can cache these directories in our tool-cache. This is useful if you want to switch back and forth between versions of a tool, or save a tool between runs for private runners (private runners are still in development but are on the roadmap). + +You'll often want to add it to the path as part of this step: + +``` +const tc = require('@actions/tool-cache'); +const core = require('@actions/core'); + +const node12Path = await tc.downloadTool('http://nodejs.org/dist/v12.7.0/node-v12.7.0-linux-x64.tar.gz'); +const node12ExtractedFolder = await tc.extractTar(node12Path, 'path/to/extract/to'); + +const cachedPath = await tc.cacheDir(node12ExtractedFolder, 'node', '12.7.0'); +core.addPath(cachedPath); +``` + +You can also cache files for reuse. + +``` +const tc = require('@actions/tool-cache'); + +tc.cacheFile('path/to/exe', 'destFileName.exe', 'myExeName', '1.1.0'); +``` + +#### Find + +Finally, you can find directories and files you've previously cached: + +``` +const tc = require('@actions/tool-cache'); +const core = require('@actions/core'); + +const nodeDirectory = tc.find('node', '12.x', 'x64'); +core.addPath(nodeDirectory); +``` + +You can even find all cached versions of a tool: + +``` +const tc = require('@actions/tool-cache'); + +const allNodeVersions = tc.findAllVersions('node'); +console.log(`Versions of node available: ${allNodeVersions}`); +```