source: x/lib/qt.xml@ 2d006066

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY qt-download-http "http://ftp.silug.org/mirrors/ftp.trolltech.com/qt/source/qt-x11-free-&qt-version;.tar.bz2">
  <!ENTITY qt-download-ftp  "ftp://ftp.trolltech.com/qt/source/qt-x11-free-&qt-version;.tar.bz2">
  <!ENTITY qt-md5sum        "cf3c43a7dfde5bfb76f8001102fe6e85">
  <!ENTITY qt-size          "14.3 MB">
  <!ENTITY qt-buildsize     "261 MB">
  <!ENTITY qt-time          "11 SBU (full), 7.5 SBU (sub-tools)">
]>

<sect1 id="qt" xreflabel="Qt-&qt-version;">
  <?dbhtml filename="qt.html" ?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Qt-&qt-version;</title>

  <indexterm zone="qt">
    <primary sortas="a-qt">Qt</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Qt</title>

    <para>The <application>Qt</application> package contains a
    <application>C++</application> GUI library. This is useful for creating
    graphical applications or executing graphical applications that are
    dynamically linked to the <application>Qt</application> library. One of
    the major users of <application>Qt</application> is
    <application>KDE</application>.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&qt-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&qt-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &qt-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &qt-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &qt-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &qt-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
       <listitem>
         <para>Required patch: <ulink
            url="http://www.trolltech.com/developer/download/Qt-3.3.8-UTF-8-fix.diff"/></para>
       </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Qt Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="x-window-system"/></para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended"><xref linkend="libjpeg"/> and
    <xref linkend="libmng"/></para>

    <para>Note: if for whatever reason you do not have the recommended
    libraries installed on your system, you must remove the corresponding
    <parameter>-system-<replaceable>&lt;library&gt;</replaceable></parameter> and
    <parameter>-plugin-imgfmt-<replaceable>&lt;library&gt;</replaceable></parameter>
    parameters from the <command>configure</command> commands shown in the
    instructions below.</para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="nas"/>,
    <xref linkend="cups"/>,
    <xref linkend="mysql"/>,
    <xref linkend="postgresql"/>,
    <xref linkend="unixodbc"/>,
    <ulink url="http://sqlite.org/">SQLite</ulink> and
    <ulink url="http://firebird.sourceforge.net/">Firebird</ulink></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/qt"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Qt</title>

    <para>The <application>Qt</application> source hard codes the location
    of the <application>X Window System</application> installtion to
    <filename class="directory">/usr/X11R6</filename>.  If you've installed
    the <application>X Window System</application> in any prefix other than
    <filename class="directory">/usr/X11R6</filename>, then you should correct
    the <application>qmake</application> configuration files with the following
    commands, replacing <replaceable>&lt;PREFIX&gt;</replaceable> with the
    installation prefix of the
    <application>X Window System</application>:</para>

<screen><userinput>for file in $(grep -lr "X11R6" *)
do
    sed -i "s@/usr/X11R6@<replaceable>&lt;PREFIX&gt;</replaceable>@g" $file
done</userinput></screen>

    <para>There are several ways to install a complicated package such as
    <application>Qt</application>. The files are not completely position
    independent. Installation procedures execute the program
    <command>pkg-config</command> to determine the location of package
    executables, libraries, headers, and other files. For
    <application>Qt</application>, <command>pkg-config</command> will look
    for the file <filename>lib/pkgconfig/qt-mt.pc</filename> which must be
    modified if relocating the package. This file is set up correctly by
    the build process.</para>

    <para>The default installation places the files in
    <filename class='directory'>/usr/local/qt/</filename>. Many commercial
    distributions place the files in the system's
    <filename class='directory'>/usr</filename> hierarchy. The package can
    also be installed in an arbitrary directory.</para>

    <para>This section will demonstrate two different methods.</para>

    <warning>
      <para>Building <application>Qt</application> in a
      <command>chroot</command> environment may fail.</para>
    </warning>

    <note>
      <para>The build time for <application>Qt</application> is quite long. If
      you want to save some time and don't want the tutorials and examples,
      change the first <command>make</command> command to:</para>

<screen><userinput>make sub-tools</userinput></screen>

    </note>

    <sect3>
      <title>Method 1 - Installing in the '/usr' Hierarchy</title>

      <para>The advantage of this method is that no updates to the
      <filename>/etc/ld.so.conf</filename> or
      <filename>/etc/man_db.conf</filename> files are required. The package
      files are distributed within several subdirectories of the
      <filename class='directory'>/usr</filename> hierarchy.
      This is the method that most commercial distributions use.</para>

