From 59c185a424da699aa5f20529ed24caa02fe1e846 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Wed, 14 Aug 2024 17:26:38 +0800 Subject: [PATCH] doc: update build script and documentation. - update build script. - update documentation about build script changes. --- README.md | 5 +- doc/src/intro.dox | 37 +++++++--- script/.gitignore | 2 + script/gen_win_build.py | 9 +-- script/win_build.new.bat | 70 ------------------- script/{win_build.bat => win_build.old.bat} | 0 ..._msvc_build.bat => win_msvc_build.old.bat} | 0 7 files changed, 36 insertions(+), 87 deletions(-) create mode 100644 script/.gitignore delete mode 100644 script/win_build.new.bat rename script/{win_build.bat => win_build.old.bat} (100%) rename script/{win_msvc_build.bat => win_msvc_build.old.bat} (100%) diff --git a/README.md b/README.md index 70027b3..f9323c2 100644 --- a/README.md +++ b/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. -For other platforms building (e.g. Linux), you can following common builing way of CMake project. +See documentation for how to build this project. diff --git a/doc/src/intro.dox b/doc/src/intro.dox index c6a8b94..f8db8cb 100644 --- a/doc/src/intro.dox +++ b/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 python3 script/gen_win_build.py first. +Then execute script/win_build.bat 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 bin/cpp_ver/install. +and you will also find your MSVC distribution in directory bin/cpp_ver/msvc_install. +\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 script/win_build.bat. -After script done, you will find CMake distribution in directory bin/install 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. script/win_build.bat NODOC. +CMake distribution has following directory structure. \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, -because MSVC distribution depend on CMake distribution. - -After creating CMake distribution, you can simply create MSVC distribution by executing script/win_msvc_build.bat. -Then you will find your MSVC distribution in directory bin/msvc_install with following structure. -Same as CMake distribution, if you don't want built documentation, -please execute script/win_msvc_build.bat NODOC. +MSVC distribution has following directory structure. \verbatim YYCC diff --git a/script/.gitignore b/script/.gitignore new file mode 100644 index 0000000..ab184df --- /dev/null +++ b/script/.gitignore @@ -0,0 +1,2 @@ +# -------------------- Output -------------------- +win_build.bat diff --git a/script/gen_win_build.py b/script/gen_win_build.py index e88817d..f57cfe1 100644 --- a/script/gen_win_build.py +++ b/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) diff --git a/script/win_build.new.bat b/script/win_build.new.bat deleted file mode 100644 index ba3175d..0000000 --- a/script/win_build.new.bat +++ /dev/null @@ -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 diff --git a/script/win_build.bat b/script/win_build.old.bat similarity index 100% rename from script/win_build.bat rename to script/win_build.old.bat diff --git a/script/win_msvc_build.bat b/script/win_msvc_build.old.bat similarity index 100% rename from script/win_msvc_build.bat rename to script/win_msvc_build.old.bat