Structure des répertoires et chemins de TeX

Une installation de TeX est une pile de dizaines de milliers de fichiers : macros, classes, polices, configuration. Pourquoi l'écriture de la seule ligne \usepackage{amsmath} trouve-t-elle de manière fiable amsmath.sty quelque part sur le disque ? Derrière cela se cachent deux conventions : un standard pour l'emplacement des fichiers (le TDS) et un mécanisme pour les trouver (kpathsea). Cette page dessine cette carte.

Le TDS : un lieu standard pour tout

Tout commence à partir d'une arborescence de répertoires appelée arbre texmf — « texmf » étant l'abréviation de *TeX et Metafont*. En dessous, les fichiers sont classés par genre : les macros et les classes vont sous tex/, tout ce qui concerne les polices sous fonts/, les données bibliographiques sous bibtex/, la documentation (manuels) sous doc/, les scripts sous scripts/. La normalisation de cette disposition sur chaque système est la tâche du TDS (TeX Directory Structure), défini par le TeX Users Group (TUG) dans les années 1990.

Pourquoi avoir une norme ? TeX fonctionne sur macOS, Unix, Windows, et plus encore, et CTAN (le Comprehensive TeX Archive Network) collecte une énorme pile de paquets. Si chaque site organisait les fichiers différemment, les personnes qui expédient les colis et les outils qui les trouvent trébucheraient à chaque fois. Une fois que les « macros en direct sous tex/ » sont corrigées, l'emplacement de n'importe quel fichier peut être déduit à partir des seules règles, sur n'importe quel OS et n'importe quelle distribution. La portabilité est exactement le problème que le TDS résout.

Les succursales ont leurs propres règles. tex/ est divisé par format, puis par package, donnant tex/<format>/<package>/ (où <format> est latex, plain, generic, …). Le article.cls standard, par exemple, se trouve sur le chemin ci-dessous – et l'outil kpsewhich présenté plus tard signalera exactement le même emplacement sur votre propre machine.

$ kpsewhich article.cls
/usr/local/texlive/2026/texmf-dist/tex/latex/base/article.cls

Les polices vont d'un niveau plus fin : fonts/<type>/<supplier>/<typeface>/. Le <type> est le type de fichier : tfm pour les métriques de police TeX, vf pour les polices virtuelles, plus type1, opentype, truetype, etc. Le <supplier> est celui qui l'a fourni (public, adobe, ams, …) et <typeface> est le nom de la police (cm = Computer Modern). Le tableau ci-dessous répertorie les branches que vous rencontrez le plus souvent et ce que chacune contient.

Plusieurs arbres, et lequel gagne

Un arbre texmf n'est pas une chose. TeX Live regroupe plusieurs arbres avec des rôles distincts, chacun nommé par une variable TEXMF…. Pourquoi les séparer ? Pour séparer trois éléments : la distribution (en lecture seule, remplacée en gros à chaque mise à jour), ce que vous avez ajouté (qui ne doit pas disparaître) et les données de travail générées automatiquement. Mélangez-les et la mise à jour de la distribution pourrait effacer vos propres styles en un instant.

Si un fichier du même nom existe dans plusieurs arbres, lequel gagne ? Ceci est décidé par la variable TEXMF, qui répertorie simplement la priorité de recherche dans l'ordre. L'interroger renvoie à peu près la séquence suivante (victoires les plus à gauche) :

$ kpsewhich -var-value=TEXMF
{$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST}

Lisez-le comme ceci : d'abord votre propre configuration (TEXMFCONFIG) et vos données de travail (TEXMFVAR), puis votre arborescence personnelle TEXMFHOME, puis le TEXMFLOCAL à l'échelle du site, et enfin la configuration du système, les données de travail et la distribution TEXMFDIST. En raison de cet ordre, déposer votre propre mystyle.sty dans TEXMFHOME le fait masquer la copie de la distribution — pas de fracas, juste un classement naturel de personnel → site → distribution. (Le premier !! est expliqué dans la section suivante.)

kpathsea : comment les fichiers sont trouvés

