# Installer des outils : brew, apt, npm

Un gestionnaire de paquets installe un logiciel en une commande, avec tout ce dont il a besoin, et sait le mettre à jour ou le retirer proprement.

## Le problème

Le projet dépend déjà de deux gestionnaires, sans le dire :

- le jeu a besoin de `pygame` et `pillow`, installés par `pip` à partir de `requirements.txt` ;
- sa documentation, comme ce site de formation, a besoin de `zudoku`, `react` et `mermaid`, installés par `npm` à partir d'un fichier `package.json`.

Et pour avoir `python` et `node` eux-mêmes, il faut un troisième outil : `brew` sur macOS, `apt` sur Ubuntu ou Debian.

Quand on ne sait pas lequel fait quoi, on finit par copier des commandes trouvées en ligne. La deuxième ligne du README en est la trace : `pip install -f requirements.txt` ne fait pas ce que son auteur voulait. La bonne option est `-r`.

## La notion

### Paquet, dépendance, dépôt

| Mot | Sens |
| --- | --- |
| Paquet | Un logiciel ou une bibliothèque, prêt à être installé |
| Dépendance | Un paquet dont un autre a besoin pour fonctionner |
| Dépôt, ou registre | Le serveur où le gestionnaire télécharge les paquets |
| Version | Le numéro qui identifie un état précis du paquet |

Le gestionnaire résout les dépendances à notre place : demander `zudoku` installe aussi les centaines de paquets dont il a besoin.

### Deux niveaux

<Mermaid
  chart={`flowchart TB
    subgraph systeme [Niveau système, pour toute la machine]
      brew[brew<br/>macOS]
      apt[apt<br/>Debian, Ubuntu]
    end
    subgraph langage [Niveau projet, pour un langage]
      pip[pip<br/>Python]
      npm[npm<br/>JavaScript]
    end
    brew -- installe --> outils[python, node, git, docker]
    apt -- installe --> outils
    outils --> pip
    outils --> npm
    pip -- installe dans .venv --> py[pygame, pillow, pytest]
    npm -- installe dans node_modules --> js[zudoku, react, mermaid]`}
/>

La règle : les **outils** s'installent au niveau système, les **bibliothèques d'un projet** s'installent dans le dossier du projet.

## Les commandes, côte à côte

| Action | brew | apt | pip | npm |
| --- | --- | --- | --- | --- |
| Installer | `brew install git` | `sudo apt install git` | `pip install pygame` | `npm install mermaid` |
| Retirer | `brew uninstall git` | `sudo apt remove git` | `pip uninstall pygame` | `npm uninstall mermaid` |
| Lister | `brew list` | `apt list --installed` | `pip list` | `npm list` |
| Chercher | `brew search node` | `apt search node` | sur pypi.org | `npm search mermaid` |
| Mettre à jour | `brew upgrade` | `sudo apt upgrade` | `pip install --upgrade pygame` | `npm update` |
| Tout installer d'un projet | | | `pip install -r requirements.txt` | `npm install` |

## brew, sur macOS

