189 lines
9.3 KiB
Plaintext
189 lines
9.3 KiB
Plaintext
/**
|
|
|
|
\page intro Introduction to YYCCommonplace
|
|
|
|
YYCCommonplace, or YYC Commonplace (abbr. YYCC),
|
|
is a static library providing various useful C++ functions
|
|
when programming with standard library or Windows environment.
|
|
|
|
During the development of a few projects,
|
|
I gradually understand how Windows make the compromise with the code written by its old developers,
|
|
and what is developer wanted in contemporary C++ standard library under Windows environment.
|
|
So I create this static library for all of my C++ project.
|
|
After this, I do not need to write these duplicated code in each project.
|
|
I can use a clear and easy way to manage these codes.
|
|
I can easily fix issues found in project using this library by updating a single project,
|
|
rather than fixing these duplicated code in each project one by one
|
|
because all of them share the same implementations.
|
|
|
|
This project mainly is served for my personal use.
|
|
But I would be honored if you would like to use this in your project.
|
|
Almost of my projects will gradually adapt to this project and drop their own individual implementations.
|
|
|
|
\section intro__why Why YYCCommonplace
|
|
|
|
\subsection intro__why__windows Windows Issues
|
|
|
|
I frequently program on Windows environment because the software I programming for, Virtools, is Windows-only software.
|
|
During programming, I found Windows is super lack in UTF8 supports.
|
|
Programmer loves UTF8, because it can handle all charcaters over the world in one encoding and is still compatible with C-Style string.
|
|
However, Windows use a weird way to achieve internationalization, 2 different function trailing, A and W for legacy code and modern code respectively.
|
|
The worst things is that the char type W trailing function used, \c WCHAR, is defined as 2 bytes long, not 4 bytes long as Linux does (\c wchar_t).
|
|
It mean that one emoji charcater will be torn into 2 \c WCHAR on Windows because emoji code unit is higher than the maximum value of \c WCHAR.
|
|
|
|
Also, there are various issues which should not be presented.
|
|
For example, Microsoft invents various \e safe standard library functions to prevent possible overflow issues raised by \c std::fgets and etc.
|
|
also, MSVC may throw weird error when you using some specific standard library functions.
|
|
You need to define some weird macros to disable this shitty behavior.
|
|
|
|
There are various non-standard issue you may faced on Windows programming.
|
|
All in all, programming on Windows is a tough work.
|
|
This is one of the reasons why I create this library.
|
|
I create much wrappers for these weird Windows functions.
|
|
Thus I can have a similar Linux C++ programming experience on Windows.
|
|
|
|
\subsection intro__why__std Standard Library Issues
|
|
|
|
The eccentric decision of standard commission also is the reason why I create this library.
|
|
|
|
\li C++ standard commission loves to bring one feature with N concepts and P assistant classes.
|
|
\li C++ standard commission seems doesn't want to bring any features the programmer urgent needed.
|
|
\li C++ standard commission loves delete programmer loved convenient functions and classes.
|
|
\li etc...
|
|
|
|
There is not a proper way to \e format a string in C++ until C++ 20 (\c std::format).
|
|
String related functions, such as split, lower, higher, replace, now still not be included in standard library.
|
|
Programmer loved, easy to used UTF8 procession functions and classes was deprecate now and will be removed in future.
|
|
|
|
That's why I create this library.
|
|
I bring these function in this library.
|
|
Not industrial level, but easy to use and have enough performance in my project.
|
|
|
|
\subsection intro__why__boost Boost Issues
|
|
|
|
Bosst is a powerful C++ library. But the shortcoming is overt. It's tooooo big.
|
|
This drawback will be more obvious considering the bad dependency mechanism of C++.
|
|
Although the most of Boost sub-library is header-only, but some library still need to link with Boost.
|
|
It order you download the whole Boost library and extract it in your hard disk.
|
|
Cost more than half hours, 5+ GB disk space and the life time of your disk.
|
|
|
|
The functions belonging to Boost is industrial level.
|
|
But what I want is not industrial level functions.
|
|
I only need a function which can barely finish my work. That's enough.
|
|
I don't need extreme performance. I just want my code works.
|
|
|
|
So I create this library, bring some Boost functions with ordinary but not bad implementation.
|
|
|
|
\section intro__usage Library Usage
|
|
|
|
Before using this library, I suggest you read this manual fully to have a full overview of this library.
|
|
Otherwise you may make mistake during using this library.
|
|
I suggest you read this manual from top to bottom in the left tree panel, one by one.
|
|
|
|
YYCC library self provides some build scripts for convenient use which are located in \c script directory.
|
|
Please note all of these script should be executed in the root of YYCC project, not the script directory
|
|
(i.e. work directory is the root directory of YYCC).
|
|
All scripts will try to do a simple check about this if you accidently execute them in a wrong place.
|
|
|
|
If you are not willing to use our build script, or our build script went wrong,
|
|
you can create your personal build script by viewing our build script.
|
|
|
|
\subsection intro__usage__linux Linux
|
|
|
|
Building YYCC on Linux is easy to do by executing <TT>script/linux_build.sh</TT>.
|
|
After script done, you will find installation result in directory <TT>bin/install</TT>.
|
|
Then other CMake project can utilize it (non-CMake project also can utilize this).
|
|
|
|
\subsection intro__usage__win Windows
|
|
|
|
For building on Windows, there are 2 distribution types which YYCC can create.
|
|
First is CMake distribution, this distribution is served for other CMake project using.
|
|
Another one is MSVC distribution, this distribution is served for other MSVC project using.
|
|
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
|
|
|
|
CMake distribution has following directory structure.
|
|
|
|
\verbatim
|
|
YYCC
|
|
├─Win32_Debug: Win32 Debug package
|
|
│ ├─include: Headers
|
|
│ └─lib: Library for linking and CMake package file
|
|
├─Win32_Release: Win32 Release package
|
|
│ ├─bin: Executable testbench
|
|
│ ├─include: Headers
|
|
│ └─lib: Library for linking and CMake package file
|
|
├─x64_Debug: x64 Debug package
|
|
│ ├─include: Headers
|
|
│ └─lib: Library for linking and CMake package file
|
|
└─x64_Release: x64 Release package
|
|
├─bin: Executable testbench
|
|
├─include: Headers
|
|
├─lib: Library for linking and CMake package file
|
|
└─share: Documentation
|
|
\endverbatim
|
|
|
|
Every different architecture and build type have a single and full directory.
|
|
CMake project can use one of by adding their build type in \c find_package path.
|
|
So that CMake will automatically utilize correct package when switching build type.
|
|
|
|
\subsubsection intro__usage__win__msvc MSVC Distribution
|
|
|
|
MSVC distribution has following directory structure.
|
|
|
|
\verbatim
|
|
YYCC
|
|
├─bin
|
|
│ ├─Win32: Win32 Release testbench
|
|
│ └─x64: x64 Release testbench
|
|
├─include: Headers
|
|
├─lib
|
|
│ ├─Win32
|
|
│ │ ├─Debug: Win32 Debug library for linking
|
|
│ │ └─Release: Win32 Release library for linking
|
|
│ └─x64
|
|
│ ├─Debug: x64 Debug library for linking
|
|
│ └─Release: x64 Release library for linking
|
|
└─share: Documentation
|
|
\endverbatim
|
|
|
|
The different between MSVC distribution and CMake distribution is
|
|
that MSVC distribution places all static library under one director \c lib.
|
|
Thus in MSVC project user can simply spcify the install path of YYCC,
|
|
and use MSVC macros in path to choose correct static library for linking
|
|
|
|
\section intro__debug Debug Tips
|
|
|
|
YYCC CMake build script contains a special option called \c YYCC_DEBUG_UE_FILTER.
|
|
If you set it to true, it will add a public macro \c YYCC_DEBUG_UE_FILTER to YYCC project.
|
|
This macro will enable special code path for the convenience of debugging \ref exception_helper related features.
|
|
So in common use, user should not enable this option.
|
|
|
|
*/
|