BUILDING AND USING A COMPATIBLE GEOS REPLACEMENT
GEOS 3.13.1 / C API 1.19.2 / Shapely 2.1.2 / Windows x64

This is an optional procedure for exercising LGPL library modification rights.
It is not part of ordinary PDN Analyzer installation or use. Work in a separate
folder you control, close all KiCad/PDN Analyzer processes, and retain the
official installation. The supplied utility never updates production services
or application registry entries and never overwrites the official installation.

1. Obtain the build prerequisites.

GEOS 3.13.1 uses CMake >= 3.15 and a C++14 compiler. The upstream Shapely
Windows recipe uses an x64 MSVC build environment, CMake and Ninja; exact
upstream files are under upstream/. Microsoft Visual Studio Build Tools with
the C++ tools and Windows SDK can provide that environment. Obtain tools from
their official publishers; compiler SDKs are not included in this archive.

Open the x64 Native Tools Command Prompt for Visual Studio and launch
Windows PowerShell from it so the MSVC compiler environment is inherited.
Confirm that cl, cmake and ninja are available. Do not mix an x86 compiler
with an x64 Python/KiCad installation.

An alternative compatible x64 C++ toolchain may be used if both GEOS DLLs are
rebuilt as a pair, their C API is compatible, and required runtime dependencies
are available. Using another toolchain does not imply bit-identical output.

2. Extract and review the complete source.

Verify the source SHA-256 in README.txt and extract geos-3.13.1.tar.bz2 with a
tool that handles tar/bzip2, such as 7-Zip. Preserve the original tarball and
licenses. The extraction produces a geos-3.13.1 folder containing source,
headers, COPYING, tests and CMake build files. The original official Elecmore
distribution has no Elecmore changes to GEOS source. The included upstream
Shapely recipe also applies no GEOS source patches.

You may modify GEOS under its LGPL terms. Preserve copyright/license notices,
identify modified files and dates, and follow the LGPL if distributing your
modified GEOS. Keep an unmodified copy for comparison.

3. Preserve the DLL names required by the existing Shapely bindings.

The shipped bindings dynamically import these exact names:

  geos-ae6efa0782962b98e358f10ea539ae5f.dll
  geos_c-072b7a9224d16d3e4ab2395bb855b2d3.dll

The geos_c DLL must itself import the matching geos DLL. Renaming only the
finished DLL filenames is insufficient because import names are embedded in
the binaries. Build both with the required output names.

In your separate extracted source folder, append the following to the END of
the root CMakeLists.txt, after both targets have been defined. Identify this
as your local build-script change with its date in the preceding comment:

  # Local user build-script change: named DLL pair for Shapely 2.1.2.
  # Modified by: <your name>; date: <YYYY-MM-DD>.
  if(WIN32)
    set_target_properties(geos PROPERTIES PREFIX ""
      OUTPUT_NAME "geos-ae6efa0782962b98e358f10ea539ae5f")
    set_target_properties(geos_c PROPERTIES PREFIX ""
      OUTPUT_NAME "geos_c-072b7a9224d16d3e4ab2395bb855b2d3")
  endif()

This modifies only the third-party source copy. Do not alter the installed
Shapely bindings, proprietary PDN native extensions or official loaders.

4. Build and test.

From the folder containing the extracted source, using the x64 compiler
environment, run these commands. They use fresh relative build/install folders:

  cmake -S .\geos-3.13.1 -B .\geos-build -G Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON -DBUILD_TESTING=ON -DCMAKE_INSTALL_PREFIX="$PWD\geos-install"
  cmake --build .\geos-build --parallel 2
  ctest --test-dir .\geos-build --output-on-failure
  cmake --install .\geos-build

Stop if compilation, linking or tests fail. The installed pair is normally
under geos-install/bin. Verify both DLLs are x64 PE files and geos_c imports
the exact geos filename above. If adding dependencies with a different build
toolchain, ensure they are available to the local process; the supplied utility
copies only the two named GEOS DLLs. Its MIT-licensed source may be adapted
when additional legitimate library support files are needed.

5. Create the separate local copy.

Extract this compliance ZIP. The root contains Relink-GEOS.ps1 and MIT.txt.
Use Windows PowerShell 5.1 or later. Replace these example paths with your
installed application folder, the directory holding your rebuilt pair, and a
NEW destination that is separate from both existing folders:

  powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Relink-GEOS.ps1 -OriginalInstallation "C:\Users\YourName\AppData\Local\Programs\Elecmore\PDN Analyzer" -ReplacementDirectory "C:\GEOSWork\geos-install\bin" -LocalCopy "C:\GEOSWork\PDNAnalyzer-local"

The ExecutionPolicy option applies only to this explicit PowerShell process;
it does not change the machine/user policy. If your organization's policy
prohibits it, use its approved method for running the reviewed script.

The utility checks the original manifest signature, every original protected
file, and the five expected loader/verifier hashes. It copies those verified
files, replaces the two GEOS DLLs, generates a fresh local RSA key, updates only
the same public loader/verifier pins and local installation lookup, and signs
the local inventory. No Elecmore/server private key is needed. Every other
file, including all proprietary native extensions, retains its verified bytes.
Read LOCAL_MODIFIED_NOTICE.txt in the resulting folder.

6. Verify compatibility before using the local copy.

First run its normal command-line help using the selected KiCad Python:

  & "C:\Program Files\KiCad\10.0\bin\python.exe" -B "C:\GEOSWork\PDNAnalyzer-local\plugin\pdn_analyzer_cli.py" --help

Use the existing documented CLI/standalone GUI and authenticate normally.
Compare geometry operations and DC engineering outputs with the official
installation before relying on results. Do not assume a successful import
proves numerical equivalence or certification of your modified library.

7. Optional use through KiCad's External Plugins menu.

Close KiCad. Locate the actual user plugin directory used by your installation
of pcbnew (SETTINGS_MANAGER.GetUserSettingsPath() plus scripting/plugins).
Retain the original official loader and disable it while testing the local
copy, for example by renaming pdn_analyzer_loader.py to a non-.py filename
such as pdn_analyzer_loader.py.disabled. Then copy the LOCAL copy's
plugin/pdn_analyzer_loader.py into that directory with a distinct filename,
for example pdn_analyzer_local_geos_loader.py. Restart KiCad.

Do not load both versions in the same KiCad/Python process. The same plugin
namespace is intentionally protected against mixed installations. The local
loader names its own local folder and does not change the official registry
registration. Account login, OTP and server entitlements remain required.

To restore ordinary use: close KiCad, remove the local plugin loader, restore
the official loader's original .py filename, and restart KiCad. Your original
installation remains unchanged. An official update may restore its loader;
repeat this optional procedure from the new official package if still needed.

LICENSES AND IDENTITY

GEOS source and modifications remain subject to the LGPL. Relink-GEOS.ps1 and
these Elecmore-authored supporting instructions are offered under MIT.txt.
The optional local copy is user-modified and is not an official Elecmore
release. Elecmore's proprietary EULA does not override LGPL modification,
relinking, redistribution or debugging rights for the covered components.
