 ▄▄▄▄▄▄▄▄                                            ░                  ▄▄▄▄▄▄
 █ ▄▄▄▄ ▓░    ░░▓▓▄▄▄▄▄▄    ░    ░          ▄▄▒▒   ░▄▓▀ ░░ ▄      ▄    ▄▀ ░░ █
 █ ████  ▄▄▄▄   ▀▀ ▄▄▄ ▀▄   ▓    ▓ ▀▀▀▀▀▓▄▄▄▄ ▀▓▄░▒▓▀ ▄▄▓▓  █▄ ▄█▀   ▄▀ ▄▄▓▓ █
 █ ████▄▄▄▄▄▄▀▄  ▄▀▄██▓▄ ▀▄  ▀▄  █ ▒▒▒ ▄▀▄████▄░▀▓▀ ▄█████   ██▀    ▀ ▄█████ █░
 █ ████████████ ▀▄███████▄ ▀▄  ▀▄█ ███▀▄█████████ ▄███████ ▄█▀▀█▄   ▄███████ ▀▓
▄▀▄████▒▒▀█████ ▓█████████▓▄ ▀▄    ▐█████  ▀▀▓███▄███▀████▀  ░░░▀▄ ▄████████░ █
 ▐█████   ▀████░████▓ ▀▓█████▄ ▀▄  ▐█████    ░▀█████ █████▄██▓▓▓   ██▓  ████▓ ▓
 ██████   ░████▓████░  ░██████▓▄ ▀▄ █████      ████  ██████████▌  ▄██░ ██████ ░
 ██████▄▄▄▓█████████     ▓███████▄ ▀█████▌  ░ ▐███   ██▀▀▀▀████▌ ░██▌  ▓▓▓▀▀▀
 ▓▓▓▓▓██████████████▄█▓▀ ░███▀█████▄ █████▄█▓▀▐███░  ▀▀▀▀▀ ████▌ ▓██▌  ▒▒▒▀▀▀░░
 ░░░░░▀▀▀▀▀▀█████████▀░    ██▓ ▀███████████▀ ▄ ███▓▄▄▄▄▄   █████ ▐███▄▄  ▄███▓▓
           ░███▓██▌▀    ░░████▓  ▀▓█████▌▀ ▄▀  ▀██████████▄▓████  ▓████████████
   ▒▒▒▒▒  ░▓███░███▌  ░░▓▓█████░ ▀▄▀█████▌   ▄▄▄▄   ▀▀█████░████▌ ░  ▀▀▀█████
   █████  ▓███▀ ███▌ ▄▓▓███████▓   ▀▄▀▓██▌ ▄█████    ▄████▀  ████░  ▄▀ ▄████▀█
   ▀████  ███▀  ███▄▓████▀██ ███    ▓█▄██▄██████▀ ░▄█████▓ █  ███▓ ▀ ▄▓█████ ▓
 ▄█ ████▒▒██▀▄▀ ███████▀▄▀██ ███    ░████▓▓███▀  ▄▓█████▀▄▀  ▄ ███ ▄██████▀▄▀░
  █ ███████▓▀   ▓▓▓▀▀▄▄▀  ▓▓ ▀▓▓     ▀▀▀▀░░██████████▓▓▒▒    █ ████████▓▀▄▀
  █ ██████▀░    ░░░       ░░  ░░     ▄██▀  ▀▀▓▓█████▀░░      ▀▀▀▀▀▀▀▀▒▒░▓  ▄▀
  █ ▓▓▀▀                               ▄     ░░              ▄▄███▀     ▒    ▄
░ █▄▄▄▓▓  G E N E S I S  P R O J E C T - C64 Scene MOD of CGterm        ░     ■
▓▄▄   ░░ ■■                                                  ■■■



//INSTALLATION GUIDE
==================================================
  CGTerm 3.0 - ULTiMATE C64 BBS WAREZ SCENE EDiTiON
==================================================


//REQUIREMENTS
--------------------------------------------------
- SDL 1.2         (required; sdl12-compat is fine)
- libopenmpt      (required on macOS/Linux for XM/MOD music)
- C compiler      (gcc or clang)
- make


//QUICK INSTALL (all platforms)
--------------------------------------------------
This is on your own, if you dont know what you are
doing please use the installation scripts below:

compile:>  make && sudo make install



//LINUX
--------------------------------------------------
Using the install script (recommended):

    ./scripts/install-linux.sh

Or manually:

    sudo apt install libsdl1.2-dev           # Debian/Ubuntu (or libsdl1.2-compat-dev)
    sudo apt install libopenmpt-dev          # for XM/MOD music
    make && sudo make install

Installs to:

    /usr/local/bin/cgterm
    /usr/local/bin/cgchat
    /usr/local/bin/cgedit
    /usr/local/share/cgterm/assets/


//macOS
--------------------------------------------------
Using the install script (recommended):

    ./scripts/install-macos.sh

