Distribution Build Scripts for Windows
======================================

The scripts are used to build the binary distribution zip files for windows.

Environment
-----------

A full installation of msys2 is required along for the build.  The
various dependencies of Emacs need to be installed also.  These change
over time, but are listed in build-deps-zips.py.



File System Organization
------------------------


They are relatively strict about the file system organization.  In
general, they should work across several more than just the version of
Emacs they come with, as the dependencies of Emacs change relatively slowly.

The file system needs to be organized like so:

~/emacs-build/git

Contains checkouts and worktrees of the Emacs git repository,
organized according to branches.

~/emacs-build/git/master

A checkout out of the master branch of the Emacs git repository.

~/emacs-build/git/emacs-$major-version

A worktree of the git repository containing the current release
branch.  This has to be created by hand.

~/emacs-build/git/emacs-$release-version

A branch of the git repository containing the last release.  The
build-zips.sh file will create this for you.

~/emacs-build/deps

A location for the dependencies.  This needs to contain two zip files
with the dependencies.  build-dep-zips.py will create these files for
you.

~/emacs-build/deps/libXpm

Contain libXpm-noX4.dll.  This file is used to load images for the
splash screen, menu items and so on.  Emacs runs without it, but looks
horrible.  The files came original from msys2, and contains no
dependencies.  It has to be placed manually (but probably never
need updating).

~/emacs-build/build/$version

We build Emacs out-of-source here.  This directory is created by
build-zips.sh.  This directory can be freely deleted after zips have
been created

~/emacs-build/install/$version

We install Emacs here.  This directory is created by build-zips.sh.
This directory can and *should* be deleted after zips have been
created.

~/emacs-upload

Zips are created and moved here from where they can be, well,
uploaded.



Build Process
-------------


### For each major version

The dependencies files need to be created.  This can be around the time
of the pre-tests, then used for all releases of that version, to
ensure the maximum stability.

To do this:

Update msys to the latest version with `pacman -Syu`.

Then run build-dep-zips.py, in the ~/emacs-build/deps directory.  Two
zips will be created, containing the dependencies, as well as the
source for these.

For emacs release or pre-test version:

Run `build-zips.sh -g` in the release branch.  This will create a worktree
with the tag of the last version.

Then run `build-zips.sh` in this worktree.  Eventually, four new zip
files will be created in ~/emacs-upload from where they can be signed
and uploaded with `gnupload`.


### For snapshots from Master

Snapshots are generally created from master when there is a release
branch on which a release has already been created.  At this point,
only pre-tests or full releases need to happen from the release
branch.

To do this:

Update msys to the latest version with `pacman -Syu`.

Then run build-dep-zips.py, in ~/emacs-build/deps directory.  Two zips
will be created, containing the dependencies, as well as the source
for these.  These deps files contain the date of creation in their
name.  The deps file can be reused as desired, or a new version
created.  Where multiple deps files exist, the most recent will be
used.

Now, run `build-zips.sh -s` to build a snapshot release.


### For snapshots from a Release Branch

Snapshots can be built from a release branch; this is really only
useful before a pre-test has happened.

The process is the same as for building from the master branch, except
that the release branch should already exist as a worktree, and the
version number must be added to the command line with `build-zips.sh
-V 27 -s`.  The final zips will be named after the branch rather than
the version (e.g emacs-27-2019-12-26.zip) rather than the Emacs
version (e.g emacs-27.0.50.zip).


### For snapshots from another branch

Snapshots can be built from any other branch.  There is rarely a need
to do this, except where some significant, wide-ranging feature is
being added on a feature branch.  In this case, the branch can be
given using `build-zips.sh -b pdumper -s` for example.  Any "/"
characters in the branch title are replaced.
