GNU Chess 3D - standard PC/GEOS SDK build
=============================================

Layout
------
Extract this bundle over the root of a PC/GEOS checkout:

  Appl/GNUChess/...
  Installed/Appl/GNUChess/local.mk

ROOT_DIR and WATCOM must already be set as required by the PC/GEOS SDK, and
wpp, perl, mkmf and pmake must be on PATH.

Linux
-----
  cd "$ROOT_DIR/Installed/Appl/GNUChess"
  mkmf
  pmake depend
  pmake full

Windows cmd.exe
---------------
  cd /d %ROOT_DIR%\Installed\Appl\GNUChess
  mkmf
  pmake depend
  pmake full

German edition
--------------
Start with a clean Installed/Appl/GNUChess build directory and run:

  mkmf
  pmake depend GNUCHESS_LANGUAGE=de
  pmake full GNUCHESS_LANGUAGE=de

Keep the English outputs before rebuilding. The SDK uses the same object
and output names in both languages. The default language is English.
The checked-in German catalog is compiled into each German geode.

What local.mk adds
------------------
* 30 GNU Chess C++ engine objects to OBJS.
* .cpp -> .obj and .cpp -> .eobj transformations using Open Watcom wpp.
* 16-bit 8086 instruction selection for the GOC interface and C++ engine.
* Optional GNUCHESS_LANGUAGE=de for a standalone German geode.
* GCxxxx text segment names required by the GEOS resource layout.
* -zt512 so the expected *_DATA1 / *_DATA2 far-data segments are emitted.
* OMF normalization after each C++ compile.
* OMF normalization of gnuchess.obj / gnuchess.eobj before Glue links.
* Engine-header dependencies (coarse: any engine .h change rebuilds all C++).

Useful targets
--------------
  pmake cpp          Build only the non-EC C++ engine objects.
  pmake cppec        Build only the EC C++ engine objects.
  pmake prebuild     Build/normalize gnuchess.obj plus NC engine objects.
  pmake prebuildec   Build/normalize gnuchess.eobj plus EC engine objects.
  pmake full         Normal complete PC/GEOS build.

OMF normalizer
--------------
The normal SDK build requires Perl. The checked-in artwork and the
separate runtime language catalogs do not need regeneration to build.

Manual Linux use:
  "$ROOT_DIR/Appl/GNUChess/tools/omf_normalize.sh" foo.obj bar.obj

Manual Windows use:
  %ROOT_DIR%\Appl\GNUChess\tools\omf_normalize.cmd foo.obj bar.obj

Both front ends use omf_normalize.pl because Perl is already a standard
PC/GEOS SDK prerequisite on Linux and Windows. local.mk calls the Perl core
directly so the makefile itself is host-independent.

Notes
-----
Open Watcom warnings such as W367/W368 (constant condition), W013
(unreachable code after constant folding), and W014 (unused header symbol) are
expected in this port. -fr is used for engine C++ compilation so warnings are
printed to the console without creating .err side files.

3D variant identity
-------------------
The source/build directories and output filenames remain GNUChess/gnuchess.
The permanent geode name is gchess3d.app; the token is Gc3D. The packaged
NC/EC files are GCHESS3D.GEO/GCHES3EC.GEO. Optional language catalogs use
USERDATA/GCHESS3D.VM and do not override the original 2D application's VM.
Both board renderers use native GEOS integer graphics. The document token
is Gc3S (manufacturer 0), distinct from the Gc3D application token. Native
GEOS documents use protocol 1.0 and include a checked application map; they
are not FEN text files. The document UI uses published GenDocumentControl,
GenDocumentGroup and GenDocument hooks, with process-thread document objects.
No private interpretation of the system New/Open preference is required.

New Game and options
-------------------
New Game uses a native modal radio-button interaction for White/Black before
the previous document's native Save/Discard/Cancel close sequence. It does
not reset an existing game when the colour dialog is cancelled. File commands
retain Ctrl+N/O/W/S and the native Exit command retains F3. A native glyph
separator precedes Exit; board preferences are in the separate Options menu.

The persistent options use published InitFile APIs and the following keys:

  [gnuchess3d]
  board2D = true/false
  showLegalMoves = true/false

GCGetLegalMoves runs on the process thread and publishes a 64-byte legal
destination mask with the board snapshot. The UI thread renders hints from
that cache and never calls the engine during drawing. Neither view option
marks the game document dirty. The existing process stack and engine arena
are retained; no framebuffer or extra engine allocation is introduced.

The checked-in appicons.goh includes updated transparent black-knight
desktop icons at 48x30 and 64x40. The standard build requires no artwork
regeneration. Optional generation/checking uses generate_appicons.py;
--exports also refreshes those large PNG/BMP editing exports and needs Pillow.

Optional native Linux harness for a Windows-only SDK archive
-----------------------------------------------------------
This does not change the application build process above. When the SDK only
contains Windows host executables, the following helpers build native host
utilities from a separate public PC/GEOS source checkout. They do not build or
replace target system libraries. GCC, ar, patch, Perl, Python 3, sed and the
Open Watcom Linux tools must already be available.

  python3 tools/setup_linux_sdk.py --pcgeos-source /path/to/pcgeos-sources \
      --sdk-root /path/to/extracted-sdk --watcom-root /path/to/watcom \
      --build-dir /path/to/native-tools
  . /path/to/native-tools/env.sh
  cd "$ROOT_DIR/Installed/Appl/GNUChess"
  mkmf
  pmake depend
  pmake -L 4 full

The helper prepares a source link and local.mk in a separate SDK copy, adds
only SDK-omitted host support scripts/headers, and writes env.sh/env.json.
It will refuse to replace an unrelated existing Appl/GNUChess directory.
The compatibility patches are applied to disposable host-tool copies.

For automated language builds and retained dist output:

  python3 tools/build_standard.py --env /path/to/native-tools/env.json \
      --language en --clean --logs build/en-logs --objects build/en-objects
  python3 tools/build_standard.py --env /path/to/native-tools/env.json \
      --language de --clean --logs build/de-logs --objects build/de-objects

The helper retains the original linker output and creates final .map summaries
using resource relocation counts from the linked header. Glue can relax local
calls in pass two after printing its map, so these counts can be lower than
stdout's preliminary counts. The structural inspector remains strict.

The four revised geodes were also audited with tools/audit_8086.py. It uses
wdis from the Open Watcom snapshot and GNU objdump, and needs the .obj/.eobj
inputs for the corresponding language. Example:

  python3 tools/audit_8086.py dist/English/NC/GCHESS3D.GEO \
      --map dist/English/NC/GCHESS3D.map --mode nc \
      --objects build/en-objects --wdis /path/to/watcom/binl64/wdis

The checked-in audit reports describe the packaged binaries. Re-linking changes
the generated creation time and geode serial number; they are not source or
machine-code differences. See docs/TEST-RESULTS.md for the current build summary and historical
Stone renderer evidence.
