Enhancing the project builder and build process 🍫

What's Changed

Maven POM

Introduced a new profile called lint
Refactored and improved several plugins configurations
Changed the output path for generated Javadocs
Configured the reporting environments
Added several user properties that could be changed

Make

Refactored and enhanced the Make files on building the project
Added make directory that contains all neccessary Make files
Introduced new experimental custom flags that can activate specific option with ease
Refactored the Makefile in project root directory

Others

Added several new entries on MANIFEST.MF
Changed all values on MANIFEST.MF to refer to Maven POM's properties
Updated and improved Make's help messages and default rule

Todo

[x] Refactor the programs on retrieving and updating the properties files | #97
[x] Update the properties files at main resources directory to ensure the project uses the correct version and other properties | #97

Description

Maven POM

The Maven POM section outlines changes related to the project's Maven configuration. These include introducing a new profile called lint, refining plugin configurations, adjusting the Javadoc output path, configuring reporting environments, and adding user properties that offer customization options.

Profiles

Profile	Description	Utilized By
`lint`	Enables and invokes the linter	`maven-compiler-plugin`, `maven-javadoc-plugin`
`include-src`	Generates another JAR file containing source files only	`maven-source-plugin`

User Properties

Property	Description	Type	Default
`jdkVersion`	Specifies the version of JDK to be used for	integer	11
`sourceJdk`	Specifies the source code's version	integer	`${jdkVersion}`
`targetJdk`	Specifies the target of Java SE release	integer	`${jdkVersion}`
`verbose`	Enables the verbose output	boolean	false
`quiet`	Enables quiet or silent mode during javadoc generation	boolean	false
`debug`	Enables debug mode	boolean	false
`_encoding`	Specifies characters encoding used by source files	string	UTF-8
`minmemory`	Sets the initial or minimum size of the heap	bytes + [k\|m\|g]	32m
`maxmemory`	Specifies the maximum size of the heap	bytes + [k\|m\|g]	64m

Make

In the Make section, you'll find details about changes made to the project's Make files and build process. This involves refactoring and improving Make file configurations, introducing a make directory containing essential Make files, creating experimental custom flags for easier option activation, and refining the project's main Makefile.

This changes also improved Make on retrieving all necessary Java commands. This is an important things, so make sure users has Java Development Kit (JDK) installed correctly. First try, it will checks the definition of JAVA_HOME environment and takes all necessary commands inside bin directory (i.e., it will be $JAVA_HOME/bin). If the first try failed, on second try it will checks necessary commands using type command, returning an error if all tries failed.

[!NOTE]
The first try may failed due to undefined JAVA_HOME on system environment. Users can check definition of this environment using this command:
printenv | grep JAVA_HOME

Usage

make <TARGET>... [[OPTION=<value>] | [CUSTOM_FLAGS]]...

Targets

Target	Description	Depends
`compile`	Compiles all source files in this project	None
`package`	Generates a JAR file containing compiled classes files	`compile`
`build-docs`	Generates HTML-based documentations	None
`clean`	Cleans the working directory thoroughly	None
`cleanbin`	Cleans all compiled classes files only	None
`cleandocs`	Cleans all generated HTML-based documentations	None
`help`	Prints and displays the help message	None

Options and User Properties

Name	Description	Type	Default	Utilized By
`LINT`	Enables and invokes the linter during build process	boolean	false	`compile`, `build-docs`
`INCLUDE_SRC`	Enables ability on `package` target rule to generate another JAR file containing only source files	boolean	false	`package`
`VERBOSE`	Enables verbose output	boolean	false	All targets
---	---	---	---	---
`FLAGS`	Specifies additional flags to specific target	string	None	All targets
`ENCODING`	Specifies characters encoding used by source files	string	UTF-8	`compile`, `build-docs`
`SOURCE_JDK`	Specifies the source code's version	integer	11	`compile`
`TARGET_JDK`	Specifies the target Java SE release	integer	11	`compile`
`MIN_MEMORY`	Sets the initial or minimum size of the heap	bytes + [k\|m\|g]	32m	`compile`, `build-docs`
`MAX_MEMORY`	Specifies the maximum size of the heap	bytes + [k\|m\|g]	64m	`compile`, `build-docs`

[!WARNING]
Please be cautious when using FLAGS option, it will force all specified targets to use the flags, which may lead to unexpected behaviors. It is recommended to use only one target when using this option.

Custom Flags

In these changes, we have introduced a new set of activator options called "Custom Flags". These custom flags allow users to easily activate or deactivate specific options. The custom flags simplify the process of enabling options because they omit the need for specifying option values. Additionally, their activation process is consistent with Maven's profiles. Here is a list of Make's custom flags:

Flag	Description	Alternative
`.lint`	Activates and invokes the linter during build process	`LINT`
`.include-src`	Enables the ability of `package` target rule to generate another JAR file containing only source files	`INCLUDE_SRC`
`.verbose`	Enables verbose output	`VERBOSE`

[!WARNING]
Please be cautious when using those custom flags, as they are experimental and may lead to unexpected behaviors and errors. It is recommended to use the <FLAGS>=<value> format for a more reliable and predictable experience.

⛔ Disadvantages

When using these custom flags as the first target or as standalone rules, they will override the default rule (top rule). Make will attempt to treat the first argument (the custom flag) as a target rule and execute it. In such cases, Make may not build anything, resulting in no actions being taken, as the first argument is not actually a target rule.

For clarity, here is the example command:
make .lint
This code won't do anything unless there is an actual targets on ahead or behind it.

Others

It covers additions to MANIFEST.MF, where several new entries have been included. Additionally, all values in MANIFEST.MF have been updated to reference properties defined in the Maven POM.

We have redesigned the help message, providing more comprehensive information about Make's targets and options. There are two types of help messages available: one with ANSI color codes for enhanced readability and the other in its original version without ANSI color codes. To deactivate ANSI color codes i.e., use other help message that doesn't have ANSI color codes, simply define the RAW or NOCC variable with a value of true on the command line. For instance:

For one-time usage:
```
make [help] [RAW=true | NOCC=true]
```
For continuous usage:
```
export [RAW=true | NOCC=true] && make [help]
```
By using this instance, users don't need to specify the variable again on later.
If users wish to reactivate ANSI color codes, simply unset the variable.
```
unset [RAW | NOCC]
```
Or assign the variable to anything other than true (including an empty string).
```
RAW=foo  # Reassign with another value
# Or use an empty string
RAW=
```

mitsuki31 / jmatrix