Nosial/ncc
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 11 Packages Wiki Activity Actions

1.0.0 Alpha Release #59

Merged
netkas merged 213 commits from v1.0.0_alpha into master 2023-01-29 23:27:58 +00:00
Conversation 2 Commits 213 Files changed 297 +85 -158
1 changed files with 85 additions and 158 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit b530376af4 - Show all commits

243
DOCUMENTATION.md
View file

@ -31,34 +31,28 @@ NCC, from basic installation, basic usage, standards and much more.
## 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
use it in your own projects or use it to run and build other projects that are designed it to run and build other projects that are designed to be used with NCC.
to be used with NCC.
## What is NCC? ## What is NCC?
NCC (*Acronym for **N**osial **C**ode **C**ompiler*) is a multi-purpose compiler, NCC (*Acronym for **N**osial **C**ode **C**ompiler*) is a multi-purpose compiler, package manager and toolkit. Allowing
package manager and toolkit. Allowing projects to be managed and built more easily projects to be managed and built more easily without having to mess with all the traditional tools that comes with your
without having to mess with all the traditional tools that comes with your language language of choice. Right now NCC only supports PHP as it's written in PHP but extensions for other languages/frameworks
of choice. Right now NCC only supports PHP as it's written in PHP but extensions can be built into the software in the future when the need comes for it.
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 NCC can make the process of building your code into a redistributable package much more efficient by treating each
more efficient by treating each building block of your project as a component that building block of your project as a component that is interconnected in your environment instead of the more popular
is interconnected in your environment instead of the more popular route taken by route taken by package/dependency managers such as [composer](https://getcomposer.org/),[npm](https://www.npmjs.com/) or
package/dependency managers such as [composer](https://getcomposer.org/), [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
Building NCC from source is easy with very few requirements Building NCC from source is easy with very few requirements to start building. At the moment ncc can only be debugged or
to start building. At the moment ncc can only be debugged tested by building a redistributable source and installing it.
or tested by building a redistributable source and
installing it.
## Requirements to build ## Requirements to build
@ -72,23 +66,18 @@ installing it.
## Installing phpab ## Installing phpab
phpab is also known as [PHP Autoload Builder](https://github.com/theseer/Autoload), phpab is also known as [PHP Autoload Builder](https://github.com/theseer/Autoload), phpab is an open source tool used
phpab is an open source tool used for creating autoload for creating autoload files, ncc needs this tool in order to generate it's autoload files whenever there's any changes
files, ncc needs this tool in order to generate it's to its source code.
autoload files whenever there's any changes to its source
code.
This tool is only required for building and or creating a This tool is only required for building and or creating a redistributable package of ncc. This component is not
redistributable package of ncc. This component is not
required to be installed to use ncc. required to be installed to use ncc.
for some components that require static loading, ncc will for some components that require static loading, ncc will automatically load it using its own
automatically load it using it's own [autoloader](src/autoload/autoload.php)
[autoloader](../src/autoload/autoload.php)
The recommended way to install phpab is by using [phive](https://phar.io/), The recommended way to install phpab is by using [phive](https://phar.io/), if you don't have phive installed you can
if you don't have phive installed you can install it by install it by running these commands in your terminal (from the official documentation)
running these commands in your terminal (from the official documentation)
```shell ```shell
wget -O phive.phar https://phar.io/releases/phive.phar wget -O phive.phar https://phar.io/releases/phive.phar
@ -99,39 +88,34 @@ chmod +x phive.phar
sudo mv phive.phar /usr/local/bin/phive sudo mv phive.phar /usr/local/bin/phive
``` ```
Once phive is installed, you can run the final command to Once phive is installed, you can run the final command to install phpab
install phpab
```shell ```shell
sudo phive install phpab --global sudo phive install phpab --global
``` ```
or you can run this command to install it locally or you can run this command to install it locally
```shell ```shell
phive install phpab phive install phpab
``` ```
**Note:** Optionally, you may want to have `phab` available in your **Note:** Optionally, you may want to have `phab` available in your `$PATH`, this can be done with this command.
`$PATH`, this can be done with this command. *(Replace `x.xx.x` with your *(Replace `x.xx.x` with your version number)* this is if you installed it locally
version number)* this is if you installed it locally
```shell ```shell
ln -s /home/user/.phive/phars/phpab-x.xx.x.phar /usr/bin/phpab ln -s /home/user/.phive/phars/phpab-x.xx.x.phar /usr/local/bin/phpab
``` ```
## Building NCC ## Building NCC
First, navigate to the main directory of NCC's source code First, navigate to the main directory of NCC's source code where the [Makefile](Makefile) is present. If you
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.
already attempted to or had built ncc before, it's
recommended to use `make clean` before building.
### Redist ### Redist
Running `redist` from the Makefile will generate all the Running `redist` from the Makefile will generate all the required autoloader for ncc and move all the required files
required autoloader for ncc and move all the required into one redistributable source folder under a directory called `build/src`
files into one redistributable source folder under a
directory called `build/src`
```shell ```shell
make redist make redist
@ -140,151 +124,108 @@ make redist
### Tar ### Tar
Running `tar` will run redist before packaging the Running `tar` will run redist before packaging the redistributable source into a tar.gz file that can be distributed to
redistributable source into a tar.gz file that can other machines, this process is not a requirement.
be distributed to other machines, this process is not
a requirement.
```shell ```shell
make tar make tar
``` ```
Once you have a populated `build/src` folder, you can Once you have a populated `build/src` folder, you can simply run execute the `installer` file to install your build of
simply run execute the `installer` file to install your ncc onto the running machine.
build of ncc onto the running machine.
------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------
# Installing NCC # Installing NCC
Installing NCC is easy, you can either download the Installing NCC is easy, you can either download the redistributable source from the [releases](https://git.n64.cc/nosial/ncc/-/releases)
redistributable source from the [releases](https://git.n64.cc/nosial/ncc/-/releases) page or you can build it from source using the instructions above.
page or you can build it from source using the
instructions above.
Once you have the redistributable source, you can Once you have the redistributable source, you can simply run execute the `INSTALL` file to install ncc onto the running
simply run execute the `INSTALL` file to install machine.
ncc onto the running machine.
## Command line arguments ## Command line arguments
The installer accepts a few command line arguments The installer accepts a few command line arguments that can be used to customize the installation process.
that can be used to customize the installation
process.
`--help` Displays the help message `--help` Displays the help message
`--auto` Automatically installs ncc without asking for user input. `--auto` Automatically installs ncc without asking for user input.
**Note:** To install composer along with ncc, you must **Note:** To install composer along with ncc, you must also provide the `--install-composer` argument.
also provide the `--install-composer` argument.
`--install-composer` Installs composer along with ncc. `--install-composer` Installs composer along with ncc. By default, ncc will not install composer and during the
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
installation process you will be asked if you want to
install composer along-side ncc, this will not conflict
with any existing composer installation. with any existing composer installation.
`--install-dir` Specifies the directory where ncc will be `--install-dir` Specifies the directory where ncc will be installed to. By default, ncc will be installed to `/etc/ncc`
installed to. By default, ncc will be installed to `/etc/ncc`
`--bypass-cli-check` Bypasses the check in the installer `--bypass-cli-check` Bypasses the check in the installer that checks if the installer is being run from the command
that checks if the installer is being run from the command
line, this is useful if you want to install ncc from a script. line, this is useful if you want to install ncc from a script.
`--bypass-checksum` Bypasses the checksum check in the `--bypass-checksum` Bypasses the checksum check in the installer, this is useful if you made modifications to the
installer, this is useful if you made modifications to installation files and want to install a modified version of ncc.
the installation files and want to install a modified
version of ncc.
But this isn't recommended and the proper way to do this But this isn't recommended and the proper way to do this is to modify the source code and build ncc from source,
is to modify the source code and build ncc from source, the Makefile task will automatically rebuild the checksum file for you.
the Makefile task will automatically rebuild the checksum
file for you.
------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------
# Uninstalling NCC # Uninstalling NCC
Uninstalling NCC is easy, simply delete the directory - Uninstalling NCC is easy, simply delete the directory where ncc was installed to, by default this is `/etc/ncc`.
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.
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 # Projects
A project is a directory that contains all the source files A project is a directory that contains all the source files to your program, it's similar to a workspace in other IDEs.
to your program, it's similar to a workspace in Usually contains a `project.json` file which contains all the information about the project that ncc needs to know.
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 This can include the name of the program, the version of the program, the author of the program, the dependencies of the
of the program, the author of the program, the program, build configurations, and more.
dependencies of the program, build configurations,
and more.
This section will cover the basics of creating a This section will cover the basics of creating a project and managing it and the technical details of the `project.json`
project and managing it and the technical details file.
of the `project.json` file.
## Creating a project ## Creating a project
This is the first step in using ncc, you must create a This is the first step in using ncc, you must create a project before you can do anything else (*not really because you
project before you can do anything else (*not really can install packages without needing to create a project and run them directly, but you get the point*)
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 The NCC command-line tool provides a management command called `project` that can be used to create a new project
called `project` that can be used to create a new project
or to manage an existing project. or to manage an existing project.
```shell ```shell
ncc project create --package "com.example.program" --name "Example Program" ncc project create --package "com.example.program" --name "Example Program"
``` ```
This command will create a new project in the current This command will create a new project in the current directory, the `--package` argument specifies the package name of
directory, the `--package` argument specifies the the project, this is used to identify the project and to avoid conflicts with other projects that may have the same name.
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, The `--name` argument specifies the name of the project, this is used to display the name of the project in the project
this is used to display the name of the project in the manager and in the project settings. This doesn't have to be the same as the package name or unique.
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 **Note:** If the options are not provided, the command will prompt you for the package name and the project name.
will prompt you for the package name and the project name.
For more information about the project command, you can For more information about the project command, you can run `ncc project --help` to display the help message.
run `ncc project --help` to display the help message.
## project.json structure ## project.json structure
The `project.json` file is a JSON file that contains The `project.json` file is a JSON file that contains all the information about the project.
all the information about the project.
When a project is created, the `project.json` file is When a project is created, the `project.json` file is automatically created and populated with the default values, you
automatically created and populated with the default can modify this file to change the default values or to add more information about the project.
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` This section will go over the structure of the `project.json` file and what each field does.
file and what each field does.
### project ### project
The `project` field contains information about the project, The `project` field contains information about the project, such as what compiler extension to use, options to pass on
such as what compiler extension to use, options to pass on
to the compiler, and more. to the compiler, and more.
| Name | Type | Required | Description | | Name | Type | Required | Description |
@ -295,8 +236,7 @@ to the compiler, and more.
### project.compiler ### project.compiler
The `project.compiler` field contains information about The `project.compiler` field contains information about the compiler extension that the project uses to compile
the compiler extension that the project uses to compile
the program. the program.
| Name | Type | Required | Description | | Name | Type | Required | Description |
@ -310,10 +250,8 @@ the program.
# Naming a package # Naming a package
NCC Follows the same naming convention as Java's naming NCC Follows the same naming convention as Java's naming convention. The purpose of naming a package this way is
convention. The purpose of naming a package this way is to easily create a "Name" of the package, this string of information contains
to easily create a "Name" of the package, this string
of information contains
- The developer/organization behind the package - The developer/organization behind the package
- The package name itself - The package name itself
@ -321,31 +259,20 @@ of information contains
## Naming conventions ## Naming conventions
Package names are written in all lower-case due to the Package names are written in all lower-case due to the fact that some operating systems treats file names
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
differently, for example on Linux `Aa.txt` and `aa.txt` capitalization and on Windows it's treated as the same file name.
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 Organizations or small developers use their domain name in reverse to begin their package names, for example
in reverse to begin their package names, for example `net.nosial.example` is a package named `example` created by a programmer at `nosial.net`
`net.nosial.example` is a package named `example`
created by a programmer at `nosial.net`
Just like the Java naming convention, to avoid conflicts Just like the Java naming convention, to avoid conflicts of the same package name developers can use something
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
different, for example as pointed out in Java's package like a region to name packages, for example `net.nosial.region.example`
naming convention developers can instead use something
like a region to name packages, for example
`net.nosial.region.example`
## References ## References
For Java's package naming conventions see For Java's package naming conventions see [Naming a Package](https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html)
[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
from the Oracle's Java documentation resource, as the conventions such as packages not being able to begin with `int` or numbers
same rules apply to NCC except for *some* illegal naming
conventions such as packages not being able to begin
with `int` or numbers