# HG changeset patch # User Michael Guravage # Date 2011-02-16 08:26:29 # Node ID e1209459d052d1125e2e427d918fe9f11b91f07e # Parent fe65715748277d4d0afabcc53eeec519fa405b0d initial commit diff --git a/doc/recipe.rst b/doc/recipe.rst new file mode 100644 --- /dev/null +++ b/doc/recipe.rst @@ -0,0 +1,245 @@ +.. $Id$ + +.. |date| date:: +.. |time| date:: %H:%M + +.. header:: + ###Title### - |date| + +.. footer:: + ###Page### + + +Virtual Leaf +============ + +Linux Installation +------------------ + +Material +++++++++ + #. The Virtual Leaf source code + #. `QT SDK `_ + #. Development Systems will have many of these items already installed: + + #. Python programming language + #. `Mercurial revision control system `_ + #. 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 `_. + + #. 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 + 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 `_ revision control system . + #. `KDiff3 diff/merge tool `_. + #. `Iconv conversion utilities `_ + (rename libiconv.dll.a to libiconv.a). + #. `Perl programming language `_. + #. `Zlib compression library `_. + #. `libz-1.dll `_ (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 `_. + + #. Create a Mercurial configuration file named .hgrc in your `home + directory `_:: + + Notepad "C:\Documents and Settings\your_name\.hgrc" + + Add these lines to the configuration file:: + + [ui] + editor = Notepad + username = your_name + + [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``. + +