Merge branch 'build-instruction-improvement' of public/ls-standard-library into development

CMakeLists.txt

@@ -32,7 +32,6 @@ option(LS_STD_BUILD_WITH_TESTS "Build project with tests..." OFF)
 option(LS_STD_BUILD_WITH_SUPPORTED_COMPILER "Build project with supported compiler only..." ON)
 option(LS_STD_BUILD_STATIC "Build ls-std static library..." ON)
 option(LS_STD_BUILD_SHARED "Build ls-std shared library..." OFF)
-option(LS_STD_BUILD_MODULE "Build ls-std module library..." OFF)
 
 set(TARGET_COUNTER 0)
 
@@ -46,11 +45,6 @@ if (${LS_STD_BUILD_SHARED})
     set(GOAL "shared library")
 endif ()
 
-if (${LS_STD_BUILD_MODULE})
-    math(EXPR TARGET_COUNTER "${TARGET_COUNTER} + 1")
-    set(GOAL "module library")
-endif ()
-
 message("${PROJECT_NAME}: [Goal] ${GOAL}")
 
 if (TARGET_COUNTER GREATER 1)
@@ -90,22 +84,8 @@ if(${LS_STD_BUILD_WITH_SUPPORTED_COMPILER})
         message("${PROJECT_NAME}: [Error] ${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION} is not supported... terminated!")
         return()
     endif ()
-
-    # define which compilers are supported for shared or module goal
-
-    if (${CMAKE_CXX_COMPILER_ID} STREQUAL MSVC AND ${LS_STD_BUILD_MODULE})
-        message("${PROJECT_NAME}: [Error] building \"${GOAL}\" with ${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION} is not supported... terminated!")
-        return()
-    endif ()
 endif()
 
-# define which goals can run tests
-
-if (${LS_STD_BUILD_WITH_TESTS} AND ${LS_STD_BUILD_MODULE})
-    message("${PROJECT_NAME}: [Error] building \"${GOAL}\" with tests is not supported... terminated!")
-    return()
-endif ()
-
 ######################################################
 # Include Directories
 ######################################################
@@ -392,11 +372,6 @@ if (${LS_STD_BUILD_SHARED})
     set_target_properties("${MODULE_NAME_BOXING}" PROPERTIES DEBUG_POSTFIX "-d")
 endif ()
 
-if (${LS_STD_BUILD_MODULE})
-    add_library("${MODULE_NAME_BOXING}" MODULE ${SOURCE_FILES_BOXING})
-    set_target_properties("${MODULE_NAME_BOXING}" PROPERTIES DEBUG_POSTFIX "-d")
-endif ()
-
 ##########################################################
 # Build Library (core)
 ##########################################################
@@ -413,11 +388,6 @@ if (${LS_STD_BUILD_SHARED})
     set_target_properties("${MODULE_NAME_CORE}" PROPERTIES DEBUG_POSTFIX "-d")
 endif ()
 
-if (${LS_STD_BUILD_MODULE})
-    add_library("${MODULE_NAME_CORE}" MODULE ${SOURCE_FILES_CORE})
-    set_target_properties("${MODULE_NAME_CORE}" PROPERTIES DEBUG_POSTFIX "-d")
-endif ()
-
 ##########################################################
 # Build Library (encoding)
 ##########################################################
@@ -434,11 +404,6 @@ if (${LS_STD_BUILD_SHARED})
     set_target_properties("${MODULE_NAME_ENCODING}" PROPERTIES DEBUG_POSTFIX "-d")
 endif ()
 
