bug#22240: Build instructions for 64-bit Windows?

[Eli Zaretskii <eliz@gnu.org>]

> From: Brian Burns <bburns.km@gmail.com>
> Date: Tue, 29 Dec 2015 01:12:51 -0600
> Cc: 22240@debbugs.gnu.org, Chris Zheng <chriszheng99@gmail.com>
> 
> Okay thanks, here's a rough draft for the instructions

Thanks.  Allow me a few comments.

> > the --host, --target, and --build switches should not be needed
> 
> I tried running configure without the '--host=x86_64-w64-mingw32' etc switches
> but got an error:
> 
> configure: error: Emacs does not support 'x86_64-pc-msys' systems.
> If you think it should, please send a report to bug-gnu-emacs@gnu.org.
> Check 'etc/MACHINES' for recognized configuration names.
> 
> but the MACHINES file says to see the nt/INSTALL document, which doesn't cover
> the 64-bit options. So I left them in for the moment - I can file a bug report
> for that also if needed.

Please do file a bug report.  Users shouldn't need to specify the host
for supported systems.

It's also worthwhile to report this to MSYS2 developers, I think: that
string is not the canonical host description for MinGW64, it's for
building an MSYS program, which is not what is going on here.

> Okay, I put the --prefix on the configure command, but I think it would be good
> if the instructions included a simple example, and refer the user to the
> INSTALL
> instructions for more options

Sorry, I don't understand: this _is_ INSTALL, isn't it?  And the
current INSTALL does include a couple of examples.  What am I missing?

> > the 'cp' commands I don't understand at all: if PREFIX is chosen
> > correctly, the Emacs's bin/ directory and the MinGW64's bin/
> > directory should be the same, so there's no need to copy; and
> > even if these two bin/ directories are different, the directory
> > with DLLs should be on PATH. this sounds like some workaround
> > for some misconfiguration, so we had better not repeated that.
> 
> I think this was in part because MSYS2 doesn't add its folders to the PATH, and
> if you use the PATH variable there might be both 32-bit and 64-bit DLLs on it,

But that's a problem MSYS2 and MinGW64 should have solved already,
right?  IOW, it's not something specific to Emacs.

> > The "Run" section doesn't belong in installation instructions.
> 
> I think it might be good to include a simple Test section that just says to 
> run emacs with
> 
> ./bin/runemacs.exe -Q
> 
> to check that it works - mainly because a Windows user might tend to launch 
> Emacs from a shortcut on the desktop and might be unused to launching it
> from the console, so a simple line like that might be helpful.

I indeed think that the instructions should tell how to create a
desktop shortcut for running Emacs.

> Any corrections or additions are welcome - I'm a novice at building things 
> like this so am not sure what a more advanced user might want to see. 

See below for some more.

> * Requirements
> 
> The total time to download all tools and build Emacs is approximately 90
> minutes on an Intel i3 processor, and 3GB of free space is required (1.8GB for
> MSYS2 / MinGW-w64 and 1.2GB for Emacs with the full repository).
> 
> Approximate times for the first pass through each step are given - to time
> them yourself you can precede any BASH command with 'time'.

I would suggest removing this time information: it is very
system-dependent, and can also change radically depending on your
network access speed.  nt/INSTALL doesn't have such information, and I
don't recall anyone ever complaining.

> Run this file to install MSYS2 in your preferred directory, e.g. the default
> C:\msys64 - this will install MinGW-w64 also. Note that a path containing
> spaces may cause problems.

GNU Coding Standards frown upon using "path" for anything except
PATH-style lists of directories.  Please use "file names" or
"directory name" instead.

Also, please keep 2 spaces between sentences, as we use the US English
conventions in GNU documentation.

> In the BASH prompt, use the following command to install the necessary
> packages (you can copy and paste it into the shell with Shift + Insert):
> 
> pacman -S base-devel \
> mingw-w64-x86_64-toolchain \
> mingw-w64-x86_64-xpm-nox \
> mingw-w64-x86_64-libtiff \
> mingw-w64-x86_64-giflib \
> mingw-w64-x86_64-libpng \
> mingw-w64-x86_64-libjpeg-turbo \
> mingw-w64-x86_64-librsvg \
> mingw-w64-x86_64-libxml2 \
> mingw-w64-x86_64-gnutls
> 
> The packages include the base developer tools (autoconf, automake, grep, make,
> etc.), the compiler toolchain (gcc, gdb, etc.), several image libraries, an
> xml library, and the GnuTLS (transport layer security) library.

Here I would say that the user can omit some or all of the optional
libraries (all but the first 3), if they so wish.

> * Install git (optional) and disable autocrlf [2 mins]

This section should say that Git is only needed if the user wants to
build the development version.

> Note that the --prefix option specifies a location for the resulting binary
> files, which 'make install' will use - if a prefix is not specified the files
> will be put in the standard MinGW-w64 directories.

No, if --prefix is not specified, the files will be installed in the
standard _Unix_ directories, not standard MinGW-w64 directories.

> ** Run make [30 mins]

This takes 4 min on my system, for the full bootstrap (building a
release tarball is much faster).  I guess you didn't use "make -j8" or
some such.  See, this is why these times are not such a good idea.

> ** Run make install [6 mins]

Takes something like 2 min here.

> Now you can run make install, which will copy the executable and other files 
> to the location specified in the configure step:
> 
> make install

One can also say

  make install prefix=/wherever

to install in a different place.

> * Emacs settings
> 
> Local Variables:
> mode: org
> sentence-end-double-space: t
> End:

This should be preceded by a Ctrl-L character, since Emacs looks for
the file-local variables in the last page of the file.

Thanks.