issie
Autumn-Spring 2024-2025
ISSIE (Interaktiver schematischer Simulator mit integriertem Editor) ist eine Anwendung für das Design und die Simulation des digitalen Schaltungskreises. Es richtet sich an Studenten und Hobbyisten, die auf einfache und unterhaltsame Weise ein Verständnis für digitale Elektronikkonzepte erhalten möchten. ISSIE soll anfängerfreundlich sein und die Benutzer über klare Fehlermeldungen und visuelle Hinweise zu ihren Zielen führen. Issie wird entwickelt und aktiv im Unterricht am Imperial College London verwendet.
Weitere technische Informationen zum Projekt finden Sie unter. Diese Dokumentation basiert teilweise auf der exzellenten Visual2 -Dokumentation, da der verwendete Technologiestapel ähnlich ist.
Für die ISSIE -Website finden Sie hier.
Die Anwendung ist hauptsächlich in F#geschrieben, das über den Fabel Compiler in JavaScript umgesetzt wird. Elektron wird dann verwendet, um die entwickelte Web-App in eine plattformübergreifende Anwendung umzuwandeln. Electron bietet Zugriff auf APIs auf Plattformebene (z. B. Zugriff auf das Dateisystem), das den Vanille-Browser-Web-Apps nicht zur Verfügung steht.
Webpack 5 ist der Modul-Bundler, der für die JavaScript-Verkettung und den automatisierten Bauprozess verantwortlich ist: Der Elektronen-Webpack-Build wird mithilfe der bereits bestehenden Skripte im Rahmen des Skriptverzeichnisses automatisiert.
Die Zeichnungsfunktionen werden (jetzt) von einer in F# implementierten benutzerdefinierten schematischen Editorbibliothek bereitgestellt und für digitale Komponenten spezialisiert.
Die Wahl von F# als Hauptprogrammiersprache für die App wurde durch einige Faktoren bestimmt:
Wenn Sie nur die App ausführen möchten, gehen Sie zur Seite zur Veröffentlichung und laden Sie die neueste vorgebaute Binärdatei für Ihre Plattform (Windows oder MacOS) herunter und führen Sie sie aus. Issie benötigt insgesamt etwa 200 m Festplattenraum.
Issie.exe -Anwendung. ISSIE installiert und läuft ohne Systemänderungen - der gesamte Code befindet sich im von Ihnen heruntergeladenen Verzeichnis. Sie können dies löschen und durch eine spätere Version von Isssie ersetzen. Jedes Designblatt wird in einer ähnlich benannten Datei im Projektverzeichnis gespeichert. Die Dort backup der Unterverzeichnis enthält eine große Anzahl von Sicherungs -Snapshots für die Entwurfswiederherstellung. Diese werden für den ISSIE -Betrieb nicht benötigt, sodass Sie sie löschen können - oder sogar das gesamte backup , wenn Sie dies wünschen.
Isssie -Binärdateien werden (in einigen Fällen) nicht aus einem vernetzten Dateiort (gefunden auf vielen Cluster -Maschinen) ausgeführt. Wenn Sie dieses Problem haben, navigieren Sie zum obersten Verzeichnis, das die ISSIE-Binärdateien in einem Befehlsfenster enthält, und geben Sie issie.exe --no-sandbox ein. Weitere Informationen finden Sie unter #125.
Sobald Sie Isssie geöffnet haben und bereit sind, können Sie sich gerne eines der Demo-Projekte aus dem Startfenster öffnen. Diese sind da, um Ihnen zu zeigen, wie ein komplettes ISSIE -Projekt aussieht, und es Ihnen ermöglichen, Spaß damit zu haben, ohne es von Grund auf neu zu entwerfen und aufbauen zu müssen. Jedes Mal, wenn Sie ein Demo -Projekt wieder eröffnen, wird es auf seinen Anfangszustand zurückgesetzt.
Wenn Sie als Entwickler beginnen möchten, befolgen Sie diese Schritte.
Download und installieren (wenn diese Tools bereits installiert sind, überprüfen Sie einfach die Versionsbeschränkungen).
npm -Paket -Manager, daher muss nicht separat installiert werden.Laden Sie das Issie -Repo herunter und entpacken Sie es lokal oder klonen Sie es auf Github und klonen Sie es dann lokal.
Überprüfen Sie, ob Sie, .NET 8.x SDK, Knoten v20.x: Wenn Sie mehr als Binärdateien erstellen möchten, auch: VS 2022 (oder neueste VS -Code + Ionid oder Reiter) installiert.
node -v zeigt die Knotenversion an. dotnet --version zeigt die Dotnet -Version an.Navigieren Sie aus dem Repo Master Branch Root-Verzeichnis (das diese ReadMe enthält) in einem Befehlszeilen-Interpreter oder starten Sie ein Menü des Verzeichniskontextes.
Führen Sie build.cmd unter Windows oder build.sh unter Linux oder macOS aus ( chmod 755 build.sh geben dem Skript die Berechtigung aus). Dadurch wird alle Abhängigkeiten heruntergeladen und installiert und dann die Anwendung im Dev -Modus mit HMR gestartet.
File -> reload pagenpm run dev erneut ein. Führen Sie npm run debug (dies wird viel langsamer als Dev).npm run dist .packet.json geändert haben und daher die Sperrendatei paket-lock.json neu erstellen müssen, verwenden Sie npm install .build killzombies beendet den Orphan -Knoten und Dotnet -Prozesse, die gelegentlich diese Build -Kette nach ungewöhnlichen Kündigungen auftreten (vielleicht nicht mehr benötigt?)npm run dist im Befehlsfenster aus, um Binärdateien unter .dist -Verzeichnis zu generieren. Für macOS müssen Sie Python 3 installieren, um native Binärdateien npm run dist kompilieren.NB - Parallel zur obigen Kompilierung wird Issie Code immer ohne Fehler (aber nicht ausgeführt) unter Dotnet kompilieren, beispielsweise durch Erstellen von Visual Studio. Die Kompilierung sollte identisch sein, aber wenn sich nicht sicher ist, warum es einen Fehler gibt, ist es sehr hilfreich, den aktuellen Code unter .NET mit VS oder VSC zu erstellen und Fehlermeldungen zu ermitteln. In ähnlicher Weise können VS oder VSC mit Vertrauen in den Refactor -Code verwendet werden und mit der Zusammenstellung getestet werden. Aufbau unter VS oder VSC kann nicht funktionieren, da der Code von Elektronen- und Knoten -APIs abhängt.
package-lock.json enthält genaue Paketversionen und wird aus dem Repo heruntergeladen. Normalerweise müssen Sie dies nicht ändern. Der obige Standard Build wird npm ci ausführen, wodurch Pakete überprüft und prüft, aber die Sperrdatei nicht ändert.package.json1 ) addieren müssen, verwenden Sie npm install , um eine Sperrdatei neu zu erstellen, die an das Repo gedrückt werden kann.npm upgrade name oder npm [-D] install name anstelle von package.json hinzugefügt werden.npm ls name verwendet, um herauszufinden, welche der erforderlichen Pakete es verwenden (normalerweise wird das Problem aktualisiert oder ersetzt). Ein sauberer Build funktioniert bei macOS ebenso gut. Es ist jedoch eher schief, wenn Sie zuvor widersprüchliche Pakete installiert haben:
Legacy -Versionen von dotnet - können bei Bedarf wie hier entfernt werden:
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 Root -Berechtigungen in Dev -Dateien. Damit Dev reibungslos arbeitet, müssen Sie jede Konfigurationsdatei unter Ihrem eigenen Benutzernamen installieren, damit Sie R/W -Zugriff haben. Dies wird brechen, wenn Sie jemals sudo verwenden, um Software zu installieren, oder wenn Sie dies einige Zeit in der Vergangenheit getan haben. In diesem Fall können Sie vorübergehend Probleme mit sudo verwenden, um die Entwicklung (oder die generierte App) mit Administratorrechten auszuführen. Das ist das Falsche. Stattdessen sollten Sie verwenden
chown -R `whoami` dir für jedes Verzeichnis, das die Dateien mit schlechten Berechtigungen enthält. Normalerweise Ihr Entwicklerverzeichnis . und /usr/local .Das Deinstallieren und Neuinstallieren der neuesten Dotnet ist hilfreich, wenn Dotnet falsch installiert wurde.
Für Apple Silicon Mac -Benutzer sollten Sie die ARM64 -Version von .NET verwenden, um die besten Ergebnisse zu erzielen. Sie können es von der offiziellen Microsoft -Website mit ihrem Installateur erhalten.
Obwohl die Entwicklerkette komplex ist, ist sie für alle Plattformen sehr glatt und identisch. Jeder dieser Schritte kann nach Bedarf durchgeführt werden:
Dotnet SDK und Node installiert. Dotnet SDK gibt Ihnen F#.dotnet tool restore bietet Ihnen die Dev Tools: Fable Compiler, Fake Build -Automatisierung, paket Dotnet Package Manager. (Die Knotenpaketverwaltung erfolgt über npm , der mit Knoten geliefert wird).dotnet paket install installiert alle benötigten Dotnet-Seite-Paketenpm ci Downloads und Audits korrekte Versionen aller NPM -Pakete. npm install wird die Versionen wiederhergestellt, wenn diese geändert und eine aktualisierte Sperrdatei generiert werden.npm run dev , npm run dist , npm run debug : Skripte in package.json , die Entwicklungsment (mit HMR) oder Produktionskompilierung mit Fabel und Packung mit WebPack 5 steuern.build.cmd und build.sh Skripte verpacken die oben genannten Schritte, die einige nicht erforderliche Verzeichnisreinigung hinzufügen - Sie können sie einzeln ausführen, um Probleme zu haben.dotnet-tools.json ..fsproj ändern Sie paket.dependencies . Abhängigkeiten auf oberster Ebene und paket.references Derzeit sind DOTNE -Pakete nicht an Versionen festgehalten, sodass die neuesten kompatiblen Versionen immer verwendet werden. Das ist wahrscheinlich falsch, scheint aber gut zu funktionieren..d -Dateien generiert. Dies funktioniert gut, aber für alles Komplexe ist eine manuelle Einstellung erforderlich. Sehen Sie sich die Elektronen -API -Schnittstelle in ISSIE an, die auf diese Weise aus einer veröffentlichten Elektronen -API -Dateien erzeugt wurde .d In diesem Fall war die manuelle Anpassung ziemlich unangenehm, da die Elektronen -API sehr komplex ist. Electron Bündel Chromium (Ansicht) und Node.js (Engine), daher wie in jedem Node.js -Projekt, gibt die package.json -Datei die (Knoten) -Modulabhängigkeiten an.
Zusätzlich der Abschnitt "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"
}
Definiert die In-Project-Verknüpfungsbefehle als eine Reihe von <key> : <value , sodass bei der Verwendung npm run <stript_key> es gleichwertig ist, <script_value> aufzurufen. In der Wurzel des Projekts entspricht das Ausführen im terminal npm run dev beispielsweise der Befehlszeile:
dotnet fable watch src/Main -s --run npm run devrenderer
Dadurch wird Fable 4 ausgeführt, um den Hauptprozess zu transportieren. Anschließend wird ( --run eine Option, dass Fable einen anderen Befehl ausführen kann) das Skript devrenderer aus, um in JavaScript zu transpilieren und die F# -Dateien im Renderer -Prozess anzusehen. Nachdem die Renderer -Transpilation beendet ist, wird das Skript ausgeführt. Dies ruft webpack auf, um den JavaScript -Code unter Electron zu packen und zu verletzen und auch Änderungen im JavaScript -Code zu beobachten, und lädt diese in der laufenden Anwendung auf
In diesem Ergebnis führt zu jeder Zeit das Speichern einer bearbeiteten F# Renderer -Projektdatei (nahezu) unmittelbar:
Das Build -System hängt von einer Fake Datei build.fsx ab. Fake ist eine DSL, die in F# geschrieben ist und für die Automatisierung von Build -Aufgaben spezialisiert ist. Build.fsx hat Ziele, die Build -Aufgaben darstellen, und normalerweise werden diese über build.cmd oder build.sh ausgeführt, anstatt dotnet fake direkt zu verwenden:
build <target> ==> dotnet fake build -t <target> Der Quellcode besteht aus zwei unterschiedlichen Abschnitten, die getrennt in JavaScript umgesetzt werden, um eine vollständige Elektronenanwendung zu erstellen.
Mit Electron können Code für einen Browser (HTML + CSS + JavaScript) als Desktop -App mit der zusätzlichen Funktion des Zugriffs des Desktop -Dateisystems über die Kommunikation zwischen den beiden Prozessen als Desktop -App ausgeführt werden.
Beide Prozesse führen JavaScript unter dem Knoten aus.
Das src/Main/Main.fs -Quelle konfiguriert das Elektronenstart und ist ein Kesselplatte. Es wird in das Root -Projektverzeichnis versetzt, damit es automatisch von Electron abgeholt werden kann.
Der verbleibende App -Code (in)
Der Code, der die F# -Projektquelle in renderer.js verwandelt, ist der Fabel -Compiler, gefolgt vom Knoten -Webpack -Bundler, der mehrere JavaScript -Dateien zu einem einzelnen renderer.js kombiniert.
Der Kompiliervorgang wird von den .fsproj -Dateien (Definieren der F# Quelle) und webpack.additions.main.js , webpack.additions.renderer.js gesteuert, die definieren, wie Webpack F# -Angänge sowohl für Elektronen -Haupt- als auch für Elektronen -Approcess und wo der ausführliche Code ausgestattet wird. Dies ist Kesselplatte, die Sie nicht ändern müssen. Normalerweise müssen die F# -Projektdateien alles geändert werden.
Im Root des Repository, build_docs.sh , befindet sich ein Skript, das die Dokumentation für das Projekt mit FSDOCs erstellt. Das Projekt muss vor dem Generieren der Dokumentation kompiliert werden.
Markdown -Dateien unter /docs werden in statische Seiten auf der Dokumentationsseite umgewandelt. Alle XML -Kommentare im Code werden für jede Funktion in der Codebasis in Dokumentationskommentare verwandelt.
Um ein Update hinzuzufügen, wechseln Sie zum Ordner /docs/updates und erstellen Sie eine neue Markdown -Datei mit den folgenden Headern:
---
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 Beispiele finden Sie im Ordner /docs/updates weitere Dokumente.
Alle XML -Kommentare (beginnend mit /// ) unter allen Modul- und Funktionserklärungen werden im Abschnitt API -Referenz der Dokumentationswebsite in Dokumentation verwandelt.
Bitte befolgen Sie die XML -Regeln, wenn Sie Dokumentationskommentare im Code erstellen, dh keine Verwendung von dreieckigen Klammern <und> als für Tags. Bitte verwenden Sie auch keine Doppelzitate!
build_docs.sh ruft auch dotnet fsdocs watch auf, um einen lokalen Server zu starten, der die Dokumentation unter http: // localhost: 8901/hostet. Die generierte Dokumentation für den Code befindet sich im Abschnitt "API -Referenz".
Wenn Sie die Dokumente erstellt haben und erneut auf den Server zugreifen möchten, können Sie dotnet fsdocs watch im Terminal ausführen.
Randnotiz: Ein Skript anstelle des üblichen
dotnet fsdocs buildwird aufgrund eines nicht dokumentierten Fehlers verwendet, bei dem der Compiler einen ungültigen XML -Code für Funktionen mit anonymen Datensätzen erstellt und Attribute mit "<>" in ihren Namen zugewiesen werden. Dies führt dazu, dass die Generation scheitert. Die Verwendung von<exclude/>behebt das Problem nicht, sodass eine Problemumgehung ein Skript aufrufen kann, das vor dem Erstellen der Dokumentation diese ungültigen Attribute aus der XML -Dokumentation entfernen.
Sehen Sie sich ein ähnliches Problem auf GitHub an, das hier einen ähnlichen Fehler wirft.
src| Unterordner oder Datei | Beschreibung |
|---|---|
Main/main.fs | Code für den Haupt -Elektronenprozess, der alles festlegt - normalerweise nicht geändert |
Renderer/Common/* | Bietet einige gemeinsame Typen und Dienstprogramme sowie Schnittstellen zu Bibliotheken -APIs und benutzerdefinierten Bibliotheken |
Renderer/Interface/* | Enthält niedrige Schnittstellenfunktionen und alle Low-Level-Dateiverwaltung |
Renderer/DrawBlock/* | Enthält alle SVG-basierten schematischen Editor-Code in F# |
Renderer/Simulator/* | Enthält die Logik, um ein schematisches Blatt zu analysieren und zu simulieren |
Renderer/UI/* | Enthält die UI -Logik |
./renderer.fs | Die obere Datei auf der Ebene der Renderer-Code: Enthält Elmish MVU-Schleifen- und Elektronen-Menücode |
Tests OrdnerDerzeit sind Tests sehr alt und funktionieren nicht. Sie basieren auf der F# -Gedodeo -Testbibliothek und grundsätzlich können hier die Breite und Simulatorcode (der unter DotNet ausgeführt wird) hier getestet werden.
Static OrdnerEnthält statische Dateien, die in der Anwendung verwendet werden.
Docs -OrdnerEnthält Quellinformationen, die die Website der Projektdokumentation https://tomcl.github.io/issie/ steuern.
Mit Issie können die Benutzer Projekte und Dateien in diesen Projekten erstellen. Ein ISSIE-Projekt ist einfach ein Ordner mit dem Namen <project-name> , der eine leere Datei mit dem Namen <project_name>.dprj enthält (DPRJ steht für Diagram-Projekt). Der Projektordner für jede Anzahl von Entwurfsdateien ungleich Null, die jeweils <component_name>.dgm (DGM für Diagramm). Jede Entwurfsdatei repräsentiert ein Designblatt eines hierarchischen Hardware -Designs. Blätter können als Komponenten und andere Blätter enthalten.
Beim Öffnen eines Projekts sucht ISSIE das angegebene Repository zunächst nach .dgm -Dateien, analysiert und lädt seinen Inhalt an und ermöglicht es dem Benutzer, sie in ISSIE zu öffnen oder als Komponenten in anderen Designs zu verwenden.
Um die Build -Umgebung neu zu installieren (ohne den Projektcode zu ändern), build.cmd (Windows) oder build.sh (Linux und MacOS).
npm run dist erzeugt die richtigen Binärdateien für Ihr System unter /dist .
