doc: update build script and documentation.

- update build script.
- update documentation about build script changes.

README.md

@@ -8,9 +8,10 @@ For more usage about this library, please build documentation of this project vi
 
 And I also highly recommend that you read documentation first before writing with this library.
 
+However, the documentation need CMake to build and you may don't know how to use CMake in this project. So as the alternative, you also can browse the raw Doxygen documentation file: `doc/src/intro.dox` for how to build this project (including documentation) first.
+
 ## Build
 
 This project require at least CMake 3.23 to build. We suggest that you only use stable version (tagged commit). The latest commit may still work in progress and not stable.
 
-For Windows builing, you can browse GitHub action script to have a preview. It actually is a simple calling to script file.
+See documentation for how to build this project.
-For other platforms building (e.g. Linux), you can following common builing way of CMake project.

doc/src/intro.dox

@@ -102,12 +102,33 @@ Another one is MSVC distribution, this distribution is served for other MSVC pro
 These have different directory layout which is specifically designed for corresponding build tools.
 See following section for more details.
 
+\subsection intro__usage__win__execute Execute Build Script
+
+For creating distribution on Windows, please execute script <TT>python3 script/gen_win_build.py</TT> first.
+Then execute <TT>script/win_build.bat</TT> to generate final result.
+
+\c script/gen_win_build.py is the generator of \c script/win_build.bat.
+It will accept various arguments and generate a proper real build script for you.
+Currently \c script/gen_win_build.py supports following arguments:
+
+\li \c -c, \c --cpp \c [cpp_version]: Specify the version of C++ standard for building.
+Due to the different defination of UTF8 char type,
+C++ 20 program can not use this library built by C++ 17 environment.
+So this switch give you a chance to decide the version of C++ standard used when building.
+The lowest and defult version of C++ standard is 17.
+\li \c -d, \c --no-doc: Specify this if you don't want to build documentation.
+End user usually needs documentation, 
+however if you are the developer of this library, you may need this switch.
+Because documentation take too much disk space and cost a bunch of time for building and copying.
+In default, generator will produce script which build documentation automatically.
+
+After script done, you will find CMake distribution in directory <TT>bin/<I>cpp_ver</I>/install</TT>.
+and you will also find your MSVC distribution in directory <TT>bin/<I>cpp_ver</I>/msvc_install</TT>.
+\e cpp_ver in path will be replaced by the C++ version you specified.
+
 \subsubsection intro__usage__win__cmake CMake Distribution
 
-For creating CMake distribution, please execute script <TT>script/win_build.bat</TT>.
+CMake distribution has following directory structure.
-After script done, you will find CMake distribution in directory <TT>bin/install</TT> with following structure.
-In default, building process will build documentation automatically.
-If you don't want built documentation, please execute with extra argument \c NODOC, i.e. <TT>script/win_build.bat NODOC</TT>.
 
 \verbatim
 YYCC
@@ -134,13 +155,7 @@ So that CMake will automatically utilize correct package when switching build ty
 
 \subsubsection intro__usage__win__msvc MSVC Distribution
 
-Before creating MSVC distribution, you should create CMake distribution first,
+MSVC distribution has following directory structure.
-because MSVC distribution depend on CMake distribution.
-
-After creating CMake distribution, you can simply create MSVC distribution by executing <TT>script/win_msvc_build.bat</TT>.
-Then you will find your MSVC distribution in directory <TT>bin/msvc_install</TT> with following structure.
-Same as CMake distribution, if you don't want built documentation, 
-please execute <TT>script/win_msvc_build.bat NODOC</TT>.
 
 \verbatim
 YYCC

script/.gitignore

@@ -0,0 +1,2 @@
+# -------------------- Output --------------------
+win_build.bat

script/gen_win_build.py

@@ -90,7 +90,7 @@ def cmake_build(f: io.TextIOWrapper, s: ScriptSettings) -> None:
     # build for Win32
     write_line(f, ':: Build for Win32')
     write_line(f, 'CD Win32')
-    write_line(f, f'cmake -G "Visual Studio 16 2019" -A Win32 -DCMAKE_CXX_STANDARD={s.m_CppVersion} -DYYCC_BUILD_TESTBENCH=ON ../..')
+    write_line(f, f'cmake -G "Visual Studio 16 2019" -A Win32 -DCMAKE_CXX_STANDARD={s.m_CppVersion} -DYYCC_BUILD_TESTBENCH=ON ../../..')
     write_line(f, 'cmake --build . --config Debug')
     write_line(f, 'cmake --install . --prefix=../install/Win32_Debug --config Debug')
     write_line(f, 'cmake --build . --config Release')
@@ -99,7 +99,7 @@ def cmake_build(f: io.TextIOWrapper, s: ScriptSettings) -> None:
     # build for x64
     write_line(f, ':: Build for x64')
     write_line(f, 'CD x64')
