cmake: Update documenation

docs/tutorials/cmake/commands.md

@@ -8,52 +8,74 @@ and the new one using CMake.
 
 The Old-Makefiles commands are run in the root folder of Kamailio source code:
 
-```
+``` bash
 cd /path/to/kamailio
 ```
 
-The CMake commands have to be run after:
+## You can build Kamailio using either of the following methods
 
-```
+### Method 1: Using CMake and Make
+
+_**Note:**_ `make` should be called in **the build directory.**
+
+_**Note:**_ if `cmake` is in the example command, it usually has to be followed by `make` to perform the compilation or installation.
+
+``` bash
 cd /path/to/kamailio
 mkdir build
 cd build
+cmake .. [options ...]  # Configuration phase
+make [target]           # Build
+make install            # Installation
+```
+
+### Method 2: Using CMake for Configuration, Build, and Install
+
+Allow builds and install using the appropriate build system (`Unix Makefiles` or `Ninja`):
+
+_**Note:**_ All `cmake` commands should be called in `kamailio` **root directory.**
+
+``` bash
+cd path/to/kamailio
+cmake -S . -B build_folder [options ...]  # Configuration phase
+cmake --build build_folder  [-t target]   # Build
+cmake --install build_folder              # Installation
 ```
 
-Also, if `cmake` is in the example command, it usually has to be followed by
-`make` to perform the compilation.
-
-Legend for the table:
-
-  - `OM` - Old-Makefiles
-  - `CM` - CMake
-
-| Type   | Description / Command |
-| :---   | :--- |
-| `---`  | Generate config files for the build system |
-| `OM`   | `make cfg` |
-| `CM`   | `cmake ..` |
-| `---`  | Specify installation path prefix |
-| `OM`   | `make PREFIX=/tmp/kamailio-dev cfg` |
-| `CM`   | `cmake -DCMAKE_INSTALL_PREFIX=/tmp/kamailio-dev ..` |
-| `---`  | Specify additional modules to be included in compilation |
-| `OM`   | `make include_modules="app_lua db_mysql" cfg` |
-| `CM`   | `cmake -DINCLUDE_MODULES="app_lua db_mysql" ..` |
-| `---`  | Specify modules to be excluded from compilation |
-| `OM`   | `make exclude_modules="app_lua db_mysql" cfg` |
-| `CM`   | `cmake -DEXCLUDE_MODULES="app_lua db_mysql" ..` |
-| `---`  | Compile `kamailio` binary (the core) |
-| `OM`   | `make` |
-| `CM`   | `make kamailio` |
-| `---`  | Compile everything (core and modules) |
-| `OM`   | `make all` |
-| `CM`   | `make` |
-| `---`  | Compile `acc` modules (substitute with any other module name) |
-| `OM`   | `make modules modules=src/modules/acc` |
-| `CM`   | `make acc` |
-| `---`  | Compile with verbose output (quiet off) |
-| `OM`   | `make Q=0` |
-| `CM`   | `make VERBOSE=on` |
-| `---`  | Specify the compiler (example with `clang`) |
-| `OM`   | `make CC=clang` |
-| `CM`   | `cmake -DCMAKE_C_COMPILER="clang" ..` |
+## Configuration comparison: Old Makefiles vs. CMake
+
+| Description / Command                                      | Old Makefiles Command                          | CMake Command                                      |
+|-----------------------------------------------------------|------------------------------------------------|---------------------------------------------------|
+| Generate configuration files for the build system         | `make cfg`                                    | `cmake ..`                                       |
+| Specify installation path prefix                           | `make PREFIX=/tmp/kamailio-dev cfg`          | `cmake -DCMAKE_INSTALL_PREFIX=/tmp/kamailio-dev ..` |
+| Specify additional modules to be included in compilation   | `make include_modules="app_lua db_mysql" cfg`| `cmake -DINCLUDE_MODULES="app_lua db_mysql" ..` |
+| Specify modules to be excluded from compilation            | `make exclude_modules="app_lua db_mysql" cfg`| `cmake -DEXCLUDE_MODULES="app_lua db_mysql" ..` |
+| Specify the compiler (example with `clang`)               | `make CC=clang`                               | `cmake -DCMAKE_C_COMPILER="clang" ..`             |
+| Provide extra compiler and linker options/flags _**See note**_| | `LDFLAGS="-Wl,-z,relro" CFLAGS="-Wformat -Werror=format-security" cmake ..`|
+
+All these options can and **SHOULD** be combined in a single `CMake` command.
+
+_**Note:**_ Be sure to run this the **first** time you run the CMake configuration phase. Subsquent calls have the corresponding CMake variables used as cached already and therefore do no use the provided ones to initialize them. You can use `cmake --fresh ..` though, as if you were calling it the first time.
+
+## Provided targets comparison: Old Makefiles vs. CMake
+
+| Description / Command | Old-Makefiles | CMake |
+| -- | -- | -- |
+| Compile everything (core and modules) | `make all` | `make` \| `make all`|
+| Compile `kamailio` binary (the core) | `make` | `make kamailio` |
+| Compile `acc` modules (substitute with any other module name) | `make modules modules=src/modules/acc` | `make acc` |
+| Compile `acc` documentation (substitute with any other module name) | `make modules-readme modules=src/modules/acc` | `make acc_doc` |
+| Compiles all modules docs (both html and txt) (Requires `BUILD_DOC` option to be enabled Default=`ON`) | `make modules-readme` | `make kamailio_docs`|
+| Compile with verbose output (quiet off) | `make [target] Q=0` | `make [target] VERBOSE=1\|on` |
+| Generate the DB Schemas for the xml files | `make dbschema`| `make dbschema` |
+| Generate specific DB schema (replace `mysql` with the name of database as found in the `utils/kamctl/`) _**See note**_ | -- | `make dbschema_mysql` |
+| **Clean targets**|||
+| Clean everything build | `make distclean`| `make clean`|
+| Clean dbschema files | -- | `make dbschema_clean` |
+| Uninstall everything (requires that it was installed with `make install`)| -- | `make uninstall` |
+| **Install targets** |||
+| Install all | `make install` | `make install` |
+| Install only docs | -- | `make install_kamailio_docs` |
+| Install only kamailio utils (`kamctl`,`kamdbctl` and their config files)| -- | `make install_kamailio_utils` |
+
+_**Note:**_ To produce the `xhttp_pi` schemas use both `make dbschema_pi_framework_mod` and `make dbschema_pi_framework_table`.

