ShiftN 5.0 - Building from source
=================================

This file describes how to build ShiftN 5.0 (64-bit, Unicode) from the
source code with Visual Studio 2026, and how to build the portable version
for PortableApps.com.

ShiftN is free software, licensed under the GNU Lesser General Public License
version 3 (see COPYING.LESSER.txt and COPYING.txt).

In 2026, parts of the software were refactored and modernized with
assistance from AI-based development tools (Claude). All modifications were
reviewed, integrated, and tested by the original author.

Contents
  1. Requirements
  2. Contents of the source package
  3. Building ShiftN
  4. Installing and running ShiftN
  5. Building the portable version (PortableApps.com)
  6. Notes for changing the source code


1. Requirements
---------------
  Windows 10/11 (64-bit) with Visual Studio 2026.
  In the Visual Studio Installer (Modify) select:
    - Workload "Desktop development with C++"
    - Component "C++ MFC for latest build tools (x86 & x64)"
    - A Windows 11/10 SDK (installed with the workload by default)

  Only for the portable version (https://portableapps.com/development):
    - PortableApps.com Launcher   (contains the Launcher Generator)
    - PortableApps.com Installer  (optional, to create an installer)


2. Contents of the source package
---------------------------------
  ShiftN.sln                    solution with all 9 projects
  ShiftN.vcxproj                ShiftN.exe (MFC application)
  ShiftN.props                  settings shared by all projects
  *.cpp, *.h                    ShiftN source code
  ShiftN.rc, resource.h, res\   resources (menus, dialogs, texts, icons)
  Splsh16.bmp                   splash screen
  shiftn_english\, shiftn_deutsch\, shiftn_francais\, shiftn_espanol\
                                language DLLs (resource-only projects)
  libjpeg\, libpng\, libtiff\, zlib\
                                libraries used by ShiftN (built from source)
  ShiftN_Help.chm, ShiftN_Hilfe.chm, ShiftN_Aide.chm, ShiftN_Ayuda.chm
                                help files (English, German, French, Spanish)
  portable\ShiftNPortable\      template of the PortableApps.com package
  build_vs2026.cmd              command-line build of ShiftN
  make_portable.cmd             command-line build of the portable version
  Doxyfile                      configuration for the code documentation
  COPYING.LESSER.txt            license of ShiftN (LGPL version 3)
  COPYING.txt                   GPL version 3 (referenced by the LGPL)

  The build creates the folders bin\, build\, dist_x64\, dist_portable\ (and
  Visual Studio .vs\). They can be deleted at any time.


3. Building ShiftN
------------------
3.1 In Visual Studio
  Open ShiftN.sln, choose the configuration "Release | x64" (or
  "Debug | x64") and select Build > Build Solution (F7).
  The libraries and the four language DLLs are built automatically before
  ShiftN.exe:
      ShiftN             ShiftN.vcxproj                   MFC application
      Libraries\zlib     zlib\zlib.vcxproj                static library
      Libraries\libjpeg  libjpeg\libjpeg.vcxproj          static library
      Libraries\libtiff  libtiff\libtiff\libtiff.vcxproj  static library
      Libraries\libpng   libpng\libpng.vcxproj            static library
      Languages\shiftn_english/deutsch/francais/espanol   language DLLs
  The result is in bin\x64\Release\ (or bin\x64\Debug\): ShiftN.exe and the
  language DLLs. You can start ShiftN directly from Visual Studio (F5).

3.2 From the command line
  build_vs2026.cmd            Release build; ready-to-run copy in dist_x64\
  build_vs2026.cmd debug      Debug build; copy in dist_x64_debug\
  build_vs2026.cmd rebuild    complete rebuild (Release)
  The script finds Visual Studio itself, so a normal command prompt is
  enough. With "set NOPAUSE=1" the script does not wait for a key at the end.


4. Installing and running ShiftN
--------------------------------
4.1 Installation
  Copy the content of dist_x64\ into a folder of your choice:
    ShiftN.exe
    shiftn_english.dll, shiftn_deutsch.dll, shiftn_francais.dll,
    shiftn_espanol.dll
    ShiftN_Help.chm, ShiftN_Hilfe.chm, ShiftN_Aide.chm, ShiftN_Ayuda.chm
  All files must be in the same folder: ShiftN.exe takes its menus, dialogs
  and texts from the language DLLs, and Help (F1) opens the .chm file of the
  selected language.
  MFC and the C/C++ runtime are linked statically, so no "Microsoft Visual
  C++ Redistributable" has to be installed.

  ShiftN stores its settings in the registry
  (HKCU\Software\Marcus Hebel Freeware\ShiftN) and in %APPDATA%\ShiftN.ini.

4.2 Command line (use by other programs)
  Other programs can call ShiftN.exe to correct an image without any user
  interaction:
      ShiftN.exe <input> <output> [A|M][formats] [focal length]
    <input>       image file (JPEG, TIFF, PNG, BMP) or the word Clipboard
    <output>      result file or the word Clipboard. ShiftN sets the
                  extension of each output format (.jpg, .bmp, .tif); a JPEG
                  or TIFF name such as out.jpeg or out.tiff is used as given.
    A             quiet mode (default): no window, no progress bar and no
                  message. ShiftN runs the automatic correction, saves the
                  result and exits.
    M             ShiftN opens its window with the image for a manual
                  correction; "Save and exit" writes the result to <output>.
    formats       optional digit directly after A or M: 1 = JPEG, 2 = BMP,
                  4 = TIFF, or the sum of several (A5 = JPEG and TIFF).
                  Without it, the formats from Options > Type of output are
                  used.
    focal length  optional focal length in mm (8 to 200); it replaces the
                  value from the EXIF data.
  Example:
      ShiftN.exe C:\Photos\house.jpg C:\Photos\house_ShiftN.jpg A1
  All other settings (resolution, JPEG quality, sharpening ...) are those
  saved by ShiftN (registry and ShiftN.ini, or Data\settings in portable
  mode). "ShiftN.exe <file>" alone opens the image in the normal window.

  In quiet mode, the exit code of ShiftN.exe reports the result:
      0   the result was saved
      1   the input could not be loaded (missing, damaged or unsupported)
      2   there is no result, or it could not be saved
      3   ShiftN could not start (language DLLs missing)
  ShiftN.exe is a Windows program: batch files and programs that wait for
  the process (e.g. CreateProcess() and WaitForSingleObject()) get the exit
  code directly (%ERRORLEVEL% in a batch file); at an interactive command
  prompt use "start /wait ShiftN.exe ...".


5. Building the portable version (PortableApps.com)
---------------------------------------------------
  The portable version runs from a USB drive or any other folder and keeps
  all settings in its own Data folder. It follows the PortableApps.com Format
  and can be used with or without the PortableApps.com Platform.

5.1 Steps
  1. Run make_portable.cmd.
     It builds ShiftN (Release) and assembles the package in
     dist_portable\ShiftNPortable\ from the template in
     portable\ShiftNPortable\, together with ShiftN.exe, the language DLLs,
     the help files and a copy of the source code.
  2. Run the PortableApps.com Launcher Generator and select the folder
     dist_portable\ShiftNPortable. It creates the launcher
     ShiftNPortable.exe in that folder.
     (When you run make_portable.cmd again later, the launcher is kept; the
     generator is only needed again after deleting dist_portable\.)
  3. Start dist_portable\ShiftNPortable\ShiftNPortable.exe. The folder can
     now be copied anywhere, e.g. to a USB drive.
  4. Optional: run the PortableApps.com Installer on the same folder. It
     creates dist_portable\ShiftNPortable_<version>.paf.exe, which can be
     installed with the PortableApps.com Platform.

5.2 Structure of the package
    ShiftNPortable\
      ShiftNPortable.exe          launcher
      help.html                   short description
      App\ShiftN\                 ShiftN.exe, language DLLs, help files
      App\AppInfo\                package information, icons, launcher
                                  configuration (Launcher\ShiftNPortable.ini)
      Other\Source\               licenses and source code
      Data\settings\              settings, created at the first start

  To change the package (name, description, icons ...), edit the template in
  portable\ShiftNPortable\, not dist_portable\ - make_portable.cmd replaces
  the App and Other folders there.
  If you publish a modified package, give it your own AppID in
  App\AppInfo\appinfo.ini (PortableApps.com rule: ShiftNPortable-<your
  PortableApps.com user name>); "ShiftNPortable" is reserved for the official
  release.

5.3 Portable mode
  The launcher sets the environment variable SHIFTN_SETTINGS to the folder
  Data\settings. If this variable contains a folder, ShiftN keeps all its
  settings there (ShiftN.ini and ShiftN_profile.ini) and does not use the
  registry or %APPDATA%. At the first start ShiftN uses the language of the
  PortableApps.com Platform (English, German, French or Spanish; otherwise
  English).
  You can also use portable mode without the launcher, e.g.:
      set SHIFTN_SETTINGS=C:\ShiftN\settings
      C:\ShiftN\ShiftN.exe
  In portable mode the file dialogs do not add the chosen files to the
  recent items of Windows. The launcher keeps the file in which the Windows
  help viewer stores its window position (%APPDATA%\Microsoft\HTML Help\
  hh.dat) in Data\settings and restores a local hh.dat after ShiftN has been
  closed ([FilesMove] in Launcher\ShiftNPortable.ini). Windows itself still
  remembers the last folders used in file dialogs (registry key
  HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\ComDlg32), as it
  does for every program.


6. Notes for changing the source code
-------------------------------------
  - The source files (.cpp, .h) are UTF-8 with BOM and are compiled with
    /utf-8. The resource files (.rc) use code page 1252 with CRLF line ends;
    keep this encoding when editing them, otherwise accented characters in
    the French, German and Spanish texts are damaged.
  - Menus, dialogs and texts of all four languages are in ShiftN.rc, one
    block per language. Each language DLL is compiled from ShiftN.rc for its
    language. A new text (string) must be added to all four language blocks.
  - The English string table in the neutral block of ShiftN.rc is only for
    ShiftN.exe and is excluded from the language DLLs with an #if around it.
    The Visual Studio resource editor may remove this #if when it saves
    ShiftN.rc; then all languages show the English status bar texts.
  - Splsh16.bmp exists in the main folder and in each shiftn_* folder (the
    language DLLs use their own copy); keep the five files identical.
  - The program icon is res\idr_main.ico. res\idr_shif.ico, res\ShiftN.ico,
    res\ShiftNDoc.ico and the same four files in the res\ folder of each
    shiftn_* project are identical copies; keep all 20 files identical. The
    icon contains the sizes 16, 20, 24, 32, 40, 48, 64 and 256 pixels. The
    portable package has its own copies: appicon.ico and appicon_*.png in
    portable\ShiftNPortable\App\AppInfo\ and appicon_75.png in
    portable\ShiftNPortable\Other\Help\Images\.
  - To link MFC as a DLL instead of statically, change UseOfMfc and
    RuntimeLibrary in ShiftN.props and add _AFXDLL to the resource
    preprocessor definitions of the four language DLL projects.
  - libjpeg, libpng, libtiff and zlib are built with the included .vcxproj
    files; the makefiles of the original library distributions are not used.
  - libjpeg (6b), libtiff (3.8.2) and zlib (1.2.3) are older versions with
    selected security fixes; all changes are marked with "ShiftN 5.0" in
    the source. The rarely used libtiff codecs CCITT fax, LogLuv, NeXT,
    PixarLog and ThunderScan are switched off (in tiffconf.h and in
    libtiff.vcxproj). ShiftN only opens common TIFF variants: 8 or 16 bits
    per channel, grayscale or RGB, uncompressed or with LZW, ZIP, JPEG or
    PackBits compression (see IsSupportedTiff() in ShiftNView.cpp). Exotic
    TIFF variants are not supported.
  - libpng is the unchanged release 1.6.59 (PNG files are only read, not
    written). pnglibconf.h is a copy of scripts\pnglibconf.h.prebuilt from
    the libpng distribution. To update libpng, replace the files in libpng\
    with those of a newer 1.6.x release (the .c files listed in
    libpng.vcxproj, the headers and pnglibconf.h).
  - All projects are compiled with Control Flow Guard (/guard:cf, set in
    ShiftN.props).
  - Code documentation: run doxygen in the main folder (uses Doxyfile); the
    result is written to doc\html.
