Building the Windows Installer for GNU units
                Jeff Conrad 2 December 2024

This procedure requires Microsoft Visual Studio; Unix-like utilities,
including a Bourne-compatible shell, cp, expr, mv, ls, rm, and sed;
MikTeX or equivalent; Inno Setup, and GnuPG or equivalent.  It was most
recently run using the following packages:

 * Microsoft Visual Studio 2022
 * PTC MKS Toolkit for Developers 10.4
 * MikTeX 24.1
 * Inno Setup 6.6.3
 * GnuPG 2.4.5
 * rmbom (optional)

Notes:
------
For the Windows build, the data file and the locale map are installed in
the same directory as the executable, and are found with relative
pathnames.  A typical build for a Unix-like environment--such as the PTC
MKS Toolkit--uses absolute pathnames for these files.  This makefile
removes the compiled files with the absolute pathnames and recompiles
them with relative pathnames.

The file 'lwords' is a list of words for spell(1) to ignore; the file
'ex.rc' is the equivalent of '.exrc' for PTC MKS vi/viw, _not_ a
Resource Compiler file.  Two programs--spellx and adjust--are mapped in
ex.rc.  The spellx program is an interactive front end to spell(1);
adjust is a line-filling program similar to fmt(1).  The standard
programs can be used to much the same effect.

'rmbom' is a program that removes a UTF-8 marker ("BOM") from one or
more files.  The program used here is an executable but some versions of
sed(1) will also work.  A "BOM" can also be removed interactively using
vim, notepad, notepad++, and perhaps some other editors.

Procedure
=========
1.  If necessary, update Readme.txt and UnitsForWindows.texinfo,
    including edition, version, copyright date, and build date.

2.  Before running configure in the source directory, examine
    Makefile.in in the Windows directory and ensure the correct values
    for

        ProgFiles32
        ProgFiles64
        GPG (GnuPG or equivalent)
        ISCC (Inno Setup)
        FLIP (program to convert LF to CRLF)
	RMBOM (program to remove UTF-8 marker; optional)
        TEXI2PDF
        ZIP (WinZip command line)

    Be aware that Makefile will be overwritten every time the configure
    script is run.  If you wish to make changes without running
    configure again, make the changes to Makefile.in, copy it to
    "Makefile", and change the line

        VERSION = @PACKAGE_VERSION@

    so it gives the proper version, e.g.,

        VERSION = 2.24a

    This version must match the version in the units executable in the
    source directory, which can be obtained by running "../units -V".

3.  If you have not already done so, run "./configure" in the source
    directory to create Makefile in the Windows directory.

4.  Ensure that the proper Visual Studio variables are set, such as by
    running "source setvcvars".

5.  From the Windows directory, run "make" to build the Windows version
    of units, generate or copy the other files, and create the
    installer.

    The process will abort if any of the text files have UTF-8 markers;
    if any are found, do what is necessary to remove the markers.  If
    you have a program that will do this, assign it to RMBOM and run
    "make rmbom".

6.  Open UnitsForWindows.pdf and verify that the Table of Contents has
    been properly generated; if not, run "make -u pdf" to recreate it;
    open and confirm that it's OK, and run "make" again.  The TEXI2PDF
    program is run twice, so the ToC should usually be correct.

7.  Run "make check" and verify that the data file and the locale map
    include only the filenames.  These are checked before building the
    installer, so there should seldom be a problem.

8.  Run the installer to confirm that it works by running "make install".
    Note the output of units -I and verify that the paths for the data
    file and the locale map are correct; as with the previous step,
    there should seldom be a problem.

9.   Run "make winsig" to create the Directive and signature.  If the
     call to gpg fails, you may need to run "gpgconf --launch gpg-agent".

10. Upload the installer:

    # for release:
    Run "make upload" to upload the installer.

    # for alpha:
    Run "make alpha" to upload the installer to the alpha site.

    # for zipped version (e.g., for 2.24):
    put units-2.24-*.zip
      or
    put units-2.24-setup.zip
    put units-2.24-setup.zip.directive.asc
    put units-2.24-setup.zip.sig

    # to archive
    put units-2.24-setup.zip.archive.directive.asc