.. $Id$

.. |date| date::
.. |time| date:: %H:%M

.. header::
  ###Title###  -  |date|

.. footer::
  ###Page### 


Virtual Leaf
============

Linux Installation
------------------

Material
++++++++
  #. The Virtual Leaf source code
  #. `QT SDK <http://qt.nokia.com>`_
  #. Development Systems will have many of these items already installed:

    #. Python programming language
    #. `Mercurial revision control system <http://mercurial.selenic.com/wiki>`_
    #. KDiff2 diff/merge tool.
    #. GCC, The GNU Compiler Collection
    #. GNU Make
    #. Iconv conversion utilities
    #. Perl programming language
    #. Zlib compression library
    #. Libxml2 XML parser

Methods
+++++++
  #. Install the aforementioned development software.  The following
     commands should show meaningful output::

      python --version
      hg --version
      gcc --version 
      make --version
      iconv --version
      perl --version
      locate libz.so
      locate libxml2.so

  #. The VirtualLeaf is written with the QT Cross platform application
     and UI framework. To compile the VirtualLeaf from source you will
     need to install the QT software development kit(SDK), which you
     can download from the `QT download site <http://qt.nokia.com/downloads/downloads>`_.

  #. Whether installed globally by a system administrator our locally in
     your own user space, make sure the QT bin directory containing qmake
     is in your execution path, e.g.::

      > PATH=/opt/QT/qt/bin:$PATH 

  #. Create a Mercurial configuration file named .hgrc in your home
     directory containing the following lines::

      [ui]
        username = Your Name <your e-mail address>
        merge = kdiff3

      [extdiff]
        cmd.vdiff = kdiff3

      [merge-tools]
        diffFiles.args = $local $other $base 
        kdiff3.args = $base $local $other -o $output

  #. Make or change to the directory where you wish to install the Virtual Leaf::

      > cd /home/michael/simulations

  #. Retrieve the Virtual Leaf source code from its  Google Code repository::

      > hg clone https://virtualleaf.googlecode.com/hg/ virtualleaf

  #. Compilation is effected with make. To facilitate cross platform
     compatibility, the makefiles use two environment variables:
     ``MAKE`` and ``QMAKE`` to name the make and QT-make utilities
     respectively. The fallback defaults are ``make`` and ``qmake``. 
     If you wish to use some other ``make`` or ``qmake`` utilities other
     than the defaults, instantiate environment variables named ``MAKE``
     and ``QMAKE``, e.g.::

      > export MAKE=gmake
      > export QMAKE=/home/michael/MyQT/qt/bin/qmake

  #. In the VirtualLeaf ``src`` directory you will find a
     ``Makefile``, the root of a hierarchy of makefiles, that will
     guide the compilation and installation of the VirtualLeaf
     executable, its default plugins and the tutorial examples.  To
     compile the VirtualLeaf**, go to the VirtualLeaf ``src`` directory
     and invoke ``make``, for example::

      > cd /home/michael/simulations/virtualleaf/src
      > make -f Makefile

     Once the compilation is complete, you will find the ``VirtualLeaf``
     binary in ``virtualleaf/bin`` and the plugins in ``virtualleaf/bin/models``.


Windows
-------

Material
++++++++
  #. The Virtual Leaf source code
  #. QT SDK:  http://get.qt.nokia.com/qtsdk/qt-sdk-win-opensource-2010.02.1.exe
  #. Development Systems most likely will have most of the items in the following list already installed:

     #. Python programming language
     #. `Mercurial <http://mercurial.selenic.com/wiki/Download#Windows>`_ revision control system .
     #. `KDiff3 diff/merge tool <http://sourceforge.net/projects/kdiff3/files/>`_.
     #. `Iconv conversion utilities <http://sourceforge.net/projects/mingw/files/MinGW/libiconv/libiconv-1.13/>`_ 
        (rename libiconv.dll.a to libiconv.a).
     #. `Perl programming language <http://strawberry-perl.googlecode.com/files/strawberry-perl-5.10.1.1.msi>`_.
     #. `Zlib compression library <http://sourceforge.net/projects/mingw/files/MinGW/zlib/zlib-1.2.3-1-mingw32/>`_.
     #. `libz-1.dll <http://sourceforge.net/projects/mingw/files/MinGW/zlib/zlib-1.2.3-1-mingw32/>`_ (rename to zlib1.dll).
     #. Libxml2 XML parser: from ftp://ftp.zlatkovic.com/libxml/ or ftp://xmlsoft.org/libxml2/win32.
        Or compile from source::

          git clone git://git.gnome.org/libxml2

        To obviate compilation problems with mingw see:
         #. https://bugzilla.gnome.org/show_bug.cgi?id=561340 
         #. http://osdir.com/ml/gnome.lib.xml.general/2004-02/msg00007.html
         #. http://www.c-plusplus.de/forum/viewtopic-var-t-is-260421.html 
         #. http://markmail.org/message/rlpeuruibg2ruqqv 


