About this package
------------------

This archive is a binary installation package for the Mercurial Source 
Control Management system.

See the PKG-INFO file or go to http://www.selenic.com/mercurial/ for 
more information about Mercurial.

This package was built from the Mercurial v1.0.2 source tarball, with 
some source modifications required to adapt it to the OS/2 EMX environment.
These patches are available separately from my website.

This package also includes a pre-built binary of a Python extension 
module (emxrt) which provides access to several EMX runtime library 
functions that are out of scope for the standard Python builtin modules. 
Source for the emxrt module is available from my website.


Installation
------------

You need the Python 2.4[.x] port installed before you can install 
this package - you should be able to get it where you obtained this 
archive.

To install (assuming a working Python installation), change to the 
directory containing the install script (install.cmd), and execute the 
script.


Configuration
-------------

To use the hg command, the directory containing hg.exe must be in the 
PATH and python24.dll must be in [BEGIN|END]LIBPATH.  hg.exe _MUST_ be 
in the same directory as python.exe - this executable is in effect a 
customised version of python.exe which executes the main hg script 
(Scripts/hg) directly.

Mercurial will check for configuration information in the following 
locations:
  [python_root]\Scripts\mercurial.ini
  %HOME%\mercurial.ini
  %HOME%\.hgrc

In this context, [python_root] is the directory that contains python.exe 
and hg.exe.

Information about the format of the configuration file is at 
http://www.selenic.com/mercurial/hgrc.5.html


YOU HAVE BEEN WARNED
--------------------

1.  This package is only very lightly tested, and that only in client 
side operation.  If you start encountering problems, please add the 
following section/items to your Mercurial configuration file to gather 
more information before asking for help:

[ui]
verbose = True
debug = True

2.  The Mercurial developers have made an explicit decision to force 
the stdin, stdout and stderr streams to binary mode - see 
http://selenic.com/repo/index.cgi/hg/rev/a3fe91b4f6eb for the checkin 
log that implemented this.

The simplest method of dealing with this is to pipe the stdout of the 
hg command to a pager utility which transparently handles the Unix line 
endings.  The OS/2 port of less, available from Hobbes, works well for 
this.  Thanks to Dave Yeo for the suggestion.

If you decide that the extra typing of piping through a pager is too
much of a burden, then:
- backup [python-root]\Scripts\hg
- copy [python-root]\Scripts\hg-text-std-out to [python-root]\Scripts\hg

This will revert stdout and stderr to text mode.

However, if you make this change, please be aware that integrating 
Mercurial with other tools may become problematic and there may be 
situations where you will have to restore the original version of the 
hg script.

Note that the above modification still leaves stdin in binary mode.

3.  You should make sure you have an appropriate editor defined, either 
in the configuration file or via the EDITOR or VISUAL environment variable.
The Mercurial source distribution defaults to attempting to use vi if 
no other definition is set.  If the editor cannot be found, the command 
will abort.

It is important that editor you use for this purpose only return control 
to the hg command when you exit the editor; returning control before then 
usually results in the hg command detecting no change to the file that 
was to be edited and the command aborts.  For this reason, the EPM editor 
should not be used.  I gather some versions of the E editor may append 
Ctrl-Z characters to edited files, which may cause problems.

4.  If your file dates/times seem to be wrong, please check the value of 
the TZ environment variable.  The EMX runtime code that parses TZ for 
timezone management info is unforgiving; if it doesn't like the format 
it sets everything to GMT.  In particular timezone names must be 3 letters 
only.  For more info refer to the EMX library docs for the tzset() 
function.

5.  Peter Weilbacher reports:
    "The Win32 text extension of Mercurial seems to work, too. I now
     have

       [extensions]
       hgext.win32text =
       [encode]
       **.cmd = dumbencode:
       [decode]
       **.cmd = dumbdecode:

     in my %HOME%\.hgrc and no longer have problems with linebreaks in OS/2
     CMD files from the Mozilla repository."

Caveat utilitor!!!


Reporting problems
------------------

Unfortunately I am not in a position to provide any information about 
general usage of Mercurial - please refer to the Mercurial website 
(http://www.selenic.com/mercurial/) which has suitable resources.

Please let me know if you encounter any problems with the installation 
package, or if there are any operational problems that might be a result 
of the modifications I've made to get this package running on OS/2.  If 
in doubt, by all means ask me about a problem but please don't be offended 
if I suggest that a problem should be taken up with the Mercurial 
developers.  Neither should the Mercurial developers be expected to know 
anything about this installable package or about OS/2.

This software is provided 'as-is', without any express or implied warranty.
In no event will the packager be held liable for any damages arising from 
the use of the software.


Acknowledgements
----------------

Many thanks to Peter Weilbacher and Dave Yeo who have tested a pre-release 
of this package on the Mozilla sources, and ground off a few rough edges 
in the process.


Andrew MacIntyre
andymac@bullseye.apana.org.au
http://www.andymac.org/
August 21, 2008
