path: root/doc/faq/install.docbook

<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
 "dtd/kdex.dtd">
-->

<chapter id="install">
<title>Installation instructions</title>

<para>These are the generic installation instructions for the Trinity
Desktop Environment. Please complement your reading with the
<filename>README</filename> and <filename>INSTALL</filename> text files that
come along with the package. Please read them carefully and try to
help yourself if anything goes wrong. If you need further
assistance, consider joining the &tde; mailing lists
(see our web site instructions for joining the &tde;
<ulink url="http://www.kde.org/mailinglists/">mailing
lists</ulink>) or newsgroups.</para>


<qandaset>


<qandaentry>
<question>
<para>To the would-be converts</para>
</question>
<answer>

<para>You have heard rumors about &tde;. Or you have seen screenshots.
You want test &tde;. Yet you know next to nothing
about this whole <quote>alternate operating system</quote> business. Don't worry!
You only need to do some (well, maybe not some) reading, that's all!</para>

<para>&tde; does not run on any version of &Microsoft; &Windows;. To run
&tde;, you need to have a &UNIX; operating system. Please refer to <xref
linkend="platform"/> for more details.</para>

<para>Decide on a platform and set it up for your system. This
<acronym>FAQ</acronym> can not help you with this, since &tde; is intended
to run on many &UNIX; platforms.</para>

<para>To obtain &tde;, please refer to <xref linkend="where-to-get-tde"/>. If
you encounter problems while installing &tde;, please do not
hesitate to make use of the &tde; <link
linkend="mailing-lists">mailing lists</link> and <link
linkend="newsgroups">newsgroups</link>. No question is too silly to ask, but
remember to first look for answers in this <acronym>FAQ</acronym>.</para>
<para>Good luck and have fun!</para>

</answer>
</qandaentry>

<qandaentry>
<question>
<para>What kind of hardware do I need to run &tde; ?</para>
</question>
<answer>
<para>To run &tde; consider at least a Pentium III processor, 512MB of memory, and 500MB of free disk space for a basic installation. A full installation will require about 3GB of hard drive storage space. While &tde; will run on slower hardware, performance likely will require some patience. Generally, if your computer runs other desktop environments then the hardware probably is capable of running &tde;.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Available package formats</para>
</question>
<answer>


<para>You can find binary and source packages for
different distributions and operating systems on the
<ulink url="http://www.trinitydesktop.org/installation.php">Trinity web site</ulink>.
The binary packages are made by dedicated members of the &tde; community.
The only <quote>official</quote> release is the source tarball
packages. Please refer to the <filename>README</filename>s and
<filename>INSTALL</filename>s in the several binaries folders.
Find the latest stable release
<ulink url="http://www.trinitydesktop.org/releases.php">here</ulink>.</para>

</answer>
</qandaentry>

<qandaentry>
<question id="prerequisites">
<para>Prerequisites</para>
</question>
<answer>

<!-- rewrite to make it more general, pointing to the according webpages? -->

<para>You need the &Qt; library as provided by the &tde; developers. Previous
versions of &Qt; will not work with the latest &tde;.
Please ensure you download the correct &Qt;. You will
also need the header files, if you want to compile &tde;
yourself. They are all available, at no cost, from the <ulink
url="http://www.trinitydesktop.org/">&tde; repository</ulink>.
There are optional libraries that might improve &tde; if
installed on your system. An example is OpenSSL which will enable
&konqueror; to browse web pages securely. These additional packages
should be provided by your distributor.</para>

</answer>
</qandaentry>

<qandaentry>
<question>
<para>Description of the base packages</para>
</question>
<answer>
<para>The base distribution currently consists of several
packages. Some are required, while others are optional. Each package
is available in each of the aforementioned package formats.</para>

