278 lines
No EOL
12 KiB
Markdown
278 lines
No EOL
12 KiB
Markdown
# 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 its 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/local/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 |