From d65795fcb54a073946f90effd2b542ff3b1595b9 Mon Sep 17 00:00:00 2001 From: Netkas Date: Sat, 28 Jan 2023 07:10:22 -0500 Subject: [PATCH] Refactored documentation into DOCUMENTATION.md --- DOCUMENTATION.md | 333 +++++++++++++++++- docs/building_ncc.md | 94 ----- docs/package_name.md | 43 --- .../project_configuration/execution_policy.md | 279 --------------- 4 files changed, 325 insertions(+), 424 deletions(-) delete mode 100644 docs/building_ncc.md delete mode 100644 docs/package_name.md delete mode 100644 docs/project_configuration/execution_policy.md diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index d8f9515..f19e8da 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -5,14 +5,31 @@ NCC, from basic installation, basic usage, standards and much more. ## Table of contents - - Introduction - - What is NCC? - - Advantages over other software - ------------------------------------------------------------------------------------- + +* [NCC Documentation](#ncc-documentation) + * [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) + - -# Introduction +## Introduction 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 @@ -31,4 +48,304 @@ NCC can make the process of building your code into a redistributable package mu more efficient by treating each building block of your project as a component that is interconnected in your environment instead of the more popular route taken by package/dependency managers such as [composer](https://getcomposer.org/), -[npm](https://www.npmjs.com/) or [pypi (or pip)](https://pypi.org/). \ No newline at end of file +[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 \ No newline at end of file diff --git a/docs/building_ncc.md b/docs/building_ncc.md deleted file mode 100644 index 2d3b6f6..0000000 --- a/docs/building_ncc.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/docs/package_name.md b/docs/package_name.md deleted file mode 100644 index 0b4586e..0000000 --- a/docs/package_name.md +++ /dev/null @@ -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 \ No newline at end of file diff --git a/docs/project_configuration/execution_policy.md b/docs/project_configuration/execution_policy.md deleted file mode 100644 index db304c2..0000000 --- a/docs/project_configuration/execution_policy.md +++ /dev/null @@ -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 - - -* [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) - - - -## 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 - } - } - ] -} -``` \ No newline at end of file