1. Introduction --------------- To set up LIGNUM and specific models implemented with it you must first install Qt4 and cvs. Qt is set of programming libraries and it is needed for LIGNUM. cvs is a software version control system used in the development of LIGNUM. After the Qt installation download the core-model of LIGNUM and the graphical user interface qt-workbench and use Qt software tools to compile then. Finally, download the tree models of interest and compile with Qt software tools. Qt is a free sofware library and it has enabled us to write graphical user interface (a.k.a Lignum Workbench) for the most common operating systems. The various tree models implemented with LIGNUM are command line programs. The simulations may take long time, and it is not practical to implement specific user interface for each model. Instead, the simulated tree can be saved into a file in XML format and this xml-file can be loaded into Lignum Workbench to inspect the simulated tree. To compile and setup both Qt and LIGNUM you need to use the command line of your operating system (Windows, Linux, Mac). The required procedures are explained step-by-step. However, the web is full of Unix and DOS tutorials. Type for example 'Unix tutorial' or 'DOS tutorial' in the Google for more information of their command line use. 2. Caveat emptor ---------------- 2.1 Operating systems --------------------- Please note that Qt4 requires up-to-date version of your Linux distribution. If you have not upgraded your operating system for a while, e.g. you have SuSe 9.x, consider upgrading it first. Qt4 may compile, as well as the graphical user interface LignumWb for LIGNUM, but it probably will fail to run because your X-Windows server (the device driver for your graphics card and the engine for your windowing system) does not support features requierd by Qt4. Windows operating systems should be fine. We have positive experience for XP. We develop LIGNUM on Mac OS X. 2.2 Qt ------ The qmake program and its project (.pro) files are an excellent way to manage software projects. There is however one feature that can be hazardous. The qmake program can describe file dependencies in pro-files (see DEPENDPATH in qmake manual) but this is not infallible. It seems that the dependency checks are limited to header (.h) files only. When editing source (.cc) files in the dependency directories the Makefiles qmake generates can rebuild the relevant libraries, but the program(s) in the main project are not relinked. That the program libraries in other projects are rebuilt is left unnoticed! Thus if this happens remove first the compiled program(s) in the main project manually and then recompile to relink against dependency libraries. 2.3 Mac OS X ------------ There is a bug in qmake prior to Qt 4.3 with the option '-spec macx-xcode'. XCode cannot parse paths generated by qmake having directories with special characters like '+' in their names. The bug has been fixed in Qt 4.3. In Qt 4.3 the option '-spec macx-xcode' produces XCode project file that compiles locally but not using distributed compilation. To define the behaviour of qmake the Qt installation has a directory called /usr/local/Qt4.3/mkspecs/common. This directory contains a file called mac-g++.conf. The file contains (on separate locations): QMAKE_CC = cc QMAKE_CXX = c++ Change them to be QMAKE_CC = gcc QMAKE_CXX = g++ to compile with XCode using distributed compilation. Qt can be downloaded as a precompiled binary for Mac OS X. Read carefully the instructions during the Qt insallation to be aware of the file locations. They are needed to set the Qt environment variables. 3. Downloading Qt ----------------- You can download the free Qt software from http://www.trolltech.com/products/qt/downloads Scroll down to the "Open Source Edition download files" and download the Qt edition for your operating system. Unpack and pull out the Qt source files from the download package. 3.1 Linux --------- Your graphical user interface should be smart enough to do unpack and untar the download package for you when you (double) click it. Otherwise you need to type 'gzip -d .tar.gz' and 'tar -xvf .tar' in the command line. 3.2 MacOS X ------------ To compile from source download the .tar.gz package. Qt has also a precompiled .dmg package. 3.3 Windows ----------- The Windows edition might be confusing because there are two download packages. Download the latest version with mingw, i.e. "-mingw.exe". Then double click the exe-file and follow the instructions. 4. Installing Qt ---------------- 4.1 Compiling from source ------------------------- It is always a good idea to ask your IT-support to do the Qt installation. Importantly, read the INSTALL file for the detailed step-by-step installation instructions for each operating system for various options. But from the point of view of LIGNUM, after dowloading and unpacking the Qt software, it has been enough to do the following to compile and install Qt. Start a terminal window, i.e. the command line tool, and type: 1. Go to Qt download directory where you can find the INSTALL file prompt% cd 2. Configure and compile Qt prompt%./configure <-- Windows users type: configure Configuration might take some time prompt%make <-- Takes even longer, possibly few hours depending on your machine. Might be a good idea to start the compilation when you leave the office and let Qt compile overnight. 3. Windows users done. This part below is for Linux to install Qt prompt%su <-- After compilation (next morning) switch to "root", i.e. system administrator prompt#make install <-- Does not take long, installs Qt to /usr/local/Trolltech/ prompt#exit prompt% 4. You are done MacOS X defines so called "sudo" users, a.k.a "sudoers" (sudo = super user do). Instead of explicitely logging as a root at Step 3. type: "sudo make install". 4.2 Mac OS X precompiled binary package --------------------------------------- After downloading the .dmg file a Finder window with ReadMe.txt and Qt.mpkg files should open. Read the ReadMe.txt for details. Most notably the precompiled binary package requires Mac OS X 10.4.x (Tiger) and gcc 4.0.x compiler. To install double click the .mpkg file, read and follow the instructions. If you are interested, it is then possible to install in the same way the so called debug libraries for Qt (libraries compiled with debugging information). Download the debug-libs.dmg package. 5. Setting up environmental variables ------------------------------------- To use Qt and cvs edit environmental variables affecting the way running processes or programs behave on a computer. You must set QTDIR to Qt installation directory, expand the PATH to QTDIR/bin and set CVS_RSH to ssh in your environment. QMAKESPEC defines the compiler to be used. In most systems it is possible to use 32 or 64 bit compilers from various vendors. Usually the default value is fine, i.e. the 'default' and 'common' are used (see mkspecs) and QMAKESPEC need not need to be set. Note that the settings for the environmental variables must be in the machine where the Qt is installed. See the details for Linux and Mac in sections 5.1-5.3 and for Windows the section 5.4 if Qt is compiled from source. For precompiled binary for Mac OS X see section 5.5. 5.1 bash-shell for Linux and Mac -------------------------------- Although all Linux distributions and MacOS X have graphical user interfaces, the traditional Unix command line tool or shell is still necessary or at least useful for example when logging in remotly to another machine and in program development. And, for the good and the bad, there are many shells to choose from. On Linux and MacOS X the shell reads configuration files at start up where the evironmental variables can be set. These files are located in your home directory, i.e. the directory Unix systems assign for each user denoted by '~' (character tilde). For example on MacOS X it is set to /Users/. When you log in or start a new shell (i.e. a terminal window in practice), your current directory a.k.a working directory will be set to your home directory. When you start a bash-shell command line tool it will first read the system wide /etc/profile and then the user defined ~/.bashrc (Linux) or ~/.bash_profile (MacOS X) file. The shell configuration file names start with a '.' (character dot), so that they won't appear in file listing ('ls -a' however shows all files in a directory). To edit these files use your favourite text editor. On MacOS X Finder by default does not show these 'hidden' files. In command line type 'open ~/.bash_profile' to edit existing .bash_profile. If it does not exists type 'touch ~/.bash_profile' to create one first. 5.2 QTDIR, PATH and CVS_RSH for bash-shell, Qt compiled from source. -------------------------------------------------------------------- Set QTDIR to the Qt installation directory, add QTDIR/bin to your PATH and set CVS_RSH to ssh. To do this the ~/.bashrc (for Linux) or ~/.bash_profile (for Mac OS X) should have the following for Qt: #QTDIR is the installation directory for Qt #where e.g. qmake is located. In Linux everything #seems to go under /usr/local/Trolltech export QTDIR=/usr/local/Trolltech/ export PATH=$QTDIR/bin:$PATH export CVS_RSH=ssh #Uncomment the 'echo' below if you want to check #that the file is processed. #echo "Setting QTDIR, PATH and CVS_RSH" The Qt binaries are in the PATH first, because you may already have older version of Qt installed when the (Linux) operating system was installed. The CVS_RSH tells the cvs to use ssh when transporting files. You may want to edit the system wide /etc/profile for bash to set QTDIR, PATH and CVS_RSH for all users. bash-shell seems to be the default shell for Mac and most Linux distributions. For other shells the process setting up environmental variables is smilar but see manual pages (e.g. type man bash) for the files to edit and the file syntax, i.e. how to create environmental variables, for the shell. A quick way to check your shell is to type: prompt%foobar -bash: foobar: command not found prompt% bash and other shells will echo their name first and then command 'foobar' is not found. To see your environment in your shell, type 'printenv' or 'env' in the command line. 5.3 environment.plist file on MacOS X ------------------------------------- On MacOS X each login process from the login window reads the file called '~/.MacOSX/environment.plist' (if it exists) to set up the environment for all the programs, not only for bash shell. If you want to use this file, select from the menu bar 'Go --> Go to Folder' in the Finder and type ~/.MacOSX/. Then double click environment.plist to edit. Or in the command line type: open ~/.MacOSX/environment.plist. Please note when the bash shell starts, it will read /etc/profile and most likely override your settings for PATH. environment.plist can be edited with a text editor, but this requires some knowledge on the XML language. 5.4 Windows ----------- For Windows adding QTDIR and expanding PATH in the environment is done using System Adminstrator tools. Depending the cvs program on Windows you may or may need to set the CVS_RSH (TortoiseCVS does not need it). Note that reboot of the machine is usually required before the changes take effect. For Windows no 'make install' step was needed for Qt. The installation directory for QTDIR is the download directory, where 'make' was issued and where the INSTALL file for Qt can be found. 5.5. Precompiled Qt for Mac OS X. --------------------------------- The installation scatters Qt files into various places, most of them under directories found in "/Developer" creating Qt directories in Tools, Applications, Examples, Documentation etc. The configuration files for qmake will be in "/usr/local/Qt4.", most notably the mkspecs directory. Add "/Developer/Tools/Qt" to the PATH. It seems qmake can find "mkspecs" directory in "/usr/local/Qt4.x" without setting QTDIR explicitely, i.e QTDIR is not needed. The qmake in the precompiled binary by default generates project files for XCode (see "/usr/local/Qt4./mkspecs/default/qmake.conf"). To change qmake to generate Makefiles for the make program set QMAKESPEC to macx-g++. Finally, set CVS_RSH to ssh. 6. Installing and getting started with CVS ------------------------------------------ You can download a popular and easy to use TortoiseCVS cvs client for Windows from http://www.tortoisecvs.org/. Again, ask your IT support to do the installation if you find it too difficult. For Mac and Linux cvs is present if the programming development tools are installed. There are four important commands in CVS that you should learn: checkout, update, commit and add. With checkout desired projects can be downloaded, update merges latest changes from the repository and commit sends changes made in a project files into the repository. With add new project files can be added for version control. When updating the files three things can occure. 1) A file is up to date and does not need merge from cvs 2) a file is out of date and the merge from cvs is successful and 3) a file is out of date and the merge is not successfull. The third case usually implies you have edited the file and your work conflicts with the work already done and committed to cvs. Please be aware of the possibilities for conflicts. They are denoted by cvs with letter 'C' in front of file name during the update. You must examine such files and resolve the reasons for conflicts manually (cvs can only detect conflicts). See the cvs manual for details. The cvs manual is called 'The Cederqvist' and one copy is available from http://www.metla.fi/lignum-weppijakelu/manuals. As you may notice there is a lot one can do with cvs. A practical way to read the manual is to look at the desired command in the Appendix A and if necessary then read the more detailed description in the manual. 7. Installing LIGNUM -------------------- 7.1 Downloading the software ---------------------------- LIGNUM is not implemented as a single program, but it is managed as a set of different software modules each serving a well defined purpose. 7.1.2 Using the command line cvs -------------------------------- To download necessary software from CVS repository first checkout the so called core-model (the libraries and headers always needed). The command line for cvs checkout is: cvs -d @ssh.metla.fi:/home/cvs checkout core-model Then in the core-model checkout the tree model(s) of your interest: cd core-model cvs checkout 7.1.3 Using TortoiseCVS on Windows ---------------------------------- In the TortoiseCVS select the directory where you want to download the core-model, right click, and choose "CVS Checkout...". This will bring you TortoiseCVS checkout dialog. Enter the following information: Protocol: Secure shell(:ext:) Server: ssh.metla.fi Port: Repository directory: /home/cvs User name: Type in the module name, i.e core-model, and press O.K. Then select the core-model, right click, and choose "CVS checkout..." and checkout the models needed. 7.2. Compiling the software --------------------------- The compilation process with qmake and make is the same for all operating systems. In general you first type 'qmake .pro' and then 'make'. The so called pro files are (human readable) project description files for qmake that can generate (less human readable) Makefiles for make. To clean up all compilation type 'make distclean'. To optimize the program for performance you can type 'qmake "CONFIG+=release" .pro' and then 'make'. The graphical user interface ---------------------------- To compile the graphical user interface (GUI) called LignumWb (a.k.a "Lignum Workbench") go to qt-workbench and see the README.txt file for compilation with qmake and make programs. Note that you need to do this only once (naturally, any changes and bug fixes require recompilation). The LignumWb is separate from the LIGNUM tree models. The tree models implemented with LIGNUM can be saved in XML files the LignumWb can read and visualize. The launch of the LignumWb depends on your platform. On Windows and Linux it is a command line binary (though you may want to double click the application icon from your desktop). On Mac the applications are arranged in a directory hierarchy with a top level directory with suffix '.app'. To launch the application type 'open LignumWb.app' in command line or double click the application icon in Finder. The tree models --------------- Similarly compile your tree models. Go to the model directory and use qmake and make. There should be a README.txt file for each model for detailed instructions. Each tree model is its own implementation and it is assumed that the user of the model is familiar with the use of the model specific command line options. 8. LignumWb quick start ----------------------- You need to compile LignumWb once, so you may find it useful to have it or a file link to it for example on your desktop. Tree models implemented with LIGNUM are in practice batch programs, i.e. they are run using the command line and do not have GUI. Instead each model is saved as an XML file that can be read and visualized with LignumWb. The visualization of models uses textures. There are a few sample files in qt-workbench. You may want to create stem and leaf textures yourself for your tree species. There are no other known restrictions other than the files must in png, jpg or xpm format (The mapping of graphics files to textures is implemented using Qt library). It is possible to visualize models without textures, but modern graphics cards can handle textures faster than e.g. wireframe models. Also, 'big' trees may take some time if the graphics card is old, but modern ones should visualize the trees reasonably fast. See Visualisation settings below for tips to speed up things. LignumWb has a Help menu. Spend a while to read through it. As a quick summary the following hints may be useful: Importing the tree - Click "Add tree" to import a new tree. - You can import several trees, but to save memory you may want to remove trees you do not need anymore. Visualization settings - Select "Options"-->Visualiztion settings" to set Segment texture, Leaf texture and Foliage texture. (We need to correct the terminology some day: Leaf texture is for leaves, but Foliage texture is for conifer needles). See qt-workbench for sample files. - Unselect visualize buds to speed up things. - "Detail settings" with less detail (smaller value) speed up things a bit in general. - Setting foliage detail to 0 will not visualize needles. - BSP (binary space partition) creates better visualization but can be slow (something for the final images for a publication). Grahical rendering of the tree - Click "Visualize selected" Other tips - "Set Working Directory" is useful. - You may find "Tracking" feature interesting. - The console command line window can execute programs, most notably your tree models. It might be more practical than working on a separate terminal window command line. However, in Windows XP with little memory (< 1 GB) the command line window seems to be unstable (LignumWb simply crashes).