2022-05-24 20:32:15 -04:00
|
|
|
# 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
|
|
|
|
|
2023-01-28 07:10:22 -05:00
|
|
|
<!-- 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 -->
|
2022-05-24 20:32:15 -04:00
|
|
|
|
2023-01-28 07:10:22 -05:00
|
|
|
## Introduction
|
2022-05-24 20:32:15 -04:00
|
|
|
|
|
|
|
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/),
|
2023-01-28 07:10:22 -05:00
|
|
|
[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
|