refactor: refactor debugging tools

- change script for installing BMap like LibCmo although no one will use it.
- move package install command into respective cmake script.
- change BMap project layout

.gitignore

@@ -1,22 +1,24 @@
-# -------------------- Personal --------------------
+## ======== Personal ========
+# Ignore build resources
+out/
+build/
+install/
+extern/
+temp/
+
 # Ignore all possible test used Virtools files
 *.nmo
 *.cmo
 *.nms
 *.vmo
 
-# Ignore CMake generated version header
+# Ignore CMake generated stuff
-LibCmo/VTVersion.hpp
-
-# Ignore temporary Visual Studio files and folders
-temp/
-out/
 CMakeSettings.json
 
-# -------------------- VSCode --------------------
+## ======== VSCode ========
 .vscode/
 
-# -------------------- CMake --------------------
+## ======== CMake ========
 CMakeLists.txt.user
 CMakeCache.txt
 CMakeFiles
@@ -29,7 +31,7 @@ compile_commands.json
 CTestTestfile.cmake
 _deps
 
-# -------------------- Visual Studio --------------------
+## ======== Visual Studio ========
 ## Ignore Visual Studio temporary files, build results, and
 ## files generated by popular Visual Studio add-ons.
 ##

Assets/Tools/MeshConv/.gitignore

@@ -0,0 +1,18 @@
+## ======== Personal ========
+# Ignore test used 3d Object
+*.bin
+*.obj
+*.mtl
+
+## ======== Python ========
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+

Assets/Tools/MeshConv/.python-version

@@ -0,0 +1 @@
+3.11

Assets/Tools/MeshConv/README.md

@@ -0,0 +1,13 @@
+# MeshConv
+
+Build complete Wavefront OBJ file from separated data for debugging libcmo21.
+
+## Usage
+
+- Restore this project by Astral UV.
+- Save all mesh components into separate files in this directory.
+    * Vertex position as `VertexPosition.bin` for example.
+    * Vertex normal as `VertexNormal.bin` for example.
+    * Vertex UV as `VertexUV.bin` for example.
+    * Face indices as `FaceIndices.bin` for example.
+- Execute `uv run main.py -p VertexPosition.bin -n VertexNormal.bin -u VertexUV.bin -i FaceIndices.bin -o mesh.obj -m mesh.mtl` for example. It will utilize previous saved file to generate a Wavefront OBJ file `mesh.obj` and corresponding material file `mesh.mtl`. For the usage of these switches, please refer to the source code.

Assets/Tools/MeshConv/main.py