Methods
+++++++
  #. Install the aforementioned development software.

  #. The VirtualLeaf is written with the QT Cross platform application
     and UI framework. To compile the VirtualLeaf from source you will
     need to install the QT software development kit(SDK), which you
     can download from the `QT download site <http://qt.nokia.com/downloads/downloads>`_.

  #. Create a Mercurial configuration file named .hgrc in your `home
     directory <http://mercurial.selenic.com/wiki/WindowsInstall#Setup_environment>`_::

       Notepad "C:\Documents and Settings\your_name\.hgrc"

     Add these lines to the configuration file::

       [ui]
         editor = Notepad
         username = your_name <your_email_address>

       [merge-tools]
         kdiff3.priority=-1
         kdiff3.args=-L1 base --L2 local --L3 other $base $local $other -o $output
         kdiff3.regkey=Software\KDiff3
         kdiff3.regappend=\kdiff3.exe
         kdiff3.fixeol=True
         kdiff3.gui=True

  #. Make or change to the directory where you wish to install the Virtual Leaf::

      > c:\Documents and Settings\michael\simulations

  #. Retrieve the Virtual Leaf source code from its  Google Code repository::

      > hg clone https://virtualleaf.googlecode.com/hg/ virtualleaf

  #. Compilation is effected with make. To facilitate cross platform
     compatibility, the makefiles use two environment variables:
     ``MAKE`` and ``QMAKE`` to name the make and QT-make utility
     respectively. The fallback defaults are ``make`` and
     ``qmake``. Since QT executable names are consistent across
     platforms, the ``QMAKE`` default value, ``QMAKE=qmake``, will
     work fine. You will have to create an environment variable named ``MAKE``
     though.

     To add an environment variable call up the *system tool*, either
     with a left click on the *start menu* then a right click on *My
     Computer* and choosing *properties* from the drop down list, or
     by choosing *control panel* from the *start menu* and then double
     clicking on the *system tool* itself. Once in the *system tool*,
     choose the *advanced* tab and then click the *environment
     variables* button. The environment variables screen is split in
     two with *User* variables above and *System* variables below. Add
     a new users variable named ``MAKE`` with the value,
     e.g. ``mingw32-make``. the QT(SDK) contains the *minimum gnu for
     windows* (mingw) compiler; commonly installed in:
     ``c:\QT\qt-version\mingw\bin``. Look there for the ``MAKE``
     utility name.

  #. For convenience sake, three required development libraries:
     ``libiconv``, ``libxml2`` and ``libz`` are distributed with the
     VirtualLeaf code, and the VirtualLeaf will compile correctly with
     them. If, however, you wish to use other versions of these
     libraries, you will need to reassign the ``LIBICONVDIR``,
     ``LIBZML2DIR`` and ``LIBZDIR`` variables in all the project
     files.

  #. After installing QT and setting the ``MAKE`` environment
     variable, you should be able to invoke a QT command window from
     the *start menu*. This shell automatically includes the necessary
     QT folder in your execution PATH. Within this command window, go
     to the VirtualLeaf ``src`` folder and invoke make, for example::

       > c:\Documents and Settings\michael\simulations\virtualleaf\src
       > mingw32-make -f Makefile

     When complete, you will find the ``VirtualLeaf.exe`` binary in
     ``v1.0/bin`` and the plugins in ``v1.0/bin/models``.


MacOS
-----

Material
++++++++

  Identical to the Linux installation except that instead of GNU GCC
  and Make, install the XCode development environment from the MacOSX
  installation DVDs.


Methods
+++++++

  Identical to the Linux installation except:
    #. Open the Terminal program (in ``/Applications/Utilities/``) and
       retrieve the Virtual Leaf source code from its Google Code
       repository::

         > hg clone https://virtualleaf.googlecode.com/hg/ virtualleaf

    #. Compile the VirtualLeaf code with the correct options::

         > cd virtualleaf/src
         > export QMAKESPEC=macx-g++; make -f Makefile

       When complete, you will find the ``VirtualLeaf`` binary in
       ``v1.0/bin`` and the plugins in ``v1.0/bin/models``.