#pragma section-numbers 2

= Hackable Mercurial for Windows =
An approach to easily hack on the Mercurial source on Windows.

<<Include(A:historic)>>

See [[https://www.mercurial-scm.org/wiki/BuildingOnWindows|BuildingOnWindows]] for modern methodology.

<<TableOfContents>>

== What is the Hackable package? ==
Compiling Mercurial is a significant barrier to testing and developing Mercurial on Windows. This package attempts to minimize that barrier by including:

 * a private copy of Python (32-bit)
 * complete Mercurial history
 * pre-compiled extensions (32-bit MinGW GCC)
 * an hg.exe wrapper to add to your path
 * in-place editable source checked out and ready to go

== Downloading and using ==
The package can be found [[https://mercurial-scm.org/release/windows/hackable/|here]]. Simply download, unzip, and run the included hg.exe.  This package will not interfere with your existing Mercurial or Python installation.

Note: The file `mercurial-2.6-hackable.zip` needs the following bugfix: The directory `hg-python26` must be renamed to `hg-python`. Otherwise you will see the error message `abort: failed to load Python DLL` or `ImportError: No module named os` when you try to run hg.exe.

<!> There is usually no need to download new copies between releases, simply pull and update.

/!\ This package includes no global configuration, so if you're not already using Mercurial, you will need to configure your username and merge tools.

== How it's built and how to build your own from scratch ==
Needed components:

 * Python MSI installer, versions 2.4 - 2.7
 * Mercurial source release (see [[Download]])
 * MinGW [[http://www.mingw.org/wiki/Getting_Started|mingw-get]] tool

Steps:

 * Download all the needed components
 * Install Python with `msiexec /i python-2.7.3.msi /qb`
 * Unpack the mingw-get tool into `c:\MinGW` and add `c:\MinGW\bin` to your path
 * Install the gcc compiler with `mingw-get gcc`
 * Unpack Mercurial source into `c:\hg`
 * Copy the Python install from `c:\Python27` to `c:\hg\hg-python`
 * Build Mercurial extensions in `c:\hg` with `hg-python\python setup.py build_ext -i --compiler=mingw32`
 * Build hg.exe in `c:\hg` with `hg-python\python setup.py build_hgexe -i --compiler=mingw32`

== Running the test suite under MSYS ==
Most of the test suite can now be run on windows too. Writing tests and debugging failures might however require both knowledge of the traditional unix environment and of the windows environment.

The tests that can’t be run on windows will automatically be skipped, so no test failures should be seen. The tests are run automatically by [[http://hgbuildbot.kublai.com/waterfall|the hg buildbot]].

Creating a `hg-winhack` package and running the test suite requires almost the same environment. The following instructions will thus contain a lot of duplication of the instructions given above, and the instructions could perhaps be merged.  (The “hackable” mentioned above might not work in development branches.)

=== Install MinGW/MSYS environment ===
 * Install MinGW/MSYS with 'mingw-get-inst-*.exe' from http://sourceforge.net/projects/mingw/files/latest/download
 * Install some mandatory extra packages: `c:\MinGW\bin\mingw-get install msys-base msys-coreutils gcc`
 * Install some optional extra packages: `c:\MinGW\bin\mingw-get install msys-rxvt msys-vim msys-wget msys-unzip msys-zip msys-openssh`
 * Install msys-bz2-1.dll (if it's missing) with: `c:\MinGW\bin\mingw-get install msys-libbz2`
 * Launch a console/terminal with: `c:\MinGW\msys\1.0\msys.bat --rxvt` and enjoy having a decent shell
 * Make mingw gcc available: `echo "c:/mingw /mingw" >> /etc/fstab`

If you're hacking on ChangesetEvolution, you'll also need a suitable [[https://curl.haxx.se/download.html|cURL binary]]. While msys supplies wget, we prefer to use curl, as it's available on macOS by default, whereas Windows always needs an extra package (either curl or wget) installed.

=== Build hg-winhack ===
{{{
# create build directory
hg clone https://www.mercurial-scm.org/repo/hg hg-winhack   # bootstrap Mercurial somehow
cd hg-winhack
# install python
wget http://python.org/ftp/python/2.7.3/python-2.7.3.msi
msiexec //i python-2.7.3.msi //qb   # avoid MSYS magic mangling of '/i'
cp -ar c:/Python27 hg-python     # python can and should now be uninstalled again
# build Mercurial extensions
hg-python/python setup.py build_ext -i --compiler=mingw32
# build hg.exe
hg-python/python setup.py build_hgexe -i --compiler=mingw32
# prepare localizations
hg-python/python setup.py build_mo
# zip it and ship it ... or continue running the test suite
cd ..
zip -r hg-winhack-x.x.zip hg-winhack/
}}}
Note that this will leave you with both a `hg.exe` which can be used from windows and a `hg` which might be picked up by MSYS bash if you have python installed.

=== Run the test suite ===
{{{
cd hg-winhack/tests
export TMPDIR=c:/tmp   # to avoid path that contains ~ which in general would require escaping
PATH="`pwd`/../hg-python:/mingw/bin:/bin" PYTHONHOME="`pwd -W`/../hg-python" ./run-tests.py --local
}}}
PATH can be extended so other non-msys tools (such as git/svn/p4?) can be found.

=== Alternative: Building the C extensions with Microsoft compiler ===
Get and install the gratis "[[http://www.microsoft.com/en-us/download/details.aspx?id=3138|Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 SP1]]" from microsoft.com. It contains both the x86 and x64 Microsoft C/C++ compiler. When running the web-installer, you'll only need to select the features "Windows Headers and Libraries" and "Visual C++ Compliers". Deselect everything else.

Copy `C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat` to `C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat`. When compiling Python C extensions with the compilers bundled with the Windows SDK (and not Visual Studio), you must set DISTUTILS_USE_SDK=1 in the environment, else Python distutils will give you errors about not being able to find vcvarsall.bat

To build Mercurial, in a MSYS shell do (requires Python on PATH):

{{{
make local
}}}
Or using cmd.exe:

{{{
python setup.py build_ext -i
python setup.py build_hgexe -i
}}}
Depending on what Python is used (x64 or x86), the extensions will be built for x64 or x86 accordingly.

=== Run tests involving Git ===
If you have Git installed on your Windows box, `hg-winhack` will incorrectly detect that git command is available, and will try to run Git-related tests. It will fail to do so, because it cannot run "git.cmd" from shell.

 * If you don't want to run Git tests, edit `hghave` file to `return False` instead of `return matchoutput('git --version 2>&1', r'^git version')`
 * If you prefer Git tests to be executed, find your Git installation folder, enter `cmd` folder and create `git` file (no extension) with the following contents:

{{{#!sh
#!/bin/sh
"$COMSPEC" //C git.cmd "$@"
}}}
== See also ==
 * ContributingChanges

----
CategoryDeveloper CategoryWindows CategoryHistorical