Add HEMTT setup script for Windows and document HEMTT use (#9184)

.github/workflows/arma.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the source code
-      uses: actions/checkout@master
+      uses: actions/checkout@v3
     - name: Validate SQF
       run: python3 tools/sqf_validator.py
     - name: Validate Config
@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the source code
-      uses: actions/checkout@master
+      uses: actions/checkout@v3
     - name: Lint (sqflint)
       uses: arma-actions/sqflint@master
       continue-on-error: true # No failure due to many false-positives
@@ -36,13 +36,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the source code
-      uses: actions/checkout@master
+      uses: actions/checkout@v3
-    - name: Build using HEMTT
+    - name: Setup HEMTT
-      uses: arma-actions/hemtt@master
+      uses: arma-actions/hemtt@v1
-      with:
+    - name: Run HEMTT build
-        command: build --release --ci
+      run: hemtt build
+    - name: Rename build folder
+      run: mv .hemttout/build .hemttout/@ace
     - name: Upload Artifact
-      uses: actions/upload-artifact@v2-preview
+      uses: actions/upload-artifact@v3
       with:
         name: ace3-${{ github.sha }}-nobin
-        path: releases/ace3_*.zip
+        path: .hemttout/@*

.github/workflows/extensions.yml

@@ -7,14 +7,14 @@ on:
 
 jobs:
   build:
-    runs-on: ${{ matrix. os }}
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [windows-latest]
 
     steps:
     - name: Checkout the source code
-      uses: actions/checkout@master
+      uses: actions/checkout@v3
     - name: Build
       shell: cmd
       run: |
@@ -23,7 +23,7 @@ jobs:
         cd build
         cmake .. && cmake --build .
     - name: Upload Artifact
-      uses: actions/upload-artifact@master
+      uses: actions/upload-artifact@v3
       with:
         name: ace3_extensions-${{ matrix.os }}-debug
         path: extensions/build

.hemtt/project.toml

@@ -1,6 +1,7 @@
 name = "ACE3"
 prefix = "ace"
 author = "ACE-Team"
+mainprefix = "z"
 
 [files]
 include = [
@@ -18,10 +19,6 @@ include = [
 [version]
 git_hash = 0
 
-# TODO Enable once templating is added in v0.10
-#[properties]
-#version = "{{git \"id 8\"}}"
-
 [asc]
 enabled = true
 exclude = [
@@ -34,4 +31,9 @@ exclude = [
 ]
 
 [hemtt.config]
-preset = "Hemtt" # TODO will change after v0.10-a14
+preset = "Hemtt"
+
+[hemtt.launch]
+workshop = [
+    "450814997", # CBA_A3's Workshop ID
+]

docs/wiki/development/setting-up-the-development-environment.md

@@ -14,21 +14,27 @@ This page describes how you can setup your development environment for ACE3, all
 
 - Arma 3
 - Arma 3 Tools (available on Steam)
-- P-drive
 - Run Arma 3 and Arma 3 Tools directly from steam once to install registry entries (and again after every update)
+- [CBA](https://github.com/CBATeam/CBA_A3/releases/latest) mod (release or development version)
+
+**HEMTT:** _(recommended)_
+- [Windows] PowerShell v3.0+ _(pre-installed on Windows 8 or newer)_
+- [HEMTT](https://github.com/BrettMayson/HEMTT/releases) (>=v1.3.2) in project root _(Windows users can double-click `tools/setup.bat`)_
+    - `hemtt` (Linux) or `hemtt.exe` (Windows)
+
+**Mikero Tools:**
+- P-drive
 - [Python 3.x](https://www.python.org/)
 - [Mikero Tools](https://mikero.bytex.digital/Downloads): DePbo, DeOgg, Rapify, MakePbo, PboProject >=3.16
   - `*.hpp` removed from PboProject's "Exclude From Pbo" list
 - Python, Mikero Tools and Git in PATH environment variable
-- [CBA](https://github.com/CBATeam/CBA_A3/releases/latest) mod (release or development version)
-- [HEMTT](https://github.com/BrettMayson/HEMTT) is needed for "file patching" dev builds using build.py. Put hemtt.exe in root ace folder
 
 
 ## 2. Why so complicated?
 
-If you have contributed to AGM you might be used to an easier build process, where there was even an .exe you could use for building. ACE3, however, makes use of CBA macros to simplify things and give the developer access to a better debug process, which requires a stricter build environment. Additionally, Mikero's Tools are stricter and report more errors than AddonBuilder does. The structure of this development environment also allows for [file patching](#7-file-patching), which is very useful for debugging.
+If you have contributed to AGM you might be used to an easier build process, where there was even an .exe you could use for building. ACE3, however, makes use of CBA macros to simplify things and give the developer access to a better debug process, which requires a stricter build environment. Additionally, HEMTT and Mikero's Tools are stricter and report more errors than AddonBuilder does. The structure of this development environment also allows for [file patching](#7-file-patching), which is very useful for debugging.
 
-Not offering .exes for the Python scripts we use allows us to make easy changes without the hassle of compiling self-extracting exes all the time.
+Not including `.exe`s in the repository for the tools we use allows us to make easy changes without the hassle of compiling self-extracting exes all the time.
 
 
 ## 3. Getting Source Code
@@ -38,7 +44,50 @@ To actually get the ACE3 source code on your machine, it is recommended that you
 If you just want to create a quick and dirty build, you can also directly download the source code using the "Download ZIP" button on the front page of the GitHub repo.
 
 
-## 4. Setup and Building
+## 4. Setup and Building (HEMTT)
+
+_Replace `hemtt` with `hemtt.exe` on Windows. P-drive is **not** required for HEMTT or file patching._
+
+### 4.1 Initial Setup
+
+Execute `tools\setup.bat` (double-click on Windows) or download [HEMTT](https://github.com/BrettMayson/HEMTT/releases/latest) and place the executable in project root (Windows and Linux - binarization supported only on Windows at this time).
+
+#### 4.1.1 File Patching Setup
+
+ACE3 comes pre-configured for testing with [file patching](#file-patching) using only CBA's latest published version. You must subscribe to [CBA_A3](https://steamcommunity.com/workshop/filedetails/?id=450814997) on the Workshop.
+
+If you intend to test using file patching with CBA versions different than latest published, or with other mods, further setup is required create the links manually. First, create a folder called `z` in your Arma 3 directory. Then run the following command as admin, replacing the text in brackets with the appropriate paths:
+
+```bat
+mklink /J "[Arma 3 installation folder]\z\ace" "[location of the ACE3 project]/.hemttout/dev"
+```
+
+### 4.2 Creating a Development Build
+
+Run `$ hemtt dev` to build the mod for use with [file patching](#file-patching) (with links to the original addon folders) without binarization (faster and often not needed for development). This will populate the `.hemttout/dev` folder with unbinarized PBOs, with links back to the original addon folders. You cannot distribute this build to others.
+
+Run `$ hemtt launch` to run ACE3 with pre-configured file patching. _Uses `$ hemtt dev` before launching Arma._
+
+To launch a development build using file patching with CBA versions different than latest published, or with other mods, you must build the mod with `$ hemtt dev` and start the game by providing a modline:
+```bat
+-mod=@CBA_A3;z\ace -skipIntro -noSplash -showScriptErrors -debug -filePatching
+```
+
+### 4.3 Creating a Test Build
+
+To create a development build to test changes or to debug something, execute `build.bat` (double-click on Windows) or run `$ hemtt build` in the root folder. This will populate the `.hemttout/build` folder with binarized PBOs. This type of build is meant for sharing, group testing, but not for release.
+
+To start the game using this build, you can use the following modline:
+```bat
+-mod=@CBA_A3;z\ace -skipIntro -noSplash -showScriptErrors -debug
+```
+
+### 4.4 Creating a Release Build
+
+To create a complete build that you can use without the source files, with full binarization and all optimizations, run `$ hemtt release` in the root folder. This will populate the `.hemttout/release` folder with binarized PBOs  and an archive in `releases` that you can redistribute. These handle like those of any other mod.
+
+
+## 4. Setup and Building (Mikero Tools)
 
 ### 4.1 Initial Setup
 
@@ -99,7 +148,7 @@ Different `make.py` command line options include:
 
 ## 7. File Patching
 
-File Patching allows you to change the files in an addon while the game is running, requiring only a restart of the mission. This makes it great for debugging, as it cuts down the time required between tests. Note that this only works with PBOs created using MakePBO, which `build.py` uses.
+File Patching allows you to change the files in an addon while the game is running, requiring only a restart of the mission. This makes it great for debugging, as it cuts down the time required between tests.
 
 To run Arma 3 with file patching add the `-filePatching` startup parameter (since Arma 3 v1.50, file patching is disabled by default).
 
@@ -136,4 +185,4 @@ Files must exist in the built PBOs for file patching to work. If you create a ne
 
 Configs are not patched during run time, only at load time. You do not have to rebuild a PBO to make config changes, just restart Arma. You can get around this though if you are on the dev branch of Arma 3 and running the [diagnostic exe](https://community.bistudio.com/wiki/Arma_3_Diagnostics_Exe). That includes `diag_mergeConfigFile` which takes a full system path (as in `diag_mergeConfigFile  ["p:\z\ace\addons\my_module\config.cpp"]`) and allows you selectively reload config files.
 
-If you need to add/remove files, then you'll need to run `build.py` again without the game running, and restart. That is all that is required to add new files for further use in testing.
+If you need to add/remove files, then you'll need to run HEMTT/`build.py` again without the game running, and restart. That is all that is required to add new files for further use in testing.

tools/setup.bat

@@ -0,0 +1,16 @@
+;@Findstr -bv ;@F "%~f0" | powershell -Command - & pause & goto:eof
+
+Write-Output "=> Downloading ..."
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+$url = "https://github.com/BrettMayson/HEMTT/releases/latest/download/windows-x64.zip"
+(New-Object Net.WebClient).DownloadFile($url, "hemtt.zip"); Write-Output "$url => hemtt.zip"
+
+Write-Output "`n=> Extracting ..."
+Expand-Archive -Path "hemtt.zip" -DestinationPath "..\." -Force; Write-Output "hemtt.zip"
+Remove-Item "hemtt.zip"
+
+Write-Output "`n=> Verifying ..."
+Start-Process -FilePath ..\hemtt.exe -ArgumentList --version -NoNewWindow -Wait
+
+Write-Output "`nTools successfully installed to project!"