Nosial/ncc
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 11 Packages Wiki Activity Actions

Added documentation regarding ExecutionPolicies & Runners

Browse source
This commit is contained in:
Netkas 2023-01-29 15:27:43 -05:00
parent 29e2ba1594
commit 4484200bb7
1 changed files with 112 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
DOCUMENTATION.md
View file

@ -31,6 +31,14 @@ NCC, from basic installation, basic usage, standards and much more.
* [project.update_source](#projectupdatesource)
* [project.update_source.repository](#projectupdatesourcerepository)
* [assembly](#assembly)
* [execution_policies](#executionpolicies)
* [execution_policy](#executionpolicy)
* [execution_policy.execute](#executionpolicyexecute)
* [execution_policy.exit_handlers](#executionpolicyexithandlers)
* [exit_handler](#exithandler)
* [Execution Policies](#execution-policies)
* [Supported Runners](#supported-runners)
* [Configuring Runners](#configuring-runners)
* [Remote Sources](#remote-sources)
* [Supported sources](#supported-sources)
* [Default sources](#default-sources)
@ -360,6 +368,110 @@ The `assembly` field contains metadata about the program, such as the name, vers
| version | `string` | Yes | The version of the package, see [Versioning](#versioning) for additional information |
| uuid | `string` | Yes | The UUID of the package, see [UUIDs](#uuids) for additional information |
### execution_policies
The `execution_policies` field contains information about the execution policies that the program uses, such as
the execution policy that the program uses to run additional programs during different stages of the installation
process of the package or used as the main execution policy for the program.
Note that this field is an array of `execution_policy` objects, see [execution_policy](#executionpolicy) for additional
information.
For more information about execution policies, see [Execution Policies](#execution-policies).
#### execution_policy
The `execution_policy` object contains information about the execution policy.
| Name | Type | Required | Description |
|---------------|----------------------------------|----------|----------------------------------------------------------------------------------------------------|
| name | `string` | Yes | The name of the execution policy, this is used to identify the execution policy |
| runner | `string` | Yes | The name of the runner that the execution policy uses, see [Supported runners](#supported-runners) |
| message | `string` | No | The message to display when the execution policy is being run |
| execute | `execution_policy.execute` | Yes | The execution policy to run when the execution policy is being run |
| exit_handlers | `execution_policy.exit_handlers` | No | The exit handlers to run when the execution policy has finished running |
#### execution_policy.execute
The `execution_policy.execute` object contains information about how to run the execution policy when triggered.
| Name | Type | Required | Description |
|-----------------------|------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| target | `string` | Yes | The target file to run when the execution policy is triggered, file path is relative to the location of your project.json file (eg; scripts/main.php) |
| working_directory | `string` | No | The working directory to run the process in. If not specified, the working directory will be your current working directory. |
| options | `string[]` | No | The options to pass to the process when running it. (eg; ["--foo", "bar", "-f"]) |
| environment_variables | `string[]` | No | The environment variables to pass to the process when running it. (eg; ["FOO=bar"]) |
| silent | `bool` | No | Whether to run the process silently or not. If not specified, the process will not be run silently. |
| tty | `bool` | No | Whether to run the process in a TTY or not. If not specified, the process will not be run in a TTY. |
| timeout | `int` | No | The timeout of the process in seconds. If not specified, the process will not have a timeout. |
| idle_timeout | `int` | No | The idle timeout of the process in seconds. If not specified, the process will not have an idle timeout. |
#### execution_policy.exit_handlers
The `execution_policy.exit_handlers` object contains information about how to run the exit handlers when the execution
policy has finished running. This is useful for running additional policies when the process has exited in a specific
way.
The two handlers that can be executed automatically despite the exit code are `success` and `error`. Which means if the
process exits with a success exit code, the `success` handler will be run, and if the process exits with an error exit
code, the `error` handler will be run. The `warning` handler will only be run if the process exits with specified exit
code.
| Name | Type | Required | Description |
|---------|----------------|----------|-------------------------------------------------------------------------------|
| success | `exit_handler` | No | The exit handler to run when the process has exited successfully. |
| warning | `exit_handler` | No | The exit handler to run when the process has exited with a warning exit code. |
| error | `exit_handler` | No | The exit handler to run when the process has exited with an error exit code. |
#### exit_handler
The `exit_handler` object contains information about how to run the exit handler when the execution policy has finished
running.
| Name | Type | Required | Description |
|---------------|----------|----------|---------------------------------------------------------------------------------------------------------------------------------------------|
| message | `string` | No | The message to display when the exit handler is triggered |
| end_execution | `bool` | No | Whether to end the execution of the program or not if this exit handler is triggered. If not specified, the program will not end execution. |
| run | `string` | No | The name of the execution policy to run when this exit handler is triggered. |
| exit_code | `int` | No | The exit code that the process must have exited with for this exit handler to be triggered. |
------------------------------------------------------------------------------------
# Execution Policies
Execution policies are the policies that are used to run additional programs during different stages of the installation
or execution of the package. These policies are defined in your project.json `execution_policies` field with unique
names for each policy, so that these policies can be referenced by other policies or by NCC if configured to do so.
## Supported Runners
At the moment, NCC only supports a select few "runners" that can be used to run the policies, these runners are:
- `php` - This runner is used to run PHP scripts, it is the default runner for NCC
- `bash` - This runner is used to run bash scripts
- `python` - This runner is used to run python scripts
- `python2` - This runner is used to run python2 scripts
- `python3` - This runner is used to run python3 scripts
- `perl` - This runner is used to run perl scripts
- `lua` - This runner is used to run lua scripts
> Note: these runners are not installed by default, you will need to install them yourself.
## Configuring Runners
If for some reason NCC cannot automatically detect the runner that you want to use, you can configure the runner yourself
by modifying your configuration file. The configuration file is located at `/var/ncc/ncc.yaml` under the `runners` field.
Or you can modify the configuration file by running the following command:
```bash
ncc config -p runners.bash -v /usr/bin/bash
```
This will set the `bash` runner to use the `/usr/bin/bash` binary.
> **Note:** You must have root permissions to modify the configuration file.
------------------------------------------------------------------------------------
# Remote Sources