Project:TeX/TeX Live Migration Guide

From Gentoo Wiki
Jump to:navigation Jump to:search
The information in this article is representative of former times and has been archived. It can be used for reference, but is most likely not appropriate for current usage. Generally, archived articles should not be edited.

This guide aims to show you how to install TeX Live 2008 on Gentoo, more specifically what you need to take care of if you already have a TeX distribution installed (like tetex or TeX Live 2005).

Clean uninstall


In this section we will assume that you have >=app-text/tetex-3 installed. This also applies if you had app-text/texlive-2005 installed. In a perfect world it would be as simple as unmerging it, but unfortunately it is not.

Saving your old configuration

If you have modified your configuration of tetex editing the files in /etc/texmf , you should save them first:

user $cp -rf /etc/texmf ~/tetex-texmf

Removing tetex

Now you can safely unmerge tetex :

root #emerge -C tetex

Some weird errors have been reported when stray configuration files were left behind in /etc/texmf . For safety and for a clean install of TeX Live it is recommended to remove the /etc/texmf/texmf.d/00texmf.cnf file:

root #rm /etc/texmf/texmf.d/00texmf.cnf
You have not lost anything since you just saved your old configuration files.

Due to tetex using texlinks outside of the scope of the package manager, simply unmerging it will have left behind some stray symlinks:

user $ls -l /usr/bin/pdftex
lrwxrwxrwx 1 root root 7 2007-07-09 07:34 /usr/bin/pdftex -> pdfetex

Of course, pdfetex has gone with tetex 's removal, so the pdftex symlink is dead and can be safely removed. The find command (with a GNU extension though) can help us find and remove dead symlinks interactively:

root #find /usr/bin -type l ! -xtype f ! -xtype d -ok rm -f {} \;
< rm ... /usr/bin/pdflatex > ? y
< rm ... /usr/bin/amstex > ? y
< rm ... /usr/bin/pdftex > ? y
< rm ... /usr/bin/eplain > ? y
< rm ... /usr/bin/jadetex > ? y
< rm ... /usr/bin/lambda > ? y
< rm ... /usr/bin/pdfamstex > ? y
< rm ... /usr/bin/elatex > ? y
< rm ... /usr/bin/lamed > ? y
< rm ... /usr/bin/pdfjadetex > ? y
< rm ... /usr/bin/latex > ? y

These were the files left over by my tetex installation.

tetex was also usingfmtutil outside of the scope of the package manager to generate the format files. WithTeX Live 2008 we now build most of the format files while compiling the packages; which format files will be installed in /var/lib/texmf . That means you have to make sure that there are no stray format files:

root #rm -rf /var/lib/texmf/web2c

Installing TeX Live 2008

If you have passed through all the above steps, installing TeX Live 2008 now should be very easy.

root #emerge --ask app-text/texlive

In theory this should just go smoothly and install everything. You might want to tune app-text/texlive USE flags to install extra TeX packages, but you can do it later; app-text/texlive is just a meta-ebuild that pulls the real packages depending on its USE flags.

Nevertheless, it is possible to get dependency problems, errors while installing a package, etc. In that case, you are advised to file a bug on . If you file a bug, please include at least the output of texconfig conf (run as the same user that failed to install, because some environment variables might be important) in addition to the error; this output will most often be requested.



As was the case for tetex-3 , TeX Live on Gentoo has its three main configuration files separated and handled by texmf-update . These files are, namely, texmf.cnf , fmtutil.cnf , updmap.cfg . They lie in /etc/texmf/web2c ; you should not modify them directly because the changes will be lost the next time texmf-update is run.


The texmf.cnf file is the main TeX installation configuration file. It contains variable definitions that will be used by a lot of programs.

The texmf.cnf file is the result of concatenating files in /etc/texmf/texmf.d . In order to modify your TeX environment configuration, you should modify the files there. At the time of writing, Gentoo TeX Live 's ebuild install six files there:

CODE texmf.d installed files

This is the result of the splitting in their respective sections of a (lightly) modified texmf.cnf file from TeX Live 2008 DVD.

The 00header.cnf , 05searchpaths.cnf , 10standardpaths.cnf and 25misc.cnf files should not be modified. If the defaults can be improved, please file a bug.

The TeX Live ebuilds are not aware of path changes of those files, so if you change any path there, make sure you know what you are doing.

The 15options.cnf and 20sizes.cnf files can be modified with caution. The comments in these files should explain what options mean. For example, in 20sizes.cnf you can increase TeX memory, in case you are trying to compile a document that is too big and runs into TeX capacity exceeded, sorry errors.

If you wish to append additions to the texmf.cnf file, you can also create a new file in /etc/texmf/texmf.d , called for example 99myadditions.cnf . Beware not to give it a higher priority than the core configuration files, so it should begin with a two digit number greater than 25 .

Packages that need to append something to the texmf.cnf file get the same treatment, they should install a texmf.d file instead:

CODE Sample code for installing a texmf.d file
insinto /etc/texmf/texmf.d
doins 40mytexmfadditions.cnf


The updmap.cfg file is the configuration file used by updmap (and updmap-sys ), unless otherwise specified. It tells it which font maps to update for the various TeX output drivers.

The updmap.cfg file in /etc/texmf/web2c is the result of concatenating the files in /etc/texmf/updmap.d . The initial 00updmap.cfg file installed by app-text/texlive-core is the result of running updmap --syncwithtrees on the the installed texmf tree (in fact, it just mimics what updmap --syncwithtrees would do, but it is only a technical detail).

