==================== 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. 1. If your system is x64-based, ``Start Menu`` → ``Visual Studio 20XX`` → ``VS20XX x64 Native Tools Command Prompts``. If your system is x86-based, launch ``VS20XX x86 Native Tools Command Prompts``. 2. On the opened command prompt, change directory to the location where extracted ``bootstrap.bat`` exists. 3. Run ``bootstrap.bat``. 4. ``b2.exe`` will be generated, then run ``b2 --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. .. _devel_proj_gen: Generate project files --------------------------- 1. If you have installed CMake from installer, ``Start Menu`` → ``CMake`` → ``CMake (cmake-gui)``. If you have downloaded CMake directly, run ``bin\cmake-gui.exe``. 2. Fill ``Where is the source code:`` by the location of THRotator source code. 3. Fill ``Where to build the binaries:`` by the location of project files you want to generate. 4. Press ``Configure``. Then generator selection window appears. Choose ``Visual Studio XX 20XX`` and press ``Finish``. Don't choose a generator name with Win64 or ARM. 5. Set the boost installation directory (where bootstrap.bat exists) to ``BOOST_INCLUDE_DIR``. 6. Set the boost library directory (``\stage\lib`` by default) to ``BOOST_LIB_DIR``. 7. Press ``Configure`` again. If you don't see any errors, press ``Generate``. Build --------------------------------- 1. Open generated ``THRotator.sln``. 2. 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) 3. Build ``d3d8`` for THRotator based on Direct3D 8, build ``d3d9`` 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 ----------------------------- 1. Create ``localization_`` folder in the directory where ``localization_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 is ``localization_fr-FR`` and memorize language ID **0x040c**. 2. From ``localization_en-US``, copy ``CMakeLists.txt``, ``resource.h``, and ``THRotator_en-US.rc`` folder to ``localization_`` (in current example, copy to ``localization_fr-FR``). 3. Rename ``localization_\THRotator_en-US.rc`` to ``localization_\THRotator_.rc`` (in current example, rename to ``THRotator_fr-FR.rc``). 2 Prepare for CMake -------------------------- 1. Open ``localization_\CMakeLists.txt`` and replace all ``en-US`` occurrences with ````. Then replace **0x0409** in ``set(language_id 0x0409)`` to the memorized language ID. In current example replace with **0x040c**. This is the end of editing ``localization_\CMakeLists.txt``. 2. Open ``CMakeLists.txt`` in the root directory of THRotator, add ``add_subdirectory(localization_)`` 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 :ref:`devel_proj_gen`. 4 Translate ----------------- After reopening or reloading ``THRotator.sln``, you can find that a project ``localization_`` is added. From Resource View of Visual Studio, you can start to translate string table and dialog box resources that belong to ``localization_``. 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_``, ``.mui`` files are generated to the ```` folder located in the output directories of ``d3d8.dll`` and ``d3d9.dll``. Copy ``d3d8.dll`` or ``d3d9.dll`` and ```` 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 -------------------------- See ``_. 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 `` to create or update .po files that will be located in ``doc/locale//LC_MESSAGES/``. ```` 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 ``/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//make.bat html``." msgstr "" "特定の言語に対してマニュアルをビルドしたいときは、" "``docs-source/<言語>/make.bat html`` を実行してください。" 4 Build ^^^^^^^ Before actual build, run ``set SPHINXOPTS=-D 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`` by ``https://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.