This is the gmt cygwin gentoo-prefix overlay.  It will be, I hope, a /temporary/
resting place for various patches that are on their way to various upstream
projects, but which, in the meanwhile, are useful or necessary for getting a
working Cygwin Gentoo Prefix install up and running.

Until then, this overlay will (try, at least, to) allow you to get up and running
with a Gentoo Prefix installation which works under the cygwin POSIX
compatibility library (see http://cygwin.com/ for more info).

LICENSE(S)
==========

Most of the code here was stolen from various other projects.  I have tried to
make it clear where those sources are, but, to be honest, I have probably not been
as clear as I could have been.  Where I have written my own code I'd like to
license it in as practical a manner as possible, first, and secondly, as permissive
a manner as possible.

Please treat the original portage additions such as the code in the ebuilds and
(the novel bits of) profile.bashrc as GPL-2, but please treat any other code I have
written and published here (especially, the various non-portage scripts, such as
gendiffs and portage_workdir_hacktool) as MIT/X11

By the above, however, I mean /original/ code (obviously), not stuff that is cloned
from other repositories -- and please bear in mind that I'm placing the burden of
determining which code is original on YOU -- because I have NOT clearly labelled it
all.  A lot of this is implicit, and if you are familiar with the various upstream
projects I'm borrowing from, you should have no trouble figuring out what comes
from where.  Ebuilds, of course, are copied from portage.  Patches labelled as
"cygport" are imported from the Cygwin Ports project; in all cases, purloined code
inherits the upstream license policy.

Enough about that.


Expertise Required
==================

For the time being, this code is very rough, and chock-full of bugs, not to mention
random hacks that represent failed experiments and the occasional flight of fancy
which may very well have zero or even negative value.

For this reason, to get anywhere with this overlay, you will need at least an
"intermediate" skill level with portage.  If you are a first-time Gentoo user, I
would not expect to get very far, even if, for example, you are an old-time pro
with BSD Ports but with no Gentoo experience.

This will hopefully improve, going forward, but that is the situation as of this
writing (3/3/12).


INSTALLATION (Getting started)
==============================

You will need a reasonably complete cygwin installation -- the exact requirements,
as far as which packages are needed, are unknown at this time.  For the time
being, you will also need to build a custom patched cygwin1.dll.  To do so:

o Check out cygwin from cvs according to the instructions here:

    http://cygwin.com/cvs.html

o apply the multiprocessing patch available here:

    http://cygwin.com/ml/cygwin/2012-10/txt00000.txt

o Follow the instructions at

    http://cygwin.com/faq/#faq.programming.building-cygwin

  to configure, build, and install a new cygwin1.dll to the
  prefix of your choosing (but not "/"!)

o Shut down all cygwin processes and replace your cygwin1.dll with the new one

This is required to work around a problem with fifos in cygwin which is triggered
by both portage (the portage program itself) and the multiprocessing eclass,
in both cases due to use of the bash duplex-redirection construct '<>'.

It is actually pretty easy to fix this problem in portage/multiprocessing.eclass
if it turns out that the problem is going to languish in cygwin.  Efforts are
underway to get the underlying problem solved so for now I'm choosing to ignore
the issue in Gentoo, pending some outcome of that process.

Once all that is ready you can proceed with a bootstrap (or an attempt at one,
see below for reasons that bootstrapping is unlikely to actually work at this
time -- if you do attempt to bootstrap and encounter problems please let me
know via email ([email protected] is fine) so that I know and can address them
(which is not (!!!) to say that I /will/ address your problem.  Lord knows,
you are probably, statistically speaking, some kind of imbecile asshole, and
I will just ignore you or even make fun of you.  But if you are reasonable,
and willing to help out, then I will gladly take a look at your problem and
we'll see what we can do about it).

BOOTSTRAPPING
=============

To bootstrap, you will, roughly, follow the recipe at:

  http://www.gentoo.org/proj/en/gentoo-alt/prefix/bootstrap-solaris.xml

A word of warning: I've been hacking on this for a while.   My initial bootstrap
efforts involved some very aggressive hacks; I have no idea, as of right now, what
would be a working, straightforward bootstrap recipe.  Going forward, I plan to
fix this somehow, either with explicit instructions or a script or both.

In fact, the bootstrap process has been completely reengineered since I last tried
it.  It WILL fail.  If not, it's a fucking miracle.  So by all means, go for it!
Just be advised you are in for a rocky ride, as you will most likely literally be
the first person, ever, to have tried it.

SHOWSTOPPER LIMITATIONS YOU WANT TO KNOW ABOUT
==============================================

-- UAC is not tested

I don't have UAC enabled on my development machines.  Unfortunately, perhaps,
corporate environments seem to keep it enabled as a policy and of course
it is not particularly recommended by anybody concerned about security
to turn it off.  If you don't know, UAC is that feature in Vista and
higher versions of windows which darkens the screen when you do something
"dangerous" and asks you if you really meant to do it.  There are plenty
of guides as to how to deactivate UAC, so if you are comfortable doing so,
your best bet, for now, is probably to go ahead and do so if you want to
play with this overlay.

My guess is that with UAC enabled, cygwin portage is going to pretty much
choke and die very quickly.  Solutions to this can and should be automated,
but in the short run, there isn't much point spending time fixing this
until it is at least possible to bootstrap the system profile.

So for now, turn it off, or fix the problems yourself and send me your
patches (I can be reached at [email protected]).

-- SMB/CIFS paths beginning with '//' are not supported by cygwin prefix!

This is extremely important.  If you are using this overlay, and you use
paths like //foo/bar to get to the 'bar' share on the 'foo' machine, this
prefix is going to give you incredible amounts of grief.  Some things
will work, but be prepared for the likelihood that some tool or another is
likely to decide that you actually mean '/foo/bar'.

Why?  Gentoo ubiquitiously assumes that any number of preceeding slashes are a
noop in a pathname.  A number of upstream packages make the same assumption.
Unfortunately for all parties, paths beginning with '//' are not a noop.
I was surprised to learn that this is not a cygwinism -- it's a POSIXism;
according to the libtool sources, POSIX reserves the '//*' path-space for
implementation-dependent special purposes and cygwin merely makes use of
this reservation.  This means that every time Gentoo acts on this assumption,
there is a bug in Gentoo.

However, The '// == /' assumption is ubiquitous in Gentoo and difficult to
fully eradicate.  Lots of bugs need to be filed for this.  In the meanwhile,
I have patched a number of utilities (notably, coreutils' "install" and libtool)
to silently drop duplicate preceeding slashes from paths.

This is easy to work around.  Just add your //foo/bar path to /etc/fstab
and mount it into your filesystem (i.e., as /mnt/foobar/ or w/e).  Now you
have a nice clean unambiguous way to refer to //foo/bar and all will be fine.
Also, for simple operations like copying files around or tab-completion,
the '//' path is still supported, so you don't necessarily need to go to all
that trouble every time.

In the future, we may have our own ebuild for cygwin1.dll, in which case we
could modify the //foo/bar feature of cygwin to work like /cygdrive: for
example, one could use /smb/foo/bar instead of //foo/bar.  It is worth
investigating whether upstream would be at all amenable to such a change, but
they have had '//' for a long time and it has worked for them, so we may need
to tread lightly there.

However, building cygwin1.dll in prefix would be inconsistent with the
long-standing prefix convention that core operating-system components
such as libc are omitted from prefix.  Years of bitter experience underly
this convention, or so I'm told, and indeed, the cygwin project is extremely
unfriendly to multiple versions of cygwin1.dll floating around, so to
really do this right, we would need cygwin portage non-prefix support,
which is probably a long way off.

USING (INSTALLATION revisited)
==============================

To "install" this overlay into your cygwin-based Gentoo Prefix:

o Put this profile in a directory directly under ${EPREFIX} (below I assume you
  used "overlay")

o put this into your PORTDIR_OVERLAY variable in make.conf i.e.:

	PORTDIR_OVERLAY="${EPREFIX}/overlay"

o create ${EPREFIX}/etc/portage/repos.conf as follows:

	[DEFAULT]
	eclass-overrides = gmt_cygwin_overlay

o invoke eselect as follows:

	PORTDIR=${EPREFIX}/overlay eselect profile set 1

  but this requires a working eselect -- if you don't have that you can just

	cd ${EPREFIX}
  	rm make.profile
	ln -s ../overlay/profiles/prefix/windows/cygwin/1.7/x86/gmtoverlay \
	      make.profile


o you will need a working 'rebase' and 'peflags' in your $PATH

Once those conditions are met, with any luck (OK, with a shit-ton of luck, and
some hacking), you may or may not be able to bootstrap cygwin prefix by
following the recipe at:

  http://www.gentoo.org/proj/en/gentoo-alt/prefix/bootstrap-solaris.xml

Please don't be surprised if stuff breaks -- I haven't ever tested this -- not
even once.

If you are having trouble bootstrapping python due to a chicken-and-egg issue
with the gcc-config -> python -> gcc -> gcc-config recursive dependency, try
emerging python with the "cygbootstraphack" USE-flag.

Rebasing
========

From time to time your gentoo portage is likely to "freak out" and dump lots of
confusing messages about fork().  When this happens there is nothing to be done
for it but to kill off /all/ of your cygwin processes and run the pfxrebase.bat
program from a "dos" prompt (not cygwin).

With any luck, that will fix the problem.  There are some paths hard-coded into
the top of the pfxrebase.bat file.  Please adjust them to reflect the specifics
of your particular installation.  If your cygwin layout is nonstandard you may
also need to hack on the "*_all" files in scripts/.

gl!

-gmt 

Greg Turner
[email protected]