PuTTY-FK source code README
===========================

This is a fork of PuTTY with macOS-specific enhancements, primarily
aimed at improving the serial port experience.

New features in this fork
--------------------------

Serial port auto-reconnect
  When a serial port disconnects (e.g. a USB adapter is removed),
  PuTTY can automatically reconnect instead of closing the window.
  Enable this in Connection > Serial > "Reconnect automatically when
  serial port disconnects", and set the retry interval in seconds.

  Read errors such as EIO (device removed on macOS) are now handled
  gracefully as a disconnect rather than crashing the process.

Disconnect / Reconnect
  A Disconnect command is available in the Window menu bar and the
  Ctrl+right-click context menu. It closes the serial port and
  releases it so another application (e.g. a firmware updater) can
  open it, while keeping the terminal window open. Use Restart Session
  to reconnect without opening a new window.

  Keypresses while disconnected are ignored rather than closing the
  window.

Always on Top
  A toggleable "Always on Top" option appears in both the Window menu
  bar and the Ctrl+right-click context menu. The state is kept in sync
  between both menus. Each window tracks its own state independently.


Building on macOS
-----------------

Prerequisites (install via Homebrew):

  brew install cmake gtk+3 imagemagick

To build PuTTY.app in one step, run the provided script from the
source directory:

  ./build-macos-app.sh

This will configure and compile the project, generate the icon, and
produce a ready-to-use PuTTY.app in the source directory.

To open a second window (connect to a second serial port):

  open -n PuTTY.app


Building manually
-----------------

PuTTY is built using CMake <https://cmake.org/>. To compile in the
simplest way, run these commands in the source directory:

  cmake -B build
  cmake --build build

To install on Linux or Mac:

  cmake --build build --target install

On Unix, pterm would like to be setuid or setgid, as appropriate, to
permit it to write records of user logins to /var/run/utmp and
/var/log/wtmp. (Of course it will not use this privilege for
anything else, and in particular it will drop all privileges before
starting up complex subsystems like GTK.) The cmake install step
doesn't attempt to add these privileges, so if you want user login
recording to work, you should manually ch{own,grp} and chmod the
pterm binary yourself after installation. If you don't do this,
pterm will still work, but not update the user login databases.


Documentation
-------------

Documentation (in various formats including Windows Help and Unix
`man' pages) is built from the Halibut (`.but') files in the `doc'
subdirectory. If you aren't using one of our source snapshots,
you'll need to do this yourself. Halibut can be found at
<https://www.chiark.greenend.org.uk/~sgtatham/halibut/>.

The upstream PuTTY home web site is

    https://www.chiark.greenend.org.uk/~sgtatham/putty/

See the file LICENCE for the licence conditions.