-if (${LS_STD_BUILD_MODULE})
-    add_library("${MODULE_NAME_ENCODING}" MODULE ${SOURCE_FILES_ENCODING})
-    set_target_properties("${MODULE_NAME_ENCODING}" PROPERTIES DEBUG_POSTFIX "-d")
-endif ()
-
 # CLI base64
 
 add_executable(${CLI_NAME_BASE64}
@@ -461,11 +426,6 @@ if (${LS_STD_BUILD_SHARED})
     set_target_properties("${MODULE_NAME_EVENT}" PROPERTIES DEBUG_POSTFIX "-d")
 endif ()
 
-if (${LS_STD_BUILD_MODULE})
-    add_library("${MODULE_NAME_EVENT}" MODULE ${SOURCE_FILES_EVENT})
-    set_target_properties("${MODULE_NAME_EVENT}" PROPERTIES DEBUG_POSTFIX "-d")
-endif ()
-
 ##########################################################
 # Build Library (io)
 ##########################################################
@@ -483,11 +443,6 @@ if (${LS_STD_BUILD_SHARED})
     set_target_properties("${MODULE_NAME_IO}" PROPERTIES DEBUG_POSTFIX "-d")
 endif ()
 
-if (${LS_STD_BUILD_MODULE})
-    add_library("${MODULE_NAME_IO}" MODULE ${SOURCE_FILES_IO})
-    set_target_properties("${MODULE_NAME_IO}" PROPERTIES DEBUG_POSTFIX "-d")
-endif ()
-
 ##########################################################
 # Build Library (time)
 ##########################################################
@@ -505,11 +460,6 @@ if (${LS_STD_BUILD_SHARED})
     set_target_properties("${MODULE_NAME_TIME}" PROPERTIES DEBUG_POSTFIX "-d")
 endif ()
 
-if (${LS_STD_BUILD_MODULE})
-    add_library("${MODULE_NAME_TIME}" MODULE ${SOURCE_FILES_TIME})
-    set_target_properties("${MODULE_NAME_TIME}" PROPERTIES DEBUG_POSTFIX "-d")
-endif ()
-
 ####################################################################################################################
 ####################################################################################################################
 ####################################################################################################################

README.md

@@ -2,28 +2,28 @@
 
 This is a cross-platform standard library written in C++ offering functionalities you would usually miss in C++'s standard template library (STL), especially if you would search for cross-platform implementations.  
 This library has been tested on __Windows__, __Linux__ and __MacOS__ systems.
-Following a modularized approach the following submodules are defined in scope of this library, which are independent:
+Following a modularized approach the following independent submodules are defined in scope of this library:
  
 #### Boxing ####
 
-This library module provides boxing classes for primitive data types (e.g. string, int, long, float...) to provide additional functionalities.
+This library module provides boxing classes for primitive data types (e.g. string, int, long, float...), adding additional functionalities.
 
 #### Core ####
 
-The core module is a base module providing a base __Class__, exceptions, data types and interfaces. Usually the other submodules are dependent on this module. 
+The core module is a base module providing common functionalities being shared among other library submodules. Functionalities provided by this module include interfaces, exceptions and base classes, which provide basic reflection functionalities.
 
 #### Encoding ####
 
-To encode a byte field (e.g. a binary file) for transfer the __Base64__ encoding / decoding functionality is being provided by this submodule as a first feature.
+To encode a byte field (e.g. a binary file) for network transfer the __Base64__ encoding / decoding functionality is being provided by this submodule as a first feature.
 
 #### Event ####
 
-This submodule comes with an __Event__ class, as well as with handlers and managers to provide an intuitive event handling for your application.
+This submodule comes with events in a primitive form, as well as with handlers and managers to provide an intuitive event handling for your application.
 
 #### IO ####
 
 To handle file operations - or to receive information of a file - this library submodule provides an own __File__ class implementation, which can also be passed to library implemented input or output stream classes.  
-Additionally __XML__ and __KV__ parsing functionalities are provided by this submodule.
+Additionally __XML__ and __KV__ parsing functionalities are provided.
 
 #### Time ####
 
@@ -62,54 +62,91 @@ This software is licensed and uses MIT-license. You can find a __LICENSE.MIT__ f
 ---
 ### Building ###
 
-To build this library you'd need a recent version of __cmake__ and your OS specific compiler collection, like __gcc__ or __MinGW__ installed.  
-Inside project's root directory create the following folder:
+Building this library would result into providing binaries for each library module and CLI tool: 
+
+| binary              | type                       |
+|---------------------|----------------------------|
+| __cli-base64__      | CLI executable             |
+| __ls-std-boxing__   | library (static / dynamic) |
+| __ls-std-core__     | library (static / dynamic) |
+| __ls-std-encoding__ | library (static / dynamic) |
+| __ls-std-event__    | library (static / dynamic) |
+| __ls-std-io__       | library (static / dynamic) |
+| __time__            | library (static / dynamic) |
+
+#### Prerequisites ####
+
+To build this library you'd need a supported __toolchain__ in place, consisting of a build tool and compiler. The following table is a listing of supported compilers and build tools associated with operating systems, where this library has been tested:
+
+| Supported Compiler<br/>(mandatory) | OS              | Supported Compiler Version<br/>(mandatory) | Build Tool<br/>(mandatory) | Build Tool Version (mandatory) |
+|------------------------------------|-----------------|--------------------------------------------|----------------------------|--------------------------------|
+| GCC                                | Linux Mint 20.3 | 12.2.0                                     | CMake                      | \>= 3.24.0                     |
+| Clang                              | Linux Mint 20.3 | 12.0.0-3ubuntu1~20.04.5                    | CMake                      | \>= 3.24.0                     |
+| MinGW-w64 / GCC                    | Windows 10      | 11.2.0                                     | CMake                      | \>= 3.24.0                     |
+| MSVC                               | Windows 10      | 19.32.31332.0                              | CMake                      | \>= 3.24.0                     |
+| AppleClang                         | MacOS Monterey  | 14.0.0                                     | CMake                      | \>= 3.24.0                     |
+
+Please note, that where the underlying operating system is optional in this listing, the toolchain itself is not! This means, that by default you should use one of the supported listed toolchains.  
+In case you'd like to use an unsupported toolchain, you can enforce this during CMake project generation. For that have a look at the CMake flag usage section below.
+
+#### Generate CMake Project (Unix) ####
+
+To prepare a CMake project, create a build folder within the project's root folder (where the CMakeLists.txt file is located) via CLI and navigate to it:
 
 ```
-cmake_build_release
+mkdir cmake-build-release
+cd cmake-build-release
 ```
 
-Open your OS specific command line interface (CLI) and navigate to this new folder and run the following command to configure the project and generate a native build system:  
+Inside this folder generate the CMake project:
 
 ```
 cmake ../
 ```
 
-Inside __cmake_build_release__ folder you will now find cmake generated files. To compile the library now, just run:   
+Alternatively, the CMake project generation can be controlled by providing library specific CMake flags. The following table is a listing of available flags:
+
+| CMake Flag                               | Default Value | Description                                                                                                                                          |
+|------------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| __LS_STD_BUILD_WITH_TESTS__              | OFF           | This flag can be enabled to build automated tests, like unit or integration tests.                                                                   |
+| __LS_STD_BUILD_WITH_SUPPORTED_COMPILER__ | ON            | This flag enforces the usage of supported compilers, only.<br/>For usage of an unsupported toolchain, set this flag to __OFF__.                      |
+| __LS_STD_BUILD_STATIC__                  | ON            | This flag indicates, that all library modules should be built as static goals.  <br/>Please note, that __LS_STD_BUILD_SHARED__ has to be turned off. |
+| __LS_STD_BUILD_SHARED__                  | OFF           | This flag indicates, that all library modules should be built as shared goals.  <br/>Please note, that __LS_STD_BUILD_STATIC__ has to be turned off. |
+
+To use one or more of these flags, you'd have to adjust previous command, like:
 
 ```
-cmake --build . --config Release
+cmake -DLS_STD_BUILD_WITH_TESTS=ON ../
 ```
 
-__Please note__: Currently only a small set of compilers is officially supported. If you'd like to compile with an unsupported compiler, you have to set __LS_STD_BUILD_WITH_SUPPORTED_COMPILER__ - option in _CMakeLists.txt_ file to __OFF__ - then reset and reload the cmake project.  
+#### Compile Project ####
 
-Find below a table of compiler/OS combinations which have been tested during library version development:
+Now, that the CMake project is generated, you should find CMake generated files inside previously created build folder. In order to compile the project run:   
 
-| Supported Compiler | OS              | Compiler Version        |
-|--------------------|-----------------|-------------------------|
-| GCC                | Linux Mint 20.3 | 12.2.0                  |
-| Clang              | Linux Mint 20.3 | 12.0.0-3ubuntu1~20.04.5 |
-| MinGW-w64 / GCC    | Windows 10      | 11.2.0                  |
-| MSVC               | Windows 10      | 19.32.31332.0           |
-| AppleClang         | MacOS Monterey  | 14.0.0                  |
+```
+cmake --build . --config Release
+```
+
+Once compilation is done, you should find generated binaries within __cmake-build-release__ folder.
 
 ---
-### Add Library To Your CMake Project ###
+### Link ls-std Libraries (CMake) ###
 
-If you would like to add this library to your CMake project (__CMakeLists.txt__ file), make sure that you would add the libraries' include directory:
+If you would like to add this library's modules to your own CMake project, make sure that you would add the libraries' include directory:
 
 ```
 include_directories(${CMAKE_CURRENT_LIST_DIR}/path/to/this/library/include)
 ```
 
-Then link the libraries' binary file inside your __CMakeLists.txt__ file:
+Then link the libraries' binary files, like:
 
 ```
-target_link_libraries(... libls-std-core libls-std-boxing ...)
+target_link_libraries(... ls-std-core ls-std-boxing ...)
 ```
 
 ---
-### Testing ###
 
-This project contains unit tests to provide test coverage.  
-To run those tests you have to build this project with option __LS_STD_BUILD_WITH_TESTS__ set to __ON__ - then reset and reload the CMake project.
+### Run Automated Tests ###
+
+When enabling test build CMake flag during CMake project generation, executable test suite binaries will be generated during project compilation.  
+You would then find individual module test suites, as well as a whole project test suite, which can be run via CLI.