<!--
      <note>
        <para>The installation incorrectly uses <command>cp</command> to
        install the files. This causes problems if the
        <application>Qt</application> libraries are already in use (e.g.,
        you are logged into your <application>KDE</application> desktop
        environment). To avoid problems, <command>cp -f</command> is
        replaced by <command>install</command> in
        <filename>qmake.conf</filename>.</para>
      </note>
-->

      <note>
        <para>If <application>Qt</application> is being reinstalled, run the
        following commands from a console or non-Qt based window manager.
        It overwrites <application>Qt</application> libraries that should not
        be in use during the install process.</para>
      </note>

    <para>A <ulink
    url='http://www.trolltech.com/company/newsroom/announcements/press.2007-03-30.9172215350'>security
    vulnerability</ulink> has been identified in the
    <application>Qt</application> package. Apply the patch to fix this
    vulnerability with the following command:</para>

<screen><userinput>patch -Np0 -i ../Qt-3.3.8-UTF-8-fix.diff</userinput></screen>

    <para>Continue with:</para>

<screen><userinput>sed -i -e 's:$(QTDIR)/include:&amp;/qt:' \
       -e 's:$(QTDIR)/lib:&amp;/qt:' \
    mkspecs/linux*/qmake.conf &amp;&amp;

bash
export PATH=$PWD/bin:$PATH &amp;&amp;
export LD_LIBRARY_PATH=$PWD/lib:$LD_LIBRARY_PATH &amp;&amp;

./configure -prefix /usr \
            -docdir /usr/share/doc/qt \
            -headerdir /usr/include/qt \
            -plugindir /usr/lib/qt/plugins \
            -datadir /usr/share/qt \
            -translationdir /usr/share/qt/translations \
            -sysconfdir /etc/qt \
            -qt-gif \
            -system-zlib \
            -system-libpng \
            -system-libjpeg \
            -system-libmng \
            -plugin-imgfmt-png \
            -plugin-imgfmt-jpeg \
            -plugin-imgfmt-mng \
            -no-exceptions \
            -thread \
            -tablet &amp;&amp;

find -type f -name Makefile | xargs sed -i "s@-Wl,-rpath,/usr/lib@@g" &amp;&amp;
make &amp;&amp;
exit</userinput></screen>

      <para>This package does not come with a test suite.</para>

      <para>Now, as the <systemitem class="username">root</systemitem>
      user:</para>

<screen role="root"><userinput>make install &amp;&amp;
ln -v -sf libqt-mt.so /usr/lib/libqt.so &amp;&amp;
cp -v -r doc/man /usr/share &amp;&amp;
cp -v -r examples /usr/share/doc/qt</userinput></screen>

    </sect3>

    <sect3>
      <title>Method 2 - Installing in '/opt'</title>

      <para>This is the method recommended by the <application>Qt</application>
      developers. It has the advantage of keeping all the package files
      consolidated in a dedicated directory hierarchy. By using this method,
      an update can be made without overwriting a previous installation and
      users can easily revert to a previous version by changing one symbolic
      link.</para>

      <para>The <application>Qt</application> developers use a default location
      of <filename class='directory'>/usr/local/qt/</filename>, however this
      procedure puts the files in <filename
      class='directory'>/opt/qt-&qt-version;/</filename>
      and then creates a symbolic link to <filename>/opt/qt/</filename>.</para>

      <para>A <ulink
      url='http://www.trolltech.com/company/newsroom/announcements/press.2007-03-30.9172215350'>security
      vulnerability</ulink> has been identified in the
      <application>Qt</application> package. Apply the patch to fix this
      vulnerability with the following command:</para>

<screen><userinput>patch -Np0 -i ../Qt-3.3.8-UTF-8-fix.diff</userinput></screen>

      <para>Continue with:</para>

<screen><userinput>bash
export QTDIR=$PWD &amp;&amp;
export LD_LIBRARY_PATH=$PWD/lib:$LD_LIBRARY_PATH &amp;&amp;
export PATH=$PWD/bin:$PATH &amp;&amp;

./configure -prefix /opt/qt-&qt-version; \
            -sysconfdir /etc/qt \
            -qt-gif \
            -system-zlib \
            -system-libpng \
            -system-libjpeg \
            -system-libmng \
            -plugin-imgfmt-png \
            -plugin-imgfmt-jpeg \
            -plugin-imgfmt-mng \
            -no-exceptions \
            -thread \
            -tablet &amp;&amp;

make &amp;&amp;
exit</userinput></screen>

      <para>This package does not come with a test suite.</para>

      <para>Now, as the <systemitem class="username">root</systemitem>
      user:</para>