docs/tutorials/cmake/index.md

@@ -6,3 +6,5 @@
 * [Customizing The Building Kamailio With CMake Options](custom.md)
 
 * [Corresponding Old-Makefiles And CMake Commands](commands.md)
+
+* [Available Targets](targets.md)

docs/tutorials/cmake/targets.md

@@ -0,0 +1,36 @@
+# Kamailio Available Targets
+
+This document lists all available targets for Kamailio with CMake, providing a brief description of each.
+
+Use `make target_name` to execute the desired target in the build folder.
+
+## Build Targets
+
+- **all**: Builds all components (core and modules) of Kamailio.
+- **install**: Installs the built components to the specified directory.
+- **clean**: Cleans up the build directory by removing all generated files.
+- **kamailio**: Builds the Kamailio core.
+- **modules**: Builds all the enabled modules.
+  + **module_name**: Compile module with name `module_name`, ie `make acc` for `acc` module.
+
+- **kamctl**: Builds the `kamctl` utility, which is used for managing Kamailio configurations.
+- **kamdbctl**: Builds the `kamdbctl` utility, which is used for managing Kamailio databases.
+
+## Install Targets
+
+- **install**: Installs the built components to the specified directory.
+- **uninstall**: Uninstalls the previously installed components.
+- **install-kamailio-utils**: Installs the Kamailio utilities (`kamctl` and `kamdbctl`) and kamailio congiguration files.
+  + **install-kamailio-utils-bin**: Installs the Kamailio utilities binaries (kamctl kamdbctl).
+  + **install-kamailio-utils-cfg**: Installs the Kamailio utilities configuration files (kamctlrc kamailio.cfg).
+- **install_kamailio_docs**: Installs the Kamailio documentation.
+
+## Documentation Targets
+
+- **kamailio_docs**: Generates the documentation for Kamailio and it's modules.
+  + **[module_name]_doc**: Generates the documentation for a specific module. Replace `module_name` with the actual module name.
+    * **[module_name]_txt**: Generates the documentation for a specific module in text format.
+    * **[module_name]_html**: Generates the documentation for a specific module in HTML format.
+    * **[module_name]_README**: Generates the documentation for a specific module in README format in the source code tree of each module.
+
+- **man**: Creates the manual pages for Kamailio commands.