<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Compilation with libQGLViewer</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="qglviewer.css" rel="stylesheet" type="text/css" />
<link rel="shortcut icon" href="images/qglviewer.ico" type="image/x-icon" />
<link rel="icon" href="images/qglviewer.icon.png" type="image/png" />
</head>
<body>
<div class="banner">
<a class="qindex" href="index.html">Home</a>
<a class="qindex" href="refManual/hierarchy.html">Documentation</a>
<a class="qindex" href="download.html">Download</a>
<a class="qindex" href="examples/index.html">Examples</a>
<a class="qindex" href="developer.html">Developer</a>
</div>
<h1>Compilation with libQGLViewer</h1>
These instructions assume that you have <a href="download.html">installed</a> Qt and libQGLViewer. They detail how to compile a program that uses the libQGLViewer library.
<p>
They apply to the provided <a href="examples/index.html">examples</a> as well as to your own programs.
</p>
<h2>Tuning the <code>.pro</code></h2>
Qt uses a <code>.pro</code> file to tune the compilation settings. The one that comes with the examples is pretty involved since it
tries to automatically detect where the library and headers files are located. It can be simplified for your projects. The three important variables that have to be set in order to use libQGLViewer are:
<ul>
<li><code><b>INCLUDEPATH</b></code> which must indicates where to find the QGLViewer's include files. Since the <code>#include</code>s use a <code>QGLViewer/qglviewer.h</code> syntax,
the <code>QGLViewer</code> suffix should be omitted in this path: If libQGLViewer was installed in the <code>/xxx/yyy/QGLViewer</code> directory, you will set this variable to <code>INCLUDEPATH *= /xxx/yyy</code>.<br /> <br /></li>
<li><code><b>LIBS</b></code> which tells that your program links with libQGLViewer. Use <code>LIBS *= -L<i>/path/to/lib</i> -lQGLViewer2</code>, where <code></i>/path/to/lib</i></code> is the path to the libQGLViewer lib, named <code>libQGLViewer2.{so|a|dylib}</code> or <code>QGLViewer2.lib</code> depending on your architecture.
<br />
<br />
</li>
<li><code><b>QT</b></code> which lists the required Qt modules: <code>QT *= opengl xml</code> is a minimum.</li>
</ul>
Here is a simple although complete <code>.pro</code> (change the paths according to your configuration):
<pre>
TARGET = myViewer
CONFIG *= qt opengl release
QT *= opengl xml
HEADERS = myViewer.h
SOURCES = myViewer.cpp main.cpp
INCLUDEPATH *= C:/Users/debunne/Documents/libQGLViewer-2.3.6
# Windows
LIBS *= -LC:/Users/debunne/Documents/libQGLViewer-2.3.6/QGLViewer -lQGLViewer2
# Linux
LIBS *= -L/home/debunne/libQGLViewer-2.3.6/QGLViewer -lQGLViewer
# Mac if you compiled a framework in /Library/Frameworks (default)
LIBS *= -framework QGLViewer
</pre>
<h2><img src="images/windows.png" width="55" height="54" alt="windows"/>Compilation using the Qt OpenSource edition and <b>MinGW</b></h2>
Launch the Qt command prompt from the <i>Start</i> menu. Then simply type :
<pre>
cd path\to\myApp
qmake
mingw32-make
myApp
</pre>
Some <code>dll</code>s need to be found in order to run your program :
<ul>
<li><code>QGLViewer2.dll</code>, which has been created when you compiled the QGLViewer library.</li>
<li>The Qt libraries (<code>QtCore4.dll, QtGui4.dll, QtOpenGL4.dll</code> and <code>QtXml4.dll</code>), which standard location is <code>C:\Qt\4.x.x\bin</code>.</li>
<li>The MinGW <code>mingwm10.dll</code>, usually located in <code>C:\Program Files\MinGW\bin</code>.</li>
</ul>
Copy them to the executable's directory, or share them in a standard library directory such as <code>C:\Windows\System32</code>.
<p>
If you used the libQGLViewer installation package, these <code>dll</code>s were installed in <code>C:\Program Files\libQGLViewer\examples</code>.
</p>
See also the advices for <a href="installWindows.html">libQGLViewer installation on Windows</a>.
<h2><img src="images/windows.png" width="55" height="54" alt="windows"/>Compilation using the Qt Commercial edition with <b>Visual Studio</b> integration</h2>
Launch Visual Studio from the Qt folder in the <i>Start</i> menu and then use the Qt menu to open the <code>.pro</code> file. All parameters should be properly configured, and your program should compile.
<p>
See the comment in the above section about <code>dll</code>s if you have an error when starting your program.
</p>
<p>See also the advices for <a href="installWindows.html">libQGLViewer installation on Windows</a>.</p>
<div class="small">
Instead of editing the <code>.pro</code>, you can add the QGLViewer's headers path (without the trailing <code>QGLViewer</code>) to <i>C/C++ / General / Additional Include Directories</i>
and add <code>QGLViewer2.lib</code> to the <i>Linker / Input / Additional Dependencies</i> using the project properties.
These settings can also be shared by all your projects by setting the <i>Tools / Options / Directories</i> Include and Library values.
<p>
A <code>fatal error C1083: 'QDomElement' : No such file or directory</code> is fixed by adding
<code>XML library</code> and <code>OpenGL library</code> in <i>Project - Add Qt module</i>.
</p>
With Visual Studio 6, use <i>File-Open workspace</i> to open the <code>.dsp</code> generated by <code>qmake</code> from the <code>.pro</code>.
<!--
<p>
Qt 2.3 users have to first edit the examples' <code>.pro</code> files (uncomment two lines and remove end of
file as explained. Remove <code>QT_DLL</code> from <code>DEFINES</code> for Visual Studio 7). If no
<code>Project created</code> dialog is displayed when you open the <code>.pro</code>, try to run
Visual with Administrator priviledges. With Qt 2.3, you also have to add <code>/GX /GR</code> in
<i>Project-Settings-C-C++, Project options</i> before compilation.
</p>
-->
</div>
<a name="unix"></a>
<h2><img src="images/linux.png" width="49" height="54" alt="linux"/>Compilation on Linux</h2>
Using the Unix command line, the compilation is as simple as:
<pre>
cd path/to/myApp
qmake
make
myApp
</pre>
<!--
The optional <code>PREFIX, INCLUDE_DIR</code> and <code>LIB_DIR</code> parameters are those you used
if you customized your <code><a href="installUnix.html#linux">make install</a></code>. Use
<code>QGLVIEWER_STATIC=yes</code> to link with the static version of the library.
These commands can also be typed in the <code>examples</code>' main directory to compile <i>all</i> the examples.
If you installed the RPM, the examples' source files are in
<code>/usr/share/doc/QGLViewer/examples</code> (may have to be copied to a place where you have
write permission). If you have downloaded the tarball instead, simply go to the
<code>examples</code> directory. Then,
-->
<div class="small">
The use of <code>-Wl,-rpath</code> in the compilation options should make your executable find the library. In case you are prompted with an <code>error while loading shared libraries</code> message when executing the program, fix the path.
An other option is to copy <code>libQGLViewer.so</code> (created when you compiled the QGLViewer library) to this directory,
or (better) move it to a standard library directory (such as <code>/usr/lib</code>, as is done when you <code>make install</code>).
<br/>
<!--
If you don't have sufficient privileges to do that, you can also add the path to the <code>libQGLViewer.so</code> to
your default library path (use <code>LD_LIBRARYN32_PATH</code> instead on some Unix flavors):
<pre>
[bash] > export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/qglviewerlib
[tcsh] > setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/path/to/qglviewerlib
</pre>
-->
Some configurations may require you to add <code>LIBS *= -lXi</code> in the <code>.pro</code> file.
Debian users may have to replace <code>-lQGLViewer</code> by <code>-lQGLViewer-2</code> in their <code>.pro</code>.
</div>
<p>
See also the <a href="installUnix.html#qt-linux">Qt-Unix</a> and <a
href="installUnix.html#linux">libQGLViewer on Unix</a> installation pages.
</p>
<a name="mac"></a>
<h2><img src="images/mac.png" width="55" height="54" alt="mac"/>Compilation on Mac</h2>
<h3>Using Xcode</h3>
<pre>
cd path/to/myApp
qmake -spec macx-xcode
</pre>
Then open and build the resulting Xcode project.
<h3>Using <code>make</code></h3>
<pre>
cd path/to/myApp
qmake -spec macx-g++
make
myApp
</pre>
<h3>Using Qt Creator</h3>
<pre>
open myApp.pro
</pre>
<h3>Next steps</h3>
You will have an error message if the libQGLViewer library is not found at runtime. Either install it in a standard directory (see the <a
href="installUnix.html#mac">installation page</a>) or use <code>install_name</code> to set its path in your program.
<p>
Read Apple's
"<a href="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPFrameworks/Tasks/CreatingFrameworks.html">Creating a Framework</a>"
as well as Qt's "<a href="http://qt.nokia.com/doc/4.6/deployment-mac.html">Deploying an Application on Mac OS X</a>" guides for details.
</p>
Tune the <code>QMAKE_LFLAGS</code> variable if the library was not installed in the default <code>/Library/Frameworks</code> directory. Use the
<code>LIBS *= -L/path/to/lib -lQGLViewer</code> Unix syntax if you compiled a dylib instead of a framework.
<!--
The compilation on Mac is essentially identical to the one described above in the linux section (<code>libQGLViewer.so</code> is named <code>libQGLViewer.dylib</code> instead).
Simply replace the above lines by:
</p>
<pre>
[bash] > export DYLD_LIBRARY_PATH=${DYLD_LIBRARY_PATH}:/path/to/qglviewerdylib
[tcsh] > setenv DYLD_LIBRARY_PATH ${DYLD_LIBRARY_PATH}:/path/to/qglviewerdylib
</pre>
You can safely ignore the prebound warning. Building a prebound library creates overlapping address
ranges. This requires further investigations and any help is more than welcome.
<p>
If you get a <code>declaration of C function 'void qObsolete' conflicts with previous declaration</code> or a
<code>template with C linkage</code> error message, try to install libQGLViewer somewhere else:
</p>
<pre>
cd QGLViewer
make uninstall
qmake INCLUDE_DIR=/usr/local/include (for instance)
make install
</pre>
Tune your <code>.pro</code> accordingly and recompile your program. Any
explanation or cleaner solution is more than welcome.
-->
<h2>Going further</h2>
Now that your program compiles and runs, you can start improving it. You will probably start by changing the <code>draw()</code> method to define your own scene.
Overload the <code>init()</code> function to initialize your scene as well as the OpenGL parameters (such as textures and objects).
<a href="introduction.html">Read the principles</a> of the library for details. If not already done, try out the
different <a href="examples/index.html">examples</a> and feel free to cut and paste code for the functionnalities you need.
<h2>Localizing your application</h2>
See the Qt Linguist Manual for an explanation of the Qt translation model. Here are the lines you typically need to add in your <code>main</code> method to translate the texts of your interface.
<pre>
QApplication application(argc,argv);
QString locale = QLocale::system().name();
QTranslator translator;
translator.load(QString("qglviewer_") + locale);
// translator.load(your application specific translation file(s));
app.installTranslator(&translator);
</pre>
This assumes that <code>qglviewer_*.qm</code> is located in your application directory. If it is not the case, copy it or use the overloaded <code>load</code> method:
<pre>
translator.load(QString("qglviewer_") + locale, "C:\\Users\\debunne\\Documents\\Code\\libQGLViewer\\QGLViewer"); // for instance
</pre>
QGLViewer translation files are available in the QGLViewer's header directory.
<p>
Please <a href="mailto:contact@libqglviewer.com">let me know</a> if you encounter any problem following this guide.
</p>
<p>
<a href="http://validator.w3.org/check/referer"><img src="images/xhtml.png" alt="Valid XHTML 1.0!" height="31" width="88"/></a>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img src="images/css.gif" alt="Valid CSS!" width="88" height="31"/></a>
<i>Last modified on Saturday, May 22, 2010.</i>
</p>
</body>
</html>
