source: x/lib/qt.xml@ 394cd759

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

  <!ENTITY qt-download-http "http://sunsite.rediris.es/mirror/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        "027f4e82fbe592b39d2f160bfb3a73af">
  <!ENTITY qt-size          "13.8 MB">
  <!ENTITY qt-buildsize     "250 MB">
  <!ENTITY qt-time          "15.5 SBU (full), 10.9 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">Qt Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para>X (<xref linkend="xfree86"/> or <xref linkend="xorg"/>)</para>

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

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

  </sect2>

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

    <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>

    <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 make line 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.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>

<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-libmng \
    -no-exceptions -thread -plugin-imgfmt-png \
    -system-libjpeg -system-libpng &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>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>

<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; -qt-gif -system-libpng \
    -system-libmng -system-zlib -system-libjpeg -no-exceptions \
    -thread -plugin-imgfmt-png &amp;&amp;
make &amp;&amp;
exit</userinput></screen>

      <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 /opt/qt/doc &amp;&amp;
cp -v -r examples /opt/qt/doc</userinput></screen>

      <note>
        <para>If you pass the
        <option>-plugin-sql-<replaceable>[driver]</replaceable></option>
        switch to the <command>configure</command> command, you must also pass
        <option>-I<replaceable>[/path/to/sql/headers]</replaceable></option>
        so <command>make</command> can find the appropriate header files.</para>
      </note>

    </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</parameter>: This switch
    forces 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</parameter>: This switch enables
    <application>libpng</application> to be linked to at runtime.</para>

    <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 /usr/share (or /opt/qt/doc)</command>:
    This command installs the man pages which are missed by
    <command>make install</command>.</para>

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

    <para><command>exit</command>: This command returns to the parent shell
    and eliminates 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.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.conf &lt;&lt; "EOF"
<literal># Begin qt addition to man.conf

MANPATH /opt/qt/doc/man

# End qt addition to man.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.conf">/etc/man.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>