% Copyright 2018 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Installation}

There are different ways of installing \pgfname, depending on your system and
needs, and you may need to install other packages as well, see below. Before
installing, you may wish to review the licenses under which the package is
distributed, see Section~\ref{section-license}.

Typically, the package will already be installed on your system. Naturally, in
this case you do not need to worry about the installation process at all and
you can skip the rest of this section.


\subsection{Package and Driver Versions}

This documentation is part of version \pgfversion\ of the \pgfname\ package. In
order to run \pgfname, you need a reasonably recent \TeX\ installation. When
using \LaTeX, you need the following packages installed (newer versions should
also work):
%
\begin{itemize}
    \item |xcolor| version \xcolorversion.
\end{itemize}
%
With plain \TeX, |xcolor| is not needed, but you obviously do not get its
(full) functionality.

Currently, \pgfname\ requires at least TeX Live 2020 which corresponds to the
following backend drivers (earlier versions also work in some cases):
%
\begin{itemize}
    \item |luatex| version 1.12.0 or higher.
    \item |pdftex| version 1.40.21 or higher.
    \item |dvips| version 2020.1 or higher.

        For inter-picture connections, you need to process pictures using
        |pdftex| version 1.40.21 or higher running in DVI mode.
    \item |dvipdfm| version 20200315 or higher.

        For inter-picture connections, you need to process pictures using
        |pdftex| version 1.40.21 or higher running in DVI mode.
    \item |dvipdfmx| version 20200315 or higher.
    \item |dvisvgm| version 2.9.1 or higher.
    \item |tex4ht| version 2018-07-03 or higher.
    \item |xetex| version 0.999992 or higher.
\end{itemize}

Currently, \pgfname\ supports the following formats:
%
\begin{itemize}
    \item |latex| with complete functionality.
    \item |plain| with complete functionality, except for graphics inclusion,
        which works only for pdf\TeX.
    \item |context| with complete functionality, except for graphics
        inclusion, which works only for pdf\TeX.
\end{itemize}

For more details, see Section~\ref{section-formats}.


\subsection{Installing Prebundled Packages}

I do not create or manage prebundled packages of \pgfname, but, fortunately,
nice other people do. I cannot give detailed instructions on how to install
these packages, since I do not manage them, but I \emph{can} tell you were to
find them. If you have a problem with installing, you might wish to have a look
at the Debian page or the MiK\TeX\ page first.


\subsubsection{Debian}

The command ``|apt-get install texlive-pictures|'' should do the trick.
Sit back and relax.


\subsubsection{MiKTeX}

For MiK\TeX, use the update wizard to install the (latest versions of the)
packages called |pgf| and |xcolor|.


\subsection{Installation in a texmf Tree}

For a permanent installation, you place the files of the \textsc{pgf} package
in an appropriate |texmf| tree.

When you ask \TeX\ to use a certain class or package, it usually looks for the
necessary files in so-called |texmf| trees. These trees are simply huge
directories that contain these files. By default, \TeX\ looks for files in
three different |texmf| trees:
%
\begin{itemize}
    \item The root |texmf| tree, which is usually located at
        |/usr/share/texmf/| or |c:\texmf\| or somewhere similar.
    \item The local  |texmf| tree, which is usually located at
        |/usr/local/share/texmf/| or |c:\localtexmf\| or somewhere similar.
    \item Your personal  |texmf| tree, which is usually located in your home
        directory at |~/texmf/| or |~/Library/texmf/|.
\end{itemize}

You should install the packages either in the local tree or in your personal
tree, depending on whether you have write access to the local tree.
Installation in the root tree can cause problems, since an update of the whole
\TeX\ installation will replace this whole tree.


\subsubsection{Installation that Keeps Everything Together}

Once you have located the right texmf tree, you must decide whether you want to
install \pgfname\ in such a way that ``all its files are kept in one place'' or
whether you want to be ``\textsc{tds}-compliant'', where \textsc{tds} means
``\TeX\ directory structure''.

If you want to keep ``everything in one place'', inside the |texmf| tree that
you have chosen create a sub-sub-directory called |texmf/tex/generic/pgf| or
|texmf/tex/generic/pgf-|\texttt{\pgfversion}, if you prefer. Then place all
files of the |pgf| package in this directory. Finally, rebuild \TeX's filename
database. This is done by running the command |texhash| or |mktexlsr| (they are
the same). In MiK\TeX, there is a menu option to do this.


\subsubsection{Installation that is TDS-Compliant}

While the above installation process is the most ``natural'' one and although I
would like to recommend it since it makes updating and managing the \pgfname\
package easy, it is not \textsc{tds}-compliant. If you want to be
\textsc{tds}-compliant, proceed as follows: (If you do not know what
\textsc{tds}-compliant means, you probably do not want to be
\textsc{tds}-compliant.)

The |.tar| file of the |pgf| package contains the following files and
directories at its root: |README|, |doc|,  |generic|, |plain|, and |latex|. You
should ``merge'' each of the four directories with the following directories
|texmf/doc|, |texmf/tex/generic|, |texmf/tex/plain|, and |texmf/tex/latex|. For
example, in the |.tar| file the |doc| directory contains just the directory
|pgf|, and this directory has to be moved to |texmf/doc/pgf|. The root |README|
file can be ignored since it is reproduced in |doc/pgf/README|.

You may also consider keeping everything in one place and using symbolic links
to point from the \textsc{tds}-compliant directories to the central
installation.

\vskip1em For a more detailed explanation of the standard installation process
of packages, you might wish to consult
\href{http://www.ctan.org/installationadvice/}{|http://www.ctan.org/installationadvice/|}.
However, note that the \pgfname\ package does not come with a |.ins| file
(simply skip that part).


\subsection{Updating the Installation}

To update your installation from a previous version, all you need to do is to
replace everything in the directory |texmf/tex/generic/pgf| with the files of
the new version (or in all the directories where |pgf| was installed, if you
chose a \textsc{tds}-compliant installation). The easiest way to do this is to
first delete the old version and then proceed as described above. Sometimes,
there are changes in the syntax of certain commands from version to version. If
things no longer work that used to work, you may wish to have a look at the
release notes and at the change log.