This builds a native .app bundle and installs to /Applications.

Dependencies (Homebrew):

    brew install sdl12-compat libopenmpt

(The old 'sdl' formula was removed from Homebrew;
sdl12-compat provides the SDL 1.2 API on top of SDL2.
libopenmpt provides XM/MOD music playback.)

On Apple Silicon, make sure these come from the native
arm64 Homebrew in /opt/homebrew — see TROUBLESHOOTING
below if the link step reports undefined arm64 symbols.

The .app bundle is created at:

    dist/CGTerm.app


//WINDOWS
--------------------------------------------------
Pre-built binaries are provided in the zip file.
Just unzip and run cgterm.exe.

Native build under MSYS2 (MINGW64 shell):

    pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make \
              mingw-w64-x86_64-SDL mingw-w64-x86_64-SDL_mixer
    mingw32-make

The Makefile detects MinGW/MSYS and selects the Windows code
paths (winsock, SDL_mixer music) by itself.

To cross-compile from macOS/Linux:

    ./scripts/cross-compile-win.sh

Output:

    dist/win32/           (portable, unzip and run)
    dist/CGTerm-3.1-win32.zip


//KEYBOARD LAYOUTS
--------------------------------------------------
CGTerm ships assets/default.kbd, which is loaded
automatically. Every other *.kbd file placed in the assets
folder shows up in the keyboard menu (K). To use a custom
map from elsewhere, pass it with -k:

    cgterm -k /path/to/your.kbd

Or set it in your config file (~/.cgtermrc):

    keyboard = default.kbd

See assets/KEYBOARD-PROFILES.md for the key-map format.


//CONFIG FILE
--------------------------------------------------
Linux/macOS:  ~/.cgtermrc
Windows:      %APPDATA%\CGTerm\cgterm.cfg

A system-wide file is read first and the per-user file on
top of it:

Linux/macOS:  /etc/cgterm.cfg
Windows:      cgterm.cfg next to cgterm.exe

Example settings:

    keyboard = default.kbd
    columns = 40
    zoom = 2
    modem = yes
    splashfont = 5
    menufont = 7
    statusline = yes
    autozmodem = yes
    transferlog = yes
    musicvolume = 64
    reconnect = 30          # redial 30 s after a dropped carrier
    logfile = ~/bbs.log     # capture every session, appended

Values may contain spaces and a leading ~/ expands to your
home directory. Most settings can also be changed from the
Options panel (O) and are saved automatically.


//PER-USER FILES
--------------------------------------------------
                        Linux/macOS               Windows (%APPDATA%\CGTerm)
settings                ~/.cgtermrc               cgterm.cfg
bookmarks               ~/.cgterm-bookmarks       cgterm-bookmarks.cfg
notes + login scripts   ~/.cgterm-notes           cgterm-notes.cfg
connection history      ~/.cgterm-history         cgterm-history.log
transfer log            ~/.cgterm-transfers.log   cgterm-transfers.log
debug log (debug = yes) ~/.cgterm-debug.log       cgterm-debug.log

On Windows an older set of these files in the start folder is
copied to %APPDATA%\CGTerm the first time the new version runs.


//TESTS
--------------------------------------------------
    make test     protocol (XMODEM, Punter, ZMODEM against lrzsz
                  when installed), ANSI emulation and disk-image
                  regression tests; no window and no network
    make fuzz     mutation fuzzing of the disk-image parser with
                  AddressSanitizer/UBSan (FUZZ_ITER=n FUZZ_TYPE=d81)

The same runs in GitHub Actions on Linux, macOS and MinGW
(.github/workflows/build.yml).


//PROGRAMS BUILT
--------------------------------------------------
cgterm    Main BBS terminal client
cgchat    Chat utility
cgedit    PETSCII editor


//DEFAULT INSTALL PATHS
--------------------------------------------------
Linux:    /usr/local/bin, /usr/local/share/cgterm/assets
macOS:    /Applications/CGTerm.app
Windows:  Portable (run from any directory)


//TROUBLESHOOTING
--------------------------------------------------
macOS (Apple Silicon): build fails with
"ld: symbol(s) not found for architecture arm64"
(undefined _SDL_*, _openmpt_*, _main)

  Your SDL/libopenmpt libraries are Intel (x86_64)
  builds — typically from an Intel Homebrew under
  /usr/local on a machine migrated from an Intel Mac.
  The compiler produces arm64 objects, the linker
  skips the x86_64 libraries, and every SDL symbol
  comes up undefined.

  Fix (preferred): install native arm64 Homebrew
  (/opt/homebrew) and the deps, then rebuild:

      brew install sdl12-compat libopenmpt
      make clean && make

  Workaround: build everything under Rosetta so the
  architectures match your x86_64 libraries:

      arch -x86_64 zsh
      make clean && make

  Or skip building entirely and use the prebuilt
  CGTerm-3.1-macos.zip from the releases page.
