README.md 6.29 KB
Newer Older
Florent Chehab's avatar
Florent Chehab committed
1
2
3
Intégration Continue : **LaTeX** et **GitLab**.
======= 

Florent Chehab's avatar
Florent Chehab committed
4
5
6
7
8
9
- [Démonstration](#d%C3%A9monstration)
- [Explications](#explications)
  - [Prérequis : activer le _shared Runner_](#pr%C3%A9requis-activer-le-shared-runner)
  - [C'est parti](#cest-parti)
      - [Remarques](#remarques)
  - [Commentaires sur l'intégration continue](#commentaires-sur-lint%C3%A9gration-continue)
10
      - [Autre possibilité](#autre-possibilit%C3%A9)
Florent Chehab's avatar
Florent Chehab committed
11
      - [Pour aller plus loin](#pour-aller-plus-loin)
Florent Chehab's avatar
Florent Chehab committed
12

Florent Chehab's avatar
Florent Chehab committed
13
# Démonstration
Florent Chehab's avatar
Florent Chehab committed
14
Ce _repo_ est en lui-même un démonstration de l'utilisation de l'intégration continue pour la compilation de LaTeX. Le fichier `main.tex` est compilé (voir [Explications](#explications)) et le `pdf` est disponible [ici](https://gitlab.utc.fr/LaTeX-UTC/LaTeX-CI/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master).
Florent Chehab's avatar
Florent Chehab committed
15

Florent Chehab's avatar
Florent Chehab committed
16
N'hésitez pas à cloner ce _repo_ pour vous en servir comme base.
Florent Chehab's avatar
Florent Chehab committed
17
18


Florent Chehab's avatar
Florent Chehab committed
19
# Explications 
Florent Chehab's avatar
Florent Chehab committed
20

Florent Chehab's avatar
Florent Chehab committed
21
## Prérequis : activer le _shared Runner_
Florent Chehab's avatar
Florent Chehab committed
22

Florent Chehab's avatar
Florent Chehab committed
23
24
25
1. Rendez-vous das les `paramètres` du projet GitLab, section `CI/CD`.
1. Cliquez sur `Runners settings` (_expand_).
1. Dans la section _Shared Runners_, cliquez sur _« Activate shared Runners »_.
Florent Chehab's avatar
Florent Chehab committed
26
27


Florent Chehab's avatar
Florent Chehab committed
28
## C'est parti 
Florent Chehab's avatar
Florent Chehab committed
29

Jean-Benoist Leger's avatar
Jean-Benoist Leger committed
30
Vous n'avez plus qu'à modifier le fichier `main.tex` et à _commit_ les changements, la compilation et la publication à l'adresse `https://gitlab.utc.fr/<login-ou-namespace>/<nom-du-projet>/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master` se fait automatiquement. Par exemple, pour ce projet, le pdf est disponible à l'adresse [https://gitlab.utc.fr/LaTeX-UTC/LaTeX-CI/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master](https://gitlab.utc.fr/LaTeX-UTC/LaTeX-CI/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master). Pour faire des liens à partir d'un fichier MarkDown (comme le `README.md`), on préferera faire un lien vers `/../builds/artifacts/master/raw/main.pdf?job=building-latex-master` ce qui permet de s'abstraire du nom du projet.
Florent Chehab's avatar
Florent Chehab committed
31
32
33
34
35


### Remarques 

- Les `pdf` compilés sont rendus disponibles en public via les _artifacts_. Ces derniers peuvent être visualisés via :
Florent Chehab's avatar
Florent Chehab committed
36
37
  - La page d'accueil du projet, cliquez sur l'icône _télécharger_ puis sur `Télécharger 'building-latex-master'`
  - Dans le menu du projet, cliquez sur `CI/CD` -> `jobs`, puis sur le badge (espérons "réussi") du status associé au job souhaité, puis dans le menu de droite, dans la section `Job artifacts` cliquez sur `browse`.
Florent Chehab's avatar
Florent Chehab committed
38
39
40
41
  - Url : 
      -  Pour la branche master : `https://gitlab.utc.fr/<login-ou-namespace>/<nom-du-projet>/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master`
      -  Pour les autres branches : `https://gitlab.utc.fr/<login-ou-namespace>/<nom-du-projet>/-/jobs/artifacts/<nom-de-la-branche>/raw/main.pdf?job=building-latex-other-branch`
- Si la compilation échoue, le _job_ sera marqué comme tel et vous pouvez accéder aux logs pour savoir où elle a échouée. 
Florent Chehab's avatar
Florent Chehab committed
42
43
- _Pensez à adapter la license à votre projet._

Florent Chehab's avatar
Florent Chehab committed
44
## Commentaires sur l'intégration continue
Florent Chehab's avatar
Florent Chehab committed
45
46
Avec GitLab, toute l'intégration continue est gérée via le fichier `.gitlab-ci.yml`. Voici celui utilisé par ce projet (avec quelques commentaires).

Florent Chehab's avatar
Florent Chehab committed
47
Il comporte 2 _jobs_ sensiblement similaires qui permettent une gestion optimale des ressources disques : à l'heure de la réalisation de ce projet il n'est pas [encore](https://gitlab.com/gitlab-org/gitlab-ce/issues/23777) possible de garder uniquement les derniers artifacts. Pour contourner le système : 
Florent Chehab's avatar
Florent Chehab committed
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
- Les artifacts issus de la branche master sont conservés 2 ans.
- Les artifacts issus des autres branches sont conservés 2 semaines.

```yaml
# Téléchargement d'une image Docker avec tous les packets
# texlive pour éviter les ennuis lors de la compilation latex
image: blang/latex

# Premier job : compilation du latex
building-latex-master:
  stage: build
  script:
    # Compilation avec latexmk du fichier main.tex 
    # qui est à la racine du repo
    - latexmk -pdf main.tex
  artifacts:
    # Génération d'une archive téléchargeable avec le fichier
    paths:
      - "*.pdf"
    expire_in: 2 year # Durée de validité de l'archive
  tags:
Florent Chehab's avatar
Florent Chehab committed
69
    # Tag pour que le shared runner du GitLab de l'UTC 
Florent Chehab's avatar
Florent Chehab committed
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
    # fasse sont travail.
    - docker

# Deuxième job : similaire, mais pour les autres branches
building-latex-other-branch:
  stage: build
  script:
    - latexmk -pdf main.tex
  artifacts:
    paths:
      - "*.pdf"
    expire_in: 2 week # durée plus courte
  except: # toutes les branches sauf master
    - master
  tags:
    - docker
```

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
### Autre possibilité

Il pourrait être plus simple et moins coûteux en espace disque d'utiliser `GitLab Pages` pour la publication des `PDF` compilés.
**Attention les données disponibles sur GitLab Pages sont publiques même si le projet est privé !**

Voici un exemple de `.gitlab-ci.yml` pour répondre à ce cas d'utilisation :

```yaml
image: blang/latex

building-latex:
  stage: build
  script:
    - latexmk -pdf main.tex
  artifacts:
    paths:
      - "*.pdf"
    expire_in: 2 weeks
  tags:
    - docker

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp main.pdf .public
    - mv .public public
  artifacts:
    paths:
      - public
  only: # publication sur GitLab pages uniquement pour 
    - master   # la branche master
  tags:
    - docker
```
_Dans ce cas, les fichiers sont mis à disposition sur l'URL définie dans `Settings` (du projet) -> `Pages`. Par exemple `url/main.pdf`._ 

Florent Chehab's avatar
Florent Chehab committed
125

Florent Chehab's avatar
Florent Chehab committed
126
### Pour aller plus loin
Florent Chehab's avatar
Florent Chehab committed
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

Dans la partie `script` d'un job décrit dans le fichier `.gitlab-ci.yml` vous pouvez installer des packets (`apt-get install --yes <nom-du-paquet>`) voire exécuter des scripts bash qui seraient disponibles dans le repo :
```yaml
# [...]
building-latex-master:
  stage: build
  script:
    - bash build.sh
# [...]
```

Les possibilités sont donc infinies :)

- Un peu de lecture : https://gitlab.com/help/user/project/pipelines/job_artifacts.md
- Pour tester vos fichiers `.gitlab-ci.yml` : https://gitlab.utc.fr/ci/lint


Florent Chehab's avatar
Florent Chehab committed
144
145
146
147
148
149
150
151
152
153
154
**Amusez-vous bien.** :wink:


# License

Le contenu de ce _repo_ est mis à disposition sous licence BSD-2, voir [LICENSE](./LICENSE);


Excepté :

Le logo GitLab utilisé dans le dossier `images` est disponible sous license [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/), plus d'informations [ici](https://about.gitlab.com/handbook/marketing/corporate-marketing/#gitlab-trademark--logo-guidelines).