Refactored documentation into DOCUMENTATION.md
This commit is contained in:
parent
bf73360f2c
commit
d65795fcb5
4 changed files with 325 additions and 424 deletions
331
DOCUMENTATION.md
331
DOCUMENTATION.md
|
@ -5,14 +5,31 @@ NCC, from basic installation, basic usage, standards and much more.
|
||||||
|
|
||||||
## Table of contents
|
## Table of contents
|
||||||
|
|
||||||
- Introduction
|
<!-- TOC -->
|
||||||
- What is NCC?
|
* [NCC Documentation](#ncc-documentation)
|
||||||
- Advantages over other software
|
* [Table of contents](#table-of-contents)
|
||||||
|
* [Introduction](#introduction)
|
||||||
|
* [What is NCC?](#what-is-ncc)
|
||||||
|
* [Building NCC from source](#building-ncc-from-source)
|
||||||
|
* [Requirements to build](#requirements-to-build)
|
||||||
|
* [Installing phpab](#installing-phpab)
|
||||||
|
* [Building NCC](#building-ncc)
|
||||||
|
* [Redist](#redist)
|
||||||
|
* [Tar](#tar)
|
||||||
|
* [Installing NCC](#installing-ncc)
|
||||||
|
* [Command line arguments](#command-line-arguments)
|
||||||
|
* [Uninstalling NCC](#uninstalling-ncc)
|
||||||
|
* [Projects](#projects)
|
||||||
|
* [Creating a project](#creating-a-project)
|
||||||
|
* [project.json structure](#projectjson-structure)
|
||||||
|
* [project](#project)
|
||||||
|
* [project.compiler](#projectcompiler)
|
||||||
|
* [Naming a package](#naming-a-package)
|
||||||
|
* [Naming conventions](#naming-conventions)
|
||||||
|
* [References](#references)
|
||||||
|
<!-- TOC -->
|
||||||
|
|
||||||
------------------------------------------------------------------------------------
|
## Introduction
|
||||||
|
|
||||||
|
|
||||||
# Introduction
|
|
||||||
|
|
||||||
This section serves the basic introduction of NCC, what it's used for and how you can
|
This section serves the basic introduction of NCC, what it's used for and how you can
|
||||||
use it in your own projects or use it to run and build other projects that are designed
|
use it in your own projects or use it to run and build other projects that are designed
|
||||||
|
@ -32,3 +49,303 @@ more efficient by treating each building block of your project as a component th
|
||||||
is interconnected in your environment instead of the more popular route taken by
|
is interconnected in your environment instead of the more popular route taken by
|
||||||
package/dependency managers such as [composer](https://getcomposer.org/),
|
package/dependency managers such as [composer](https://getcomposer.org/),
|
||||||
[npm](https://www.npmjs.com/) or [pypi (or pip)](https://pypi.org/).
|
[npm](https://www.npmjs.com/) or [pypi (or pip)](https://pypi.org/).
|
||||||
|
|
||||||
|
|
||||||
|
------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
# Building NCC from source
|
||||||
|
|
||||||
|
Building NCC from source is easy with very few requirements
|
||||||
|
to start building. At the moment ncc can only be debugged
|
||||||
|
or tested by building a redistributable source and
|
||||||
|
installing it.
|
||||||
|
|
||||||
|
## Requirements to build
|
||||||
|
|
||||||
|
- php8.0+
|
||||||
|
- php-mbstring
|
||||||
|
- php-ctype
|
||||||
|
- php-common (covers tokenizer & posix among others)
|
||||||
|
- make
|
||||||
|
- phpab
|
||||||
|
- tar *(optional)*
|
||||||
|
|
||||||
|
## Installing phpab
|
||||||
|
|
||||||
|
phpab is also known as [PHP Autoload Builder](https://github.com/theseer/Autoload),
|
||||||
|
phpab is an open source tool used for creating autoload
|
||||||
|
files, ncc needs this tool in order to generate it's
|
||||||
|
autoload files whenever there's any changes to its source
|
||||||
|
code.
|
||||||
|
|
||||||
|
This tool is only required for building and or creating a
|
||||||
|
redistributable package of ncc. This component is not
|
||||||
|
required to be installed to use ncc.
|
||||||
|
|
||||||
|
for some components that require static loading, ncc will
|
||||||
|
automatically load it using it's own
|
||||||
|
[autoloader](../src/autoload/autoload.php)
|
||||||
|
|
||||||
|
The recommended way to install phpab is by using [phive](https://phar.io/),
|
||||||
|
if you don't have phive installed you can install it by
|
||||||
|
running these commands in your terminal (from the official documentation)
|
||||||
|
|
||||||
|
```shell
|
||||||
|
wget -O phive.phar https://phar.io/releases/phive.phar
|
||||||
|
wget -O phive.phar.asc https://phar.io/releases/phive.phar.asc
|
||||||
|
gpg --keyserver hkps://keys.openpgp.org --recv-keys 0x9D8A98B29B2D5D79
|
||||||
|
gpg --verify phive.phar.asc phive.phar
|
||||||
|
chmod +x phive.phar
|
||||||
|
sudo mv phive.phar /usr/local/bin/phive
|
||||||
|
```
|
||||||
|
|
||||||
|
Once phive is installed, you can run the final command to
|
||||||
|
install phpab
|
||||||
|
```shell
|
||||||
|
sudo phive install phpab --global
|
||||||
|
```
|
||||||
|
|
||||||
|
or you can run this command to install it locally
|
||||||
|
```shell
|
||||||
|
phive install phpab
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** Optionally, you may want to have `phab` available in your
|
||||||
|
`$PATH`, this can be done with this command. *(Replace `x.xx.x` with your
|
||||||
|
version number)* this is if you installed it locally
|
||||||
|
|
||||||
|
```shell
|
||||||
|
ln -s /home/user/.phive/phars/phpab-x.xx.x.phar /usr/bin/phpab
|
||||||
|
```
|
||||||
|
|
||||||
|
## Building NCC
|
||||||
|
|
||||||
|
First, navigate to the main directory of NCC's source code
|
||||||
|
where the [Makefile](../Makefile) is present. If you
|
||||||
|
already attempted to or had built ncc before, it's
|
||||||
|
recommended to use `make clean` before building.
|
||||||
|
|
||||||
|
|
||||||
|
### Redist
|
||||||
|
|
||||||
|
Running `redist` from the Makefile will generate all the
|
||||||
|
required autoloader for ncc and move all the required
|
||||||
|
files into one redistributable source folder under a
|
||||||
|
directory called `build/src`
|
||||||
|
|
||||||
|
```shell
|
||||||
|
make redist
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### Tar
|
||||||
|
|
||||||
|
Running `tar` will run redist before packaging the
|
||||||
|
redistributable source into a tar.gz file that can
|
||||||
|
be distributed to other machines, this process is not
|
||||||
|
a requirement.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
make tar
|
||||||
|
```
|
||||||
|
|
||||||
|
Once you have a populated `build/src` folder, you can
|
||||||
|
simply run execute the `installer` file to install your
|
||||||
|
build of ncc onto the running machine.
|
||||||
|
|
||||||
|
------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
# Installing NCC
|
||||||
|
|
||||||
|
Installing NCC is easy, you can either download the
|
||||||
|
redistributable source from the [releases](https://git.n64.cc/nosial/ncc/-/releases)
|
||||||
|
page or you can build it from source using the
|
||||||
|
instructions above.
|
||||||
|
|
||||||
|
Once you have the redistributable source, you can
|
||||||
|
simply run execute the `INSTALL` file to install
|
||||||
|
ncc onto the running machine.
|
||||||
|
|
||||||
|
## Command line arguments
|
||||||
|
|
||||||
|
The installer accepts a few command line arguments
|
||||||
|
that can be used to customize the installation
|
||||||
|
process.
|
||||||
|
|
||||||
|
`--help` Displays the help message
|
||||||
|
|
||||||
|
`--auto` Automatically installs ncc without asking for user input.
|
||||||
|
|
||||||
|
**Note:** To install composer along with ncc, you must
|
||||||
|
also provide the `--install-composer` argument.
|
||||||
|
|
||||||
|
`--install-composer` Installs composer along with ncc.
|
||||||
|
By default, ncc will not install composer and during the
|
||||||
|
installation process you will be asked if you want to
|
||||||
|
install composer along-side ncc, this will not conflict
|
||||||
|
with any existing composer installation.
|
||||||
|
|
||||||
|
`--install-dir` Specifies the directory where ncc will be
|
||||||
|
installed to. By default, ncc will be installed to `/etc/ncc`
|
||||||
|
|
||||||
|
`--bypass-cli-check` Bypasses the check in the installer
|
||||||
|
that checks if the installer is being run from the command
|
||||||
|
line, this is useful if you want to install ncc from a script.
|
||||||
|
|
||||||
|
`--bypass-checksum` Bypasses the checksum check in the
|
||||||
|
installer, this is useful if you made modifications to
|
||||||
|
the installation files and want to install a modified
|
||||||
|
version of ncc.
|
||||||
|
|
||||||
|
But this isn't recommended and the proper way to do this
|
||||||
|
is to modify the source code and build ncc from source,
|
||||||
|
the Makefile task will automatically rebuild the checksum
|
||||||
|
file for you.
|
||||||
|
|
||||||
|
|
||||||
|
------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
# Uninstalling NCC
|
||||||
|
|
||||||
|
Uninstalling NCC is easy, simply delete the directory
|
||||||
|
where ncc was installed to, by default this is `/etc/ncc`.
|
||||||
|
|
||||||
|
To delete all the data that ncc has created, you can
|
||||||
|
also delete the `/var/ncc` directory.
|
||||||
|
|
||||||
|
Finally, remove the symlink that was created in `/usr/local/bin`
|
||||||
|
to the `ncc` entry point file.
|
||||||
|
|
||||||
|
------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
# Projects
|
||||||
|
|
||||||
|
A project is a directory that contains all the source files
|
||||||
|
to your program, it's similar to a workspace in
|
||||||
|
other IDEs. Usually contains a `project.json` file which
|
||||||
|
contains all the information about the project that
|
||||||
|
ncc needs to know.
|
||||||
|
|
||||||
|
This can include the name of the program, the version
|
||||||
|
of the program, the author of the program, the
|
||||||
|
dependencies of the program, build configurations,
|
||||||
|
and more.
|
||||||
|
|
||||||
|
This section will cover the basics of creating a
|
||||||
|
project and managing it and the technical details
|
||||||
|
of the `project.json` file.
|
||||||
|
|
||||||
|
|
||||||
|
## Creating a project
|
||||||
|
|
||||||
|
This is the first step in using ncc, you must create a
|
||||||
|
project before you can do anything else (*not really
|
||||||
|
because you can install packages without needing to create
|
||||||
|
a project and run them directly, but you get the point*)
|
||||||
|
|
||||||
|
The NCC command-line tool provides a management command
|
||||||
|
called `project` that can be used to create a new project
|
||||||
|
or to manage an existing project.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
ncc project create --package "com.example.program" --name "Example Program"
|
||||||
|
```
|
||||||
|
|
||||||
|
This command will create a new project in the current
|
||||||
|
directory, the `--package` argument specifies the
|
||||||
|
package name of the project, this is used to identify
|
||||||
|
the project and to avoid conflicts with other projects
|
||||||
|
that may have the same name.
|
||||||
|
|
||||||
|
The `--name` argument specifies the name of the project,
|
||||||
|
this is used to display the name of the project in the
|
||||||
|
project manager and in the project settings. This doesn't
|
||||||
|
have to be the same as the package name or unique.
|
||||||
|
|
||||||
|
**Note:** If the options are not provided, the command
|
||||||
|
will prompt you for the package name and the project name.
|
||||||
|
|
||||||
|
For more information about the project command, you can
|
||||||
|
run `ncc project --help` to display the help message.
|
||||||
|
|
||||||
|
## project.json structure
|
||||||
|
|
||||||
|
The `project.json` file is a JSON file that contains
|
||||||
|
all the information about the project.
|
||||||
|
|
||||||
|
When a project is created, the `project.json` file is
|
||||||
|
automatically created and populated with the default
|
||||||
|
values, you can modify this file to change the default
|
||||||
|
values or to add more information about the project.
|
||||||
|
|
||||||
|
This section will go over the structure of the `project.json`
|
||||||
|
file and what each field does.
|
||||||
|
|
||||||
|
### project
|
||||||
|
|
||||||
|
The `project` field contains information about the project,
|
||||||
|
such as what compiler extension to use, options to pass on
|
||||||
|
to the compiler, and more.
|
||||||
|
|
||||||
|
| Name | Type | Required | Description |
|
||||||
|
|---------------|--------------------------------------|----------|----------------------------------------------------------------------------------------------------|
|
||||||
|
| compiler | [project.compiler](#projectcompiler) | Yes | The compiler extension that the project uses to compile the program |
|
||||||
|
| options | `array` | No | An array of options to pass on to the compiler, the options vary depending on the compiler and NCC |
|
||||||
|
| update_source | `project.update_source` | No | The source for where the program can fetch updates from |
|
||||||
|
|
||||||
|
### project.compiler
|
||||||
|
|
||||||
|
The `project.compiler` field contains information about
|
||||||
|
the compiler extension that the project uses to compile
|
||||||
|
the program.
|
||||||
|
|
||||||
|
| Name | Type | Required | Description |
|
||||||
|
|-----------------|----------|----------|------------------------------------------------------------------------------------------------|
|
||||||
|
| extension | `string` | Yes | The name of the compiler extension that the project uses to compile the program |
|
||||||
|
| minimum_version | `string` | No | The minimum version of the compiler extension that the project requires to compile the program |
|
||||||
|
| maximum_version | `string` | No | The maximum version of the compiler extension that the project requires to compile the program |
|
||||||
|
|
||||||
|
|
||||||
|
------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
# Naming a package
|
||||||
|
|
||||||
|
NCC Follows the same naming convention as Java's naming
|
||||||
|
convention. The purpose of naming a package this way is
|
||||||
|
to easily create a "Name" of the package, this string
|
||||||
|
of information contains
|
||||||
|
|
||||||
|
- The developer/organization behind the package
|
||||||
|
- The package name itself
|
||||||
|
|
||||||
|
|
||||||
|
## Naming conventions
|
||||||
|
|
||||||
|
Package names are written in all lower-case due to the
|
||||||
|
fact that some operating systems treats file names
|
||||||
|
differently, for example on Linux `Aa.txt` and `aa.txt`
|
||||||
|
are two entirely different file names because of the
|
||||||
|
capitalization and on Windows it's treated as the same
|
||||||
|
file name.
|
||||||
|
|
||||||
|
Organizations or small developers use their domain name
|
||||||
|
in reverse to begin their package names, for example
|
||||||
|
`net.nosial.example` is a package named `example`
|
||||||
|
created by a programmer at `nosial.net`
|
||||||
|
|
||||||
|
Just like the Java naming convention, to avoid conflicts
|
||||||
|
of the same package name developers can use something
|
||||||
|
different, for example as pointed out in Java's package
|
||||||
|
naming convention developers can instead use something
|
||||||
|
like a region to name packages, for example
|
||||||
|
`net.nosial.region.example`
|
||||||
|
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
For Java's package naming conventions see
|
||||||
|
[Naming a Package](https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html)
|
||||||
|
from the Oracle's Java documentation resource, as the
|
||||||
|
same rules apply to NCC except for *some* illegal naming
|
||||||
|
conventions such as packages not being able to begin
|
||||||
|
with `int` or numbers
|
|
@ -1,94 +0,0 @@
|
||||||
# Building NCC from source
|
|
||||||
|
|
||||||
Building NCC from source is easy with very few requirements
|
|
||||||
to start building. At the moment ncc can only be debugged
|
|
||||||
or tested by building a redistributable source and
|
|
||||||
installing it.
|
|
||||||
|
|
||||||
## Requirements to build
|
|
||||||
|
|
||||||
- php8.0+
|
|
||||||
- php-mbstring
|
|
||||||
- php-ctype
|
|
||||||
- php-tokenizer *(or php-common)*
|
|
||||||
- make
|
|
||||||
- phpab
|
|
||||||
- tar *(optional)*
|
|
||||||
|
|
||||||
## Installing phpab
|
|
||||||
|
|
||||||
phpab is also known as [PHP Autoload Builder](https://github.com/theseer/Autoload),
|
|
||||||
phpab is an open source tool used for creating autoload
|
|
||||||
files, ncc needs this tool in order to generate it's
|
|
||||||
autoload files whenever there's any changes to its source
|
|
||||||
code.
|
|
||||||
|
|
||||||
This tool is only required for building and or creating a
|
|
||||||
redistributable package of ncc. This component is not
|
|
||||||
required to be installed to use ncc.
|
|
||||||
|
|
||||||
for some components that require static loading, ncc will
|
|
||||||
automatically load it using it's own
|
|
||||||
[autoloader](../src/autoload/autoload.php)
|
|
||||||
|
|
||||||
The recommended way to install phpab is by using [phive](https://phar.io/),
|
|
||||||
if you don't have phive installed you can install it by
|
|
||||||
running these commands in your terminal (from the official documentation)
|
|
||||||
|
|
||||||
```shell
|
|
||||||
wget -O phive.phar https://phar.io/releases/phive.phar
|
|
||||||
wget -O phive.phar.asc https://phar.io/releases/phive.phar.asc
|
|
||||||
gpg --keyserver hkps://keys.openpgp.org --recv-keys 0x9D8A98B29B2D5D79
|
|
||||||
gpg --verify phive.phar.asc phive.phar
|
|
||||||
chmod +x phive.phar
|
|
||||||
sudo mv phive.phar /usr/local/bin/phive
|
|
||||||
```
|
|
||||||
|
|
||||||
Once phive is installed, you can run the final command to
|
|
||||||
install phpab
|
|
||||||
```shell
|
|
||||||
phive install phpab
|
|
||||||
```
|
|
||||||
|
|
||||||
**Note:** Optionally, you may want to have `phab` available in your
|
|
||||||
`$PATH`, this can be done with this command. *(Replace `x.xx.x` with your
|
|
||||||
version number)*
|
|
||||||
|
|
||||||
```shell
|
|
||||||
ln -s /home/user/.phive/phars/phpab-x.xx.x.phar /usr/bin/phpab
|
|
||||||
```
|
|
||||||
|
|
||||||
## Building NCC
|
|
||||||
|
|
||||||
First, navigate to the main directory of NCC's source code
|
|
||||||
where the [Makefile](../Makefile) is present. If you
|
|
||||||
already attempted to or had built ncc before, it's
|
|
||||||
recommended to use `make clean` before building.
|
|
||||||
|
|
||||||
|
|
||||||
### Redist
|
|
||||||
|
|
||||||
Running `redist` from the Makefile will generate all the
|
|
||||||
required autoloaders for ncc and move all the required
|
|
||||||
files into one redistributable source folder under a
|
|
||||||
directory called `build/src`
|
|
||||||
|
|
||||||
```shell
|
|
||||||
make redist
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
### Tar
|
|
||||||
|
|
||||||
Running `tar` will run redist before packaging the
|
|
||||||
redistributable source into a tar.gz file that can
|
|
||||||
be distributed to other machines, this process is not
|
|
||||||
a requirement.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
make tar
|
|
||||||
```
|
|
||||||
|
|
||||||
Once you have a populated `build/src` folder, you can
|
|
||||||
simply run execute the `installer` file to install your
|
|
||||||
build of ncc onto the running machine.
|
|
|
@ -1,43 +0,0 @@
|
||||||
# Naming a package
|
|
||||||
|
|
||||||
**Updated on Tuesday, July 26, 2022**
|
|
||||||
|
|
||||||
NCC Follows the same naming convention as Java's naming
|
|
||||||
convention. The purpose of naming a package this way is
|
|
||||||
to easily create a "Name" of the package, this string
|
|
||||||
of information contains
|
|
||||||
|
|
||||||
- The developer/organization behind the package
|
|
||||||
- The package name itself
|
|
||||||
|
|
||||||
|
|
||||||
# Naming conventions
|
|
||||||
|
|
||||||
Package names are written in all lower-case due to the
|
|
||||||
fact that some operating systems treats file names
|
|
||||||
differently, for example on Linux `Aa.txt` and `aa.txt`
|
|
||||||
are two entirely different file names because of the
|
|
||||||
capitalization and on Windows it's treated as the same
|
|
||||||
file name.
|
|
||||||
|
|
||||||
Organizations or small developers use their domain name
|
|
||||||
in reverse to begin their package names, for example
|
|
||||||
`net.nosial.example` is a package named `example`
|
|
||||||
created by a programmer at `nosial.net`
|
|
||||||
|
|
||||||
Just like the Java naming convention, to avoid conflicts
|
|
||||||
of the same package name developers can use something
|
|
||||||
different, for example as pointed out in Java's package
|
|
||||||
naming convention developers can instead use something
|
|
||||||
like a region to name packages, for example
|
|
||||||
`net.nosial.region.example`
|
|
||||||
|
|
||||||
|
|
||||||
# References
|
|
||||||
|
|
||||||
For Java's package naming conventions see
|
|
||||||
[Naming a Package](https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html)
|
|
||||||
from the Oracle's Java documentation resource, as the
|
|
||||||
same rules apply to NCC except for *some* illegal naming
|
|
||||||
conventions such as packages not being able to begin
|
|
||||||
with `int` or numbers
|
|
|
@ -1,279 +0,0 @@
|
||||||
# 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
|
|
||||||
}
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
Loading…
Add table
Reference in a new issue