@@ -0,0 +1,178 @@
+import argparse
+import io
+import struct
+import typing
+import itertools
+from pathlib import Path
+from dataclasses import dataclass
+
+# region: Kernel
+
+T = typing.TypeVar('T')
+Vector = tuple[float, ...]
+Indices = tuple[int, ...]
+
+def get_file_length(fs: typing.BinaryIO) -> int:
+    """
+    Get the full length of given file in bytes.
+
+    :param fs: File stream for measuring.
+    :return: File length in bytes.
+    """
+    pos = fs.tell()
+    fs.seek(0, io.SEEK_END)
+    fsize = fs.tell()
+    fs.seek(pos, io.SEEK_SET)
+    return fsize
+
+def evaluate_count(filename: Path, unit_size: int) -> int:
+    """
+    Evaluate the count of items in given file.
+
+    :param filename: File name to evaluate.
+    :param unit_size: Size of each item in bytes.
+    :return: Count of items in given file.
+    """
+    with open(filename, 'rb') as fs:
+        file_size = get_file_length(fs)
+        count, modrem = divmod(file_size, unit_size)
+        if modrem != 0:
+            raise Exception("invalid file length")
+        return count
+
+def assert_file_size(fs: typing.BinaryIO, expected_size: int):
+    """
+    Check whether given file has expected size.
+
+    :param fs: File stream to check.
+    :param expected_size: Expected file size.
+    """
+    if expected_size != get_file_length(fs):
+            raise Exception("invalid file length")
+
+def read_f32s(filename: Path, count: int) -> tuple[float, ...]:
+    with open(filename, 'rb') as fs:
+        # construct class
+        cstruct = struct.Struct(f'<{count}f')
+        # assert file size
+        assert_file_size(fs, cstruct.size)
+        # read
+        return cstruct.unpack(fs.read(cstruct.size))
+
+def read_u16s(filename: Path, count: int) -> tuple[int, ...]:
+    with open(filename, 'rb') as fs:
+        # construct class
+        cstruct = struct.Struct(f'<{count}H')
+        # assert file size
+        assert_file_size(fs, cstruct.size)
+        # read
+        return cstruct.unpack(fs.read(cstruct.size))
+    
+def batched_tuple(full_list: tuple[T, ...], couple_count: int) -> tuple[tuple[T, ...], ...]:
+    """
+    Batch a tuple into a tuple of tuples.
+
+    This function will check whether given tuple can be batched without any remnants.
+    If it is, throw exception, otherwise return the batched tuple.
+
+    For example, given `('roses', 'red', 'violets', 'blue', 'sugar', 'sweet')`,
+    it will produce `(('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet'))`.
+
+    :param full_list: The tuple to batch.
+    :param couple_count: The count of items in each batch.
+    :return: The batched tuple.
+    """
+    # TODO: Replace the whole body with itertools.batched once we upgrade into Python 3.12
+    # return itertools.batched(full_list, couple_count, strict=True)
+    count, modrem = divmod(len(full_list), couple_count)
+    if modrem != 0:
+        raise Exception("invalid tuple length")
+    
+    return tuple(map(lambda x: tuple(full_list[x * couple_count:x * couple_count + couple_count]), range(count)))
+    
+def build_obj_file(filename: Path, vpos: tuple[Vector, ...], vnml: tuple[Vector, ...], vuv: tuple[Vector, ...], findices: tuple[Indices, ...]):
+    with open(filename, 'w', encoding='utf-8') as fs:
+        for v in vpos:
+            fs.write(f'v {v[0]} {v[1]} {v[2]}\n')
+        for v in vnml:
+            fs.write(f'vn {v[0]} {v[1]} {v[2]}\n')
+        for v in vuv:
+            fs.write(f'vt {v[0]} {v[1]}\n')
+        for f in findices:
+            fs.write(f'f {f[0] + 1}/{f[0] + 1}/{f[0] + 1} {f[1] + 1}/{f[1] + 1}/{f[1] + 1} {f[2] + 1}/{f[2] + 1}/{f[2] + 1}\n')
+        fs.write('g obj\n')
+
+# endregion
+
+# region Command Line Processor
+
+@dataclass
+class Cli:
+    """Command Line Arguments"""
+
+    in_vpos: Path
+    """The path to file storing vertex positions"""
+    in_vnml: Path
+    """The path to file storing vertex normals"""
+    in_vuv: Path
+    """The path to file storing vertex UVs"""
+    in_findices: Path
+    """The path to file storing face indices"""
+    out_obj: Path
+    """The path to output OBJ file"""
+    out_mtl: Path
+    """The path to output MTL file"""
+
+def parse() -> Cli:
+    # construct parser
+    parser = argparse.ArgumentParser(description='The mesh data combinator for libcmo21 debugging.')
+    parser.add_argument('-p', '--in-vpos', required=True, type=str, action='store', dest='in_vpos', metavar='vpos.bin',
+                        help='''The path to file storing vertex positions''')
+    parser.add_argument('-n', '--in-vnml', required=True, type=str, action='store', dest='in_vnml', metavar='vnml.bin',
+                        help='''The path to file storing vertex normals''')
+    parser.add_argument('-u', '--in-vuv', required=True, type=str, action='store', dest='in_vuv', metavar='vuv.bin',
+                        help='''The path to file storing vertex UVs''')
+    parser.add_argument('-i', '--in-findices', required=True, type=str, action='store', dest='in_findices', metavar='findices.bin',
+                        help='''The path to file storing face indices''')
+    parser.add_argument('-o', '--out-obj', required=True, type=str, action='store', dest='out_obj', metavar='mesh.obj',
+                        help='''The path to output OBJ file''')
+    parser.add_argument('-m', '--out-mtl', required=True, type=str, action='store', dest='out_mtl', metavar='mesh.mtl',
+                        help='''The path to output MTL file''')
+
+    # parse arg
+    args = parser.parse_args()
+    # return value
+    return Cli(
+        Path(args.in_vpos),
+        Path(args.in_vnml),
+        Path(args.in_vuv),
+        Path(args.in_findices),
+        Path(args.out_obj),
+        Path(args.out_mtl)
+    )
+
+
+# endregion
+
+def main():
+    # parse arguments
+    opts = parse()
+    
+    vertex_count = evaluate_count(opts.in_vpos, 3 * 4) # 3 float(4 bytes)
+    print(f'Vertex Count Evaluated: {vertex_count}')
+    vpos = batched_tuple(read_f32s(opts.in_vpos, 3 * vertex_count), 3)
+
+    vnml = batched_tuple(read_f32s(opts.in_vnml, 3 * vertex_count), 3)
+
+    vuv = batched_tuple(read_f32s(opts.in_vuv, 2 * vertex_count), 2)
+
+    face_count = evaluate_count(opts.in_findices, 3 * 2) # 3 WORD(2 bytes)
+    print(f'Face Count Evaluated: {face_count}')
+    findices = batched_tuple(read_u16s(opts.in_findices, 3 * face_count), 3)
+
+    build_obj_file(opts.out_obj, vpos, vnml, vuv, findices)
+    print('Done')
+    
+
+if __name__ == '__main__':
+    main()

Assets/Tools/MeshConv/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "mesh-conv"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []

Assets/Tools/MeshConv/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 2
+requires-python = ">=3.11"
+
+[[package]]
+name = "mesh-conv"
+version = "0.1.0"
+source = { virtual = "." }

Assets/Tools/README.md

