Development¶
Note
This page assumes development on Windows.
Get the THRotator source code¶
Clone the THRotator repository by git.
- DLL’s source code: massanoori/THRotator (GitHub).
- Manual’s source code: massanoori/THRotator-manual (GitHub).
Next, change directory to cloned directory and run git submodule update --init
.
This command downloads the source code of external libraries, fmt,
json.hpp, and ImGui.
Build THRotator¶
This section gives you an instruction to build THRotator from source code.
The prerequisites are the following:
- Microsoft Visual C++ (2015 or later)
- Boost C++ Libraries
- CMake
Install Microsoft Visual C++¶
Note
If you have installed Visual C++, skip this step.
Download Visual Studio from Home page of Visual Studio. Community Edition is just enough.
Since the installer of Visual Studio 2015, Visual C++ is not installed by default. Edit the installation option so that Visual C++ is installed.
Install Boost C++ Libraries¶
Note
If you have built filesystem
modules, skip this step.
Access to Boost C++ Libraries and download the latest release from Current Release.
Then extract ZIP archive to some location (for example C:\boost\
).
Next, build filesystem
modules by following the steps given below.
- If your system is x64-based,
Start Menu
→Visual Studio 20XX
→VS20XX x64 Native Tools Command Prompts
. If your system is x86-based, launchVS20XX x86 Native Tools Command Prompts
. - On the opened command prompt, change directory to the location where extracted
bootstrap.bat
exists. - Run
bootstrap.bat
. b2.exe
will be generated, then runb2 --with-filesystem runtime-link=shared,static
.
Install CMake¶
Note
If you have installed CMake 3.5 or later, skip this step.
Access to Home page of CMake. Then download one of the following from Download page.
- Windows win64-x64 Installer
- Windows win64-x64 ZIP
- Windows win32-x86 Installer
- Windows win32-x86 ZIP
If you are using x64-based system, you can use both win64-x64 and win32-x86. If you are using x86-based system, you can use only win32-x86.
Generate project files¶
- If you have installed CMake from installer,
Start Menu
→CMake
→CMake (cmake-gui)
. If you have downloaded CMake directly, runbin\cmake-gui.exe
. - Fill
Where is the source code:
by the location of THRotator source code. - Fill
Where to build the binaries:
by the location of project files you want to generate. - Press
Configure
. Then generator selection window appears. ChooseVisual Studio XX 20XX
and pressFinish
. Don’t choose a generator name with Win64 or ARM. - Set the boost installation directory (where bootstrap.bat exists) to
BOOST_INCLUDE_DIR
. - Set the boost library directory (
<boost install directory>\stage\lib
by default) toBOOST_LIB_DIR
. - Press
Configure
again. If you don’t see any errors, pressGenerate
.
Build¶
- Open generated
THRotator.sln
. - Five projects are loaded.
- ALL_BUILD (project to build all the other projects)
- d3d8 (THRotator based on Direct3D 8)
- d3d9 (THRotator based on Direct3D 9)
- localization_en-US (English resource DLL of THRotator)
- ZERO_CHECK (automatically generated by CMake)
- Build
d3d8
for THRotator based on Direct3D 8, buildd3d9
for THRotator based on Direct3D 9.
Localization¶
THRotator supports dialog boxes and error messages in multiple languages by Multilingual User Interface (MUI).
You can easily add new language based on English localization resource. Let’s look at how to add a new language with French example.
Note
This section doesn’t refer to the actual translation.
1 Copy template¶
- Create
localization_<language name>
folder in the directory wherelocalization_en-US
exists. Language name is one of Language/culture name found in Available Language Packs for Windows. This page also provides language ID in Language hexadecimal identifier, which should be memorized for a later step. Since example is French, folder name islocalization_fr-FR
and memorize language ID 0x040c. - From
localization_en-US
, copyCMakeLists.txt
,resource.h
, andTHRotator_en-US.rc
folder tolocalization_<language name>
(in current example, copy tolocalization_fr-FR
). - Rename
localization_<language name>\THRotator_en-US.rc
tolocalization_<language name>\THRotator_<language name>.rc
(in current example, rename toTHRotator_fr-FR.rc
).
2 Prepare for CMake¶
- Open
localization_<language name>\CMakeLists.txt
and replace allen-US
occurrences with<language name>
. Then replace 0x0409 inset(language_id 0x0409)
to the memorized language ID. In current example replace with 0x040c. This is the end of editinglocalization_<language name>\CMakeLists.txt
. - Open
CMakeLists.txt
in the root directory of THRotator, addadd_subdirectory(localization_<language name>)
to the final line.
In current French example, localization_fr-FR\CMakeLists.txt
finally looks like the following:
# resource language and its ID
# for a list of languages and IDs, visit https://msdn.microsoft.com/en-us/library/hh825678.aspx
set(language fr-FR) # Edited
set(language_id 0x040c) # Edited
include(../internationalization/THRotator_i18n.cmake)
CMakeLists.txt
finally looks like the following:
# Abbreviated
add_subdirectory(d3d9)
add_subdirectory(d3d8)
add_subdirectory(localization_en-US)
add_subdirectory(localization_fr-FR) # Added
3 Generate project files¶
Generate project files as described in Generate project files.
4 Translate¶
After reopening or reloading THRotator.sln
,
you can find that a project localization_<language name>
is added.
From Resource View of Visual Studio, you can start to translate string table and dialog box resources that belong to localization_<language name>
.
On property window, change language of string table and dialog boxes from English (United States)
to the language name you want to translate into.
In French example, change to French (France)
.
5 Build and launch¶
By building localization_<language name>
, .mui
files are generated to the <language name>
folder located in the output directories of d3d8.dll
and d3d9.dll
.
Copy d3d8.dll
or d3d9.dll
and <language name>
folder to the directory where the executable of the game is located.
If your system supports the language you are trying to add, GUI and messages are now in that language.
Note
The respective checksum of d3d8.dll
and d3d9.dll
is embedded to d3d8.dll.mui
and d3d9.dll.mui
.
If the embedded checksum doesn’t match that of .dll, that language will not be loaded.
Build manual¶
Sphinx is used to build the manual of THRotator.
The prerequisites are the following:
- Python
- Sphinx
- Items below are required for internationalization.
- Sphinx-intl
Install Python and Sphinx¶
Install Sphinx-intl¶
Sphinx-intl is a package for internationalization of sphinx.
To install it, run python -m pip install sphinx-intl
.
Build (English)¶
Open command prompt, change directory to docs/
, and run make.bat html
.
Then html files are generated in docs/_build/html/
.
Build (other languages)¶
Build manual in another language involves a bit complicated process.
1 Collecting texts to be translated¶
Open command prompt, change directory to docs/
, and run make.bat gettext
.
2 Create or update .po file¶
Run sphinx-intl.exe update -p .\_build\gettext -l <language>
to create or update .po files
that will be located in doc/locale/<language>/LC_MESSAGES/
.
<language>
is one of strings listed in Sphinx Documentation.
.po file contains pairs of original English text and translated text.
Note
sphinx-intl.exe is located in <Python installation>/Scripts/
3 Edit .po file¶
Add your translation to generated or updated .po file.
Single line translation example for Japanese:
msgid "THRotator User's Manual"
msgstr "THRotator ユーザーマニュアル"
Multi line translation example:
msgid ""
"If you would like to build the manual in a specific language,"
"run ``docs-source/<language>/make.bat html``."
msgstr ""
"特定の言語に対してマニュアルをビルドしたいときは、"
"``docs-source/<言語>/make.bat html`` を実行してください。"
4 Build¶
Before actual build, run set SPHINXOPTS=-D language=<language>
to specify the final language of manual.
Then run make.bat html
. Html files will be generated in docs/_build/html/
.
Continuous integration¶
THRotator owns two continuous integration (CI) projects on AppVeyor.
THRotator¶
https://ci.appveyor.com/project/massanoori/throtator
Simple build and packaging project.
This project builds INSTALL.vcxproj
generated by CMake.
Files copied by building INSTALL.vcxproj
will be treated as an artifact of the project.
THRotator-cov¶
https://ci.appveyor.com/project/massanoori/throtator-n7skl
This project builds cov-int
tarball required by Coverity Scan
to launch static analysis.
The built cov-int
directory is treated as an artifact of the project.
The project of Coverity Scan can be found here. If you are permitted to submit a build, you can launch a static analysis by following steps:
- Visit Submit a Project Build via URL.
- Fill
File URL
byhttps://ci.appveyor.com/api/projects/massanoori/throtator-n7skl/artifacts/build%2Fcov-int.zip
. - Click
Upload URL for analysis
.
Note
You can also upload cov-int.zip
downloaded from AppVeyor to Coverity Scan.
But it can take several minutes or hours to upload a file depending on your internet connection.
Incrementing version¶
The version format of THRotator adheres to Semantic Versioning 2.0.
Major version is incremented when:
- You have made huge design changes that affect user interactions.
- New data format is incompatible with older versions.
- You have made other revolutionary changes.
Minor version is incremented when:
- You have added new relatively big features or improvements.
- New data format is upgradable from, but irreversible to, older versions.
Patch version is incremented when:
- You have fixed small but important issues that should be released as soon as possible.
- You have added new relatively small features or improvements.
- Changes above don’t break forward- and backward-compatibility of data format.