Installation Instructions
=========================

$Id: INSTALL.in,v 6c57b4d97bfd 2013/09/04 15:45:38 keithmarshall $

The information which follows describes the procedure for installing and
configuring mingw-get, and for keeping the  installation  current.   The
online  version  of  this document is an abridged form, focussing on the
installation of binary releases; users who prefer to build  and  install
from source are advised to consult the unabridged form of this document,
which may be found  in  the  file  "INSTALL",  within  the  source  code
distribution tarball.

Please report bugs as directed at http://mingw.org/Reporting_Bugs


First Time Installation of a Current Binary Release
---------------------------------------------------

Note that, as of release 0.6.0, the installation procedure for mingw-get
has been significantly simplified.  The installation instructions  which
follow  relate  to this release, and later; for instructions relating to
any earlier release, or if you are unable to run the new setup  tool  on
any  legacy  version  of Windows, please refer to the following section,
under the heading "First Time Installation of a Legacy Binary Release".

To install mingw-get, visit the MinGW files repository at:

    http://sourceforge.net/projects/mingw/files

then, from the "Installer" folder, download and run mingw-get-setup.exe,
and  select  your  choices  from  the  options presented [*], to install
mingw-get.  When this has completed, you will then be offered the option
to  immediately  continue  with the installation of a basic selection of
MinGW packages  [**].   If  you  do  choose  to  continue  with  package
selection, this will be processed by an integrated preview of the mingw-
get GUI  application,  (regardless  of  whether  you  have  accepted  or
declined  the  option  to  install  the  GUI);  to complete your initial
installation:--

- Select individual packages, within the upper  right  hand  "list-view"
  pane of the GUI window;

- From  the  "Package"  menu,  (which also appears as a pop-up, when you
  click the status icon at the left hand side of the list entry), select
  the  option  to  "Mark  for  Installation", in respect of each package
  which you wish to install;

- Having so marked all packages which you  wish  to  install,  from  the
  "Installation"  menu  select  the  "Apply Changes" option, to complete
  your initial installation.

After you have completed the installation  of  mingw-get,  as  described
above,  and  regardless  of  whether  you  chose  to  install additional
packages, or not, you  are  advised  to  review  the  configuration,  as
specified  in  your  profile.xml file, and noting in particular, any new
features which are described in the supplied defaults.xml file,  if  you
have  a profile.xml from a previous release; please refer to the section
below, under the heading "Specifying the Configuration", for details.

[*] By default, mingw-get-setup.exe will offer to install mingw-get into
the  "C:\MinGW" directory.  You are *strongly* recommended to adopt this
default; however, if you do decide to change it, please *do*  choose  an
alternative  with  no  white  space  within  its absolute path name.  In
particular, those who choose to ignore this advice,  and  install  MinGW
into  some  subdirectory  of  (for  example)  C:\Program Files", usually
discover to their cost that certain tools may not work correctly.

[**] The set  of  packages  offered,  as  the  foundation  for  a  basic
installation,  are equivalent to those offered by the mingw-get-inst.exe
companion to earlier releases of mingw-get.  Unlike  mingw-get-inst.exe,
mingw-get-setup.exe,  does  *not*  insist that you install the basic GCC
compiler suite.  You are free to install it, or not, at your own option;
if  you do wish to install it, please select the "mingw32-base" package,
which is the equivalent of the minimum mandatory  selection  imposed  by
mingw-get-inst.exe


First Time Installation of a Legacy Binary Release
--------------------------------------------------

The  instructions  which  follow relate to the installation of mingw-get
releases prior to version 0.6.0; they also apply in the  case  of  later
versions,  where  a  legacy version of Windows may not permit you to run
the new mingw-get-setup.exe tool.  For installation of release 0.6.0, or
any  later  release,  using the new tool, please refer to the preceeding
section, under the heading "First Time Installation of a Current  Binary
Release".

To install mingw-get, visit the MinGW files repository at:

    http://sourceforge.net/projects/mingw/files

and,  from the "Installer/mingw-get-<version>-<class>-<release>" folder,
download your choice of either:

    mingw-get-<version>-mingw32-<class>-<release>-bin.zip

or (preferred, if you know how to unpack it):

    mingw-get-<version>-mingw32-<class>-<release>-bin.tar.xz

Whichever of these you choose to download, you should unpack it into the
directory  in  which  you  intend  to  host your MinGW installation; (we
*strongly* recommend that you adopt our standard of C:\MinGW [*], unless
you  have an exceptional reason to make an alternative choice), then use
your preferred method for assignment of environment variables to add the
appropriate  directory (default C:\MinGW\bin) to your PATH; (this should
be added as a permanent PATH assignment).

