actions
/
toolkit
mirror of https://github.com/actions/toolkit
1
0
Fork 0
Code

Update package docs (#38) 

* Update README.md

* Add exec guidance

* Add io guidance

* Add tool-cache guidance

* Readability

* Readability

* Readability

* Nit

* Nit

* Nit
pull/40/head
Danny McCormick 2019-08-04 09:00:04 -04:00 committed by Bryan MacFarlane
parent 0bb10220a7
commit 293aa1ae02
4 changed files with 254 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
packages/core/README.md
View File

@ -4,4 +4,83 @@
## Usage ## 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');
}
```

59
packages/exec/README.md
View File

@ -1,7 +1,60 @@
# `@actions/exec` # `@actions/exec`
> Functions necessary for running tools on the command line
## Usage ## Usage
See [src/exec.ts](src/exec.ts). #### 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']);
```

80
packages/io/README.md
View File

@ -4,46 +4,50 @@
## Usage ## 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:
``` ```
/** const io = require('@actions/io');
* 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<void>
/** await io.mkdirP('path/to/make');
* Remove a path recursively with force ```
*
* @param path path to remove
*/
export function rmRF(path: string): Promise<void>
/** #### cp/mv
* Make a directory. Creates the full path with folders in between
*
* @param p path to create
* @returns Promise<void>
*/
export function mkdirP(p: string): Promise<void>
/** 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):
* 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<void>
/** ```
* Returns path of a tool had the tool actually been invoked. Resolves via paths. const io = require('@actions/io');
*
* @param tool name of the tool // Recursive must be true for directories
* @param options optional. See WhichOptions. const options = { recursive: true, force: false }
* @returns Promise<string> path to tool
*/ await io.cp('path/to/directory', 'path/to/dest', options);
export function which(tool: string, options?: WhichOptions): Promise<string> 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']);
```

77
packages/tool-cache/README.md
View File

@ -4,4 +4,79 @@
## Usage ## Usage
See [src/tool-cache.ts](src/tool-cache.ts). #### 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}`);
```