% 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\ supports the following backend drivers: % \begin{itemize} \item |luatex| version 0.76 or higher. Most earlier versions also work. \item |pdftex| version 0.14 or higher. Earlier versions do not work. \item |dvips| version 5.94a or higher. Earlier versions may also work. For inter-picture connections, you need to process pictures using |pdftex| version 1.40 or higher running in DVI mode. \item |dvipdfm| version 0.13.2c or higher. Earlier versions may also work. For inter-picture connections, you need to process pictures using |pdftex| version 1.40 or higher running in DVI mode. \item |dvipdfmx| version 0.13.2c or higher. Earlier versions may also work. \item |dvisvgm| version 1.2.2 or higher. Earlier versions may also work. \item |tex4ht| version 2003-05-05 or higher. Earlier versions may also work. \item |vtex| version 8.46a or higher. Earlier versions may also work. \item |textures| version 2.1 or higher. Earlier versions may also work. \item |xetex| version 0.996 or higher. Earlier versions may also work. \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 ``|aptitude install pgf|'' 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.