Skip to content

TARGET_BUILDS.md

Latest commit

 

History

History
692 lines (497 loc) · 16.2 KB

TARGET_BUILDS.md

File metadata and controls

692 lines (497 loc) · 16.2 KB

Targets de Build Rust - Guide Complet

📋 Table des Matières

  1. Introduction
  2. Qu'est-ce qu'un Target ?
  3. Format des Targets
  4. Targets Principaux
  5. Cross-Compilation
  6. Gestion des Targets
  7. Configuration dans Cargo.toml
  8. Exemples Pratiques
  9. Troubleshooting
  10. FAQ

Introduction

Les targets (cibles) de build Rust définissent pour quelle plateforme (architecture CPU + système d'exploitation) votre code sera compilé. Rust supporte la cross-compilation, ce qui signifie que vous pouvez compiler pour une plateforme différente de celle sur laquelle vous travaillez.

Points Importants

  • ✅ Cross-compilation native : Compiler pour d'autres plateformes depuis votre machine
  • ✅ Support étendu : Des dizaines de targets disponibles
  • ✅ Facile à utiliser : rustup target add et cargo build --target
  • ✅ Performance : Compilation rapide même pour d'autres architectures

Qu'est-ce qu'un Target ?

Un target est un triplet qui identifie une plateforme :

architecture-vendor-os-abi

Exemples :

  • x86_64-pc-windows-gnu : Windows 64-bit avec GCC
  • x86_64-pc-windows-msvc : Windows 64-bit avec MSVC
  • x86_64-unknown-linux-gnu : Linux 64-bit
  • aarch64-apple-darwin : macOS Apple Silicon
  • wasm32-unknown-unknown : WebAssembly

Composants d'un Target

1. Architecture (CPU) :

  • x86_64 : Processeurs 64-bit Intel/AMD
  • i686 : Processeurs 32-bit Intel/AMD
  • aarch64 : ARM 64-bit
  • arm : ARM 32-bit
  • wasm32 : WebAssembly 32-bit
  • riscv64 : RISC-V 64-bit

2. Vendor (Fabricant) :

  • pc : PC standard
  • apple : Apple
  • unknown : Inconnu/générique
  • nvidia : NVIDIA (pour CUDA)

3. OS (Système d'exploitation) :

  • windows : Windows
  • linux : Linux
  • darwin : macOS/iOS
  • android : Android
  • freebsd : FreeBSD
  • none : Pas de système d'exploitation (embeddé)

4. ABI (Application Binary Interface) :

  • gnu : GNU (Linux standard)
  • msvc : Microsoft Visual C++ (Windows)
  • musl : Musl libc (Linux léger)
  • unknown : ABI inconnu
  • eabi : Embedded ABI

Format des Targets

Structure Complète

architecture-vendor-os-abi

Exemples Détaillés

Windows :

x86_64-pc-windows-gnu      # Windows 64-bit avec MinGW/GCC
x86_64-pc-windows-msvc     # Windows 64-bit avec MSVC (recommandé)
i686-pc-windows-gnu        # Windows 32-bit avec MinGW
i686-pc-windows-msvc      # Windows 32-bit avec MSVC

Linux :

x86_64-unknown-linux-gnu   # Linux 64-bit standard
x86_64-unknown-linux-musl  # Linux 64-bit avec musl (statique)
aarch64-unknown-linux-gnu  # Linux ARM 64-bit
arm-unknown-linux-gnueabihf # Linux ARM 32-bit

macOS/iOS :

x86_64-apple-darwin        # macOS Intel
aarch64-apple-darwin       # macOS Apple Silicon
aarch64-apple-ios         # iOS ARM 64-bit
x86_64-apple-ios          # iOS Simulator

WebAssembly :

wasm32-unknown-unknown     # WebAssembly standard
wasm32-wasip1              # WebAssembly System Interface
wasm32-unknown-emscripten # Emscripten

Embedded :

thumbv7em-none-eabihf      # ARM Cortex-M avec FPU
riscv32imc-unknown-none-elf # RISC-V 32-bit
aarch64-unknown-none       # ARM 64-bit bare metal

Targets Principaux

Windows

Target Description Compilateur
x86_64-pc-windows-msvc Windows 64-bit (recommandé) MSVC
x86_64-pc-windows-gnu Windows 64-bit MinGW/GCC
i686-pc-windows-msvc Windows 32-bit MSVC
i686-pc-windows-gnu Windows 32-bit MinGW/GCC
aarch64-pc-windows-msvc Windows ARM 64-bit MSVC

Recommandation : Utilisez -msvc pour de meilleures performances et compatibilité.

Linux

Target Description Notes
x86_64-unknown-linux-gnu Linux 64-bit standard Nécessite glibc
x86_64-unknown-linux-musl Linux 64-bit statique Binaire autonome
aarch64-unknown-linux-gnu Linux ARM 64-bit Pour Raspberry Pi, etc.
arm-unknown-linux-gnueabihf Linux ARM 32-bit Pour ARMv7

Recommandation : Utilisez -musl pour des binaires statiques portables.

macOS

Target Description
x86_64-apple-darwin macOS Intel
aarch64-apple-darwin macOS Apple Silicon (M1/M2)

Note : Apple recommande de compiler des universal binaries qui fonctionnent sur les deux.

WebAssembly

Target Description
wasm32-unknown-unknown WebAssembly standard
wasm32-wasip1 WASI (WebAssembly System Interface)
wasm32-unknown-emscripten Emscripten (legacy)

Recommandation : Utilisez wasm32-unknown-unknown pour les applications web modernes.

Android

Target Description
aarch64-linux-android Android ARM 64-bit
armv7-linux-androideabi Android ARM 32-bit
x86_64-linux-android Android x86_64

Cross-Compilation

La cross-compilation permet de compiler pour une plateforme différente de celle sur laquelle vous travaillez.

Avantages

  • ✅ Développement sur une seule machine : Compilez pour Windows, Linux, macOS depuis n'importe quelle plateforme
  • ✅ CI/CD simplifié : Un seul serveur peut compiler pour toutes les plateformes
  • ✅ Tests : Vérifiez que votre code compile sur différentes plateformes

Limitations

  • ⚠️ Dépendances natives : Certaines dépendances nécessitent des outils spécifiques
  • ⚠️ Tests : Vous ne pouvez pas exécuter les binaires cross-compilés directement
  • ⚠️ Temps de compilation : Peut être plus long pour certaines plateformes

Gestion des Targets

Lister les Targets Disponibles

rustup target list

Sortie :

aarch64-apple-darwin
aarch64-unknown-linux-gnu
x86_64-pc-windows-gnu (installed)
x86_64-pc-windows-msvc
wasm32-unknown-unknown
...

Les targets installés sont marqués (installed).

Installer un Target

# Installer un target spécifique
rustup target add x86_64-unknown-linux-gnu

# Installer plusieurs targets
rustup target add wasm32-unknown-unknown aarch64-apple-darwin

Désinstaller un Target

rustup target remove x86_64-unknown-linux-gnu

Voir le Target par Défaut

rustup show

Affiche le target par défaut (généralement celui de votre machine).

Compilation pour un Target

Compiler pour le Target par Défaut

cargo build
# Compile pour votre plateforme actuelle

Compiler pour un Target Spécifique

# Compiler pour Linux depuis Windows
cargo build --target x86_64-unknown-linux-gnu

# Compiler pour WebAssembly
cargo build --target wasm32-unknown-unknown

# Compiler pour macOS depuis Linux
cargo build --target x86_64-apple-darwin

Compiler en Release pour un Target

cargo build --release --target x86_64-unknown-linux-gnu

Emplacement des Binaires

Les binaires compilés sont dans :

target/<target>/debug/<nom>
target/<target>/release/<nom>

Exemple :

target/x86_64-unknown-linux-gnu/release/mini_sheet

Configuration dans Cargo.toml

Définir un Target par Défaut

[build]
target = "x86_64-unknown-linux-gnu"

Configurer un Target Spécifique

[target.x86_64-unknown-linux-gnu]
linker = "x86_64-linux-gnu-gcc"

[target.wasm32-unknown-unknown]
runner = "wasm-bindgen-test-runner"

Configurer des Linkers

Pour la cross-compilation, vous devez souvent spécifier un linker :

[target.x86_64-unknown-linux-gnu]
linker = "x86_64-linux-gnu-gcc"

[target.arm-unknown-linux-gnueabihf]
linker = "arm-linux-gnueabihf-gcc"

Configurer des Build Scripts

[target.'cfg(target_os = "windows")'.dependencies]
winapi = "0.3"

[target.'cfg(target_os = "linux")'.dependencies]
libc = "0.2"

Exemples Pratiques

Exemple 1 : Compiler pour Linux depuis Windows

1. Installer le target :

rustup target add x86_64-unknown-linux-gnu

2. Installer les outils (si nécessaire) :

# Sur Windows avec MSYS2
pacman -S mingw-w64-x86_64-gcc

3. Configurer Cargo.toml :

[target.x86_64-unknown-linux-gnu]
linker = "x86_64-linux-gnu-gcc"

4. Compiler :

cargo build --release --target x86_64-unknown-linux-gnu

Exemple 2 : Compiler pour WebAssembly

1. Installer le target :

rustup target add wasm32-unknown-unknown

2. Compiler :

cargo build --release --target wasm32-unknown-unknown

3. Le binaire sera dans :

target/wasm32-unknown-unknown/release/mini_sheet.wasm

Exemple 3 : Compiler pour macOS depuis Linux

1. Installer le target :

rustup target add x86_64-apple-darwin

2. Installer osxcross (outil de cross-compilation macOS) :

# Nécessite osxcross et le SDK macOS
# Voir : https://github.com/tpoechtrager/osxcross

3. Configurer :

[target.x86_64-apple-darwin]
linker = "x86_64-apple-darwin-clang"

Exemple 4 : Compiler pour Android

1. Installer les targets Android :

rustup target add aarch64-linux-android
rustup target add armv7-linux-androideabi
rustup target add x86_64-linux-android

2. Installer le NDK Android :

  • Télécharger Android NDK
  • Configurer les variables d'environnement

3. Compiler :

cargo build --release --target aarch64-linux-android

Exemple 5 : Compiler pour Embedded (ARM)

1. Installer le target :

rustup target add thumbv7em-none-eabihf

2. Compiler :

cargo build --release --target thumbv7em-none-eabihf

Configuration Avancée

Variables d'Environnement

Vous pouvez configurer des variables d'environnement pour la cross-compilation :

# Linker personnalisé
export CC_x86_64_unknown_linux_gnu=x86_64-linux-gnu-gcc
export CXX_x86_64_unknown_linux_gnu=x86_64-linux-gnu-g++

# Compiler
cargo build --target x86_64-unknown-linux-gnu

Fichier .cargo/config.toml

Créez .cargo/config.toml à la racine de votre projet :

[build]
target = "x86_64-unknown-linux-gnu"  # Target par défaut

[target.x86_64-unknown-linux-gnu]
linker = "x86_64-linux-gnu-gcc"
runner = "qemu-x86_64"

[target.wasm32-unknown-unknown]
runner = "wasm-bindgen-test-runner"

Utiliser des Toolchains Spécifiques

# Installer une toolchain pour un target spécifique
rustup toolchain install stable-x86_64-unknown-linux-gnu

# Utiliser cette toolchain
cargo +stable-x86_64-unknown-linux-gnu build --target x86_64-unknown-linux-gnu

Troubleshooting

Erreur : "linker not found"

Problème : Le linker pour le target n'est pas installé.

Solution :

# Installer le linker (exemple pour Linux depuis Windows)
# Sur Windows avec MSYS2
pacman -S mingw-w64-x86_64-gcc

# Configurer dans .cargo/config.toml
[target.x86_64-unknown-linux-gnu]
linker = "x86_64-linux-gnu-gcc"

Erreur : "cannot find -l"

Problème : Une bibliothèque système est manquante.

Solution :

  • Installer les bibliothèques de développement pour le target
  • Utiliser des dépendances Rust pures quand possible
  • Utiliser -musl pour des binaires statiques

Erreur : "target not installed"

Problème : Le target n'est pas installé.

Solution :

rustup target add <target>

Erreur : Build Scripts Échouent

Problème : Les build scripts (build.rs) peuvent nécessiter des outils spécifiques.

Solution :

  • Vérifier que tous les outils nécessaires sont installés
  • Utiliser des variables d'environnement pour pointer vers les outils
  • Considérer désactiver certains build scripts si possible

Binaires Trop Volumineux

Solution :

[profile.release]
opt-level = "z"      # Optimiser pour la taille
lto = true           # Link-Time Optimization
strip = true         # Supprimer les symboles

FAQ

Q: Quel target dois-je utiliser pour Windows ?

R:

  • Recommandé : x86_64-pc-windows-msvc (meilleure compatibilité)
  • Alternative : x86_64-pc-windows-gnu (si vous utilisez MinGW)

Q: Comment compiler un binaire statique pour Linux ?

R: Utilisez le target -musl :

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

Le binaire sera statique et portable.

Q: Puis-je compiler pour macOS depuis Windows ?

R: Techniquement oui, mais c'est complexe :

  • Nécessite le SDK macOS (propriétaire Apple)
  • Nécessite osxcross
  • Recommandation : Utiliser un Mac ou CI/CD (GitHub Actions, etc.)

Q: Comment compiler pour plusieurs targets à la fois ?

R: Utilisez un script ou CI/CD :

#!/bin/bash
for target in \
  x86_64-pc-windows-msvc \
  x86_64-unknown-linux-gnu \
  x86_64-apple-darwin
do
  cargo build --release --target $target
done

Q: Les binaires cross-compilés sont-ils plus lents ?

R: Non, les binaires compilés pour un target spécifique ont les mêmes performances que s'ils étaient compilés nativement sur cette plateforme.

Q: Puis-je tester un binaire cross-compilé ?

R:

  • Sur la même machine : Non (sauf avec émulateurs comme QEMU)
  • Sur la machine cible : Oui, transférez et exécutez-le
  • Tests unitaires : Oui, Rust peut compiler et exécuter les tests pour le target

Q: Comment savoir quel target utiliser ?

R:

  • Pour votre machine : rustup show affiche le target par défaut
  • Pour une autre machine : Utilisez le target correspondant à son architecture et OS
  • Pour le web : wasm32-unknown-unknown

Q: Les dépendances fonctionnent-elles avec tous les targets ?

R: La plupart oui, mais certaines dépendances :

  • Nécessitent des bibliothèques système spécifiques
  • Ne supportent pas tous les targets
  • Peuvent nécessiter des features spécifiques

Vérifiez la documentation de chaque dépendance.

Q: Comment compiler pour 32-bit sur une machine 64-bit ?

R:

# Installer le target 32-bit
rustup target add i686-pc-windows-msvc

# Compiler
cargo build --target i686-pc-windows-msvc

Q: Puis-je compiler pour ARM depuis x86_64 ?

R: Oui, c'est une cross-compilation standard :

rustup target add aarch64-unknown-linux-gnu
cargo build --target aarch64-unknown-linux-gnu

Commandes Utiles

# Lister tous les targets disponibles
rustup target list

# Lister les targets installés
rustup target list --installed

# Installer un target
rustup target add <target>

# Désinstaller un target
rustup target remove <target>

# Compiler pour un target spécifique
cargo build --target <target>

# Compiler en release pour un target
cargo build --release --target <target>

# Voir le target par défaut
rustup show

# Voir les toolchains installées
rustup toolchain list

# Installer une toolchain pour un target
rustup toolchain install stable-<target>

Résumé des Targets Courants

Target Plateforme Usage
x86_64-pc-windows-msvc Windows 64-bit ✅ Recommandé pour Windows
x86_64-unknown-linux-gnu Linux 64-bit Linux standard
x86_64-unknown-linux-musl Linux 64-bit Binaire statique
x86_64-apple-darwin macOS Intel macOS Intel
aarch64-apple-darwin macOS Apple Silicon macOS M1/M2
wasm32-unknown-unknown WebAssembly Applications web
aarch64-linux-android Android ARM 64-bit Applications Android
thumbv7em-none-eabihf ARM Cortex-M Microcontrôleurs

Exemple Complet : MiniSheet

Pour compiler MiniSheet pour différentes plateformes :

1. Windows (par défaut) :

cargo build --release
# → target/release/mini_sheet.exe

2. Linux :

rustup target add x86_64-unknown-linux-gnu
cargo build --release --target x86_64-unknown-linux-gnu
# → target/x86_64-unknown-linux-gnu/release/mini_sheet

3. WebAssembly :

rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown
# → target/wasm32-unknown-unknown/release/mini_sheet.wasm

Note : Pour WebAssembly, vous devrez peut-être adapter le code pour utiliser wasm-bindgen ou wasm-pack.

Dernière mise à jour : 2026-01-20