Having completed this phase of installation, you may then wish to review
the following section on configuration; if nothing else, you may wish to
copy the supplied defaults.xml file to profile.xml, even if  you  choose
not  to  introduce  any  customisations.   Finally,  to  initialise  the
installation recording database, you should run the command [**]:

    C:\> mingw-get install mingw-get


[*] If you insist on adopting a different directory from the recommended
default,  you  are  *strongly*  advised to avoid any directory which has
white space in its absolute path name; in particular, those  who  choose
to  ignore this advice, and install MinGW into some subdirectory of (for
example) C:\Program Files", usually discover to their cost that  certain
tools may not work correctly.

This document will refer to files as though installed in the recommended
default location, with a path prefix of C:\MinGW.  If, having  read  the
above  warning, you do decide to adopt an alternative installation path,
then please substitute your alternative prefix,  as  appropriate,  where
this document refers to C:\MinGW.

[**] If  you  have  chosen  mingw-get-0.6.3-mingw32-bin.tar.xz  as  your
installation source, rather  than  mingw-get-0.6.3-mingw32-bin.zip,  you
may like to create the directory:

    C:\MinGW\var\cache\mingw-get\packages

(together  with any requisite parents, and adjusting the C:\MinGW prefix
to suit your installation choice, if necessary).  You may then move  the
mingw-get-0.6.3-mingw32-bin.tar.gz  file  to  it,  *before*  you run the
above command; this will relieve mingw-get of the overhead  which  would
be incurred by downloading the file a second time.


Specifying the Configuration
----------------------------

When  you  invoke  mingw-get, it will attempt to read configuration data
from the file:

    C:\MinGW\var\lib\mingw-get\data\profile.xml

(with any necessary adjustment of the C:\MinGW installation  prefix,  as
noted  previously);  if,  and  only if, this file cannot be read, then a
fallback attempt will be made, to read the configuration from:

    C:\MinGW\var\lib\mingw-get\data\defaults.xml

instead.  Of this pair of files, profile.xml is  *not*  included  within
the  mingw-get  distribution,  but defaults.xml *is*.  It is a liberally
commented XML file, which you are advised to copy to create profile.xml;
you  may then modify this, as you see fit, to suit your own installation
requirements. [*]

At the present time, the only entries you should consider  changing  are
the path names specified by the "path" attribute associated with each of
the "sysroot" elements within the  first  (only)  "system-map"  element;
(these  specify  the prefix directory path names for your installation).
You probably want to make the path for  the  "mingw32"  subsystem  match
your choice for your mingw-get installation; (the "%R" notation, used in
defaults.xml, sets it up thus,  regardless  of  whether  you  choose  to
install in C:\MinGW, or an alternative location).

[*] The  recommendation  to copy defaults.xml to profile.xml may seem to
be an unnecessary inconvenience; it is implemented this way in order  to
safeguard any configuration changes you wish to make; during an upgrade,
defaults.xml will be overwritten, but  profile.xml  will  not,  so  your
configuration will be preserved.


Upgrading an Existing Installation to a Newer Binary Release
------------------------------------------------------------

Once  you have completed a first-time installation of mingw-get, whether
from a binary release or by building and installing from source, you may
wish  to upgrade it, as the project team publishes new releases.  Unless
you insist on *always* installing  from  source,  (in  which  case  each
upgrade effectively becomes a fresh first-time installation from the new
source code), and provided:

- you have previously installed mingw-get-0.1-mingw32-alpha-3 or  newer,
  and

- you have completed the first-time installation process, by running

      C:\> mingw-get install mingw-get

then you may upgrade to a newer binary release by running

      C:\> mingw-get update
      C:\> mingw-get upgrade mingw-get

Otherwise,  if  you have a previously unfinalised installation, i.e. you
did not previously run

      C:\> mingw-get install mingw-get

and that previous installation is  of  mingw-get-0.1-mingw32-alpha-3  or
newer, then you may upgrade and finalise by running

      C:\> mingw-get update
      C:\> mingw-get install mingw-get

Alternatively, any previous installation of mingw-get may be upgraded by
simply  performing  a  new  first-time  installation,  overwriting   the
previously installed version; (this is the only option available, if the
original installation predates mingw-get-0.1-mingw32-alpha-3).


Building and Installing from Source
-----------------------------------

In order to build mingw-get from source, you will require:

- A build platform which is capable of  running  Bourne  shell  scripts,
  which  provides  at  least  the  set of core tools required by the GNU
  Coding Standards, together with a C/C++ compiler suite generating code
  for execution on a native MS-Windows host.  Suitable platforms include
  MSYS, in it's normal MinGW personality, with the MinGW compiler suite,
  or either of Cygwin or GNU/Linux, with a suitable cross-compiler suite
  for a MinGW host.

