diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 1679a58..53f20b1 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -33,6 +33,7 @@ basic usage, standards, and much more. * [Creating a new project (create)](#creating-a-new-project-create) * [Applying Templates (template)](#applying-templates-template) * [phpcli template](#phpcli-template) + * [phplib template](#phplib-template) * [Package Management (package or pkg)](#package-management-package-or-pkg) * [Listing Installed Packages (list)](#listing-installed-packages-list) * [Installing Packages (install)](#installing-packages-install) @@ -577,7 +578,7 @@ build/release/com.example.cli_program.ncc To test your program, you can run `ncc exec` on the compiled binary package ```shell -$ ncc exec --package build/release/com.example.cli_program.ncc +$ ncc exec --package MyCommandLineProgram/build/release/com.example.cli_program.ncc Hello World from com.example.cli_program! ``` @@ -599,10 +600,349 @@ build/release/MyCommandLineProgram Now you may directly run the program without the need of `ncc exec` ```shell -$ build/release/MyCommandLineProgram +$ MyCommandLineProgram/build/release/MyCommandLineProgram Hello World from com.example.cli_program! ``` +#### phplib template + +The phplib template is a template for creating a library project, allowing you to create a library with ease similar to +creating a CLI program, this section will guide you through how to create a library for your program and how to use it +as a dependency in another project. This section will use the previous `phpcli` template as a base for creating a library +to use in a CLI program. + +First, let's begin by creating a new project. + +```shell +$ ncc project create -n MyLibrary --pkg com.example.library --ext php +No path specified, using 'MyLibrary' +Project successfully created in 'MyLibrary' +Modify the project configuration in 'MyLibrary/project.json' +```` + +Next, let's apply the `phplib` template to the project. + +```shell +$ ncc project template -p MyLibrary -n phplib +Template successfully applied to project in 'MyLibrary' +``` + +Similarly to phpcli, additional files will be created for your project + +```shell +$ tree MyLibrary +MyLibrary/ +├── Makefile +├── project.json +└── src + └── MyLibrary + └── MyLibrary.php +``` + +This is a blank library, you can write your code however you want, but for this example we are going to demonstrate +a function call with this template to show how it works, first we'll modify the `MyLibrary.php` file to add a function +that returns a string. + +```php + require 'ncc'; +php > import('com.example.library'); +php > +php > $my_library = new \MyLibrary\MyLibrary(); +php > echo $my_library->getName('John'); +Hello John! +``` + +But libraries are usually used by other programs, so let's go back to our `MyCommandLineProgram` project and use the +library we just created. If you don't have the project, you can create it by following the steps in the +[phpcli template](#phpcli-template) section. + +First, we'll need to add the library as a dependency to the project, this can be done by editing the `project.json` in +the `build` section by creating an array of dependencies you need, a dependency looks something like this once it's +defined in `project.json` + +```json +{ + "dependencies": [ + { + "name": "com.example.library", + "version": "latest" + } + ] +} +``` + +Now if you hosted your project on a remote source, you may also define where ncc should get the package from if the +dependency is not available on the system. + +```json +{ + "dependencies": [ + { + "name": "com.example.library", + "version": "latest", + "source": "johndoe/example_library=latest@n64" + } + ] +} +``` + +overall, your project.json file should look something like this + +```json +{ + "project": { + "compiler": { + "extension": "php", + "minimum_version": "8.2", + "maximum_version": "8.0" + }, + "options": { + "create_symlink": true + } + }, + "assembly": { + "name": "MyCommandLineProgram", + "package": "com.example.cli_program", + "version": "1.0.0", + "uuid": "462a7f76-2cdc-428a-bbc6-c5feba614799" + }, + "build": { + "source_path": "src/MyCommandLineProgram", + "default_configuration": "release", + "main": "main_policy", + "define_constants": { + "ASSEMBLY_PACKAGE": "%ASSEMBLY.PACKAGE%", + "ASSEMBLY_VERSION": "%ASSEMBLY.VERSION%", + "ASSEMBLY_UID": "%ASSEMBLY.UID%" + }, + "dependencies": [ + { + "name": "com.example.library", + "version": "latest" + } + ], + "configurations": [ + { + "name": "release", + "build_type": "ncc", + "output": "build/release/%ASSEMBLY.PACKAGE%.ncc" + }, + { + "name": "debug", + "build_type": "ncc", + "output": "build/debug/%ASSEMBLY.PACKAGE%.ncc", + "define_constants": { + "DEBUG": "1" + } + }, + { + "name": "release_executable", + "build_type": "executable", + "output": "build/release/%ASSEMBLY.NAME%", + "options": { + "ncc_configuration": "release" + } + }, + { + "name": "debug_executable", + "build_type": "executable", + "output": "build/debug/%ASSEMBLY.NAME%", + "options": { + "ncc_configuration": "debug" + }, + "define_constants": { + "DEBUG": "1" + } + } + ] + }, + "execution_policies": [ + { + "name": "main_policy", + "runner": "php", + "execute": { + "working_directory": "%CWD%", + "silent": false, + "tty": true, + "timeout": null, + "idle_timeout": null, + "target": "main" + } + } + ] +} +``` + +Once you have defined the dependency on your program, let's modify the CLI program to use the library we created, we'll +modify the `src/MyCommandLineProgram/Program.php` file to use the library. + +```php +getName('John') . PHP_EOL); + + return 0; + } + } +``` + +Notice how we don't use the `import()` function to import the package, this is because ncc's import system will take a +look at the requirements that your package needs and automatically import them for you, this is useful for CLI programs +as it allows you to import packages without having to worry about whether the package is installed or not. This works +recursively, so if the package you imported also has a dependency, it will also be imported. + +Now let's build the program + +```shell +$ ncc build -p MyCommandLineProgram +Building project 'MyCommandLineProgram' +[ =========== ] 100% 2/2 remaining: 0 sec. elapsed: 0 sec. +build/release/com.example.cli_program.ncc +``` + +And let's test it! + +```shell +$ ncc exec --package MyCommandLineProgram/build/release/com.example.cli_program.ncc +Hello John! +``` + +Great! We successfully created a library and used it in a CLI program, this is just a simple example of how to use the +phplib template, you can use it however you want to create your own libraries and use them in your projects. + +If you'd like to create a build a static version of your package where all your dependencies are bundled into one file, +you can modify the project.json file to achieve this, more specifically the build configuration, in this case the +default build configuration we're using is called `release` so we'd need to adjust the configuration as so by adding the +`static` option to the configuration. + +```json +{ + "name": "release", + "build_type": "ncc", + "output": "build/release/%ASSEMBLY.PACKAGE%.ncc", + "options": { + "static": true + } +} +``` + +Now let's build the program again and test it + +```shell +$ ncc build -p MyCommandLineProgram +Building project 'MyCommandLineProgram' +[ =========== ] 100% 2/2 remaining: 0 sec. elapsed: 0 sec. +$ ncc exec --package MyCommandLineProgram/build/release/com.example.cli_program.ncc +Hello John! +``` + +And if you'd like to confirm if the dependencies are actually bundled into your program, you may ues the package +inspection command to view its headers, inside it you'll notice the components for `MyLibrary` being bundled into the +package. + +```shell +$ ncc ins -p MyCommandLineProgram/build/release/com.example.cli_program.ncc headers +headers +1937008233: '2.0' +1936941414: + - static_dependencies +1869898597: + '@1835365473': '0:137' + '@1634956133': '137:114' + '@1702389091:main_policy': '251:868' + '@1668246896:src/MyCommandLineProgram/Program.php': '1119:2996' + '@1668047219:MyCommandLineProgram\Program': '1119:2996' + '@1684369509:com.example.library': '4115:40' + '@1668246896:src/MyLibrary.php': '4155:1366' + '@1668047219:MyLibrary\MyLibrary': '4155:1366 +``` + +You may uninstall the package `com.example.library` from the system and try to run the program again, you'll notice that +the program will still run without any issues, this is because the package is bundled into the program itself. + +```shell +$ sudo ncc package uninstall -p com.example.library -y +Uninstalling package com.example.library=1.0.0 +Uninstalled 1 packages + +$ ncc exec --package MyCommandLineProgram/build/release/com.example.cli_program.ncc +Hello John! +``` + +And that's the magic that ncc does for you, it allows you to create libraries and bundle them into your programs without +having to worry about whether the library is installed or not, and with its import system you no longer have to worry +about autoloaders or anything like that, ncc will take care of that for you. This is what composer cannot do, composer +can only install packages onto your project directory, but it cannot bundle them into your programs if you wish to +have an easy way to distribute your project to other people, this is where ncc shines. ## Package Management (package or pkg) @@ -625,6 +965,7 @@ $ ncc package list Total: 4 packages ``` + ### Installing Packages (install) To install a package, you can use the `package install` command, this command will install the specified package and