387 lines
13 KiB
Markdown
387 lines
13 KiB
Markdown
Title: Utiliser make pour compiler ses documents LaTeX
|
|
Category: linux
|
|
Tags: make, Makefile, LaTeX
|
|
Date: 2023-08-30 12:10
|
|
cover: assets/backgrounds/machine_zorba.jpg
|
|
status: draft
|
|
|
|
Dans mon précédent [article]({filename}../fonctionnement_makefile/index.md),
|
|
nous avons vu comment fonctionne *make* et son langague utilisé dans les
|
|
`Makefile`. Comme promis, voici le premier example d'utilisation : la
|
|
construction de document *PDF* à partir de fichiers sources LaTeX, de fichiers
|
|
*SVG* et d'images matricielles.
|
|
|
|
Nous allons avancer progressivement tout au long de cet article, ainsi nous
|
|
commencerons avec un `Makefile` des plus basique pour l'améliorer au fur et à
|
|
mesure.
|
|
|
|
## Avant de commencer
|
|
|
|
Vous trouverez des fichiers d'exemples pour chacune des étapes [dans cette
|
|
archive]({attach}./files/examples.tbz). Les corrections sont disponibles dans
|
|
le répertoire `Makefile/`.
|
|
|
|
Faites attention aux copiés/collés : les tabulations sont transformées en
|
|
espace dans les blocs de code de cet article. Or *make* se sert des tabulations
|
|
pour déterminer les actions relatives aux cibles. Lors de l'exécution de *make*,
|
|
vous aurez l'erreur `Makefile:23: *** missing separator. Stop.`, il suffira de
|
|
revoir votre indentation.
|
|
|
|
## Permier pas, simple mais pas efficace
|
|
|
|
Notre base de départ est simple, elle permet de compiler un document appelé
|
|
`document.tex` dans le répertoire courant. Voici le code de `Makefile`:
|
|
|
|
```make
|
|
LC = lualatex
|
|
LCFLAGS = --interaction=nonstopmode
|
|
|
|
default: document.pdf
|
|
|
|
document.pdf: document.tex
|
|
$(LC) $(LCFLAGS) $<
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
@rm document.aux document.log documents.pdf
|
|
```
|
|
|
|
|
|
Nous utilisons ce qui se fait déjà pour la compilation de programme en `C`, à
|
|
savoir placer le compitateur et ses paramètres dans des variables. Nous avons
|
|
donc `$(LC)` pour *LaTeX Compiler* -- j'utilise LuaLatex -- et `$(LCFLAGS)`
|
|
pour les paramètres.
|
|
|
|
## un répertoire pour les compiler tous
|
|
|
|
À la premièrer compilation, on s'aperçoit vite que plusieurs fichiers
|
|
apparaissent dans notre répertoire (fichiers `aux`, `log`, `toc` etc.) Il
|
|
devient alors un peu confus, nous allons faire en sorte de placer tous ces
|
|
fichiers (ainsi que le fichier PDF généré) dans un répertoire séparé.
|
|
|
|
```make
|
|
LC = lualatex
|
|
LCFLAGS = --interaction=nonstopmode --output-directory $(OUTPUT)
|
|
OUTPUT = build
|
|
|
|
default: $(OUTPUT)/document.pdf
|
|
|
|
$(OUTPUT)/document.pdf: document.tex
|
|
$(LC) $(LCFLAGS) $<
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
@rm -rf $(OUTPUT)
|
|
```
|
|
Nous définissons la variables `OUTPUT` qui contient le répertoire dans lequel
|
|
placer tous les fichiers générés par `lualatex`. L'options qui va bien est
|
|
ajoutée à `LCFLAGS`. `OUTPUT` est aussi utilisée pour la cible `clean`, notre
|
|
nettoyage n'en est que plus simple!.
|
|
|
|
Tout ces fichiers sont maintenant dans le répertoire `build/`.
|
|
|
|
## Tous ne s'appellent pas document
|
|
|
|
Tous nos documents de s'appellent pas *document*, leurs noms dépendent souvent
|
|
du contexte. Rendons donc ce `Makefile` plus générique grâce aux variables et
|
|
macros
|
|
|
|
```make
|
|
LC = lualatex
|
|
LCFLAGS = --interaction=nonstopmode --output-directory $(OUTPUT)
|
|
OUTPUT = build
|
|
DOCUMENTS = $(addprefix $(OUTPUT)/, $(patsubst %.tex,%.pdf,$(wildcard *.tex)))
|
|
|
|
default: $(DOCUMENTS)
|
|
|
|
$(OUTPUT)/%.pdf: %.tex
|
|
@mkdir -p $(OUTPUT)
|
|
$(LC) $(LCFLAGS) $<
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
@rm -rf $(OUTPUT)
|
|
```
|
|
notre macro `DOCUMENTS` est un imbrication de 3 fonction :
|
|
|
|
1. `wildcard <motif>` pour récupérer une liste de fichier dans le répersoire
|
|
courant en fonction d'un motif;
|
|
2. `patsubst <motif>,<remplacement>,<chaine>` pour substituer une partie de la
|
|
chaine dans un chemin, `%` fait ici office de caractère joker;
|
|
3. `addprefix <prefix>, <chaine>` pour ajouter un préfixe à chacun des éléments
|
|
d'une chaine de caracères. Pour *make*, les éléments d'une chaine de
|
|
caractère sond délimités par des espaces.
|
|
|
|
Elle permet d'obtenir le nom d'une cible en fonction des fichiers `tex` contenu
|
|
dans notre répertoire : `document.tex` deviendra alors `build/document.pdf`.
|
|
|
|
`$(DOCUMENTS)` est maintenant une dépendance de notre cible `default`. Et chacun
|
|
de ses élémets appelle la cible `$(OUTPUT)/%.pdf: %.tex` qui dépend de `%.tex` :
|
|
la source LaTeX, `%` étant remplacé par le nom donné dans la cible :
|
|
`build/document.pdf` donnerait `document.tex` comme dépendance.
|
|
|
|
Cette solution nous permet maintenant d'appeler notre source LaTeX comme bon
|
|
nous semble. Mieux encore nous nouvons **avoir plusieurs fichiers** à la racine
|
|
de notre répertoire, il seront tous compilés indépendament. C'est très pratique
|
|
lorsque vous avez un rapport et la présentation dans un même dépôt par exemple.
|
|
|
|
## Les images matricielles
|
|
|
|
Il n'est pas rare qu'un document contienne des **images au format matriciel** :
|
|
des photos au format JPEG ou des captures d'écran au format PNG par exemple. Il
|
|
est alors nécessaire de prendre en compte la modification de ces images pour la
|
|
compilation de nos documents.
|
|
|
|
```make
|
|
LC = lualatex
|
|
LCFLAGS = --interaction=nonstopmode --output-directory $(OUTPUT)
|
|
OUTPUT = build
|
|
IMAGES_DIR = images/bitmap
|
|
|
|
DOCUMENTS = $(addprefix $(OUTPUT)/, $(patsubst %.tex,%.pdf,$(wildcard *.tex)))
|
|
IMAGES = $(wildcard $(IMAGES_DIR)/*.*)
|
|
|
|
default: $(DOCUMENTS)
|
|
|
|
$(OUTPUT)/%.pdf: %.tex $(IMAGES)
|
|
@mkdir -p $(OUTPUT)
|
|
$(LC) $(LCFLAGS) $<
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
@rm -rf $(OUTPUT)
|
|
```
|
|
|
|
Nous avons maintenant une variable `IMAGES_DIR` qui nous permet de spécifier le
|
|
répertoire dans lequel sont stockées les images -- nous verrons plus tard que
|
|
d'autres sous-dossiers d'*images* apparaîtront. La liste des images est
|
|
récupérée grace à la macro `IMAGES` qui utilise la fonction `wildcard` pour
|
|
récupérer **tous les fichiers de ce répertoire**.
|
|
|
|
Le résultat de cette macro est donné en dépendance de notre cible de
|
|
contruction des documents `$(OUTPUT)/%.pdf: %.tex`. **Ainsi si une image est
|
|
modifiée ou ajoutée, alors la compilation du fichier PDF sera relancée**.
|
|
|
|
Notre technique a cependant deux défauts. D'abord si une image est ajoutée mais
|
|
n'est pas utilisée le document sera quand même compilé alors que ce n'est pas
|
|
nécessaire.
|
|
|
|
Enfin si une image utilisée **seulement** dans le document *B* est modifiée, *A*
|
|
et *C* **seraient aussi compilés**. Ce dernier problème pourrait être résolu,
|
|
mais au prix d'une complexification de notre processus de compilation.
|
|
|
|
## Les images SVG
|
|
|
|
Personnellement j'utilise beaucoup *Inkscape* pour produire diverses images.
|
|
Mais le format SVG n'est pas utilisable tel quel en LaTeX[^n_svgtex]. Il est
|
|
nécesssaire de passer par une étape intermédiaire pour le transformer en PDF.
|
|
|
|
```make
|
|
LC = lualatex
|
|
LCFLAGS = --interaction=nonstopmode --output-directory $(OUTPUT)
|
|
SC = inkscape
|
|
SCFLAGS = --export-type=pdf --export-pdf-version=1.4
|
|
|
|
OUTPUT = build
|
|
IMAGES_DIR = images/bitmap
|
|
SVG_DIR = images/svg
|
|
SVG_EXPORTED_DIR = images/generated
|
|
|
|
DOCUMENTS = $(addprefix $(OUTPUT)/, $(patsubst %.tex,%.pdf,$(wildcard *.tex)))
|
|
IMAGES = $(wildcard $(IMAGES_DIR)/*.*)
|
|
SVG = $(wildcard $(SVG_DIR)/*.svg)
|
|
|
|
SVG_EXPORTED = $(subst $(SVG_DIR), $(SVG_EXPORTED_DIR), $(patsubst %.svg,%.pdf,$(SVG)))
|
|
|
|
default: $(DOCUMENTS)
|
|
|
|
$(OUTPUT)/%.pdf: %.tex $(IMAGES) $(SVG_EXPORTED)
|
|
@mkdir -p $(OUTPUT)
|
|
$(LC) $(LCFLAGS) $<
|
|
|
|
$(SVG_EXPORTED_DIR)/%.pdf : $(SVG_DIR)/%.svg
|
|
$(SC) $(SCFLAGS) -o $@ $<
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
@rm -rf $(OUTPUT
|
|
```
|
|
|
|
Le principe est ici simple : nous allons utiliser *Inkscape* pour exporter les
|
|
fichiers au format PDF. Pourquoi exporter en PDF? C'est un format bien supporté
|
|
par les moteurs *LaTeX*. Il permet aussi de conserver au maximum le format
|
|
vectoriel[^n_svgpdf].
|
|
|
|
Quatres variables font leur apparition :
|
|
|
|
* `SC` pour *SVG compiler*, nous utilisons *Inkscape*;
|
|
* `SCFLAGS` qui contient les paramètres de la commande `Inkcape`;
|
|
* `SVG_DIR` qui contient le chemin vers les fichiers SVG;
|
|
* `SVG_EXPORTED_DIR` qui contient le chemin vers les fichiers PDF exportés
|
|
depuis *Inkscape*.
|
|
|
|
Nous avons aussi deux macros
|
|
|
|
* `SVG` liste les fichiers SVG, cette macro utilise la fonction `wildcard`
|
|
interne à *make* qui permet de récupérer une liste de fichiers en fonction
|
|
d'un motif;
|
|
* `SVG_EXPORTED` transforme la liste de fichiers SVG en liste de fichiers PDF.
|
|
Deux fonctions imbriquées sont nécessaires :`subst` qui permet de remplacer
|
|
un motif dans des chaines et `patsubst` que nous avons vu précédemment. Cette
|
|
macro est donnée en dépendance de la cible de compilation des documents.
|
|
|
|
Ensuite la cible qui nous permet de convertir les fichiers :
|
|
`$(SVG_EXPORTED_DIR)/%.pdf: $(SVG_DIR)/%.svg` et la commande associée.
|
|
|
|
[^n_svgtex]: Ce n'est pas tout à fait vrai, il est possible d'utiliser le
|
|
package LaTeX *svg* et sa commande `\includesvg` mais les contraintes sont
|
|
nombreuses.
|
|
|
|
[^n_svgpdf]: Sauf dans quelques cas spécifiques comme l'utilisation de certains
|
|
filtres, mais les éléments concernés seront convertis en matriciels dans le
|
|
PDF rendu.
|
|
|
|
## Les cibles accessoires
|
|
|
|
Nous avons vu jusqu'ici les cibles principales, nous allons maintenant ajouter
|
|
deux cibles qui pourront nous faciliter la vie.
|
|
|
|
### Afficher des informations
|
|
|
|
Notre `Makefile` est maintenant conséquent, il contient quelques **macros qu'il
|
|
est parfois utiles d'afficher**. Cette affichage nous permettra par exemple de
|
|
vérifier les images matricielles prises en compte ou encore les fichiers SVG qui
|
|
seront exportées.
|
|
|
|
```make
|
|
LC = lualatex
|
|
LCFLAGS = --interaction=nonstopmode --output-directory $(OUTPUT)
|
|
SC = inkscape
|
|
SCFLAGS = --export-type=pdf --export-pdf-version=1.4
|
|
|
|
OUTPUT = build
|
|
IMAGES_DIR = images/bitmap
|
|
SVG_DIR = images/svg
|
|
SVG_EXPORTED_DIR = images/generated
|
|
|
|
DOCUMENTS = $(addprefix $(OUTPUT)/, $(patsubst %.tex,%.pdf,$(wildcard *.tex)))
|
|
IMAGES = $(wildcard $(IMAGES_DIR)/*.*)
|
|
SVG = $(wildcard $(SVG_DIR)/*.svg)
|
|
|
|
SVG_EXPORTED = $(subst $(SVG_DIR),$(SVG_EXPORTED_DIR),$(patsubst %.svg,%.pdf,$(SVG)))
|
|
|
|
default: $(DOCUMENTS)
|
|
|
|
$(OUTPUT)/%.pdf: %.tex $(IMAGES) $(SVG_EXPORTED)
|
|
@mkdir -p $(OUTPUT)
|
|
$(LC) $(LCFLAGS) $<
|
|
|
|
$(SVG_EXPORTED_DIR)/%.pdf : $(SVG_DIR)/%.svg
|
|
$(SC) $(SCFLAGS) -o $@ $<
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
@rm -rf $(OUTPUT)
|
|
|
|
.PHONY: info
|
|
info:
|
|
@echo "document.............'$(DOCUMENTS)'"
|
|
@echo "bitmap images........'$(IMAGES)'"
|
|
@echo "SVG images...........'$(SVG)'"
|
|
@echo "exported SVG images..'$(SVG_EXPORTED)'"
|
|
```
|
|
|
|
Nous n'utilisons pas la commande relatives au messages (`info`, `warning` et
|
|
`error`) que nous avons vu dans le précédent article, sinon un message `make:
|
|
Nothing to be done for 'info'.` apparaît après les informations.
|
|
|
|
### Lancer l'application de visualisation des PDF
|
|
|
|
Lancer la compilation d'un document et l'afficher ensuite dans notre visionneur
|
|
de document permet souvent de gagner du temps.
|
|
|
|
```make
|
|
LC = lualatex
|
|
LCFLAGS = --interaction=nonstopmode --output-directory $(OUTPUT)
|
|
SC = inkscape
|
|
SCFLAGS = --export-type=pdf --export-pdf-version=1.4
|
|
|
|
VIEWER = zathura
|
|
VIEWER_FLAGS = --fork
|
|
|
|
OUTPUT = build
|
|
IMAGES_DIR = images/bitmap
|
|
SVG_DIR = images/svg
|
|
SVG_EXPORTED_DIR = images/generated
|
|
|
|
DOCUMENTS = $(addprefix $(OUTPUT)/, $(patsubst %.tex,%.pdf,$(wildcard *.tex)))
|
|
IMAGES = $(wildcard $(IMAGES_DIR)/*.*)
|
|
SVG = $(wildcard $(SVG_DIR)/*.svg)
|
|
|
|
SVG_EXPORTED = $(subst $(SVG_DIR),$(SVG_EXPORTED_DIR),$(patsubst %.svg,%.pdf,$(SVG)))
|
|
|
|
default: $(DOCUMENTS)
|
|
|
|
$(OUTPUT)/%.pdf: %.tex $(IMAGES) $(SVG_EXPORTED)
|
|
@mkdir -p $(OUTPUT)
|
|
$(LC) $(LCFLAGS) $<
|
|
|
|
$(SVG_EXPORTED_DIR)/%.pdf : $(SVG_DIR)/%.svg
|
|
$(SC) $(SCFLAGS) -o $@ $<
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
@rm -rf $(OUTPUT)
|
|
|
|
.PHONY: info
|
|
info:
|
|
@echo "document.............'$(DOCUMENTS)'"
|
|
@echo "bitmap images........'$(IMAGES)'"
|
|
@echo "SVG images...........'$(SVG)'"
|
|
@echo "exported SVG images..'$(SVG_EXPORTED)'"
|
|
|
|
.PHONY: view
|
|
view: default
|
|
@$(VIEWER) $(VIEWER_FLAGS) $(DOCUMENTS)
|
|
```
|
|
|
|
Deux nouvelles variables font leur apparition :
|
|
|
|
* `VIEWER` qui contient le nom du programme utilisé comme visionneur,
|
|
[zathura][l_zathura] dans l'exemple.
|
|
* `VIEWER_FLAGS` qui contient les options de notre visionneur
|
|
|
|
Nous avons aussi une nouvelle cible `view`, comme elle ne réalise aucune
|
|
création de fichier nous ladéclarons comme cible `.PHONY`. La seule dépendance
|
|
ce cette cible est `default`. Ainsi lors de l'appel de `view`, **notre document
|
|
sera recompilé si nécessaire**.
|
|
|
|
[l_zathura]:https://pwmt.org/projects/zathura/
|
|
|
|
## En conclusion
|
|
|
|
Partant d'un `Makefile` standard, nous l'avons amélioré au fur et à mesure en
|
|
utilisant les fonctionnalités proposé par *make*. Bien entendu cet exemple est
|
|
valable pour les documents simple, il sera alors nécessaire de l'adapter pour
|
|
prendre en compte les **compilations multi-passes** pour la gestion des
|
|
bibiographies par exemple.
|
|
|
|
De mon côté j'ai profité de l'écriture de cet article pour améliorer mon
|
|
processus de compilation de mes documents LaTeX. Au final, chaque dépôt de code
|
|
contenant des documents prend la forme suivante :
|
|
|
|
```
|
|
├── images
|
|
│ ├── bitmap
|
|
│ │ └── ...
|
|
│ ├── generated
|
|
│ └── svg
|
|
│ └── ...
|
|
├── Makefile
|
|
├── build
|
|
├── README.md
|
|
└── document.tex
|
|
```
|
|
|
|
*[PDF]: Portable Document Format
|
|
*[SVG]: Scalable Vector Graphics
|