- A statically linkable libz.a (or  equal)  for  the  native  MS-Windows
  host, together with its associated header files.

- A  statically  linkable  libbz2.a (or equal) for the native MS-Windows
  host, together with its associated header files.

- A statically linkable liblzma.a (or equal) for the  native  MS-Windows
  host, together with its associated header files; (this should be built
  from libxz sources no older than version 4.999.9beta, with a  snapshot
  release date of 2009-12-09 or later).

- A  statically  linkable  liblua.a  for  the  native  MS-Windows  host,
  together with its associated header  files;  (this  should  be  binary
  compatible with the lua-5.2.0 release, as offered by MinGW.org).

- A  statically  linkable  libwtklite.a,  together  with  its associated
  header files; (this is a MinGW.org specific product, currently offered
  only  in source format, which you are advised to build and install for
  yourself).

Having provisioned a suitable build platform, with  these  pre-requisite
libraries  installed,  you  should obtain and unpack the source tarball,
mingw-get-0.6.3-mingw32-src.tar.gz, in any  working  directory  of  your
choice, to create your mingw-get-0.6.3 source directory.

At this point, you may elect to build in-source, in which case you would
follow the conventional GNU build procedure:

    $ cd mingw-get-0.6.3
    $ ./configure --prefix=/mingw [options ...]
    $ make

However, it is strongly recommended that you elect  instead,  to  create
and  use a separate build directory.  This may be a subdirectory of your
mingw-get-0.6.3 source directory,  e.g. build-dir,  in  which  case  you
would proceed as follows:

    $ mkdir mingw-get-0.6.3/build-dir
    $ cd mingw-get-0.6.3/build-dir
    $ ../configure --prefix=/mingw [options ...]
    $ make

Finally,  if you are building on the host on which you intend to deploy,
and provided the build has completed  without  error,  you  may  install
mingw-get by executing:

    $ make install

or:

    $ make install-strip

Alternatively,  if you wish to create an installation kit for deployment
on any remote host, you may:

    $ mkdir staged
    $ make prefix=`pwd`/staged install

or:

    $ mkdir staged
    $ make prefix=`pwd`/staged install-strip

and then:

    $ cd staged
    $ tar cf ../mingw-get-0.6.3-mingw32-inst.tar .

to create an installation tarball,  which  may  be  deployed  simply  by
unpacking it in the /mingw root directory, on any host you choose.


Building and Installing from Source in Git
------------------------------------------

If,  rather than building mingw-get from the source code provided in the
form of a release tarball, you prefer to keep on  the  cutting  edge  of
development within the public CVS repository, there are a few additional
pre-requisites which you must satisfy on your build platform:

- You must have either a git client, or  a  mercurial  client  with  the
  hggit  extension  enabled,  which you can use to fetch the source code
  from the repository, and subsequently keep it current.

- You must have the GNU autoconf package, with a version number of  2.59
  or later, (and preferrably 2.67 or later).

- You must have a working lex, (or flex), scanner generating tool.

- If  you  also  wish to be able to generate the documentation files, as
  included in the top level directory of a source distribution  tarball,
  you will need a working nroff implementation.

Provided  you can satisfy (at least the first three of) these additional
pre-requisites, you may check out the latest source code thus [*]:

    $ git clone git://git.code.sf.net/p/mingw/mingw-get

or:

    $ hg clone git://git.code.sf.net/p/mingw/mingw-get

This will create a working copy of the mingw-get  source  tree,  in  the
mingw-get subdirectory of your current working directory [**].

[*] If  you are an accredited MinGW Developer, you may prefer to use the
SSH access protocol for git, in conjunction  with  your  registered  SSH
keys,  to  access  the git repository; in this case, you should know the
appropriate procedure to use, in place of the above.

[**] Note that, if you are a git user, you *must* perform an  additional
checkout step, (which is not necessary for hg users):

    $ cd mingw-get
    $ git submodule add ../build-aux

Having  thus  obtained your working copy of the source code from the git
repository, you should then:

    $ cd mingw-get
    $ autoconf

(git users should omit the 'cd mingw-get' step, since they will  already
be in the appropriate directory, following the addition of the build-aux
submodule), to generate the configure script, and then:

    $ mkdir obj
    $ cd obj
    $ ../configure --prefix=/mingw [options ...]
    $ make

to progress the build [***], as in the previous case  of  building  from
the source code extracted from a distribution tarball.

[***] Notice  that here we choose to build in a subdirectory called obj;
when building from source in git, building in-source becomes  even  less
desirable  than it is when building from distributed source.  The choice
of obj for the build directory name is dictated by the configuration  of
mingw-get's  git  module  itself;  both  git  and  hg  "know"  that this
directory does not contain any source files of interest to them.

$RCSfile: INSTALL.in,v $: end of file