@@ -0,0 +1,24 @@
+# Tools
+
+The developer need to know the loaded data whether is correct when testing LibCmo.
+So we create this folder and you can use Unvirt and the tools located in this folder to test the correction of loaded data.
+
+Unvirt can show the data of each CKObject, such as Texture, Mesh and etc. 
+For example, Unvirt can provide vertex's position, normal, UV, even the face's indices data for CKMesh. 
+You can use tools to broswer memory to get them, but you couldn't evaluate them how they shape a mesh. 
+This is the reason why this folder existed and in this README I will tell you how to debug the loaded data.
+
+## Memory Inspector
+
+I suggest you to use HxD to broswer memory, but if you have other softwares which you have been familiar with, use it freely.
+
+## CKTexture Debugging
+
+* Install [PixelViewer](https://github.com/carina-studio/PixelViewer) first.
+* Change profile to `BGRA_8888` (actually is little-endian RGBA8888, but I think the developer of PixelViewer get confused).
+* The image resolution can be gotten from Uvirt. Set it in PixelViewer.
+* The image address also can be gotten from Unvirt. Save the image data from memory to local file and open it by PixelViewer.
+
+## CKMesh Debugging
+
+See [MeshConv README](./MeshConv/README.md)

BMap/CMakeLists.txt

@@ -3,21 +3,22 @@ add_library(BMap SHARED "")
 # Setup sources
 target_sources(BMap
 PRIVATE
-	BMap.cpp
+	BMap/BMap.cpp
-	BMExports.cpp
+	BMap/BMExports.cpp
 )
 # Setup headers
 target_sources(BMap
-PRIVATE
+PUBLIC
 FILE_SET HEADERS
 FILES
-	BMap.hpp
+	BMap/BMap.hpp
-	BMExports.hpp
+	BMap/BMExports.hpp
 )
 # Setup header infomation
 target_include_directories(BMap
-PRIVATE
+PUBLIC
-	"${CMAKE_CURRENT_LIST_DIR}"
+    "$<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}>"
+    "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
 )
 # Setup linked library infomation
 target_link_libraries(BMap
@@ -25,31 +26,42 @@ PRIVATE
 	YYCC::YYCCommonplace
 	LibCmo
 )
-# Setup C++ standard
-set_target_properties(BMap
-PROPERTIES
-    CXX_STANDARD 20
-    CXX_STANDARD_REQUIRED 20
-    CXX_EXTENSION OFF
-)
-# Setup project macros
-target_compile_definitions(BMap
 # Enable export macro
+target_compile_definitions(BMap
 PRIVATE
 	BMAP_EXPORTING
-# Order Unicode charset for private using
-PRIVATE
-    $<$<CXX_COMPILER_ID:MSVC>:UNICODE>
-    $<$<CXX_COMPILER_ID:MSVC>:_UNICODE>
-)
-# Order build as UTF-8 in MSVC
-target_compile_options(BMap
-PRIVATE
-    $<$<CXX_COMPILER_ID:MSVC>:/utf-8>
 )
 
-# Install BMap only on Release mode
+# Install binary and headers
 install(TARGETS BMap
-    CONFIGURATIONS Release RelWithDebInfo MinSizeRel
+    EXPORT BMapTargets
-    RUNTIME DESTINATION ${YYCC_INSTALL_BIN_PATH}
+    LIBRARY DESTINATION ${NEMO_INSTALL_LIB_PATH}
+    ARCHIVE DESTINATION ${NEMO_INSTALL_LIB_PATH}
+    INCLUDES DESTINATION ${NEMO_INSTALL_INCLUDE_PATH}
+    FILE_SET HEADERS DESTINATION ${NEMO_INSTALL_INCLUDE_PATH}
+)
+# Install target
+install(EXPORT BMapTargets
+    FILE BMapTargets.cmake
+    NAMESPACE NeMo::
+    DESTINATION ${NEMO_INSTALL_LIB_PATH}/cmake/BMap
+)
+# Package configuration file
+write_basic_package_version_file(
+    BMapConfigVersion.cmake
+    VERSION ${PACKAGE_VERSION}
+    COMPATIBILITY SameMinorVersion
+)
+configure_package_config_file(
+    ${CMAKE_CURRENT_LIST_DIR}/../CMake/BMapConfig.cmake.in 
+    "${CMAKE_CURRENT_BINARY_DIR}/BMapConfig.cmake"
+    INSTALL_DESTINATION ${NEMO_INSTALL_LIB_PATH}/cmake/BMap
+)
+# Copy package files to install destination
+install(
+FILES
+    "${CMAKE_CURRENT_BINARY_DIR}/BMapConfig.cmake"
+    "${CMAKE_CURRENT_BINARY_DIR}/BMapConfigVersion.cmake"
+DESTINATION
+    ${NEMO_INSTALL_LIB_PATH}/cmake/BMap
 )

CMake/BMapConfig.cmake.in

@@ -0,0 +1,7 @@
+
+@PACKAGE_INIT@
+
+# Include targets file
+include("${CMAKE_CURRENT_LIST_DIR}/BMapTargets.cmake")
+
+check_required_components(BMap)

CMake/FindSTB.cmake

@@ -0,0 +1,52 @@
+# - Find STB library
+# Find the STB headers
+#
+# This module defines the following variables:
+#   STB_FOUND        - True if STB was found
+#   STB_INCLUDE_DIRS - Location of the STB headers
+#
+# This module defines the following imported targets:
+#   STB::STB - Header-only interface library for STB
+
+# STB_ROOT must be specified by the user
+if (NOT DEFINED STB_ROOT)
+    set(STB_FOUND FALSE)
+else ()
+    # Look for STB_image.h in the specified STB_ROOT directory
+    find_path(STB_INCLUDE_DIR
+        NAMES STB_image.h
+        HINTS ${STB_ROOT}
+        NO_DEFAULT_PATH
+    )
+
+    # Check find status
+    if(STB_INCLUDE_DIR)
+        set(STB_FOUND TRUE)
+        set(STB_INCLUDE_DIRS ${STB_INCLUDE_DIR})
+    else()
+        set(STB_FOUND FALSE)
+    endif()
+
+    # Hide intermediate variables
+    mark_as_advanced(STB_INCLUDE_DIR)
+endif ()
+
+# Check find result
+if (STB_FOUND)
+    # Add library
+    message(STATUS "Found STB library")
+    # Add library
+    add_library(STB INTERFACE IMPORTED)
+    # Add alias to it
+    add_library(STB::STB ALIAS STB)
+    # Setup header files
+    set_target_properties(STB PROPERTIES
+    INTERFACE_INCLUDE_DIRECTORIES
+        "${STB_INCLUDE_DIRS}"
+    )
+else ()
+    # If it is required, show infomations.
+    if (std_FIND_REQUIRED)
+        message(FATAL_ERROR "Fail to find STB library.")
+    endif ()
+endif ()

CMake/custom_import_iconv.cmake

@@ -1,9 +0,0 @@
-if (WIN32)
-    # In Windows, we should not import Iconv.
-    # Send a notice to programmer.
-    message("Windows environment detected, skip finding Iconv!")
-else ()
-    # In non-Windows, we simply import Iconv from CMake preset.
-    # It will produce Iconv::Iconv target for including and linking.
-    find_package(Iconv REQUIRED)
-endif ()

CMake/custom_import_stb.cmake

@@ -1,14 +0,0 @@
-# Check stb path variable
-if (NOT DEFINED STB_IMAGE_PATH)
-    message(FATAL_ERROR "You must set STB_IMAGE_PATH variable to the root directory of std-image repository.")
-endif()
-
-# Add library
-add_library(stb-image INTERFACE IMPORTED)
-# Add alias for it
-add_library(stb::stb-image ALIAS stb-image)
-# Setup header files
-set_target_properties(stb-image PROPERTIES
-INTERFACE_INCLUDE_DIRECTORIES
-    "${STB_IMAGE_PATH}"
-)

CMake/custom_import_yycc.cmake

@@ -1,15 +0,0 @@
-
-# Check YYCC path environment variable
-if (NOT DEFINED YYCC_PATH)
-    message(FATAL_ERROR "You must set YYCC_PATH variable to one of YYCC CMake distribution installation path.")
-endif()
-
-# Find YYCC library
-# It will produce YYCC::YYCCommonplace target for including and linking.
-# 
-# Please note we MUST set CMake variable YYCCommonplace_ROOT to make sure CMake can found YYCC in out given path.
-# The cache status of YYCCommonplace_ROOT is doesn't matter.
-# CMake will throw error if we use HINTS feature in find_package to find YYCC.
-set(YYCCommonplace_ROOT ${YYCC_PATH} CACHE PATH
-"The path to YYCC CMake distribution installation path.")
-find_package(YYCCommonplace REQUIRED)

CMake/custom_import_zlib.cmake

@@ -1,34 +0,0 @@
-if (WIN32)
-    # In Windows, we use custom way to import ZLib.
-    # Before using this CMake file in Windows, you should do following steps first.
-    # 1. Get ZLib repository: https://github.com/madler/zlib
-    # 2. Navigate to `contrib/vstudio` and choose a proper Visual Studio project according to your environment.
-    # 3. Open project file and build. Then you will get the built binary.
-    # 4. The directory binary located is the argument you should passed to ZLIB_BINARY_PATH, for example: `contrib/vstudio/vc14/x64/ZlibDllRelease`
-
-    # Check ZLib path variable
-    if (NOT DEFINED ZLIB_HEADER_PATH)
-        message(FATAL_ERROR "You must set ZLIB_HEADER_PATH to the root directory of ZLib repository.")
-    endif()
-    if (NOT DEFINED ZLIB_BINARY_PATH)
-        message(FATAL_ERROR "You must set ZLIB_BINARY_PATH to the directory where include binary built by contributed Visual Studio project.")
-    endif()
-    # Add imported library
-    add_library(ZLIB INTERFACE IMPORTED)
-    # Add alias for it to let it has the same behavior with CMake imported ZLib.
-    add_library(ZLIB::ZLIB ALIAS ZLIB)
-    # Setup header files
-    set_target_properties(ZLIB PROPERTIES
-    INTERFACE_INCLUDE_DIRECTORIES
-        "${ZLIB_HEADER_PATH}"
-    )
-    # Setup lib files
-    set_target_properties(ZLIB PROPERTIES
-    INTERFACE_LINK_LIBRARIES
-        "${ZLIB_BINARY_PATH}/zlibwapi.lib"
-    )
-else ()
-    # In non-Windows, we simply import ZLib from CMake preset.
-    # It will produce ZLIB::ZLIB target for including and linking.
-    find_package(ZLIB REQUIRED)
-endif ()

CMakeLists.txt

@@ -1,6 +1,8 @@
+# Minimum required CMake version
 cmake_minimum_required(VERSION 3.23)
+# Project definition
 project(NeMo
-    VERSION 0.3.0
+    VERSION 0.4.0
     LANGUAGES CXX
 )
 
@@ -9,6 +11,11 @@ option(NEMO_BUILD_UNVIRT "Build Unvirt, the console interface operator of LibCmo
 option(NEMO_BUILD_BMAP "Build BMap, the example use of LibCmo which can read and write Ballance game map." OFF)
 option(NEMO_BUILD_DOC "Build document of LibCmo and all related stuff." OFF)
 
+# Set C++ standards
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
 # Setup install path from CMake provided install path for convenient use.
 include(GNUInstallDirs)
 set(NEMO_INSTALL_INCLUDE_PATH ${CMAKE_INSTALL_INCLUDEDIR} CACHE PATH
@@ -20,11 +27,17 @@ set(NEMO_INSTALL_BIN_PATH ${CMAKE_INSTALL_BINDIR} CACHE PATH
 set(NEMO_INSTALL_DOC_PATH ${CMAKE_INSTALL_DOCDIR} CACHE PATH
 "Non-arch doc install path relative to CMAKE_INSTALL_PREFIX unless set to an absolute path.")
 
-# Import essential packages
+# Add our CMake in module found path
-include(${CMAKE_CURRENT_LIST_DIR}/CMake/custom_import_zlib.cmake)
+set(CMAKE_MODULE_PATH
-include(${CMAKE_CURRENT_LIST_DIR}/CMake/custom_import_iconv.cmake)
+    "${CMAKE_CURRENT_LIST_DIR}/CMake"
-include(${CMAKE_CURRENT_LIST_DIR}/CMake/custom_import_yycc.cmake)
+)
-include(${CMAKE_CURRENT_LIST_DIR}/CMake/custom_import_stb.cmake)
+# Find required packages
+find_package(ZLIB REQUIRED)
+find_package(YYCCommonplace REQUIRED)
+find_package(STB REQUIRED)
+
+# Import package helper
+include(CMakePackageConfigHelpers)
 
 # If we are not in Windows environment, and we need to build shared library BMap,
 # we should enable PIC (position independent code), otherwise build process will fail.
@@ -36,7 +49,7 @@ if ((NOT WIN32) AND NEMO_BUILD_BMAP)
     set(CMAKE_POSITION_INDEPENDENT_CODE True)
 endif ()
 
-# Import build targets
+# Include build targets by options
 add_subdirectory(LibCmo)
 if (NEMO_BUILD_UNVIRT)
     add_subdirectory(Unvirt)
@@ -47,31 +60,3 @@ endif ()
 if (NEMO_BUILD_DOC)
     add_subdirectory(Documents)
 endif ()
-
-# Install target and package
-# Install target
-install(EXPORT LibCmoTargets
-    FILE LibCmoTargets.cmake
-    NAMESPACE NeMo::
-    DESTINATION ${NEMO_INSTALL_LIB_PATH}/cmake/LibCmo
-)
-# Package configuration file
-include(CMakePackageConfigHelpers)
-write_basic_package_version_file(
-    LibCmoConfigVersion.cmake
-    VERSION ${PACKAGE_VERSION}
-    COMPATIBILITY SameMinorVersion
-)
-configure_package_config_file(
-    ${CMAKE_CURRENT_LIST_DIR}/CMake/LibCmoConfig.cmake.in 
-    "${CMAKE_CURRENT_BINARY_DIR}/LibCmoConfig.cmake"
-    INSTALL_DESTINATION ${NEMO_INSTALL_LIB_PATH}/cmake/LibCmo
-)
-# Copy package files to install destination
-install(
-FILES
-    "${CMAKE_CURRENT_BINARY_DIR}/LibCmoConfig.cmake"
-    "${CMAKE_CURRENT_BINARY_DIR}/LibCmoConfigVersion.cmake"
-DESTINATION
-    ${NEMO_INSTALL_LIB_PATH}/cmake/LibCmo
-)

COMPILE.md

@@ -1,35 +1,43 @@
 # Compile Manual
 
+## Choose Version
+
+We suggest that you only use stable version (tagged commit).
+The latest commit always present current works.
+It means that it is not stable and work in progress.
+
 ## Requirements
 
-This project require:
-
 * CMake 3.23 at least.
-* The common compiler supporting C++ 20 (GCC / Clang / MSVC).
+* The common compiler supporting C++ 23 (GCC / Clang / MSVC).
 * Littile-endian architecture system.
 * zlib.
-* iconv (non-Windows system required).
+* [stb](https://github.com/nothings/stb).
-* [stb](https://github.com/nothings/stb): For image read and write.
+* [YYCCommonplace](https://github.com/yyc12345/YYCCommonplace).
-* [YYCCommonplace](https://github.com/yyc12345/YYCCommonplace): My personal invented library concentrating some common functions for mine.
+* Doxygen (Required if you build documentation).
-
-Since libcmo21 0.2.0, we only provide it in CMake build system. So Windows user should install CMake first or use Visual Studio directly (Visual Studio provides CMake build system supports).
 
 ## Preparations
 
 ### YYCCommonplace
 
-You should clone YYCCommonplace and switch to the latest release tag (or specified commit hash provided with libcmo21 release infos if you are building for specific libcmo21 version). When configuring YYCCommonplace, you should notice following infos:
+Following these steps to prepare YYCCommonplace:
 
-* Please make sure that you have specified C++ 20 explicitly by passing `-DCMAKE_CXX_STANDARD=20` in command line. This is crucial because libcmo21 use C++ 20, and YYCCommonplace's ABI is incompatible between C++ 17 version and C++ 20 version.
+1. Clone YYCCommonplace first.
-* If you need `BMap` in final libcmo21 built artifacts, and you are in non-Windows system now, please specify position independent code flag by passing `-DCMAKE_POSITION_INDEPENDENT_CODE=True` in command line. GCC and Clang will reject linking if you don't flag it.
+1. Switch to the latest **release** tag, or **specified commit hash** provided with libcmo21 release infos if you are building for specific libcmo21 version.
+1. Following compile manual provided by YYCCommonplace to configure, compile and install it.
 
-After configuring, you can normally build YYCCommonplace like a common CMake project.
+> [!IMPORTANT]  
-
+> If you need `BMap` component in final libcmo21 built artifacts, and you are in non-Windows system now, please specify position independent code flag by passing `-DCMAKE_POSITION_INDEPENDENT_CODE=True` in command line when configuring YYCCommonplace. Otherwise GCC and Clang will reject linking.
-Please note if your final program or dynamic library is provided for end user, please choose `RelWithDebInfo` build type (`Release` is not suggested because it will strip all debug infos and it is not good for bug reporter, which is embedded in program, to report crash). If final program is served for programmer debugging, please choose `Debug` build type.
 
 ### stb
 
-You should clone stb repository first, then switch to a specific commit hash `2e2bef463a5b53ddf8bb788e25da6b8506314c08`. In ideally scenario, people like to choose the latest commit. However, I not frequently update this dependency.
+Following these steps to prepare stb:
+
+1. Clone stb repository first.
+1. Switch to a **specific commit hash** `2e2bef463a5b53ddf8bb788e25da6b8506314c08`. I do not frequently update this dependency so using the latest commit is inviable.
+
+> [!NOTE]  
+> std is a header-only C project. So we don't need compile it. libcmo21 will use homemade CMake script to find it.
 
 ### zlib
 
@@ -37,47 +45,93 @@ If you are in Windows, you should download zlib source code and build it with gi
 
 If you are running on non-Windows system. You usually do not need to do anything. Because zlib development environment may be configured by your package manager correctly.
 
-## Compile
+If you are in Windows, or in Linux but want to use specific zlib version due to various reasons, following these steps to prepare zlib:
 
-### Directory Hierarchy
+1. Download zlib source code from its official.
+1. Extract it into a directory.
+1. Enter this directory and create 2 subdirectory `build` and `install` for CMake build and install respectively.
+1. Enter `build` directory and configure CMake with extra `-DCMAKE_CXX_STANDARD=23 -DZLIB_BUILD_EXAMPLES=OFF -DCMAKE_INSTALL_PREFIX=<path-to-install>` parameters. And `<path-to-install>` is the absolute path to your created `install` directory in previous step (Idk why `--prefix` argument is not works for zlib).
+1. Use CMake to build zlib
+1. Use CMake to install zlib into previous we created `install` directory.
 
-First, create subdirectory `Bin/build` and `Bin/install` at the root directory of libcmo21.
+> [!NOTE]  
+> We use CMake, rather than any other to compile zlib because zlib provide it, and we also use CMake as our build system, so that we do not need to write any extra files for adaption.
 
-### Configuration
+> [!CAUTION]  
+> Windows developer should highly notice that please do NOT use Visual Studio file located in `contrib/vstudio` directory to produce binary zlib on Windows. That project will produce `zlibwapi.dll` which is not our expected `zlib.dll`. Please use Visual Studio embedded CMake to configure zlib and compile it directly.
 
-Then enter subdirectory `Bin/build` and use following command to configure CMake:
+### Doxygen
 
-- Windows (MSVC): `cmake -DNEMO_BUILD_UNVIRT=ON -DNEMO_BUILD_BMAP=ON -DNEMO_BUILD_DOC=OFF -DSTB_IMAGE_PATH=<path-to-stb> -DYYCC_PATH=<path-to-yycc-install> -DZLIB_HEADER_PATH=<path-to-zlib-hdr> -DZLIB_BINARY_PATH=<path-to-zlib-bin> ../..`
+Doxygen is required only if you need to build documentation.
-- non-Windows: `cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DNEMO_BUILD_UNVIRT=ON -DNEMO_BUILD_BMAP=ON -DNEMO_BUILD_DOC=OFF -DSTB_IMAGE_PATH=<path-to-stb> -DYYCC_PATH=<path-to-yycc-install> ../..`
+If you don't need this please skip this chapter.
 
-The arguments in command should be replaced by:
+We use Doxygen 1.9.7.
+It would be okey use other versions but I have not test on them.
 
-* `<path-to-stb>`: The root directory of your cloned stb repository.
+YYCCommonplace use Doxygen as its documentation system.
-* `<path-to-yycc-install>`: The directory to installed CMake package you chosen when building YYCCommonplace.
+So before compiling, you must make sure `doxygen` are presented in your environment.
-* `<path-to-zlib-hdr>` (Windows only): The root directory of downloaded zlib source code.
-* `<path-to-zlib-bin>` (Windows only): The directory where you can find built `zlibwapi.dll`.
 
-The switches in command can be switched as you wish:
+## Build and Install
 
-* `NEMO_BUILD_UNVIRT`: Build `Unvirt`, a command line application debugging Virtools files.
+Using CMake is the only viable way to build and install this repository.
-* `NEMO_BUILD_BMAP`: Build `BMap`, a dynamic library specific used for loading Ballance map file. If you are coming from my another project [BallanceBlenderPlugin](https://github.com/yyc12345/BallanceBlenderHelper), this is what you need.
-* `NEMO_BUILD_DOC`: Build the document of libcmo21.
 
-### Build
+### Configurable Variables
 
-Execute following command to build libcmo21.
+First, there is a list listing all variables you may configure during compiling.
 
-* Windows: `cmake --build . --config RelWithDebInfo`
+* `NEMO_BUILD_UNVIRT`: Set it to `ON` to build `Unvirt`. `ON` in default.
-* non-Windows: `cmake --build .`
+This is an interactive tool for loading, saving Virtools file.
+It is extremely useful for debugging this project.
+* `NEMO_BUILD_BMAP`: Set it to `ON` to build `BMap`. `OFF` in default.
+It is a dynamic library specific used for loading Ballance map file.
+If you are coming from my another project [BallanceBlenderPlugin](https://github.com/yyc12345/BallanceBlenderHelper), this is what you need.
+* `NEMO_BUILD_DOC`: Set it to `ON` to build documentation. `OFF` in default.
+It may be useful for the developer who firstly use this project in their own projects.
+Please note that generated documentation is different in different platforms.
+* `YYCCommonplace_ROOT`: Set to the install path of YYCCommonplace.
+* `stb_ROOT`: Set to the root directory of stb.
+* `ZLIB_ROOT`: Set to the install path of zlib.
+If you are using zlib which is not build by your own, you usually do not need specify this variable.
 
-### Build Type
+### Configure CMake
 
-Like YYCCommonplace, we suggest `RelWithDebInfo` for end user. If you want to build for programmer debugging, please replace all `RelWithDebInfo` to `Debug`. The build type between YYCCommonplace and libcmo21 should keep same to reduce any possibility about ABI incompatible issue.
+When configure CMake, you may use different options on different platforms.
+Following list may help you.
 
-## Install
+- On Windows:
+    * `-A Win32` or `-A x64` to specify architecture.
+- On Linux or other POSIX systems:
+    * `-DCMAKE_BUILD_TYPE=Debug` or `-DCMAKE_BUILD_TYPE=Release` to specify build type.
 
-Currently the CMake install script still has some bugs and can not work as expected. So as the alternative, just go into build directory and find your final program please. It's pretty simple.
+Additionally, you can attach any variables introduced above with `-D` option during CMake configurations.
 
-## Note
+> [!NOTE]  
+> Position independent code flag is automatically added if you enable `BMap` so you don't need manually specify it. You just need to make sure that all dependencies enable this.
 
-You may face issue when compiling this program on Linux or macOS because I develop this project on Windows frequently. The compatibility with Linux will only be checked just before releasing. And I don't have any Apple device to check the compatibility with macOS. So, for Linux issue, please report it directly and I will try to fix. For macOS bug, PR is welcomed.
+### Build with CMake
+
+After configuration, you can use `cmake --build .` to build project,
+with additional options on different platforms.
+Following list may help you.
+
+- On Windows:
+    * `--config Debug` or `--config Release` to specify build type.
+- On Linux or other POSIX systems:
+    * None
+
+### Install with CMake
+
+After building, you can use `cmake --install . --prefix <path-to-prefix>`
+to install project into given path, with additional options on different platforms.
+Following list may help you.
+
+- On Windows:
+    * `--config Debug` or `--config Release` to specify build type.
+- On Linux or other POSIX systems:
+    * None
+
+## Compatibility Notes
+
+You may face issue when compiling this program on Linux or macOS because I develop this project on Windows frequently.
+The compatibility with Linux and macOS will only be checked just before releasing. 
+And, I don't have any Apple devices, so the compatibility with macOS is checked by GitHub Action.

CodeGen/UniversalEncoding/.gitignore

@@ -1,2 +0,0 @@
-# Result
-*.cpp

CodeGen/UniversalEncoding/EncodingTable.csv

@@ -1,98 +0,0 @@
-Encoding	Alias	Code Page	Iconv Identifier
-ascii	646, us-ascii	437	ASCII
-big5	big5-tw, csbig5	950	BIG5
-big5hkscs	big5-hkscs, hkscs		BIG5-HKSCS
-cp037	IBM037, IBM039	037	
-cp273	273, IBM273, csIBM273		
-cp424	EBCDIC-CP-HE, IBM424		
-cp437	437, IBM437	437	
-cp500	EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500	500	
-cp720		720	
-cp737		737	
-cp775	IBM775	775	
-cp850	850, IBM850	850	CP850
-cp852	852, IBM852	852	
-cp855	855, IBM855	855	
-cp856			
-cp857	857, IBM857	857	
-cp858	858, IBM858	858	
-cp860	860, IBM860	860	
-cp861	861, CP-IS, IBM861	861	
-cp862	862, IBM862	862	CP862
-cp863	863, IBM863	863	
-cp864	IBM864	864	
-cp865	865, IBM865	865	
-cp866	866, IBM866	866	CP866
-cp869	869, CP-GR, IBM869	869	
-cp874		874	CP874
-cp875		875	
-cp932	932, ms932, mskanji, ms-kanji, windows-31j	932	CP932
-cp949	949, ms949, uhc	949	CP949
-cp950	950, ms950	950	CP950
-cp1006			
-cp1026	ibm1026	1026	
-cp1125	1125, ibm1125, cp866u, ruscii		
-cp1140	ibm1140	1140	
-cp1250	windows-1250	1250	CP1250
-cp1251	windows-1251	1251	CP1251
-cp1252	windows-1252	1252	CP1252
-cp1253	windows-1253	1253	CP1253
-cp1254	windows-1254	1254	CP1254
-cp1255	windows-1255	1255	CP1255
-cp1256	windows-1256	1256	CP1256
-cp1257	windows-1257	1257	CP1257
-cp1258	windows-1258	1258	CP1258
-euc_jp	eucjp, ujis, u-jis	20932	EUC-JP
-euc_jis_2004	jisx0213, eucjis2004		
-euc_jisx0213	eucjisx0213		
-euc_kr	euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001	51949	EUC-KR
-gb2312	chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58	936	CP936
-gbk	936, cp936, ms936	936	GBK
-gb18030	gb18030-2000	54936	GB18030
-hz	hzgb, hz-gb, hz-gb-2312	52936	HZ
-iso2022_jp	csiso2022jp, iso2022jp, iso-2022-jp	50220	ISO-2022-JP
-iso2022_jp_1	iso2022jp-1, iso-2022-jp-1		ISO-2022-JP-1
-iso2022_jp_2	iso2022jp-2, iso-2022-jp-2		ISO-2022-JP-2
-iso2022_jp_2004	iso2022jp-2004, iso-2022-jp-2004		
-iso2022_jp_3	iso2022jp-3, iso-2022-jp-3		
-iso2022_jp_ext	iso2022jp-ext, iso-2022-jp-ext		
-iso2022_kr	csiso2022kr, iso2022kr, iso-2022-kr	50225	ISO-2022-KR
-latin_1	iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1	28591	ISO-8859-1
-iso8859_2	iso-8859-2, latin2, L2	28592	ISO-8859-2
-iso8859_3	iso-8859-3, latin3, L3	28593	ISO-8859-3
-iso8859_4	iso-8859-4, latin4, L4	28594	ISO-8859-4
-iso8859_5	iso-8859-5, cyrillic	28595	ISO-8859-5
-iso8859_6	iso-8859-6, arabic	28596	ISO-8859-6
-iso8859_7	iso-8859-7, greek, greek8	28597	ISO-8859-7
-iso8859_8	iso-8859-8, hebrew	28598	ISO-8859-8
-iso8859_9	iso-8859-9, latin5, L5	28599	ISO-8859-9
-iso8859_10	iso-8859-10, latin6, L6		ISO-8859-10
-iso8859_11	iso-8859-11, thai		ISO-8859-11
-iso8859_13	iso-8859-13, latin7, L7	28603	ISO-8859-13
-iso8859_14	iso-8859-14, latin8, L8		ISO-8859-14
-iso8859_15	iso-8859-15, latin9, L9	28605	ISO-8859-15
-iso8859_16	iso-8859-16, latin10, L10		ISO-8859-16
-johab	cp1361, ms1361	1361	JOHAB
-koi8_r			
-koi8_t			KOI8-T
-koi8_u			
-kz1048	kz_1048, strk1048_2002, rk1048		
-mac_cyrillic	maccyrillic	10007	MacCyrillic
-mac_greek	macgreek	10006	MacGreek
-mac_iceland	maciceland	10079	MacIceland
-mac_latin2	maclatin2, maccentraleurope, mac_centeuro		
-mac_roman	macroman, macintosh		MacRoman
-mac_turkish	macturkish	10081	MacTurkish
-ptcp154	csptcp154, pt154, cp154, cyrillic-asian		PT154
-shift_jis	csshiftjis, shiftjis, sjis, s_jis	932	SHIFT_JIS
-shift_jis_2004	shiftjis2004, sjis_2004, sjis2004		
-shift_jisx0213	shiftjisx0213, sjisx0213, s_jisx0213		
-utf_32	U32, utf32		UTF-32
-utf_32_be	UTF-32BE		UTF-32BE
-utf_32_le	UTF-32LE		UTF-32LE
-utf_16	U16, utf16		UTF16
-utf_16_be	UTF-16BE		UTF-16BE
-utf_16_le	UTF-16LE		UTF-16LE
-utf_7	U7, unicode-1-1-utf-7	65000	UTF-7
-utf_8	U8, UTF, utf8, utf-8, cp65001	65001	UTF-8
-utf_8_sig			

CodeGen/UniversalEncoding/UniversalEncoding.py

@@ -1,63 +0,0 @@
-import typing
-import io
-import os
-
-class LanguageToken:
-    m_Name: str
-    m_Alias: tuple[str, ...]
-    m_CodePage: str | None
-    m_IconvCode: str | None
-
-    def __init__(self, name: str, alias: typing.Iterator[str], code_page: str, iconv_code: str):
-        self.m_Name = name.lower()
-        self.m_Alias = tuple(map(lambda x: x.lower(), alias))
-        self.m_CodePage = None if code_page == '' else code_page
-        self.m_IconvCode = None if iconv_code == '' else iconv_code
-
-def extract_data(fs: io.TextIOWrapper) -> tuple[str, ...]:
-    # remove first line to remove table header
-    return fs.readlines()[1:]
-
-def extract_token(csv_data: tuple[str, ...]) -> tuple[LanguageToken, ...]:
-    ret: list[LanguageToken] = []
-    for line in csv_data:
-        line = line.strip('\n')
-        line_sp = line.split('\t')
-        alias_sp = filter(lambda x: x != '', map(lambda x: x.strip(), line_sp[1].split(',')))
-        ret.append(LanguageToken(line_sp[0], alias_sp, line_sp[2], line_sp[3]))
-    return tuple(ret)
-
-def write_alias_map(fs: io.TextIOWrapper, data: tuple[LanguageToken, ...]) -> None:
-    fs.write('static const std::map<std::u8string, std::u8string> c_AliasMap {\n')
-    for i in data:
-        for j in i.m_Alias:
-            fs.write(f'\t{{ u8"{j}", u8"{i.m_Name}" }},\n')
-    fs.write('};\n')
-
-def write_win_cp_map(fs: io.TextIOWrapper, data: tuple[LanguageToken, ...]) -> None:
-    fs.write('static const std::map<std::u8string, UINT> c_WinCPMap {\n')
-    for i in data:
-        if i.m_CodePage is not None:
-            fs.write(f'\t{{ u8"{i.m_Name}", static_cast<UINT>({i.m_CodePage}u) }},\n')
-    fs.write('};\n')
-
-def write_iconv_map(fs: io.TextIOWrapper, data: tuple[LanguageToken, ...]) -> None:
-    fs.write('static const std::map<std::u8string, std::string> c_IconvMap {\n')
-    for i in data:
-        if i.m_IconvCode is not None:
-            fs.write(f'\t{{ u8"{i.m_Name}", "{i.m_IconvCode}" }},\n')
-    fs.write('};\n')
-
-if __name__ == '__main__':
-    # get file path
-    self_path: str = os.path.dirname(__file__)
-    csv_file: str = os.path.join(self_path, 'EncodingTable.csv')
-    cpp_file: str = os.path.join(self_path, 'EncodingTable.cpp')
-    # process files
-    with open(csv_file, 'r', encoding='utf-8') as fr:
-        with open(cpp_file, 'w', encoding='utf-8') as fw:
-            data = extract_data(fr)
-            token = extract_token(data)
-            write_alias_map(fw, token)
-            write_win_cp_map(fw, token)
-            write_iconv_map(fw, token)

Docs/CMakeLists.txt

@@ -0,0 +1,36 @@
+# Extract all public macros defined in LibCmo
+# However, you should note that these extratcted macros have generator expressions.
+get_target_property(LIBCMO_COMPILE_DEFINITIONS LibCmo COMPILE_DEFINITIONS)
+if (LIBCMO_COMPILE_DEFINITIONS STREQUAL "LIBCMO_COMPILE_DEFINITIONS-NOTFOUND")
+    message(FATAL_ERROR "Cannot extract compile definitions from LibCmo.")
+endif ()
+# Convert list to string for expanding in future.
+list(JOIN LIBCMO_COMPILE_DEFINITIONS " " LIBCMO_MACRO_GENERATOR_EXPRESSIONS)
+
+# We simply configure Doxygen config file first.
+configure_file(
+    ${CMAKE_CURRENT_LIST_DIR}/Doxyfile.in
+    ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+    @ONLY
+)
+
+# Then we use "file GENERATE" syntax to generate per-config truely Doxyfile used by Doxygen.
+# Because there is no "$<>" syntax in Doxyfile, so we can safely use it.
+# Please note that the generation of "file GENERATE" syntax will be postponed until the build stage.
+file(GENERATE
+    OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/Doxyfile"
+    INPUT "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
+    TARGET LibCmo
+)
+
+# Add custom target using per-config Doxyfile
+add_custom_target (LibCmoDocuments
+    Doxygen::doxygen "${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/Doxyfile"
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Generating documentation" VERBATIM
+)
+
+# Install built documentation
+install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
+    DESTINATION ${NEMO_INSTALL_DOC_PATH}
+)

Docs/Doxyfile.in

@@ -2310,7 +2310,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # C-preprocessor directives found in the sources and include files.
 # The default value is: YES.
 
-ENABLE_PREPROCESSING   = NO
+ENABLE_PREPROCESSING   = YES
 
 # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
 # in the source code. If set to NO, only conditional compilation will be
@@ -2360,7 +2360,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = YYCC_DOXYGEN
+PREDEFINED             = @LIBCMO_MACRO_GENERATOR_EXPRESSIONS@
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

Documents/CMakeLists.txt

@@ -1,19 +0,0 @@
-# Configure Doxygen config file
-configure_file(
-    ${CMAKE_CURRENT_LIST_DIR}/Doxyfile.in
-    ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-    @ONLY
-)
-
-# Add custom target
-add_custom_target (NeMoDocuments
-    doxygen ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-    COMMENT "Generating LibCmo documentation" VERBATIM
-)
-
-# Install built documentation
-install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
-    CONFIGURATIONS Release RelWithDebInfo MinSizeRel
-    DESTINATION ${NEMO_INSTALL_DOC_PATH}
-)

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2022-2024 yyc12345
+Copyright (c) 2022-2026 yyc12345
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal