issie
Autumn-Spring 2024-2025
ISSIE（具有集成編輯器的交互式示意圖）是用於數字電路設計和仿真的應用程序。它針對的是希望以簡單而有趣的方式掌握數字電子概念的學生和業餘愛好者。 ISSIE旨在通過明確的錯誤消息和視覺線索來引導用戶實現其目標。 Issie是在倫敦帝國學院的教學中開發和積極使用的。
有關該項目的更多技術信息，請繼續閱讀。鑑於所使用的技術堆棧的相似性，該文檔部分基於出色的Visual2文檔。
對於ISSIE網站，請轉到此處。
該應用程序主要用F＃編寫，該應用程序通過寓言編譯器將其轉移到JavaScript。然後，電子用於將開發的Web應用程序轉換為跨平台應用程序。 Electron提供了對平台級API（例如對文件系統的訪問）的訪問權限，而Vanilla瀏覽器Web應用程序將無法使用。
WebPack 5是負責JavaScript串聯和自動化構建過程的模塊Bundler：使用腳本目錄下的預先存在的腳本來自動化Electron-webpack構建。
（現在）由F＃實現並專門用於數字組件的自定義示意圖編輯器庫（現在）提供了繪圖功能。
F＃作為該應用的主要編程語言的選擇已由一些因素決定：
如果您只想運行該應用程序，請訪問發布頁面，然後下載並運行最新的平台預構建二進製文件（Windows或MacOS）。 ISSIE總共需要約200m的磁盤空間。
Issie.exe應用程序。ISSIE安裝和運行而無需進行系統更改 - 其所有代碼都在您下載的目錄內。您可以將其刪除並替換為以後版本的ISSIE。每個設計表都存儲在項目目錄下的類似命名的文件中。子目錄backup包含大量備份快照，用於設計恢復。這些不需要ISSIE操作，因此您可以刪除它們 - 甚至是整個backup目錄，如果需要的話。
ISSIE二進製文件（在某些情況下）不會從網絡文件位置（在許多集群機上找到）運行。如果您有此問題，請導航到命令窗口中包含ISSIE二進製文件的頂級目錄，並鍵入issie.exe --no-sandbox 。有關詳細信息，請參見＃125。
一旦您打開Issie並準備出發，請隨時從啟動窗口打開一個演示項目。這些都可以向您展示一個完整的ISSIE項目的樣子，並使您能夠玩得開心，而無需從頭開始設計和構建它。每次您重新打開演示項目時，都會重置為初始狀態。
如果您想從開發人員開始，請按照以下步驟操作。
下載並安裝（如果您已經安裝了這些工具，只需檢查版本約束）即可。
npm軟件包管理器，因此無需單獨安裝。下載並解開ISSIE倉庫，或在本地克隆，或在Github上分叉，然後在本地克隆。
檢查您有.NET 8.X SDK，Node V20.X：如果您想做的不僅僅是製作二進製文件，還要安裝：vs 2022（或最新的VS Code + Ionide或Rider）。
node -v顯示節點版本。 dotnet --version顯示dotnet版本。從命令行解釋器中的repo主人分支根目錄（包含此讀數）或從目錄上下文菜單中啟動一個。
在Windows或MacOS下的Windows或build.sh下運行build.cmd （ chmod 755 build.sh將授予腳本執行權限）。這將下載並安裝所有依賴項，然後使用HMR以DEV模式啟動應用程序。
File -> reload pagenpm run dev 。運行npm run debug調試模式（這將比DEV慢得多）。npm run dist生成可分佈的二進製文件。packet.json ，因此需要重新製作鎖定文件paket-lock.json使用npm install 。build killzombies將終止孤兒節點和dotnet過程，這些過程偶爾會在異常終止後使用此構建鏈發生（也許不再需要？）npm run dist ，以生成二進製文件.dist目錄。對於MacOS，您需要安裝Python 3來編譯本機二進製文件 - 您將自動進行此操作，但然後需要再次運行npm run dist 。NB-與上述彙編並行，ISSIE代碼將始終在Dotnet下沒有錯誤（但不運行）的情況下進行編譯，例如，通過Visual Studio構建它。彙編應該是相同的，但是當不確定為什麼出現錯誤時，使用VS或VSC下構建.NET下的當前代碼並更易於查找錯誤消息非常有幫助。同樣，VS或VSC可以置信度用於重構代碼，並進行編譯測試。在VS或VSC下建造無法正常工作，因為代碼取決於電子和節點API。
package-lock.json包含精確的軟件包版本，並從存儲庫下載。通常，您無需更改此問題。上面的標準構建將運行npm ci該NPM CI檢查和審核軟件包，但不會更改鎖定文件。package.json1中）使用npm install來重新創建鎖定文件，可以將其推入存儲庫。npm upgrade name或npm [-D] install name而不是編輯package.json 。npm ls name來查找所需的包裝中的哪一個（通常升級或更換它們會刪除問題）。 乾淨的構建在MacOS上同樣可以很好地工作，但是，如果您以前安裝了相互衝突的軟件包，則更有可能出錯：
dotnet的舊版本 - 如果需要的話，可以如下刪除：
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開發文件中的根本權限。為了使開發人員順利進行工作，您需要在自己的用戶名下安裝每個配置文件，因此您可以使用R/W訪問。如果您發現自己使用sudo來紮根安裝軟件，或者過去一段時間以來，這將中斷。在這種情況下，您可以通過使用sudo運行具有管理員特權的開發（或生成的應用程序）來暫時遇到圓形問題。這是錯誤的事情。相反，您應該使用
chown -R `whoami` dir to the可能具有不良權限的文件。通常是您的開發目錄.和/usr/local 。如果dotnet安裝了錯誤，卸載和重新安裝最新的dotnet將很有幫助。
對於Apple Silicon Mac用戶，您應該使用ARM64版本的.NET，以獲得最佳結果。您可以使用其安裝程序從Microsoft官方網站獲得它。
儘管開發鏈很複雜，但對於所有平台來說，它現在非常平穩且相同。可以根據需要執行這些步驟：
Dotnet SDK和Node 。 Dotnet SDK給您F＃。dotnet tool restore為您提供開發工具： Fable編譯器， Fake構建自動化， paket Dotnet軟件包管理器。 （節點軟件包管理是通過npm帶有節點的）。dotnet paket install install instancnpm ci下載和審核所有NPM軟件包的正確版本。如果已更改並生成更新的鎖定文件， npm install將重做版本。npm run dev ， npm run dist ， npm run debug ： package.json中定義的腳本。build.cmd and build.sh腳本包裝上述步驟添加一些不需要的目錄清潔 - 如果有問題，您可以單獨運行它們。dotnet-tools.json 。paket.dependencies在最高級別和paket.references相關.fsproj文件目錄中的參考。當前，dotnet軟件包尚未固定在版本中，因此始終使用最新的兼容版本。這可能是錯誤的，但似乎很好。.d文件生成F＃接口。這效果很好，但是對於任何復雜的東西都需要手動調整。請參閱ISSIE中的電子API接口，該界面是從已發布的Electron API .d文件中生成的 - 在這種情況下，手動調整非常不愉快，因為電子API非常複雜。電子捆綁鉻（視圖）和node.js（發動機），因此，如每個node.js項目中， package.json文件指定（節點）模塊依賴項。
此外， "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"
}
將項目注射快捷方式命令定義為<key> : <value行，以便當我們使用npm run <stript_key>時，它等同於調用<script_value> 。例如，在項目的根部中，在終端npm run dev中運行與命令行相當：
dotnet fable watch src/Main -s --run npm run devrenderer
這將運行寓言4來轉移主過程，然後（ --run是運行另一個命令的寓言的一種選擇）運行腳本devrenderer將其轉移到JavaScript並觀看渲染器過程中的F＃文件。渲染器轉卸啟動完成後。將運行JS腳本。這將調用webpack在電子下打包和Lauch javaScript代碼，並觀看更改JavaScript代碼的更改，並將其加載到運行的應用程序上
因此，在任何時候保存編輯的F＃渲染器項目文件原因（幾乎）立即：
構建系統取決於Fake文件build.fsx 。假是F＃編寫的DSL，專門用於自動化構建任務。 build.fsx具有代表構建任務的目標，通常這些目標是通過build.cmd或build.sh運行的，而不是直接使用dotnet fake ：
build <target> ==> dotnet fake build -t <target> 源代碼由兩個分開移交給JavaScript的兩個不同部分組成，以製定完整的電子應用。
因此，電子允許為瀏覽器（HTML + CSS + JavaScript）編寫代碼作為桌面應用程序運行，並通過兩個進程之間的通信訪問桌面文件系統的附加功能。
這兩個過程都在節點下運行JavaScript。
src/Main/Main.fs源配置電子啟動，是樣板。它被轉移到根項目目錄，因此可以由電子自動拾取。
其餘的應用程序代碼（in）
將F＃項目源變成renderer.js代碼是寓言編譯器，其後是Node WebPack Bundler，將多個JavaScript文件組合到一個renderer.js中。
編譯過程由.fsproj文件（定義f＃source）和webpack.additions.main.js ， webpack.additions.renderer.js控制，該文件定義了WebPack如何組合elether Main和Electron App Process和Electron App進程的F＃輸出f＃輸出。這是您不需要更改的樣板；通常，F＃項目文件需要修改。
存儲庫的根部build_docs.sh根部有一個腳本，該腳本將使用FSDOC構建項目的文檔。在生成文檔之前，該項目必須準備就緒。
在文檔站點上，下屬/docs下的降價文件將變成靜態頁面。代碼中的任何XML註釋都將代碼庫中每個函數的文檔註釋。
要添加更新，請轉到/docs/updates文件夾，並使用以下標頭創建一個新的markdown文件：
---
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有關示例，請參見/docs/updates文件夾中的其他文檔。
在任何模塊和功能聲明下，所有XML註釋（以///開頭）都將文檔網站的API參考部分轉換為文檔。
在代碼中創建文檔註釋時，請遵循XML規則，即除標籤外，沒有使用三角形支架<and>。請不要使用雙引號！
build_docs.sh還調用dotnet fsdocs watch以啟動託管文檔的本地服務器，該服務器在http：// localhost：8901/。代碼生成的文檔在“ API參考”部分下。
如果您已經構建了文檔並想再次訪問服務器，則可以在終端運行dotnet fsdocs watch 。
旁注：腳本而不是通常的
dotnet fsdocs build是由於無證錯誤而使用的，在該錯誤中，編譯器為具有匿名記錄的函數創建無效的XML代碼，並在其名稱中以“ <>”分配屬性。這導致一代失敗。使用<exclude/>無法解決問題，因此解決方法是調用一個腳本，該腳本在構建文檔之前使用Regex從XML文檔中刪除這些無效屬性。
在GitHub上查看類似的問題，此處在此處拋出了類似的錯誤。
src文件夾| 子文件夾或文件 | 描述 |
|---|---|
Main/main.fs | 主要電子過程的代碼，該過程設置了所有內容 - 通常不會更改 |
Renderer/Common/* | 提供了一些常見類型和實用程序，以及庫API和自定義庫的界面 |
Renderer/Interface/* | 包含低級接口函數和所有低級文件管理 |
Renderer/DrawBlock/* | 在F＃中包含所有基於SVG的原理圖編輯器代碼 |
Renderer/Simulator/* | 包含分析和模擬示意圖的邏輯 |
Renderer/UI/* | 包含UI邏輯 |
./renderer.fs | 驅動渲染器代碼的頂級文件：包含Elmish MVU循環和電子菜單代碼 |
Tests文件夾目前的測試很舊，無法正常工作。它們基於F＃期望測試庫，原則上可以在此處測試Widthinferrer和Simulator代碼（在DotNet下運行）。
Static文件夾包含應用程序中使用的靜態文件。
Docs文件夾包含控制項目文檔網站https://tomcl.github.io/issie/的源信息。
ISSIE允許用戶在這些項目中創建項目和文件。 ISSIE項目只是一個名為<project-name>的文件夾，其中包含一個名為<project_name>.dprj的空文件（DPRJ代表圖表項目）。該項目文件夾任何非零數量的設計文件，每個文件都命名為<component_name>.dgm （DGM代表圖表）。每個設計文件代表一個設計表的一個層次硬件設計，可以包含作為組件的其他紙。
打開項目時，ISSIE最初將搜索給定存儲庫中的.dgm文件，解析和加載其內容，並允許用戶在ISSIE中打開它們或將其用作其他設計中的組件。
為了重新安裝構建環境（不更改項目代碼）重新構建build.cmd （Windows）或build.sh （Linux和MacOS）。
npm run dist將為您的系統下/dist生成正確的二進製文件。
