ncc/DOCUMENTATION.md

# NCC Documentation

This document serves the purpose of presenting the documentation for using/developing
NCC, from basic installation, basic usage, standards and much more.

## Table of contents

<!-- TOC -->
* [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)
<!-- TOC -->

## 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
to be used with NCC. 

## What is NCC?

NCC (*Acronym for **N**osial **C**ode **C**ompiler*) is a multi-purpose compiler,
package manager and toolkit. Allowing projects to be managed and built more easily
without having to mess with all the traditional tools that comes with your language
of choice. Right now NCC only supports PHP as it's written in PHP but extensions
for other languages/frameworks can be built into the software in the future when
the need comes for it.

NCC can make the process of building your code into a redistributable package much
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/).


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

# 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