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生成正确的二进制文件。