<variablelist>
<varlistentry>
<term>tqt3</term>
<listitem>
<para>Required</para>
<para>This package contains the foundational widget support needed by all
&tde; applications.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tqtinterface</term>
<listitem>
<para>Required</para>
<para>Necessary for supporting subsequent versions of Qt.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>arts</term>
<listitem>
<para>Required</para>
<para>The core sound system for &tde;</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdelibs</term>
<listitem>
<para>Required</para>
<para>This package contains shared libraries that are needed by all
&tde; applications.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdebase</term>
<listitem>
<para>Required</para>
<para>This package contains the base applications that form the core
of the Trinity Desktop Environment like the window manager, the terminal
emulator, the control center, the file manager, and the panel.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>&arts;</term>
<listitem>
<para>Required</para>
<para>The &arts; sound server. A powerful, network transparent sound
server.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdeaddons</term>
<listitem>
<para>Optional but recommended</para>
<para>Various plugins for &kate;, &kicker;, &knewsticker;, &konqueror; and &noatun; </para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdeartwork</term>
<listitem>
<para>Optional</para>
<para>Additional wallpapers, themes, styles, sounds ...</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdebindings</term>
<listitem>
<para>Optional</para>
<para>Various bindings for other languages, including &Java;, Perl, Python, ...</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdegames</term>
<listitem>
<para>Optional</para>
<para>Various games like &kmahjongg;, &ksnake;, &kasteroids;, and
&kpatience;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdegraphics</term>
<listitem>
<para>Optional but recommended</para>
<para>Various graphics-related programs like &PostScript; previewer,
&DVI; previewer, and a drawing program.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdeutils</term>
<listitem>
<para>Optional but recommended</para>
<para>Various desktop tools like a calculator, an editor and other
nifty stuff.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdemultimedia</term>
<listitem>
<para>Optional but recommended</para>
<para>Multimedia applications like a &CD; player and a mixer.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdenetwork</term>
<listitem>
<para>Optional</para>
<para>Network applications. Currently contains the instant messaging client &kopete;, the
download manager &kget;, and several other network-related programs.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdepim</term>
<listitem>
<para>Optional but recommended</para>
<para>Personal information management tools. Contains the email client &kmail;, the newsreader &knode; and other related programs.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdeadmin</term>
<listitem>
<para>Optional but recommended</para>
<para>System administration programs.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdeedu</term>
<listitem>
<para>Optional</para>
<para>
Educational and entertaining applications for &tde;'s younger users.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdeaccessibility</term>
<listitem>
<para>Optional but recommended</para>
<para>
&tde; accessibility programs such as a screen magnifier and speech synthesizer front end.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdetoys</term>
<listitem>
<para>Optional</para>
<para>Toys!</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdevelop</term>
<listitem>
<para>Optional</para>
<para>A complete Integrated Development Environment for &tde; and &Qt;</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdewebdev</term>
<listitem>
<para>Optional</para>
<para>Web development applications. Contains such applications as &quanta;, an integrated web development environment and other applications useful in web development</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tdesdk</term>
<listitem>
<para>Optional</para>
<para>&tde; Software Development Kit. Contains a collection of applications and tools used by &tde; Developers.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Information about compiling all packages is available at the
<ulink url="http://www.trinitydesktop.org/wiki/bin/view/Developers/HowToBuild">
Trinity wiki</ulink>.</para>

<para>Most package management tools will let you put all these
packages in one folder and install them all at once, figuring out
the dependencies as they go.</para>

</answer>
</qandaentry>

<qandaentry>
<question>
<para>Installation instructions for the different package formats</para>
</question>
<answer>
<para>As &tde; is intended for many &UNIX; systems, please consult the installtion
procedures and package management document for the system being used.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Post-installation procedures</para>
</question>
<answer>
<para>There should be nothing to do after installing the packages except use them!
Nonetheless, should problems arise, there are some common problems to consider:</para>

<variablelist>

<varlistentry>
<term>System search path</term>
<listitem>
<para>Be sure all &tde; binary files are installed
in a location listed in your system's <envar>PATH</envar>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Library files</term>
<listitem>
<para>Be sure the &tde; library files are installed in the expected locations for your
system.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><envar>TDEDIR</envar> environment variable</term>
<listitem>
<para>Be sure the <envar>TDEDIR</envar> environment variable is correctly set.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename>starttde</filename> script installation</term>
<listitem>
<para>Verify the <filename>starttde</filename> script is installed to <filename
class="directory">$<envar>TDEDIR</envar>/bin</filename> and therefore in your
system's search path.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename>starttde</filename> script is run correctly</term>
<listitem>
<para>Be sure the <filename>starttde</filename> script is being run from within the appropriate
xinitrc or xsession script.</para>
</listitem>
</varlistentry>

</variablelist>

<para>This should present you with a new &tde; desktop. You
can now start to explore the wonderful world of &tde;. In case you
want to read some documentation first, there is a recommended
<ulink url="help:/khelpcenter/quickstart">A Quick Start Guide to the Desktop</ulink>
available. Furthermore, every application has an online
help that is available via the <guimenu>Help</guimenu> menu.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Should I remove old version xyz before installing a new
one?</para>
</question>
<answer>
<para>In principle, this is not necessary. The various distro package managers
should handle all dependencies.</para>
<para>If you compile the source code yourself, you should take more care.</para>
</answer>
</qandaentry>