-    write_line(f, f'cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_CXX_STANDARD={s.m_CppVersion} -DYYCC_BUILD_TESTBENCH=ON ../..')
+    write_line(f, f'cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_CXX_STANDARD={s.m_CppVersion} -DYYCC_BUILD_TESTBENCH=ON ../../..')
     write_line(f, 'cmake --build . --config Debug')
     write_line(f, 'cmake --install . --prefix=../install/x64_Debug --config Debug')
     write_line(f, 'cmake --build . --config Release')
@@ -109,7 +109,7 @@ def cmake_build(f: io.TextIOWrapper, s: ScriptSettings) -> None:
     if not s.m_NoDoc:
         write_line(f, ':: Build for documentation')
         write_line(f, 'CD documentation')
-        write_line(f, f'cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_CXX_STANDARD={s.m_CppVersion} -DYYCC_BUILD_DOC=ON ../..')
+        write_line(f, f'cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_CXX_STANDARD={s.m_CppVersion} -DYYCC_BUILD_DOC=ON ../../..')
         write_line(f, 'cmake --build . --config Release')
         write_line(f, 'cmake --build . --target YYCCDocumentation')
         write_line(f, 'cmake --install . --prefix=../install/x64_Release --config Release')
@@ -159,8 +159,9 @@ if __name__ == '__main__':
     # build settings
     settings = ScriptSettings(args.cpp, args.no_doc)
     # write result
-    filepath = os.path.join(os.path.dirname(__file__), 'win_build.new.bat')
+    filepath = os.path.join(os.path.dirname(__file__), 'win_build.bat')
     with open(filepath, 'w') as f:
+        write_line(f, '@ECHO OFF')
         script_head(f, settings)
         create_directory(f, settings)
         cmake_build(f, settings)

script/win_build.new.bat

@@ -1,70 +0,0 @@
-:: Navigate to project root directory
-CD /d J:\YYCCommonplace
-:: Create build directory and enter it
-MKDIR bin
-CD bin
-MKDIR cpp20
-CD cpp20
-
-:: Create internal build directory
-MKDIR Win32
-MKDIR x64
-MKDIR documentation
-:: Create internal install directory
-MKDIR install
-CD install
-MKDIR Win32_Debug
-MKDIR Win32_Release
-MKDIR x64_Debug
-MKDIR x64_Release
-CD ..
-:: Create internal MSVC specific install directory
-MKDIR msvc_install
-CD msvc_install
-MKDIR bin
-MKDIR include
-MKDIR lib
-MKDIR share
-CD bin
-MKDIR Win32
-MKDIR x64
-CD ..
-CD lib
-MKDIR Win32\Debug
-MKDIR Win32\Release
-MKDIR x64\Debug
-MKDIR x64\Release
-CD ..
-CD ..
-
-:: Build for Win32
-CD Win32
-cmake -G "Visual Studio 16 2019" -A Win32 -DCMAKE_CXX_STANDARD=20 -DYYCC_BUILD_TESTBENCH=ON ../..
-cmake --build . --config Debug
-cmake --install . --prefix=../install/Win32_Debug --config Debug
-cmake --build . --config Release
-cmake --install . --prefix=../install/Win32_Release --config Release
-CD ..
-:: Build for x64
-CD x64
-cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_CXX_STANDARD=20 -DYYCC_BUILD_TESTBENCH=ON ../..
-cmake --build . --config Debug
-cmake --install . --prefix=../install/x64_Debug --config Debug
-cmake --build . --config Release
-cmake --install . --prefix=../install/x64_Release --config Release
-CD ..
-
-:: Copy header files
-XCOPY install\x64_Release\include msvc_install\include\ /E /Y
-:: Copy binary files
-COPY install\Win32_Release\bin\YYCCTestbench.exe msvc_install\bin\Win32\YYCCTestbench.exe /Y
-COPY install\x64_Release\bin\YYCCTestbench.exe msvc_install\bin\x64\YYCCTestbench.exe /Y
-:: Copy library files
-COPY install\Win32_Debug\lib\YYCCommonplace.lib msvc_install\lib\Win32\Debug\YYCCommonplace.lib /Y
-COPY install\Win32_Release\lib\YYCCommonplace.lib msvc_install\lib\Win32\Release\YYCCommonplace.lib /Y
-COPY install\x64_Debug\lib\YYCCommonplace.lib msvc_install\lib\x64\Debug\YYCCommonplace.lib /Y
-COPY install\x64_Release\lib\YYCCommonplace.lib msvc_install\lib\x64\Release\YYCCommonplace.lib /Y
-
-:: Leave build directory and report
-CD ..\..
-ECHO Windows CMake Build Done