ChromiumFX sert de passerelle entre le monde .NET et le Chromium Embedded Framework, un peu comme un traducteur assermenté entre deux administrations qui ne se parlent pas. Vous embarquez un Chromium dans une application Windows Forms ou WPF, sans bricoler un moteur web à la main. Ce tutoriel déroule l’installation et la configuration, avec les pièges classiques évités dès le départ.
ChromiumFX : Prérequis système et logiciels
Ces prérequis coupent court aux setups qui déraillent à mi-chemin, quand tout semble “presque” prêt. Ils couvrent la machine et l’outillage, car Chromium et CEF ne pardonnent ni l’approximation ni le manque d’espace.
- Processeur x86-64 et 8 Go de RAM minimum, avec 16 Go recommandés.
- Espace disque libre de 100 Go.
- Visual Studio 2022 avec le workload Microsoft.VisualStudio.Workload.NativeDesktop.
- Composants Visual C++ ATLMFC (VC.ATLMFC) et Windows 11 SDK.
- Git for Windows depuis git-scm.com.
- Python 3.9 et CMake 3.21 ou supérieur.
- Pour ARM64, ajouter VC.Tools.ARM64 et VC.MFC.ARM64, et poser aussi DEPOT_TOOLS_WIN_TOOLCHAIN=0.
Téléchargement des binaires CEF et ChromiumFX
L’objectif tient en deux mots, code et binaires, avec une exigence non négociable, la compatibilité entre ChromiumFX et libcef.dll. ChromiumFX vérifie l’API via un hash au démarrage, donc un mauvais package CEF transforme votre lancement en mur de briques.
- Cloner ChromiumFX. `git clone https://github.com/prepare/ChromiumFX\`.
- Récupérer les binaires CEF depuis le site officiel, via les liens indiqués dans le Readme du dépôt.
- Choisir entre suivre un processus de build CEF ou utiliser des binaires distribués.
- Comprendre le contrôle de compatibilité, ChromiumFX valide l’API hash de libcef.dll au démarrage.
- Définir CfxRuntime.LibCefDirPath avant l’initialisation pour pointer vers le dossier qui contient libcef et ses compagnons natifs.
Le chemin CfxRuntime.LibCefDirPath se règle avant toute initialisation runtime.
Installation de visual studio et outils de build
Configuration visual studio
Une installation reproductible passe par la ligne de commande, ce qui évite les cases oubliées dans l’installateur graphique. La liste des workloads et composants sert de contrat, pas de suggestion.
- Lancer l’installation avec les composants requis. `PATH_TO_INSTALLER.EXE –add Microsoft.VisualStudio.Workload.NativeDesktop –add Microsoft.VisualStudio.Component.VC.ATLMFC –includeRecommended`.
- Pour ARM64, ajouter les composants ARM64. `–add Microsoft.VisualStudio.Component.VC.Tools.ARM64 –add Microsoft.VisualStudio.Component.VC.MFC.ARM64`.
- Définir la variable d’emplacement. `set vs2022_install=C:\Program Files\Microsoft Visual Studio\2022\Professional`.
- Conserver l’inclusion des composants recommandés avec –includeRecommended.
Installation de depot_tools et git
depot_tools alimente l’outillage Chromium, et Git évite les fetch qui s’emmêlent dans les fins de ligne et les permissions fantômes. L’ordre du PATH compte, depot_tools doit passer avant Python, sinon vous récoltez des erreurs aussi cryptiques qu’un grimoire.
- Télécharger depot_tools puis extraire dans C:\src\depot_tools.
- Ajouter C:\src\depot_tools au PATH système avant Python.
- Définir la variable d’environnement. `set DEPOT_TOOLS_WIN_TOOLCHAIN=0`.
- Configurer l’identité Git. `git config –global user.name « Name »`.
- Configurer l’email Git. `git config –global user.email « email@chromium.org« `.
- Appliquer les réglages Git. `git config –global core.autocrlf false` ; `git config –global core.filemode false` ; `git config –global core.preloadindex true` ; `git config –global core.fscache true` ; `git config –global branch.autosetuprebase always`.
Initialisation et configuration du projet
Vous enchaînez récupération des sources, génération des fichiers de build, puis initialisation du runtime côté application. Cette séquence évite les artefacts inconsistants, ceux qui transforment un build en loterie.
- Créer un dossier de travail src.
- Lancer le fetch de chromium via les outils Chromium.
- Générer les fichiers GN. `cd src` puis `gn gen out/Default`.
- Exécuter gclient pour installer msysgit et python.
- Côté ChromiumFX et CEF, initialiser via `CfxRuntime.Initialize(CfxSettings, CfxApp, CfxRenderProcessStartupDelegate)` et passer le callback render process directement.
Les commandes s’exécutent dans l’ordre, sinon la génération sort incomplète.
Compilation du projet ChromiumFX
Le build comporte deux axes, un flux Chromium via autoninja, puis un flux CEF piloté par CMake. Le temps de compilation tire en longueur, surtout lors du premier cycle, donc prévoyez une machine qui respire.
- Compiler Chromium. `autoninja -C out/Default chrome`.
- Anticiper un temps de build long, surtout au premier passage, avec des itérations suivantes plus supportables.
- Utiliser CMake côté CEF pour télécharger les binaries et générer les fichiers de build.
- Lancer la commande Windows 64-bit prévue par le process CEF.
- Retrouver une sortie de type exécutable minimal en debug, et mettre à jour CEF_VERSION dans le top-level CMakeLists.txt via la version issue du Spotify automated builder.
Lancement et test de la première instance
Le test vise deux choses, valider l’exécution et confirmer les versions CEF et Chrome vues par le runtime. Vous réduisez le doute, soit ça démarre, soit vous savez où creuser.
- Lancer le binaire Chromium généré. `out/Default/chrome.exe`.
- Modifier un fichier, par exemple chrome/app/settings_chromium_strings.grdp, puis recompiler pour valider la chaîne de build.
- Démarrer l’exécutable minimal CEF en configuration debug.
- Vérifier les versions via CfxRuntime.VersionInfo(entry) pour confirmer l’alignement CEF et Chrome.
Le critère de succès tient en deux points, un lancement propre et des versions cohérentes.
Configuration avancée et bonnes pratiques
Gestion des versions cef
La logique d’update repose sur une version stable, choisie via le Spotify builder plutôt que sur un zip trouvé au hasard. La modification se fait dans CEF_VERSION, dans le top-level CMakeLists.txt, ce qui centralise la vérité. Vous relancez ensuite cmake pour régénérer les fichiers de build et recaler le pipeline.
Les patches Google s’ajoutent si besoin dans cef/patches. Cette option sert quand une version stable exige un ajustement pour passer un build ou aligner un comportement.
Dépannage des erreurs courantes
| Symptôme / erreur | Cause probable + solution |
|---|---|
| Erreur DLL __CxxFrameHandler4. | Installation Visual Studio incomplète ou corrompue, réinstallez Visual Studio et ses composants C++ requis. |
| Problèmes de slashes dans les chemins. | Environnement de commande inadéquat, lancez les commandes via cmd.exe. |
| Erreurs liées à Python alors que depot_tools est présent. | PATH mal ordonné, placez depot_tools avant Python dans le PATH système. |
| Échec du contrôle API hash au démarrage. | Binaires CEF incompatibles avec ChromiumFX, récupérez une distribution CEF correspondant à l’API attendue. |
| Build ou exécution sous Linux qui échoue. | Support Linux cassé, référez-vous au suivi du projet, notamment l’issue 9. |
Vérifiez d’abord la compatibilité CEF via le hash et l’ordre du PATH, car ces deux points déclenchent la majorité des échecs. Confirmez ensuite l’OS cible, ChromiumFX reste orienté Windows et le support Linux ne tient pas la route.
