From b530376af4538909c6dc55859171d9a59920a095 Mon Sep 17 00:00:00 2001 From: Netkas Date: Sat, 28 Jan 2023 07:35:03 -0500 Subject: [PATCH] Reformatted DOCUMENTATION.md --- DOCUMENTATION.md | 243 +++++++++++++++++------------------------------ 1 file changed, 85 insertions(+), 158 deletions(-) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index f19e8da..21ef75e 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -31,34 +31,28 @@ NCC, from basic installation, basic usage, standards and much more. ## 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. +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 (*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/). +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. +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 @@ -72,23 +66,18 @@ installing it. ## 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. +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 +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) +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) +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 @@ -99,39 +88,34 @@ 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 +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 +**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 +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. - +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` +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 @@ -140,151 +124,108 @@ 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. +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. +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. +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. +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. +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. +**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 +`--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` +`--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 +`--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. +`--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. +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. + - 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. +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 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. +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*) +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 +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. +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. +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. +**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. +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. +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. +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. +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 +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 | @@ -295,8 +236,7 @@ to the compiler, and more. ### project.compiler -The `project.compiler` field contains information about -the compiler extension that the project uses to compile +The `project.compiler` field contains information about the compiler extension that the project uses to compile the program. | Name | Type | Required | Description | @@ -310,10 +250,8 @@ 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 +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 @@ -321,31 +259,20 @@ of information contains ## 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. +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` +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` +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 +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