ncc/docs/project_configuration/execution_policy.md

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

• Execution Policies
  • Table of Contents
  • JSON Example
  • ExecutionPolicy Object
    • Object Properties
    • JSON Example
  • ExecutionConfiguration Object
    • Object Properties
    • JSON Example
  • ExitHandler Object
    • Object Properties
    • JSON Example
  • More Examples
    • bash
    • lua
    • php
    • perl
    • python (or python2/python3)
    • shell

JSON Example

{
  "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

{
  "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

{
  "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

{
  "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

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

lua

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

php

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

perl

{
  "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)

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

shell

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