Various TeX Live ebuilds will add files to the /etc/texmf/updmap.d directory when they install fonts. While you can edit those files to disable some font maps to be updated, it would probably be wiser to remove the relevant package.

If a third party package wants to add font maps, it should install a file in /etc/texmf/updmap.d and let texmf-update handle it.

Sometimes you can see updmap-sys --enable in some ebuilds or some installation instructions of a third party font package, while this might work at first, these changes will be reverted the next time texmf-update is run.

A better way of handling this would be to create a file to be installed in /etc/texmf/updmap.d and install it for TeX distributions that support the texmf-update way:

CODE How to enable a font map
inherit latex-package
src_install() {
    if latex-package_has_tetex_3; then
        insinto /etc/texmf/updmap.d
        doins myfontmapconfig.cfg
pkg_postinst() {

The files in /etc/texmf/updmap.d should respect updmap syntax:

CODE Snippet of updmap.cfg explaining the syntax
There are two possible entries: Map and MixedMap. Both have one additional
argument: the file name of the map file. MixedMap ("mixed" means that the font
is available as bitmap and as outline) lines will not be used in the default map
of dvips if dvipsPreferOutline is false. Inactive Map files should be marked by
"#! " (without the quotes), not just #.


The fmtutil.cnf file contains information on how to build and handle a format file.

The fmtutil.cnf file is the result of concatenating the files in /etc/texmf/fmtutil.d . Various TeX Live ebuilds install files there. Those files come with the formats they add support for and the symlink to the relevant engine.

CODE Snippet of the fmtutil.cnf(5) man page that explains the syntax
The fmtutil.cnf file contains the configuration information for fmtutil(8).
Each line contains the name of the format (e.g., "tex", "latex", "omega"), the
name of the engine that is used by that format (e.g., "tex", "etex", "omega"),
the pattern file (e.g., language.dat, language.def), and any arguments (name of
an .ini file).

Fields are separated by whitespace and complete lines can be commented out with
"#".  The "pattern file" field cannot be used to define a file that is used
while building the format. It tells fmtutil which file the format creation
procedure reads and it has an effect to the options --showhyphen and --byhyphen.
If the format has no way to customize hyphenation, a "-" can be used to indicate

TeX Live ebuilds that install a fmtutil.d file, install the relevant format files in /var/lib/texmf/web2c and create the symlink from the format to the engine.

Note that when a support file for a language gets added, texmf-update takes care of adding it to the language.dat file and regenerates the format files to support the newly installed language.

Updating your configuration

Now that you know how TeX Live configuration is managed, you should be able to port the changes you had made to your older TeX distribution configuration to the TeX Live configuration layout.

Common errors


In this chapter we will try to give a short summary of the most common errors and explain what has gone wrong.

Format was written by (pdf)etex

Sometimes when installing some packages that requires latex, you'll get this error:

CODE Format was written by pdfetex
---! //var/lib/texmf/web2c/latex.fmt was written by pdfetex

This is due to old files remaining from an old installation of a TeX distribution based on etex . This most likely means you did not follow entirely this guide, especially the #uninstall .

Nevertheless, it is still possible to fix it quickly without having to reinstall anything, just run as root:

root #rm -rf /var/lib/texmf/web2c
root #texmf-update

Format directory does not exist

When installing e.g., texlive-latex , you might encounter the error:

CODE Format directory does not exist
fmtutil: format directory
`/var/tmp/portage/dev-texlive/texlive-latex-2008/work/texmf-var/web2c' does not exist.

This is most likely due to a wrong configuration. Try to run the following command and get the same results:

user $kpsewhich --var-value=TEXMFMAIN

This is very important, since fmtutil looks for mktexdir at this location; if you have a different result then fmtutil will not find mktexdir and thus will fail to create the directory where to temporarily store the compiled formats.

There is no magic command to fix this one, you should check that your configuration is correct, that there are no stray configuration files in /etc/texmf/texmf.d . This will most likely be due to an old 00texmf.cnf being still there and thus setting wrong definitions for the texmf.cnf file. Please refer to the #uninstall and remember that when you modify or remove a file in /etc/texmf/*.d you need to run texmf-update to have the changes taken into account.

Missing .tex files

When installing texlive-latex (or any other format that has babel hyphenation support), you might encounter an error like:

CODE missing bghyphen.tex
Local configuration file hyphen.cfg used
bel/hyphen.cfg (/usr/share/texmf/tex/generic/hyphen/hyphen.tex)
! I can't find file `bghyphen.tex'.
l.10   \input bghyphen.tex
Please type another input file name:
! Emergency stop.
l.10   \input bghyphen.tex
No pages of output.
Transcript written on latex.log.
Error: `pdftex -ini  -jobname=latex -progname=latex
-translate-file=cp227.tcx *latex.ini' failed

In that case, you will have to check which language.dat file is being used:

user $kpsewhich language.dat

This file is automatically generated by texmf-update and is the result of concatenating language.*.dat files present in the directory with (for TeX Live 2008, the language.*.dat files are taken from /etc/texmf/language.dat.d/ ). This directory should be /usr/share/texmf/tex/generic/config/ . So you should check that there are no other language.*.dat files in that directory other than the ones installed by the various dev-texlive/texlive-lang* ebuilds. A file present in that directory means that you want to enable hyphenation support for a specific language; if you don't have the hyphenation support files the formats that use this extra hyphenation support will fail to build.


We would like to thank the following authors and editors for their contributions to this guide:

  • Alexis Ballier