1Distribution Build Scripts for Windows
2======================================
3
4The scripts are used to build the binary distribution zip files for windows.
5
6Environment
7-----------
8
9A full installation of msys2 is required along for the build. The
10various dependencies of Emacs need to be installed also. These change
11over time, but are listed in build-deps-zips.py.
12
13
14
15File System Organization
16------------------------
17
18
19They are relatively strict about the file system organization. In
20general, they should work across several more than just the version of
21Emacs they come with, as the dependencies of Emacs change relatively slowly.
22
23The file system needs to be organized like so:
24
25~/emacs-build/git
26
27Contains checkouts and worktrees of the Emacs git repository,
28organized according to branches.
29
30~/emacs-build/git/master
31
32A checkout out of the master branch of the Emacs git repository.
33
34~/emacs-build/git/emacs-$major-version
35
36A worktree of the git repository containing the current release
37branch. This has to be created by hand.
38
39~/emacs-build/git/emacs-$release-version
40
41A branch of the git repository containing the last release. The
42build-zips.sh file will create this for you.
43
44~/emacs-build/deps
45
46A location for the dependencies. This needs to contain two zip files
47with the dependencies. build-dep-zips.py will create these files for you.
48
49~/emacs-build/deps/libXpm
50
51Contain libXpm-noX4.dll. This file is used to load images for the
52splash screen, menu items and so on. Emacs runs without it, but looks
53horrible. The files came original from msys2, and contains no
54dependencies. It has to be placed manually (but probably never
55need updating).
56
57~/emacs-build/build/$version
58
59We build Emacs out-of-source here. This directory is created by
60build-zips.sh. This directory can be freely deleted after zips have
61been created
62
63~/emacs-build/install/$version
64
65We install Emacs here. This directory is created by build-zips.sh.
66This directory can and *should* be deleted after zips have been
67created.
68
69~/emacs-upload
70
71Zips are created and moved here from where they can be, well,
72uploaded.
73
74
75
76Build Process
77-------------
78
79
80### For each major version
81
82The dependencies files need to be created. This can be around the time
83of the pre-tests, then used for all releases of that version, to
84ensure the maximum stability.
85
86To do this:
87
88Update msys to the latest version with `pacman -Syu`.
89
90Then run build-dep-zips.py, in the ~/emacs-build/deps directory. Two
91zips will be created, containing the dependencies, as well as the
92source for these.
93
94For emacs release or pre-test version:
95
96Run `build-zips.sh -g` in the release branch. This will create a worktree
97with the tag of the last version.
98
99Then run `build-zips.sh` in this worktree. Eventually, four new zip
100files will be created in ~/emacs-upload from where they can be signed
101and uploaded with `gnupload`.
102
103
104### For snapshots from Master
105
106Snapshots are generally created from master when there is a release
107branch on which a release has already been created. At this point,
108only pre-tests or full releases need to happen from the release
109branch.
110
111To do this:
112
113Update msys to the latest version with `pacman -Syu`.
114
115Then run build-dep-zips.py, in ~/emacs-build/deps directory. Two zips
116will be created, containing the dependencies, as well as the source
117for these. These deps files contain the date of creation in their
118name. The deps file can be reused as desired, or a new version
119created. Where multiple deps files exist, the most recent will be
120used.
121
122Now, run `build-zips.sh -s` to build a snapshot release.
123
124
125### For snapshots from a Release Branch
126
127Snapshots can be built from a release branch; this is really only
128useful before a pre-test has happened.
129
130The process is the same as for building from the master branch, except
131that the release branch should already exist as a worktree, and the
132version number must be added to the command line with `build-zips.sh
133-V 27 -s`.  The final zips will be named after the branch rather than
134the version (e.g emacs-27-2019-12-26.zip) rather than than the Emacs
135version (e.g emacs-27.0.50.zip).
136
137
138### For snapshots from another branch
139
140Snapshots can be build from any other branch.  There is rarely a need
141to do this, except where some significant, wide-ranging feature is
142being added on a feature branch.  In this case, the branch can be
143given using `build-zips.sh -b pdumper -s` for example. Any "/"
144characters in the branch title are replaced.
145