<qandaentry>
<question id="starttde">
<para>How do I start &tde;?</para>
</question>
<answer>
<para>There are only two methods of starting &tde;: using a login
manager such as &tdm; or from the command line, using <command>startx</command>.
The respective startup scripts should contain a reference to the
<filename>starttde</filename> script.</para>
</answer>
</qandaentry>
<!-- Still needed?
<qandaentry>
<question>
<para>Whenever I start &tde;, it complains about "shadow passwords".
Why?</para>
</question>
<answer>
<para>When your system uses shadow passwords, the screensaver can only
run properly if the suid bit is set. This bit gives the screensavers
root privileges, which are needed to access the shadow passwords.
<caution><para>The screensavers might be configured to secure the
machine until the password is entered.</para></caution></para>
<procedure>
<title>Setting the suid bit on the screensavers</title>
<step performance="required"><para>become root</para></step>
<step performance="required"><para><command>chown root
$<envar>TDEDIR</envar>/bin/*.kss</command></para></step>
<step performance="required"><para><command>chmod u+s
$<envar>TDEDIR</envar>/bin/*.kss</command></para></step>
</procedure>
<para>Alternatively, if you compile &tde; from source, you can use
<command>./configure <option>with-shadow</option></command> to
configure tdebase. Then the suid bit is set automatically during
<command>make install</command>.</para>
</answer>
</qandaentry>
-->

<qandaentry>
<question>
<para><command>starttde</command> fails with <errorname>can not connect to X
server</errorname>. What is wrong?</para>
</question>
<answer>
<para>You probably tried to start &tde; directly with <command>starttde</command> rather
than letting the login manager or startx process run that script. From the command
line the X server is started with <command>startx</command>.
<command>starttde</command> is the
script that should be run from your <filename>.xinitrc</filename>, <filename>.xsession</filename>, or
<filename>.Xclients</filename> to activate the window manager and the necessary server
daemons for &tde;. See also <xref linkend="starttde"/>.</para>
</answer>
</qandaentry>

<!--<qandaentry>
<question>
<para>&tde; on &AIX;?</para>
</question>
<answer>
<para>
<acronym>IBM</acronym> now officially support &tde; on &AIX;. You can find
details at <ulink
url="http://www.ibm.com/servers/aix/products/aixos/linux/index.html">http://www.ibm.com/servers/aix/products/aixos/linux/index.html</ulink>.
There is also some older information at <ulink url="http://space.twc.de/~stefan/kde/aix.html">http://space.twc.de/~stefan/kde/aix.html</ulink>.</para>
</answer>
</qandaentry>-->

<!--<qandaentry>
<question>
<para>&tde; on a laptop?</para>
</question>
<answer>
<para>If you can get &X-Window; to run on your laptop, you should not have any problem
getting &tde; to run on it. In addition, you might find the following
links helpful:</para>
<itemizedlist>
<listitem>
<para><ulink url="http://www.linux-laptop.net/">http://www.linux-laptop.net/</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.sanpei.org/Laptop-X/note-list.html">http://www.sanpei.org/Laptop-X/note-list.html</ulink></para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>-->

<!--<qandaentry>
<question>
<para>I do not like the default &tde; folder after installation. How
do I move it without breaking anything?</para>
</question>
<answer>
<para>Assuming the default is <filename
class="directory">/opt/kde</filename> and you want to move it to
<filename class="directory">/usr/local/kde</filename>, here's what
you have to do:</para>
<procedure>
<step performance="required"><para>change to superuser if you aren't already</para></step>
<step performance="required"><para><command>mv /opt/kde /usr/local/kde</command></para></step>
<step performance="required"><para><command>ln -s /usr/local/kde
/opt/kde</command></para></step>
</procedure>
<para>This will put all your &tde; files in <filename
class="directory">/usr/local/kde</filename> but everything is
still accessible from <filename
class="directory">/opt/kde</filename>.</para>
</answer>
</qandaentry>-->

<!--<qandaentry>
<question>
<para>What files can I delete from my &tde; install folder?  Can all the
<filename>*.h</filename>, <filename>*.c</filename> and <filename>*.o</filename>
files be safely removed?</para>
</question>
<answer>
<para>There should not be any need to keep the <filename>.c</filename> and
<filename>.o</filename> files, but you might want to keep the
<filename>.h</filename> files, as they are used by includes if you ever want to
compile your own &tde; programs. But if you wish to add patches to the source
programs as they become available (rather than downloading everything again),
then they should stay.</para>
</answer>
</qandaentry>-->

<qandaentry>
<question>
<para>Will I lose my current settings when I update &tde;?</para>
</question>
<answer>
<para>You shouldn't. &tde; should transport your settings
intact. All settings should be safe.</para>
</answer>
</qandaentry>

<qandaentry id="greyscreen">
<question>
<para>I updated &tde; and all seemed to go fine, but when I start &tde;,
I get a blank gray screen, and nothing happens. There are errors in
the console about DCOPserver. What's going on?</para>
</question>

<answer>
<para>
&tde; uses several temporary files during its operation.
Usually these directories and files are found in the following locations:</para>
<itemizedlist>
<listitem><para><filename>$HOME/.DCOPserver-*</filename> (there are usually two of these; one is a symlink to the other)</para></listitem>
<listitem><para><filename>$HOME/.trinity/socket-<replaceable>hostname</replaceable></filename></para></listitem>
<listitem><para><filename>$HOME/.trinity/tmp-<replaceable>hostname</replaceable></filename>, which normally is a symlink to the next file:</para></listitem>
<listitem><para><filename>$TMP/tde-<replaceable>USER</replaceable></filename></para></listitem>
<listitem><para><filename>$HOME/.trinity/socket-<replaceable>hostname</replaceable></filename>, which normally is a symlink to:</para></listitem>
<listitem><para><filename>$TMP/tdesocket-<replaceable>USER</replaceable></filename></para></listitem>
</itemizedlist>

<para>If the symlinks get broken, such as when
<command>cron</command> or a shutdown script is emptying the
<filename class="directory">/tmp</filename> folder, then strange
things will happen. These files, and the symlinks, will all be
created automatically at the start of &tde; so you can safely remove
them <emphasis>while &tde; is not running</emphasis>.</para>

<para>If you are only getting a gray screen when you start &tde;, or if you get an error message telling you to <errorname>Check your installation</errorname>, then shut down X and delete all the files listed above, then try to restart X.</para>

<para>Normally (&ie; when not updating between &tde; versions) it's
quite safe to leave these files intact, and you may shave a few
seconds off your &tde; startup time by doing so.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Is &tde; backwards or binary compatible with KDE 3?</para>
</question>
<answer>
<para>While many programs originally designed for KDE 3 will compile on Trinity, binary
compatibility with KDE 3 is not a goal of &tde; developers.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Is &tde; backwards or binary compatible with previous releases of &tde;?</para>
</question>
<answer>
<para>Possibly, but binary compatibility is not a project goal with major point
releases. A package that built on a previous version of &tde; but no longer builds
on the current release should be brought to the attention of the developers.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Is my KDE 3 profile directory compatible with Trinity?</para>
</question>
<answer>
<para>Not quite but don't worry. Some "scrubbing" cleanup is required to migrate
a KDE 3 profile. For new users or those with little customization we recommend
creating a fresh profile. For those long-time users who cringe at the thought
of recreating their desktop, we provide a migratekde3 shell script. That script
copies a $HOME/.kde3 profile directory to $HOME/.trinity and performs the required
"scrubbing" cleanup. Although the script has been tested we provide the tool "as is"
with no warranties or guarantees. (The script works really well, actually. :-))</para>
</answer>
</qandaentry>

<!--<qandaentry>
<question>
<para>Compiling tdebase gives me a <errorname>bin/sh: msgfmt: command
not found</errorname> error!</para>
</question>
<answer>
<para>You need the &GNU; <application>msgfmt</application> which is
part of the &GNU; i18n package <application>gettext</application>.
You should be able to download it from any
&GNU; mirror.</para>
</answer>
</qandaentry>-->

<!--<qandaentry>
<question>
<para>How do I uninstall &tde; applications compiled from
source?</para>
</question>
<answer>
<para>You can uninstall your programs by typing <command>make
uninstall</command> in the folder where you did <command>make
install</command>. If you have already deleted that folder,
then there is only one way, and it is not good: go to <filename
class="directory">$<envar>TDEDIR</envar>/bin</filename> and start deleting files
one by one.</para>
<para>If you expect to find yourself in this situation, you might want to
consider a program such as &GNU; <application>stow</application>, found at
<ulink url="http://www.gnu.org/software/stow/stow.html">http://www.gnu.org/software/stow/stow.html</ulink>.</para>
</answer>
</qandaentry>-->

<!--<qandaentry>
<question id="gif">
<para>What is up with &GIF; support?</para>
</question>
<answer>
<para>This has to do with issues with Unisys' &LZW; patent. &GIF;
support is turned off from &Qt; 1.44 onwards by default. When you want to use
&GIF;s and have the relevant license, recompile &Qt; with &GIF; support.
<command>./configure <option>-gif</option></command>.</para>
</answer>
</qandaentry>-->

</qandaset>
</chapter>