RP412/docs/BUILD-NOTES.md

# Repository & Build Findings

Notes from the initial git import and build assessment of the Red Planet v4.10
Win32 source. See [BUILD.md](../BUILD.md) for the practical build instructions;
this file records *what was found and what was changed*, and why.

---

## 1. What this repository is

- Win32 source for the game **Red Planet v4.10** (string confirmed in
  `RP_L4/rpl4.log`: `Red Planet v4.10`).
- Engine: **MUNGA** (`MUNGA/`) — a cross-platform C++ game/sim engine.
- Platform layer: **MUNGA_L4** (`MUNGA_L4/`) — Win32 + DirectX 9 backend
  (Direct3D 9, DirectInput 8, OpenAL audio, SOS audio middleware headers).
- Game code: **RP** (`RP/`) and **RP_L4** (`RP_L4/`).
- Support projects: **DivLoader** (asset/DIV loader), **Setup1** (installer).
- ~551 tracked files, ~9 MB.

### Toolchain detected on the import machine

At import time the build machine had **no usable C++ toolchain**:

- No Visual Studio, no `cl.exe`, no `VCBuild.exe`, no `vswhere`.
- Only .NET Framework `MSBuild.exe` (v2–v4) — which cannot build `.vcproj`.
- MinGW gcc/g++ (unusable for this MSVC/DirectX codebase).
- The required **DirectX SDK (March 2009)** was not installed.

A build attempt confirmed the blocker:

```
error MSB3428: Could not load the Visual C++ component "VCBuild.exe".
```

Building therefore requires installing VS 2005/2008 + the DirectX SDK
(the user is sourcing these separately).

---

## 2. Changes made during preparation

### 2.1 Git hygiene (initial import commit)

- Removed stale **Subversion** metadata (`Setup1/.svn/`) that pointed at a dead
  server (`https://dev.vgcorps.com/svn/WinTesla`).
- Added [`.gitignore`](../.gitignore) — VS build artifacts, IDE state, `*.log`,
  OS cruft. This excludes the runtime log `RP_L4/rpl4.log`.
- Added [`.gitattributes`](../.gitattributes) — normalizes line endings, forces
  CRLF on Win32 source, marks `.lib/.res/.egg/.rtf` as binary.

### 2.2 Solution cleanup (`WinTesla.sln`)

The original solution referenced **10** projects, but only **4** exist in the
repo. The 6 dangling references were removed so the solution loads cleanly:

| Removed project | Path referenced | Present? |
|-----------------|-----------------|----------|
| BT410_L4 | `BT410_L4\BT410_L4.vcproj` | ❌ missing |
| TextureExp | `TextureExp\TextureExp.vcproj` | ❌ missing |
| MeshExp | `MeshExp\MeshExp.vcproj` | ❌ missing |
| SphereExp | `SphereExp\SphereExp.vcproj` | ❌ missing |
| DetailExp | `DetailExp\DetailExp.vcproj` | ❌ missing |
| MatReplaceExp | `MatReplaceExp\MatReplaceExp.vcproj` | ❌ missing |

Remaining (present) projects: **RP_L4, Munga_L4, RPL4TOOL, DivLoader**.
Their `GlobalSection(ProjectConfigurationPlatforms)` entries were pruned to
match. `SolutionConfigurationPlatforms` (Debug/Release/Remote Debug | Win32)
were left unchanged.

> The 6 missing projects appear to be model/texture exporter tools and a sister
> game project (`BT410` — a different pod title) that live in other
> repositories. If you obtain them, re-add them to the solution.

### 2.3 DirectX SDK path un-hardcoded

`Munga_L4.vcproj` and `RP_L4.vcproj` (the VS2005 / v8.00 files) hardcoded:

```
C:\Program Files (x86)\Microsoft DirectX SDK (March 2009)\Include
C:\Program Files (x86)\Microsoft DirectX SDK (March 2009)\Lib\x86
```

Both were replaced (6 occurrences each) with the installer-provided variable,
matching what the existing `... VS2008.vcproj` variants already used:

```
$(DXSDK_DIR)Include
$(DXSDK_DIR)Lib\x86
```

`DXSDK_DIR` is set by the DirectX SDK installer and ends in a trailing
backslash, so `$(DXSDK_DIR)Include` resolves correctly.