[Homebrew](https://brew.sh) n'est pas fourni avec macOS : on l'installe une fois, avec la commande donnée sur son site.

```bash
brew install python node git     # des outils en ligne de commande
brew install --cask virtualbox   # une application graphique
brew update                      # rafraîchir la liste des paquets
brew upgrade                     # mettre à jour ce qui est installé
```

Une *formula* est un outil en ligne de commande, un *cask* une application avec fenêtre. `brew` s'utilise sans `sudo`.

## apt, sur Debian et Ubuntu

`apt` est fourni avec le système. C'est lui qu'on utilisera sur un serveur ou dans une machine virtuelle.

```bash
sudo apt update                  # rafraîchir la liste des paquets
sudo apt install python3 git     # installer
sudo apt upgrade                 # mettre à jour ce qui est installé
```

`sudo` lance la commande avec les droits d'administrateur, et demande le mot de passe. Il est nécessaire parce qu'`apt` modifie le système.

:::warning{title="update n'installe rien"}

`apt update` met à jour la **liste** des paquets disponibles. `apt upgrade` met à jour les paquets **installés**. Sur une machine neuve, un `apt install` qui échoue avec « paquet introuvable » se règle presque toujours par un `sudo apt update` d'abord.

:::

## npm, pour JavaScript

`npm` arrive avec Node.js. Contrairement à `brew` et `apt`, il travaille **dans le dossier du projet**.

| Fichier ou dossier | Rôle | Dans Git ? |
| --- | --- | --- |
| `package.json` | Les dépendances voulues et les scripts du projet | Oui |
| `package-lock.json` | Les versions exactes réellement installées | Oui |
| `node_modules/` | Les paquets téléchargés | Non |

Le `package.json` de ce site, à la racine du dépôt :

```json
{
  "scripts": {
    "dev": "zudoku dev",
    "build": "zudoku build"
  },
  "dependencies": {
    "mermaid": "^11.17.2",
    "zudoku": "^0.93.2"
  }
}
```

```bash
npm install          # installe tout ce que liste package.json
npm run dev          # lance le script "dev"
npm install mermaid  # ajoute un paquet et l'inscrit dans package.json
npx zudoku --help    # lance un outil du projet sans l'installer sur la machine
```

L'option `-g` installe un paquet pour toute la machine. À réserver aux outils qu'on utilise partout, jamais aux dépendances d'un projet.

## pip et npm : le même schéma

Les deux font le même travail pour deux langages.

| Rôle | Python | JavaScript |
| --- | --- | --- |
| Gestionnaire | `pip` | `npm` |
| Liste des dépendances | `requirements.txt` | `package.json` |
| Versions exactes | `requirements.txt` avec `==` | `package-lock.json` |
| Dossier d'installation | `.venv/` | `node_modules/` |
| Isolation par projet | À créer avec `python3 -m venv` | Automatique |
| Dépôt public | pypi.org | npmjs.com |

## Figer les versions

Sans version précise, deux personnes qui installent le projet à un mois d'écart n'obtiennent pas les mêmes paquets. Le jour où une bibliothèque change de comportement, le jeu marche chez l'un et pas chez l'autre.

Le `requirements.txt` du projet le fait correctement :

```text
pillow==12.3.0
pygame==2.6.1
```

| Écriture | Sens |
| --- | --- |
| `pygame==2.6.1` | Exactement cette version |
| `pygame>=2.6` | Cette version ou plus récente |
| `"^11.17.2"` dans `package.json` | 11.17.2 ou plus, mais pas 12 |

Les trois nombres d'une version se lisent **majeur.mineur.correctif**. Par convention, un changement de majeur peut casser du code existant, un changement de mineur ajoute sans casser, un correctif répare.

## Dans le projet

Les deux lignes du README, corrigées et dans le bon ordre :

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Et quand on ajoute une dépendance, par exemple `pytest` :

```bash
pip install pytest
pip freeze > requirements.txt
```

`pip freeze` écrit **tout** ce qui est installé dans l'environnement. D'où l'importance de l'environnement virtuel : sans lui, le fichier se remplit des paquets de tous les autres projets de la machine.

## Les précautions

- **Installer peu.** Chaque paquet est du code écrit par quelqu'un d'autre, qui s'exécute sur la machine.
- **Vérifier le nom.** Des paquets malveillants portent des noms proches de paquets connus.
- **Lire avant de coller.** Une commande du type `curl ... | bash` télécharge un script et l'exécute sans qu'on l'ait lu.
- **Ne pas mettre `sudo` devant `pip` ou `npm`.** Si une installation demande des droits d'administrateur, c'est qu'elle ne se fait pas dans le dossier du projet.

## À retenir

- `brew` et `apt` installent des outils sur la machine. `pip` et `npm` installent des bibliothèques dans un projet.
- La liste des dépendances va dans Git, le dossier des paquets installés n'y va pas.
- `apt update` rafraîchit la liste, `apt upgrade` met à jour.
- Des versions figées donnent le même projet chez tout le monde.

## Exercices

1. Corriger le `README.md` du projet avec les bonnes commandes d'installation.
2. Trouver avec quel gestionnaire `python3`, `node` et `git` ont été installés sur sa machine. `which` aide.
3. Dans un environnement virtuel neuf, installer `pytest`, mettre à jour `requirements.txt`, et regarder ce qui a été ajouté en plus de `pytest`. Pourquoi ?
4. À la racine de ce dépôt, supprimer `node_modules`, puis le reconstruire. Combien de temps, combien de paquets ?
5. Vérifier que `.venv` et `node_modules` sont bien ignorés par Git.
