diff --git a/doc/installation.rst b/doc/installation.rst --- a/doc/installation.rst +++ b/doc/installation.rst @@ -16,73 +16,118 @@ Installation Instructions Requirements ------------ -The Virtual Leaf is written with the QT Cross platform application and +The VirtualLeaf is written with the QT Cross platform application and UI framework, and can run on Linux, Apple Macintosh and Windows -machines. To compile the Virtual Leaf 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. +machines. 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. Platform specific instructions follow. All Platforms ------------- Compilation is effected with make, either the native ``make`` on UNIX -and MAC systems or the ``mingw32-make`` distributed with the windows -version of QT. In the Virtual Leaf ``src`` directory you will find a +and MAC systems or ``mingw32-make`` distributed with the windows +version of QT. 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 facilitate cross -platform compatibility, the makefiles expect an environment variable -named ``MAKE`` to name the make utility to use. The fallback default -is 'make.' Platform specific instructions follow. +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``. Platform specific instructions follow. Linux ----- -Prepend the QT bin directory to your path, for example:: +So the Makefiles can find ``qmake``, prepend the QT bin directory to +your execution path, for example:: > PATH=/opt/QT/qt/bin:$PATH -If you wish to use some other make utility than make, instantiate an -environment variable named ``MAKE``, for example:: +If you wish to use some other ``make`` or ``qmake`` utilities other +than the defaults, instantiate environment variables named ``MAKE`` +and ``QMAKE``, for example:: - > export MAKE=gmake. + > export MAKE=gmake + > export QMAKE=/home/michael/MyQT/qt/bin/qmake -Go to the ``src`` directory and invoke make, for example:: +To compile the VirtualLeaf, go to the VirtualLeaf ``src`` directory +and invoke ``make``, for example:: > cd /home/michael/VirtualLeaf/v1.0/src > make -When complete, you will find the ``VirtualLeaf`` binary in -``v1.0/bin`` and the plugins in ``v1.0/bin/models``. +Once the compilation is complete, you will find the ``VirtualLeaf`` +binary in ``v1.0/bin`` and the plugins in ``v1.0/bin/models``. Windows ------- -For convenience sake the libiconv, libxml2 and libz header files and -libraries are distributed with the Virtual Leaf code, and Virtual Leaf -will compile correctly with them. If, however, you wish to compile -with other versions of these libraries, you will need to reassign the -``LIBZML2DIR``, ``LIBICONVDIR`` and ``LIBZDIR`` variables in all the -project files. +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. + +As stated earlier, the Makefiles rely on two environment variables: +``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 named ``MAKE`` +though. -After installing QT 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 -Virtual Leaf's src directory, +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. -In the start menu, right click on My Computer and choose properties -from the drop down list. In the advanced tab click on environment -variables. Append the QT +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\VirtualLeaf\v1.0\src + > mingw32-make + +When complete, you will find the ``VirtualLeaf.exe`` binary in +``v1.0/bin`` and the plugins in ``v1.0/bin/models``. MacOS ----- +Make sure that XCode development environment is installed from +the MacOSX installations DVDs. Also download and install a recent +version of Qt as described above (version >4.4). +Open the Terminal program (in ``/Applications/Utilities/``). +Unpack the VirtualLeaf source package into your home folder, +by typing:: + > cd + > tar xzf VirtualLeaf-V1.0.tgz + +Now go to the ``src`` directory, set the right options for qmake, +and invoke make, by typing, for example:: + + > cd + > cd VirtualLeaf/v1.0/src + > export QMAKESPEC=macx-g++; make + +When complete, you will find the ``VirtualLeaf`` binary in +``v1.0/bin`` and the plugins in ``v1.0/bin/models``. +