Même avec la mise en page corrigée, qui trouve réellement un fichier ? Il s'agit de kpathsea (kpse, *kpath search*) — la bibliothèque de recherche de chemin partagée par TeX et ses outils associés. tex, pdflatex, dvipdfmx et les autres ne recherchent pas par eux-mêmes ; ils demandent tous à kpathsea : « où est amsmath.sty ?

kpathsea exprime un chemin de recherche sous la forme d'une chaîne avec des règles. Trois symboles valent la peine d'être connus : $VAR développe une variable ; un // final signifie « rechercher tout ce qui se trouve en dessous, de manière récursive » ; et le début !! signifie « ne pas analyser le disque directement — consulter uniquement la base de données de noms de fichiers décrite ci-dessous. » Le chemin pour trouver les sources de LaTeX, TEXINPUTS, ressemble en fait à ceci :

$ kpsewhich -var-value=TEXINPUTS
.:$TEXMF/tex/{latex,generic,}//

Lisez-le comme suit : regardez d'abord dans . (le répertoire actuel) ; à défaut, parcourez la branche tex/ de chaque arbre texmf dans l'ordre latex → generic → tout le reste. Cela donne le comportement intuitif que vous attendez : un fichier à côté de votre manuscrit l'emporte, sinon revenez à la distribution.

Mais analyser réellement des dizaines de milliers de répertoires à chaque fois serait beaucoup trop lent. Ainsi, kpathsea utilise une base de données de noms de fichiers appelée ls-R placée à la racine de chaque arborescence — une liste de texte indiquant quel fichier se trouve dans quel répertoire. Consulter cet index au lieu de parcourir le disque rend les recherches instantanées. Le !! vu précédemment signifie « faire confiance uniquement à l'index (ne jamais toucher au disque réel) », et il est attaché à des arborescences comme la distribution qui changent rarement.

Le revers de la médaille : après avoir ajouté un fichier à une arborescence, TeX peut ne pas le trouver tant que ls-R n'est pas reconstruit — en particulier dans les arborescences système !!. La commande qui régénère l'index est mktexlsr, également connue sous le nom de texhash. Les arbres personnels comme TEXMFHOME sont traités avec plus d'indulgence et ne nécessitent souvent aucune reconstruction, mais après avoir mis quelque chose dans TEXMFLOCAL, la solution la plus sûre consiste à exécuter la ligne ci-dessous.

# Rebuild the ls-R filename databases after adding files to a tree
$ mktexlsr        # texhash is an exact alias

En cas de problème, la première étape consiste à interroger les fichiers et les variables directement avec kpsewhich : « quel fichier est réellement en cours de lecture ? et "à quoi cette variable s'étend-elle?" reçoivent une réponse instantanée, vous permettant d'isoler une mauvaise configuration. L'ensemble complet des options de kpsewhich et les commandes de gestion telles que tlmgr sont traitées en détail sur une page séparée.

PATH : le chemin vers les commandes

kpathsea trouve les fichiers que TeX lit, mais avant cela, le shell doit localiser l'exécutable lui-même, pdflatex. C'est le travail du OS : il recherche dans l'ordre les répertoires répertoriés dans la variable d'environnement PATH. TeX Live conserve ses exécutables dans un seul répertoire bin par OS et par architecture, et le mettre sur PATH est la touche finale d'une installation.

Le nom du répertoire intègre l'année et la plateforme : sur Linux /usr/local/texlive/2026/bin/x86_64-linux, sur macOS /usr/local/texlive/2026/bin/universal-darwin, sur Windows ...\bin\windows. Sur macOS, MacTeX fournit un lien symbolique stable et indépendant de l'année sur /Library/TeX/texbin, donc une mise à niveau annuelle ne nécessite aucune modification de votre PATH. Vous pouvez voir ce qu'il pointe actuellement comme ceci :

$ which pdflatex
/Library/TeX/texbin/pdflatex
$ readlink /Library/TeX/texbin
Distributions/Programs/texbin

Si jamais vous voyez « pdflatex: command not found », neuf fois sur dix, le répertoire bin est tout simplement absent de PATH. La procédure OS-by-OS pour le configurer et les vérifications post-installation sont laissées à la page d'installation.

