yyc12345/libcmo21
1
0
Fork 0
Code Activity

chore: update build script

Browse Source 
- change project layout for better understanding.
- update build script for more close to standard cmake way.
This commit is contained in:
yyc12345
2026-01-24 17:13:54 +08:00
parent af6a50c2f9
commit f9ab66dfc2
78 changed files with 290 additions and 283 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
COMPILE.md
View File

@@ -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): For image read and write.
* [YYCCommonplace](https://github.com/yyc12345/YYCCommonplace): My personal invented library concentrating some common functions for mine.
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).
* [stb](https://github.com/nothings/stb).
* [YYCCommonplace](https://github.com/yyc12345/YYCCommonplace).
* Doxygen (Required if you build documentation).
## 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.
* 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. Clone YYCCommonplace first.
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.
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.
> [!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.
### 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,109 @@ 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> ../..`
- 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> ../..`
Doxygen is required only if you need to build documentation.
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.
* `<path-to-yycc-install>`: The directory to installed CMake package you chosen when building YYCCommonplace.
* `<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`.
YYCCommonplace use Doxygen as its documentation system.
So before compiling, you must make sure `doxygen` are presented in your environment.
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.
* `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.
There are 2 different ways to build this project.
If you are the user of this project (just want this project to make something works), please choose "User Build".
If you are a developer (developer of this project, or use this project as dependency to develop your project), please choose "Developer Build".
### Build
### User Build
Execute following command to build libcmo21.
"User Build" is basically how GitHub Action build this project.
* Windows: `cmake --build . --config RelWithDebInfo`
* non-Windows: `cmake --build .`
Under **the root directory** of this project, execute:
### Build Type
- `Script/windows_build.bat` on Windows
- or `Script/linux_build.sh` on Linux
- or `Script/macos_build.sh` on macOS
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.
The final built artifact is under `Bin/install` directory.
## Install
### Developer Build
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.
#### Configurable Variables
## Note
First, there is a list listing all variables you may configure during compiling.
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.
* `NEMO_BUILD_UNVIRT`: Set it to `ON` to build `Unvirt`. `ON` in default.
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.
#### Configure CMake
When configure CMake, you may use different options on different platforms.
Following list may help you.
- 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.
Additionally, you can attach any variables introduced above with `-D` option during CMake configurations.
> [!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.
#### 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.