issie
Autumn-Spring 2024-2025
ISSIE (interactif Schematic Simulator avec éditeur intégré) est une application pour la conception et la simulation de circuits numériques. Il est destiné aux étudiants et aux amateurs qui souhaitent maîtriser les concepts de l'électronique numérique d'une manière simple et amusante. Issie est conçue pour être adaptée aux débutants et guider les utilisateurs vers leurs objectifs via des messages d'erreur clairs et des indices visuels. Issie est développée et activement utilisée dans l'enseignement à l'Imperial College de Londres.
Pour plus d'informations techniques sur le projet, lisez la suite. Cette documentation est en partie basée sur l'excellente documentation Visual2, étant donné la similitude de la pile technologique utilisée.
Pour le site Web d'Issie, allez ici.
L'application est principalement écrite en F #, qui est transpirée en JavaScript via le compilateur Fable. L'électron est ensuite utilisé pour convertir l'application Web développée en une application multiplateforme. Electron donne accès aux API au niveau de la plate-forme (telles que l'accès au système de fichiers) qui ne seraient pas disponibles pour les applications Web du navigateur Vanilla.
WebPack 5 est le bundler du module responsable de la concaténation JavaScript et du processus de construction automatisé: la version Electron-WebPack est automatisée à l'aide des scripts préexistants dans le répertoire des scripts.
Les capacités de dessin sont fournies (maintenant) par une bibliothèque d'éditeurs de schéma personnalisée implémentée dans F # et spécialisée pour les composants numériques.
Le choix de F # en tant que langage de programmation principal pour l'application a été dicté par quelques facteurs:
Si vous souhaitez simplement exécuter l'application, accédez à la page des versions et téléchargez et exécutez le dernier binaire préfère pour votre plateforme (Windows ou MacOS). Issie exigera au total environ 200 millions d'espace disque.
Issie.exe de niveau supérieur dans les fichiers décompressés. Issie installe et s'exécute sans apporter de modifications au système - tout son code se trouve dans le répertoire que vous téléchargez. Vous pouvez le supprimer et le remplacer par une version ultérieure d'Issie. Chaque feuille de conception est stockée dans un fichier nommé de la même manière dans le répertoire du projet. La backup du sous-répertoire contient un grand nombre d'instantanés de sauvegarde pour la récupération de conception. Ceux-ci ne sont pas nécessaires pour l'opération ISSIE, vous pouvez donc les supprimer - ou même le répertoire backup entier, si vous le souhaitez.
Les binaires Issie ne s'exécuteront pas (dans certains cas) à partir d'un emplacement de fichier en réseau (trouvé sur de nombreuses machines de cluster). Si ce problème, accédez au répertoire de niveau supérieur contenant les binaires Issie dans une fenêtre de commande et tapez issie.exe --no-sandbox . Voir # 125 pour plus de détails.
Une fois que vous ouvrez Issie et que vous êtes prêt à partir, n'hésitez pas à ouvrir l'un des projets de démonstration de la fenêtre de démarrage. Ceux-ci sont là pour vous montrer à quoi ressemble un projet Issie complet et vous permettre de vous amuser sans avoir à le concevoir et à le construire à partir de zéro. Chaque fois que vous rouvrez un projet de démonstration, il sera réinitialisé à son état initial.
Si vous souhaitez commencer en tant que développeur, suivez ces étapes.
Téléchargez et installez (si vous avez déjà installé ces outils, vérifiez simplement les contraintes de version).
npm , donc cela n'a pas besoin d'être installé séparément.Téléchargez et dézip le repo Issie, ou le clonez-le localement, ou le fourrez-le sur github, puis le clonez-le localement.
Vérifiez que vous avez, .NET 8.x SDK, Node v20.x: Si vous voulez faire plus que faire des binaires, également: vs 2022 (ou dernier VS Code + Ionide, ou Rider) installé.
node -v affiche la version nœud. dotnet --version montre la version Dotnet.Naviguer à partir du répertoire racine de la branche Master Repo (qui contient cette lecture), dans un interprète de ligne de commande, ou démarrez-en un à partir du menu contextuel du répertoire.
Exécutez build.cmd sous Windows ou build.sh sous Linux ou MacOS ( chmod 755 build.sh donnera au script exécuter l'autorisation). Cela téléchargera et installera toutes les dépendances, puis lancera l'application en mode Dev avec HMR.
File -> reload pagenpm run dev . Exécutez npm run debug pour le mode de débogage (cela va être beaucoup plus lent que Dev).npm run dist .packet.json et que vous devez donc refaire le fichier de verrouillage paket-lock.json Utilisez npm install .build killzombies terminera les processus de nœuds orphelins et de dotnet qui se produisent occasionnellement en utilisant cette chaîne de construction après des terminaisons inhabituelles (peut-être plus nécessaires?)npm run dist dans la fenêtre de commande pour générer des binaires sous .dist Directory. Pour MacOS, vous devrez installer Python 3 pour compiler les binaires natifs - vous serez achevé automatiquement pour ce faire, mais vous devrez ensuite exécuter npm run dist .NB - En parallèle avec la compilation ci-dessus, le code ISSIE se compilera toujours sans erreurs (mais pas exécuté) sous Dotnet, par exemple en le construisant à partir de Visual Studio. La compilation doit être identique, mais lorsqu'il ne sait pas pourquoi il y a une erreur, il est très utile de créer le code actuel sous .NET avec VS ou VSC et de devenir plus facile de trouver des messages d'erreur. De même, VS ou VSC peuvent être utilisés avec confiance pour refacter le code, testant avec compilation. La construction sous VS ou VSC ne peut pas fonctionner car le code dépend des API d'électrons et de nœuds pour fonctionner.
package-lock.json contient des versions exactes du package et est téléchargée à partir du dépôt. Normalement, vous n'avez pas besoin de changer cela. La version standard ci-dessus exécutera npm ci qui vérifie et vérifie les packages mais ne modifie pas le fichier de verrouillage.package.json1 ) Utilisez npm install pour recréer un fichier de verrouillage, qui peut être poussé vers le repo.npm upgrade name ou npm [-D] install name au lieu de modifier package.json .npm ls name pour trouver lequel des packages requis l'utilise (généralement la mise à niveau ou les remplacer de supprimer le problème). Une construction propre fonctionnera aussi bien sur MacOS, mais les choses sont plus susceptibles de se tromper si vous avez précédemment installé des packages contradictoires:
Les versions héritées de dotnet - peuvent être supprimées si nécessaire comme ici:
curl -O https://raw.githubusercontent.com/dotnet/sdk/main/scripts/obtain/uninstall/dotnet-uninstall-pkgs.sh
chmod u+x dotnet-uninstall-pkgs.sh
sudo ./dotnet-uninstall-pkgs.sh Autorisations racinaires dans les fichiers Dev. Pour que Dev fonctionne en douceur, vous avez besoin de chaque fichier de configuration à installer sous votre propre nom d'utilisateur, vous avez donc un accès R / W. Cela se cassera si vous vous retrouvez à utiliser sudo pour rooter le logiciel d'installation, ou si vous l'avez fait quelque temps dans le passé. Dans ce cas, vous pouvez temporairement obtenir des problèmes ronds en utilisant sudo pour exécuter le développement (ou l'application générée) avec les privilèges d'administration. C'est la bonne chose à faire. Au lieu de cela, vous devriez utiliser
chown -R `whoami` dir pour chaque répertoire qui pourrait avoir les fichiers avec de mauvaises autorisations. Généralement, votre répertoire de développement . et /usr/local .La désinstallation et la réinstallation du dernier DOTNET sont utiles si DOTNET a été mal installé.
Pour les utilisateurs d'Apple Silicon Mac, vous devez utiliser la version ARM64 de .NET afin d'obtenir les meilleurs résultats. Vous pouvez l'obtenir sur le site officiel de Microsoft, en utilisant leur installateur.
Bien que la chaîne de développement soit complexe, elle est désormais très fluide et identique pour toutes les plates-formes. Chacune de ces étapes peut être effectuée au besoin:
Node Dotnet SDK . Dotnet SDK vous donne F #.dotnet tool restore vous propose le compilateur Dev Tools: Fable , Fake Build Automation, paket Dotnet Package Manager. (La gestion des packages de nœuds est via npm qui est livré avec le nœud).dotnet paket install installe tous les packages côté dotnet nécessairenpm ci sont les versions correctes de tous les packages NPM. npm install réduira les versions si elles ont changé et génèrent un fichier de verrouillage mis à jour.npm run dev , npm run dist , npm run debug : Scripts défini dans package.json qui contrôlent le développement (avec HMR) ou la compilation de production avec Fable, et l'emballage à l'aide de WebPack 5.build.cmd et build.sh emballent les étapes ci-dessus en ajoutant certains de nettoyage du répertoire généralement nécessaire - vous pouvez les exécuter individuellement dans l'ordre si vous avez des problèmes.dotnet-tools.json .paket.dependencies au niveau supérieur et paket.references dans le répertoire du fichier .fsproj pertinent. Actuellement, les packages DOTNET ne sont pas épinglés aux versions, donc les dernières versions compatibles sont toujours utilisées. C'est probablement faux mais semble bien fonctionner..d TypeScript. Cela fonctionne bien, mais un ajustement manuel est nécessaire pour quelque chose de complexe. Voir l'interface API Electron dans ISSIE qui a été générée de cette manière à partir d'un fichier API .d électronique publié - dans ce cas, le réglage manuel était assez désagréable car l'API électronique est très complexe. Electron Bundles Chromium (View) et Node.js (moteur), donc comme dans chaque projet Node.js, le fichier package.json spécifie les dépendances du module (nœud).
De plus, la section "scripts" :
"scripts": {
"clean-dev-mac": "sudo killall -9 node && sudo killall -9 dotnet && sudo killall -9 issie",
"clean-dev-win": "taskkill /f /im node.exe && taskkill /f /im dotnet.exe && taskkill /f /im issie.exe",
"compile": "dotnet fable src/Main -s && dotnet fable src/Renderer -s --define PRODUCTION",
"debug": "dotnet fable watch src/Main -s --run npm run debugrenderer",
"debugrenderer": "dotnet fable watch src/Renderer -s --define ASSERTS --run npm run start",
"dev": "dotnet fable watch src/Main -s --run npm run devrenderer",
"devrenderer": "dotnet fable watch src/Renderer -s --run npm run start",
"start": "cross-env NODE_ENV=development node scripts/start.js",
"build": "cross-env NODE_ENV=production node scripts/build.js",
"pack": "npm run compile && npm run build && electron-builder --dir",
"dist": "npm run compile && npm run build && electron-builder",
"buildonly": "electron-builder",
"compile-sass": "cd src/renderer/scss && node-sass main.scss main.css",
"testcompiler": "cd src/Renderer/VerilogComponent/test && dotnet fable --noCache && node testParser.fs.js"
}
Définit les commandes de raccourci dans le projet comme un ensemble de <key> : <value , de sorte que lorsque nous utilisons npm run <stript_key> il équivaut à appeler <script_value> . Par exemple, dans la racine du projet, l'exécution dans le terminal npm run dev est équivalent à la ligne de commande:
dotnet fable watch src/Main -s --run npm run devrenderer
Cela exécute Fable 4 pour transpiler le processus principal, puis ( --run est une option de fable pour exécuter une autre commande) exécute le script devrenderer pour transpiler en JavaScript et regarder les fichiers F # dans le processus de rendu. Une fois la transpilation du rendu, le script est terminé. Le script sera exécuté. Cela appelle webpack pour emballer et lauch le code JavaScript, sous Electron, et regarde également les modifications du code JavaScript, et Hot charge -les sur l'application en cours d'exécution
À cause de cela, à tout moment, enregistrant un fichier de projet F # édité provoque (presque) immédiat:
Le système de construction dépend d'une Fake build.fsx . Fake est un DSL écrit en F # qui est spécialisé pour automatiser les tâches de construction. Build.fsx a des cibles représentant des tâches de construction, et normalement celles-ci sont exécutées via build.cmd ou build.sh , au lieu d'utiliser directement dotnet fake :
build <target> ==> dotnet fake build -t <target> Le code source se compose de deux sections distinctes transpirées séparément en JavaScript pour créer une application électronique complète.
Electron permet donc au code écrit pour qu'un navigateur (HTML + CSS + JavaScript) soit exécuté en tant qu'application de bureau avec la capacité supplémentaire de l'accès au système de fichiers de bureau via la communication entre les deux processus.
Les deux processus exécutent JavaScript sous nœud.
La source src/Main/Main.fs configure le démarrage Electron et est chaudière. Il est transpiré dans le répertoire du projet racine afin qu'il puisse être automatiquement ramassé par Electron.
Le code d'application restant (in)
Le code qui transforme la source du projet F # en renderer.js est le compilateur fable suivi du bundler webpack nœud qui combine plusieurs fichiers JavaScript dans un seul renderer.js .
Le processus de compilation est contrôlé par les fichiers .fsproj (définissant la source f #) et webpack.additions.main.js , webpack.additions.renderer.js qui définissent comment WebPack combine les sorties F # pour les processus d'application électron principale et électronique et lorsque le code exécutable est mis. Il s'agit de la buissier debout que vous n'avez pas besoin de modifier; Normalement, les fichiers du projet F # sont tout ce qui doit être modifié.
Il y a un script à la racine du référentiel, build_docs.sh , qui construira la documentation du projet à l'aide de FSDOC. Le projet doit être prêt pour la compilation avant de générer la documentation.
Les fichiers de marque sous /docs sont transformés en pages statiques sur le site de documentation. Tous les commentaires XML dans le code sont transformés en commentaires de documentation pour chaque fonction de la base de code.
Pour ajouter une mise à jour, accédez au dossier /docs/updates et créez un nouveau fichier Markdown avec les en-têtes suivants:
---
layout : post
title : [title here]
date : [ ISO 8601 UTC datetime, etc 2021-07-04 15:52:01 +0100]
category : Updates
index : [index that decides the order of the update. later updates have greater indexes]
---
# your markdown content below Voir d'autres documents dans le dossier /docs/updates pour des exemples.
Tous les commentaires XML (à commencer par /// ) dans n'importe quel module et déclarations de fonction sont transformés en documentation dans la section de référence de l'API du site Web de documentation.
Veuillez suivre les règles XML lors de la création de commentaires de documentation dans le code, c'est-à-dire aucune utilisation des supports triangulaires <et> autres que pour les balises. Veuillez également n'utiliser pas de citations doubles!
build_docs.sh appelle également dotnet fsdocs watch pour démarrer un serveur local hébergeant la documentation sur http: // localhost: 8901 /. La documentation générée pour le code se situe dans la section "référence de l'API".
Si vous avez construit les documents et souhaitez accéder à nouveau au serveur, vous pouvez exécuter dotnet fsdocs watch dans le terminal.
Remarque latérale: Un script, plutôt que la
dotnet fsdocs buildest utilisé en raison d'un bug sans papiers où le compilateur crée du code XML non valide pour les fonctions avec des enregistrements anonymes, attribuant des attributs avec "<>" dans leurs noms. Cela fait échouer la génération. L'utilisation de<exclude/>ne résout pas le problème, donc une solution de contournement consiste à appeler un script qui utilise Regex pour supprimer ces attributs non valides de la documentation XML avant de construire la documentation.
Voir un problème similaire sur GitHub qui lance une erreur similaire ici.
src| Sous-dossier ou fichier | Description |
|---|---|
Main/main.fs | Code du processus électronique principal qui définit tout - pas normalement modifié |
Renderer/Common/* | Fournit certains types et services publics communs, ainsi que des interfaces aux bibliothèques API et bibliothèques personnalisées |
Renderer/Interface/* | Contient des fonctions d'interface de bas niveau et toute la gestion des fichiers de bas niveau |
Renderer/DrawBlock/* | Contient tout le code d'éditeur schématique basé sur SVG dans F # |
Renderer/Simulator/* | Contient la logique pour analyser et simuler une feuille schématique |
Renderer/UI/* | Contient la logique d'interface utilisateur |
./renderer.fs | Fichier de niveau supérieur qui pilote le code de rendu: contient une boucle Elmish MVU et un code de menu d'électrons |
Tests FolderLes tests sont actuellement très anciens et ne fonctionneront pas. Ils sont basés sur la bibliothèque de tests F # Expectro et en principe, le code WidthinFerrer et le Simulator (qui s'exécute sous DotNet) pourrait être testé ici.
StaticContient des fichiers statiques utilisés dans l'application.
DocsContient des informations source qui contrôle le site Web de la documentation du projet https://tomcl.github.io/issie/.
Issie permet aux utilisateurs de créer des projets et des fichiers dans ces projets. Un projet ISSIE est simplement un dossier nommé <project-name> qui contient un fichier vide nommé <project_name>.dprj (DPRJ signifie Diagram Project). Le dossier du projet tout nombre non nul de fichiers de conception, chacun nommé <component_name>.dgm (DGM signifie Diagramme). Chaque fichier de conception représente une feuille de conception d'une conception matérielle hiérarchique, les feuilles peuvent contenir, comme composants, d'autres feuilles.
Lors de l'ouverture d'un projet, Issie recherchera initialement le référentiel donné pour les fichiers .dgm , analyse et chargera son contenu, et permettra à l'utilisateur de les ouvrir dans Issie ou de les utiliser comme composants dans d'autres conceptions.
Pour réinstaller l'environnement de construction (sans modifier le code de projet) Rerun build.cmd (Windows) ou build.sh (Linux et macOS).
npm run dist générera les binaires corrects pour votre système sous /dist .