texmf.cnf : d'où viennent les paramètres

D'où viennent réellement toutes les variables jusqu'à présent - TEXMF, TEXINPUTS, l'emplacement de chaque arbre ? La réponse est un fichier de configuration appelé texmf.cnf. Avant de faire quoi que ce soit, kpathsea le lit pour récupérer les paramètres de fonctionnement : les chemins de recherche, l'emplacement de chaque arbre, les limites de mémoire, etc. La copie principale réside sous le web2c/ de la distribution :

$ kpsewhich texmf.cnf
/usr/local/texlive/2026/texmf.cnf

La partie intéressante : il peut y avoir plus d'un texmf.cnf. kpathsea lit texmf.cnf à plusieurs endroits le long d'un chemin de recherche dédié (la variable TEXMFCNF), dans l'ordre, et prend la première définition qu'il trouve pour une variable donnée (les fichiers ultérieurs ne remplacent pas les précédentes). Vous laissez donc le gros fichier par défaut de la distribution intact et déposez un petit fichier de remplacement dans un emplacement de priorité plus élevée – un schéma de superposition qui ajoute uniquement vos modifications, en toute sécurité. L'ajout de -all révèle les fichiers réellement empilés :

$ kpsewhich -all texmf.cnf
/usr/local/texlive/2026/texmf.cnf
/usr/local/texlive/2026/texmf-dist/web2c/texmf.cnf

Ici, le texmf.cnf supérieur (le remplacement fin de TeX Live) est lu avant le texmf-dist/web2c/texmf.cnf inférieur (des centaines de lignes de valeurs par défaut). Lorsque vous souhaitez modifier une valeur de manière permanente, la convention n'est pas de modifier le fichier de la distribution mais d'écrire uniquement les lignes dont vous avez besoin dans un emplacement de priorité supérieure tel que TEXMFLOCAL/web2c/texmf.cnf. Faites cela et vos paramètres survivent à une mise à niveau de distribution.

En résumé, voici comment TeX trouve un fichier : texmf.cnf corrige d'abord où se trouvent les arbres et à quoi ressemblent les chemins de recherche ; en suivant cet ordre, kpathsea localise la cible (généralement via l'index ls-R) ; et PATH fournit le point d'entrée à l'exécutable lui-même. Ces trois couches s'entremêlent de sorte qu'une seule ligne de \usepackage{...} se résout silencieusement.

Où placer vos propres fichiers

La règle pratique la plus importante est la suivante : ne modifiez pas l'arborescence de distribution. Si vous placez un thesisstyle.sty réservé à la thèse ou un labreport.cls à l'échelle du laboratoire dans /usr/local/texlive/2026/texmf-dist, une mise à jour ou une réinstallation peut l'effacer. Placez les fichiers personnels dans TEXMFHOME, les fichiers à l'échelle du laboratoire dans TEXMFLOCAL et conservez la disposition TDS.

En revanche, les fichiers qui appartiennent à un seul ensemble de soumission — une conférence myconf.cls ou une revue journal.sty — peuvent résider à côté du manuscrit. TEXINPUTS vérifie d'abord le répertoire actuel, donc TeX préférera cette copie. C'est aussi pourquoi placer des noms génériques tels que article.cls ou un ancien amsmath.sty à côté du manuscrit est dangereux : cela occulte la distribution et crée des pannes qui n'apparaissent que sur d'autres machines.

# 個人用スタイルを TEXMFHOME に置く例
mkdir -p ~/texmf/tex/latex/thesisstyle
cp thesisstyle.sty ~/texmf/tex/latex/thesisstyle/

# TeX がどれを拾うか確認する
kpsewhich thesisstyle.sty

Une fois que kpsewhich indique le chemin que vous attendez, le manuscrit peut simplement indiquer \usepackage{thesisstyle}. S'il ne rapporte rien, vérifiez dans l'ordre : si le fichier se trouve sous tex/latex/<package>/, si la casse du nom de fichier correspond et si mktexlsr a été exécuté pour une arborescence système. Cela décrit l'échec comme « où l'ai-je mis sur la carte de recherche ? » plutôt que « TeX est cassé ».