# Execution Policies

**Updated on Wednesday, December 07, 2022**

An execution policy is a policy defined in the Project
configuration file (`project.json`) that can be used
to execute a script or program in any stage of the package

For instance, you can have a script that is executed before
the build process starts, or in different installation stages
when the user is installing your package you can have a unit
run before or after the installation/uninstallation process
starts.#

Use cases such as this allows you to properly implement
and control your program's files & assets that are not
handled by NCC's compiler extensions.

## Table of Contents

<!-- TOC -->
* [Execution Policies](#execution-policies)
  * [Table of Contents](#table-of-contents)
  * [JSON Example](#json-example)
  * [ExecutionPolicy Object](#executionpolicy-object)
    * [Object Properties](#object-properties)
    * [JSON Example](#json-example-1)
  * [ExecutionConfiguration Object](#executionconfiguration-object)
    * [Object Properties](#object-properties-1)
    * [JSON Example](#json-example-2)
  * [ExitHandler Object](#exithandler-object)
    * [Object Properties](#object-properties-2)
    * [JSON Example](#json-example-3)
  * [More Examples](#more-examples)
    * [bash](#bash)
    * [lua](#lua)
    * [php](#php)
    * [perl](#perl)
    * [python (or python2/python3)](#python--or-python2python3-)
    * [shell](#shell)
<!-- TOC -->


## JSON Example

```json
{
  "execution_policies": {
    "main": {
      "runner": "php",
      "message": "Running main %ASSEMBLY.PACKAGE%",
      "exec": {
        "target": "scripts/main.php",
        "working_directory": "%INSTALL_PATH.SRC%",
        "silent": false
      }
    },
    "hello_world": {
      "runner": "shell",
      "message": "Running HTOP",
      "options": {
        "htop": null
      },
      "exec": {
        "tty": true
      }
    }
  }
}
```

------------------------------------------------------------

## ExecutionPolicy Object

Execution Policies for your project **must** have unique
names, because they way you tell NCC to execute these
policies is by referencing their name in the configuration.

Invalid names/undefined policies will raise errors when
building the project

### Object Properties

| Property Name   | Value Type                      | Example Value        | Description                                                                                |
|-----------------|---------------------------------|----------------------|--------------------------------------------------------------------------------------------|
| `runner`        | string                          | bash                 | The name of a supported runner instance, see runners in this document                      |
| `message`       | string, null                    | Starting foo_bar ... | *Optional* the message to display before running the execution policy                      |
| `exec`          | ExecutionConfiguration          | N/A                  | The configuration object that tells how the runner should execute the process              |
| `exit_handlers` | ExitHandlersConfiguration, null | N/A                  | *Optional* Exit Handler Configurations that tells NCC how to handle exits from the process |

### JSON Example

```json
{
  "name": "foo_bar",
  "runner": "bash",
  "message": "Running foo_bar ...",
  "exec": null,
  "exit_handlers": null
}
```

------------------------------------------------------------

## ExecutionConfiguration Object

### Object Properties

| Property Name       | Value Type        | Example Value                   | Description                                                            |
|---------------------|-------------------|---------------------------------|------------------------------------------------------------------------|
| `target`            | `string`          | scripts/foo_bar.bash            | The target file to execute                                             |
| `working_directory` | `string`, `null`  | %INSTALL_PATH.SRC%              | *optional* The working directory to execute the process in             |
| `options`           | `array`, `null`   | {"run": null, "log": "verbose"} | Commandline Parameters to pass on to the target or process             |
| `silent`            | `boolean`, `null` | False                           | Indicates if the target should run silently, by default this is false. |
| `tty`               | `boolean`, `null` | False                           | Indicates if the target should run in TTY mode                         |
| `timeout`           | `integer`, `null` | 60                              | The amount of seconds to wait before the process is killed             |

### JSON Example

```json
{
  "target": "scripts/foo_bar.bash",
  "working_directory": "%INSTALL_PATH.SRC%",
  "options": {"run": null, "log": "verbose"},
  "silent": false,
  "tty": false,
  "timeout": 10
}
```


------------------------------------------------------------

## ExitHandler Object

An exit handler is executed once the specified exit code is
returned or the process exits with an error or normally, if
an exit handler is specified it will be executed.

### Object Properties

| Property Name | Value Type         | Example Value | Description                                                                  |
|---------------|--------------------|---------------|------------------------------------------------------------------------------|
| `message`     | `string`           | Hello World!  | The message to display when the exit handler is triggered                    |
| `end_process` | `boolean`, `null`  | False         | *optional* Kills the process after this exit handler is triggered            |
| `run`         | `string`, `null`   | `null`        | *optional* A execution policy to execute once this exit handler is triggered |
| `exit_code`   | `int`, `null`      | 1             | The exit code that triggers this exit handler                                |
### JSON Example

```json
{
  "message": "Hello World",
  "end_process": false,
  "run": null,
  "exit_code": 1
}
```


## More Examples

Just like the `project.json` file, you can have multiple
execution policies in your project, here are some examples
of how you can use them:

### bash

```json
{
  "execution_policies": [
    {
      "name": "main",
      "runner": "bash",
      "message": "Running main %ASSEMBLY.PACKAGE%",
      "exec": {
        "target": "scripts/main.bash",
        "working_directory": "%INSTALL_PATH.SRC%",
        "silent": false
      }
    }
  ]
}
```

### lua

```json
{
  "execution_policies": [
    {
      "name": "main",
      "runner": "lua",
      "message": "Running main %ASSEMBLY.PACKAGE%",
      "exec": {
        "target": "scripts/main.lua",
        "working_directory": "%INSTALL_PATH.SRC%",
        "silent": false
      }
    }
  ]
}
```

### php

```json
{
  "execution_policies": [
    {
      "name": "main",
      "runner": "php",
      "message": "Running main %ASSEMBLY.PACKAGE%",
      "exec": {
        "target": "scripts/main.php",
        "working_directory": "%INSTALL_PATH.SRC%",
        "silent": false
      }
    }
  ]
}
```

### perl

```json
{
  "execution_policies": [
    {
      "name": "main",
      "runner": "perl",
      "message": "Running main %ASSEMBLY.PACKAGE%",
      "exec": {
        "target": "scripts/main.pl",
        "working_directory": "%INSTALL_PATH.SRC%",
        "silent": false
      }
    }
  ]
}
```

### python (or python2/python3)

```json
{
  "execution_policies": [
    {
      "name": "main",
      "runner": "python",
      "message": "Running main %ASSEMBLY.PACKAGE%",
      "exec": {
        "target": "scripts/main.py",
        "working_directory": "%INSTALL_PATH.SRC%",
        "silent": false
      }
    }
  ]
}
```

### shell

```json
{
  "execution_policies": [
    {
      "name": "main",
      "runner": "shell",
      "message": "Running main %ASSEMBLY.PACKAGE%",
      "exec": {
        "target": "scripts/main.sh",
        "working_directory": "%INSTALL_PATH.SRC%",
        "silent": false
      }
    }
  ]
}
```