<screen role="root"><userinput>make install &amp;&amp;
ln -v -sfn qt-&qt-version; /opt/qt &amp;&amp;
ln -v -s libqt-mt.so /opt/qt/lib/libqt.so &amp;&amp;
cp -v -r doc/man examples /opt/qt/doc</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>sed -i -e ... mkspecs/linux*/qmake.conf</command>:
    Directories in <filename>qmake.conf</filename> need to be adjusted
    to match the BLFS Method 1 installation directories.</para>

    <para><command>bash</command>: This command enters a sub-shell to isolate
    environment changes.</para>

    <para><command>export QTDIR=$PWD</command>: This command defines where
    the root of the <application>Qt</application> directory is located.</para>

    <para><command>export LD_LIBRARY_PATH=$PWD/lib:$LD_LIBRARY_PATH</command>:
    This command allows the not yet installed <application>Qt</application>
    libraries to be used by the not yet installed <application>Qt</application>
    programs.</para>

    <para><command>export PATH=$PWD/bin:$PATH</command>: This command
    allows the build process to find supporting executables.</para>

    <para><parameter>-qt-gif</parameter>: This switch adds support for
    <filename>gif</filename> files to the libraries.</para>

    <para><parameter>-system-zlib -system-libpng -system-libjpeg
    -system-mng</parameter>: These switches force the build instructions to use
    the shared libraries that are on your system instead of creating a custom
    set of support libraries for these functions.</para>

    <para><parameter>-plugin-imgfmt-png -plugin-imgfmt-jpeg
    -plugin-imgfmt-mng</parameter>: These switches enable run-time linking of
    the referenced libraries.</para>

    <para>If you pass the
    <option>-plugin-sql-<replaceable>&lt;driver&gt;</replaceable></option> or
    <option>-qt-sql-<replaceable>&lt;driver&gt;</replaceable></option> switch
    to the <command>configure</command> command, you must also pass
    <option>-I<replaceable>&lt;/path/to/sql/headers&gt;</replaceable></option>
    so <command>make</command> can find the appropriate header files.  For
    instance, building in <application>MySQL</application> support (as opposed
    to building the plugin) will need to use <option>-I/usr/include/mysql
    -qt-sql-mysql</option>.</para>

    <note>
      <para>To check if <application>mysql</application> is autotetected
      properly, examine the output of <command>./configure -I/usr/include/mysql
      -help</command>. Other database support will require similar
      <command>configure</command> parameters.</para>
    </note>

    <para><parameter>-no-exceptions</parameter>: This switch disables
    the exceptions coding generated by the <application>C++</application>
    compiler.</para>

    <para><parameter>-thread</parameter>: This switch adds
    support for multi-threading.</para>

    <para><command>find -type f -name Makefile | xargs sed -i
    "s@-Wl,-rpath,/usr/lib@@g"</command>: This command removes hardcoded
    run-time paths. Otherwise, <command>uic</command> always tries to run
    with <application>Qt</application> libraries in
    <filename>/usr/lib</filename>.</para>

    <para><command>ln -v -s libqt-mt.so /usr/lib/libqt.so</command>: This
    command allows <command>configure</command> scripts to find a working
    <application>Qt</application> installation.</para>

    <para><command>cp -v -r doc/man examples /usr/share (or
    /opt/qt/doc)</command>:
    This command installs the man pages and examples which are missed by
    <command>make install</command>.</para>

    <para><command>exit</command>: This command returns to the parent shell
    and eliminates the environment variables set earlier.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Qt</title>

    <sect3 id='qt-config'>
      <title>Configuration Information</title>

      <para>The <envar>QTDIR</envar> environment variable needs to be set when
      building packages that depend on <application>Qt</application>. Add the
      following to the <filename>.bash_profile</filename> initialization script
      for each user that builds packages using the <application>Qt</application>
      libraries. Alternatively, the variable can be set in the system wide
      <filename>/etc/profile</filename> file.</para>

      <para>For Method 1 (This is optional, only set this if an application is
      unable to find the installed libraries):</para>

<screen><literal>export QTDIR=/usr</literal></screen>

      <para>or for Method 2:</para>

<screen><literal>export QTDIR=/opt/qt</literal></screen>

      <para>If you installed <application>Qt</application> using Method 2,
      you also need to update the following configuration files so that
      <application>Qt</application> is correctly found by other packages
      and system processes.</para>

      <para>Update the <filename>/etc/ld.so.conf</filename> and
      <filename>/etc/man_db.conf</filename> files:</para>

<screen role="root"><userinput>cat &gt;&gt; /etc/ld.so.conf &lt;&lt; "EOF" &amp;&amp;
<literal># Begin qt addition to /etc/ld.so.conf

/opt/qt/lib

