.. ......................................
.. UHDAS/CODAS restructured text document
.. ......................................
.. _CODAS_Compilation:

Part 2: CODAS Compilation
-------------------------

You need a C compiler.
~~~~~~~~~~~~~~~~~~~~~~

- **Linux** : gcc is available as a standard package on every
  linux distribution; if it is not already installed, install it.

- **OSX** : install the complete XCode Tools.
  It should be on your OSX installation DVD.
  It is also at http://developer.apple.com/tools/xcode/.
  This is is a huge download  (1.1 GB), so do it when you have a
  good network connection.

- **Windows**: we use Windows as little as possible and as
  simply as possible, so we do not use MS compilers.  Instead,
  we use a Windows version of the standard free compiler, "gcc".

  .. NOTE::
      We have not tried anything newer than Win XP, 32 bits.

  One easy way to get such a version at present is by downloading
  an installer from
  `Equation Solution <http://www.equation.com/servlet/equation.cmd?fa=fortran>`_.
  The installer includes much more than gcc, but that is not a problem.
  Now follow the next **four** steps:

  1. Download the package and install it.

    Let's assume you install it in ``C:\gcc``.
    (Do not install it in ``C:\Program Files`` or any other path
    with spaces.)

  2. Add the compiler location to your path.

    Bring up the Windows Control Panel, select System, then click
    Advanced, and you will be able to edit the system "PATH"
    environment variable.  Append ``;C:\gcc\bin`` (or appropriate
    path) to it.  Note that the path variable is a set of paths
    separated by semicolons.

  3. We use a tool called `Scons <http://www.scons.org>`_
     (see below) to manage the compilation.
     You must  ensure that Scons will be able to find and identify
     the  compiler.

    The Windows port of gcc is of a style called "mingw";
    SCons will need to detect this by finding (but not
    actually running) a file called ``mingw32-gcc.exe``. Using the
    example above, look for ``C:\gcc\bin\gcc.exe`` and make sure
    there is also a file called:

    ``C:\gcc\bin\mingw32-gcc.exe``

    (copy and rename if necessary).

  4. Now tell Python distutils what kind of compiler to use.

    If your Python is installed in ``C:\Python26``, for example,
    put the contents below in the file
    ``C:\Python26\lib\distutils\distutils.cfg``; or save the file
    from this `link <../txtfiles/distutils.cfg>`_ to that location.

    ::

       [build]
       compiler = mingw32

    .. NOTE ::
        Make sure your file is saved as ``distutils.cfg`` not
        ``distutils.cfg.txt``!  Windows tends to tack on spurious
        extensions without asking, and then fails to display
        the full filename with the added extension.

  There are other distributions of mingw. If you
  find a different one that you like, please tell us, and we
  may add it to this documentation.  If you have problems,
  please find a Windows expert to sort them out; we cannot
  take on that role.  If you discover things that would be
  useful to others if included in this documentation, again,
  tell us.


You need the build tool, scons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`Scons <http://www.scons.org>`_ is a build system.  Together with
scripts in codas3, it generates the many commands required to compile,
link, and install codas3 with whatever C compiler is available, on
whatever type of system you are working on.  It is written in pure
python so it is easy to install.

.. NOTE::

        On Windows, assuming you have python installed in
        "C:\python26" you will need to make sure that
        "C:\python26\scripts" is on your system PATH

Bring up the Windows Control Panel, select System,
then click Advanced, and you will be able to edit the system
"PATH" environment variable.  Append ``;C:\Python26\scripts``
(or appropriate).  Note that the path variable is a set of paths
separated by semicolons.



How to compile
~~~~~~~~~~~~~~

Compile codas3 **first**: go to the codas3 directory and
read "INSTALL.txt".  From that directory, you would typically
compile as in these examples:

**linux, 32-bit:** ::

    scons platform=lnx

**OSX intel:**     ::

    scons platform=osxintel

**Windows:**       ::

    scons platform=win32