> **Status update:** the **DirectX SDK (June 2010)** is now installed at
> `C:\Program Files (x86)\Microsoft DirectX SDK (June 2010)\`, and `DXSDK_DIR`
> is set machine-wide to that path. All required headers (`d3d9.h`, `d3dx9.h`,
> `dinput.h`) and libs (`d3d9.lib`, `d3dx9.lib`, `dxerr.lib`, `dxguid.lib`) are
> present. The un-hardcoded projects resolve to it automatically.

### 2.4 ATL removed (enables VC++ Express)

The Express editions of Visual C++ ship without ATL. The codebase's only ATL
usage was in `MUNGA_L4/L4APP.cpp` — `<atlbase.h>` / `<atlconv.h>` and the
`USES_CONVERSION` / `W2A` macros (28 references, all in that one file), used
purely to convert wide command-line arguments to ANSI in the arg parser. No
COM, no `CComPtr`, no ATL windows.

Changes:
- Replaced the ATL includes with a self-contained `L4WideToAnsi` helper class
  (a `WideCharToMultiByte` wrapper) plus local `USES_CONVERSION` / `W2A` macros
  that reproduce ATL's `W2A` semantics — each use yields an independent buffer
  valid until the end of the enclosing full-expression. Every call site consumes
  the result immediately (compare via `stricmp`, assign to MUNGA's `CString`,
  or pass to `atoi`/`atol`), so the behaviour is identical.
- Set `UseOfATL="0"` in `Munga_L4.vcproj`, `RP_L4.vcproj`, and the two `VS2008`
  variants.

`CString` in this file is **MUNGA's own** class (`MUNGA/CSTR.h`), not ATL's, so
dropping the ATL headers does not affect it.

### 2.5 Wire remaining DirectX SDK paths (build now succeeds)

The first real build attempt surfaced two projects that referenced DirectX but
were never repointed at `$(DXSDK_DIR)` (they had no hardcoded path to replace in
§2.3):

- **DivLoader** failed to compile (`VGCDivLoader.h`: cannot open `D3DX9.h`).
  Added `AdditionalIncludeDirectories="$(DXSDK_DIR)Include"` to both compiler
  configurations.
- **RPL4TOOL** failed to link (`LNK1181: cannot open input file 'dinput8.lib'`).
  Added `$(DXSDK_DIR)Lib\x86` to `AdditionalLibraryDirectories` in both
  `RPL4TOOL.vcproj` and `RPL4TOOL VS2008.vcproj`.

After these edits: **`4 Projects succeeded, 0 Projects failed`** for
`Release|Win32`.

> **Environment gotcha:** the DirectX SDK installer sets `DXSDK_DIR` at machine
> scope, but any shell already running when it was set won't inherit it. The
> first build failed on `D3DX9.h` purely because the build shell had an empty
> `DXSDK_DIR`; setting it explicitly in the build script fixed it. See the CLI
> recipe in [BUILD.md](../BUILD.md) §7.

### 2.6 Build outputs kept out of git

The Release build writes `Munga_L4.lib` and `DivLoader.lib` into the tracked
`lib/` directory (that is their configured output path). These are build
artifacts — `Munga_L4.lib` alone is ~200 MB — and are now git-ignored by name.
The two genuine dependency libs in `lib/` (`OpenAL32.lib`, `libsndfile-1.lib`)
remain tracked. Executables and per-project `Release/`/`Debug/` intermediate
folders were already covered by `.gitignore`.

---

## 3. Project reference data

Collected from the `.vcproj` files for quick reference.

### Configuration types
- `ConfigurationType="1"` → Application (exe): `RP_L4`, `RPL4TOOL`
- `ConfigurationType="4"` → Static library: `Munga_L4`, `DivLoader`

### Link dependencies
- **Munga_L4:** `OpenAL32.lib D3D9.lib D3DX9.lib DXERR.lib`
- **RP_L4:** `WS2_32.lib Munga_l4.lib dinput8.lib dxguid.lib openal32.lib
  libsndfile-1.lib d3dx9.lib d3d9.lib dbghelp.lib`
- **RPL4TOOL:** `Munga_l4.lib libsndfile-1.lib WS2_32.lib dinput8.lib dxguid.lib`

### Preprocessor definitions (RP_L4)
- Debug: `WIN32;_DEBUG;_WINDOWS;_CRT_SECURE_NO_DEPRECATE`
- Release: `WIN32;_WINDOWS;_CRT_SECURE_NO_DEPRECATE`

### Character set
- `Munga_L4`, `RP_L4`, `RPL4TOOL`: `CharacterSet="1"` (Unicode)
- `DivLoader`: `CharacterSet="2"` (MBCS)

---

## 4. Orphaned / non-build files (informational)

These files are present but are **not referenced by any project**, so they do
not affect the build. Left in place for historical completeness:

- `MUNGA_L4/JOYSTICK.asm` — MASM source, **not** in any `.vcproj`. No MASM
  toolchain is required to build. (`L4JOYSTK.h` exists but the `.asm` is unused.)
- `MUNGA_L4/sos/SOSMAWE.C` and the `sos/bc4`, `sos/wc` header trees — SOS audio
  middleware for old Borland/Watcom compilers; headers only.
- `RP_L4/TEST.EGG`, `RP_L4/last.egg` — `.egg` data blobs. `last.egg` is likely
  runtime-generated ("last loaded"); kept in tracking pending confirmation.
- `docs/audionotes.rtf` — design notes.

---

## 5. Open questions for the owner

1. Are the 6 removed projects (BT410_L4, *Exp tools) needed here, or do they
   belong to separate repos?
2. Is `RP_L4/last.egg` a real asset or generated output? If generated, add it to
   `.gitignore` and untrack it.
3. Which VS version is the target going forward — keep VS2005/2008 `.vcproj`, or
   upgrade to `.vcxproj` for a modern VS + Windows SDK (dropping the legacy
   DirectX SDK in favor of the Windows SDK's Direct3D)?