# End qt addition</literal>
EOF
ldconfig &amp;&amp;
cat &gt;&gt; /etc/man_db.conf &lt;&lt; "EOF"
<literal># Begin qt addition to man_db.conf

MANDATORY_MANPATH /opt/qt/doc/man

# End qt addition to man_db.conf</literal>
EOF</userinput></screen>

      <indexterm zone="qt qt-config">
        <primary sortas="e-etc-ld.so.conf">/etc/ld.so.conf</primary>
      </indexterm>

      <indexterm zone="qt qt-config">
        <primary sortas="e-etc-man_db.conf">/etc/man_db.conf</primary>
      </indexterm>

      <indexterm zone="qt qt-config">
        <primary sortas="e-etc-profile">/etc/profile</primary>
      </indexterm>

      <indexterm zone="qt qt-config">
        <primary sortas="e-AA.bash_profile">~/.bash_profile</primary>
      </indexterm>

      <para>Update the <envar>PKG_CONFIG_PATH</envar> environment variable
      in your <filename>~/.bash_profile</filename> or
      <filename>/etc/profile</filename> with the following:</para>

<screen><literal>PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/opt/qt/lib/pkgconfig</literal></screen>

      <para>If you want the <application>Qt</application> executables in your
      shell search path, update the <envar>PATH</envar> environment variable
      in your <filename>~/.bash_profile</filename> or
      <filename>/etc/profile</filename> to include
      <filename class='directory'>/opt/qt/bin</filename>.</para>

      <para>As with most libraries, there is no explicit configuration to do.
      After updating <filename>/etc/ld.so.conf</filename> as explained above,
      run <command>/sbin/ldconfig</command> so that <command>ldd</command>
      can find the shared libraries.</para>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>assistant, designer, linguist, lrelease, lupdate, moc,
        qm2ts, qmake, qtconfig, and uic</seg>
        <seg>libqt-mt.so, libqt.so libqui.so, libdesignercore.a,
        libeditor.a, and libqassistantclient.a</seg>
        <seg>/opt/qt-&qt-version; or /usr/lib/qt, /usr/share/qt,
        /usr/share/doc/qt, /usr/include/qt, and /etc/qt</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="assistant">
        <term><command>assistant</command></term>
        <listitem>
          <para>is a tool for presenting on-line documentation.</para>
          <indexterm zone="qt assistant">
            <primary sortas="b-assistant">assistant</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="designer">
        <term><command>designer</command></term>
        <listitem>
          <para>is a full-fledged GUI builder. It includes
          powerful features such as preview mode, automatic widget
          layout, support for custom widgets, and an advanced
          property editor.</para>
          <indexterm zone="qt designer">
            <primary sortas="b-designer">designer</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="linguist">
        <term><command>linguist</command></term>
        <listitem>
          <para>provides support for translating applications into
          local languages. </para>
          <indexterm zone="qt linguist">
            <primary sortas="b-linguist">linguist</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lrelease">
        <term><command>lrelease</command></term>
        <listitem>
          <para>is a simple command line tool. It reads a Qt project
          file and produces message files used by the application.</para>
          <indexterm zone="qt lrelease">
            <primary sortas="b-lrelease">lrelease</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lupdate">
        <term><command>lupdate</command></term>
        <listitem>
          <para>reads a Qt project file, finds the translatable
          strings in the specified source, header and Qt Designer
          interface files, and produces or updates the translation
          files listed in the project file.</para>
          <indexterm zone="qt lupdate">
            <primary sortas="b-lupdate">lupdate</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="moc">
        <term><command>moc</command></term>
        <listitem>
          <para>generates Qt meta object support code.</para>
          <indexterm zone="qt moc">
            <primary sortas="b-moc">moc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qm2ts">
        <term><command>qm2ts</command></term>
        <listitem>
          <para>is a tool for converting Qt message file formats.</para>
          <indexterm zone="qt qm2ts">
            <primary sortas="b-qm2ts">qm2ts</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qmake">
        <term><command>qmake</command></term>
        <listitem>
          <para>qmake uses information stored in project files to
          determine what should go in the makefiles it generates.</para>
          <indexterm zone="qt qmake">
            <primary sortas="b-qmake">qmake</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qtconfig">
        <term><command>qtconfig</command></term>
        <listitem>
          <para>is used to customize the appearance of Qt applications.</para>
          <indexterm zone="qt qtconfig">
            <primary sortas="b-qtconfig">qtconfig</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="uic">
        <term><command>uic</command></term>
        <listitem>
          <para>is a Qt user interface compiler.</para>
          <indexterm zone="qt uic">
            <primary sortas="b-uic">uic</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>