issie
Autumn-Spring 2024-2025
Issie (simulador esquemático interactivo con editor integrado) es una aplicación para el diseño y simulación del circuito digital. Está dirigido a estudiantes y aficionados que desean comprender los conceptos de electrónica digital de una manera simple y divertida. Issie está diseñada para ser amigable para principiantes y guiar a los usuarios hacia sus objetivos a través de mensajes de error claros y pistas visuales. Issie se desarrolla y se usa activamente en la enseñanza en el Imperial College London.
Para obtener más información técnica sobre el proyecto, siga leyendo. Esta documentación se basa en parte en la excelente documentación de Visual2, dada la similitud en la pila de tecnología utilizada.
Para el sitio web de Issie, vaya aquí.
La aplicación se escribe principalmente en F#, que se transpila a JavaScript a través del compilador Fable. El electrón se usa para convertir la aplicación web desarrollada en una aplicación multiplataforma. Electron proporciona acceso a API a nivel de plataforma (como el acceso al sistema de archivos) que no estarían disponibles para las aplicaciones web del navegador de vainilla.
Webpack 5 es el Bundler del módulo responsable de la concatenación de JavaScript y el proceso de construcción automatizado: la compilación Electron-Webpack se automatiza utilizando los scripts preexistentes en el directorio de scripts.
Las capacidades de dibujo son proporcionadas (ahora) por una biblioteca de editor esquemático personalizado implementada en F# y especializadas para componentes digitales.
La elección de F# como lenguaje de programación principal para la aplicación ha sido dictada por algunos factores:
Si solo desea ejecutar la aplicación, vaya a la página de versiones y descargue y ejecute el último binario prebuilt para su plataforma (Windows o macOS). Issie requerirá en total aproximadamente 200 metros de espacio en disco.
Issie.exe de nivel superior en los archivos descomprimidos. Issie instala y se ejecuta sin hacer cambios en el sistema: todo su código está dentro del directorio que descarga. Puede eliminar esto y reemplazarlo mediante una versión posterior de Issie. Cada hoja de diseño se almacena en un archivo con nombre similar en el directorio del proyecto. La backup del subdirectorio allí contiene una gran cantidad de instantáneas de copia de seguridad para la recuperación del diseño. Estos no son necesarios para la operación ISSIE para que pueda eliminarlos, o incluso todo el directorio backup , si lo desea.
Los binarios de ISSIE no se ejecutarán (en algunos casos) desde una ubicación de archivo en red (que se encuentra en muchas máquinas de clúster). Si tiene este problema, navegue al directorio de nivel superior que contiene los binarios ISSIE en una ventana de comando y escriba issie.exe --no-sandbox . Ver #125 para más detalles.
Una vez que abra Issie y esté listo para comenzar, no dude en abrir uno de los proyectos de demostración desde la ventana de inicio. Estos están ahí para mostrarle cómo se ve un proyecto ISSIE completo y le permite divertirse con él sin tener que diseñarlo y construirlo desde cero. Cada vez que vuelva a abrir un proyecto de demostración, se restablecerá a su estado inicial.
Si desea comenzar como desarrollador, siga estos pasos.
Descargue e instale (si ya tiene estas herramientas instaladas, simplemente verifique las restricciones de la versión).
npm , por lo que esto no es necesario instalar por separado.Descargue y descomprima el repositorio de ISSIE, o clona localmente, o lo burbujee en Github y luego clono localmente.
Verifique que tenga, .NET 8.x SDK, nodo V20.x: si desea hacer más que hacer binarios, también: VS 2022 (o último VS Code + Ionide, o piloto) instalado.
node -v muestra la versión del nodo. dotnet --version muestra la versión de Dotnet.Navegue desde el Directorio Repo Master Branch Root (que contiene este ReadMe), en un intérprete de línea de comandos, o inicie uno desde el menú contextual del directorio.
Ejecute build.cmd en Windows o build.sh en Linux o macOS ( chmod 755 build.sh dará el permiso de ejecución del script). Esto descargará e instalará todas las dependencias y luego inicia la aplicación en modo Dev con HMR.
File -> reload pagenpm run dev . Ejecutar npm run debug para el modo de depuración (esto será mucho más lento que Dev).npm run dist .packet.json y, por lo tanto, debe rehacer el archivo de bloqueo paket-lock.json use npm install .build killzombies terminará los procesos de nodo huérfano y Dotnet que ocasionalmente ocurren usando esta cadena de compilación después de terminaciones inusuales (¿tal vez ya no es necesario?)npm run dist en la ventana de comando para generar binarios en el directorio .dist . Para MacOS, deberá instalar Python 3 para compilar binarios nativos: se le promplirá automáticamente para hacer esto, pero luego deberá ejecutar npm run dist nuevamente.NB: en paralelo con la compilación anterior, el código ISSIE siempre se compilará sin errores (pero no ejecutados) en Dotnet, por ejemplo, construyéndolo desde Visual Studio. La compilación debe ser idéntica, pero cuando no está seguro de por qué hay un error, es muy útil construir el código actual en .NET con VS o VSC y obtener mensajes de error más fáciles de encontrar. Del mismo modo, VS o VSC se puede usar con confianza para refactorizar el código, probando con la compilación. La construcción de VS o VSC no puede funcionar porque el código depende de las API de electrones y nodos para funcionar.
package-lock.json contiene versiones de paquete exactas y se descarga del repositorio. Normalmente no necesitas cambiar esto. La compilación estándar anterior ejecutará npm ci que verifica y audita los paquetes, pero no cambia el archivo de bloqueo.package.json1 ), use npm install para recrear un archivo de bloqueo, que se puede empujar al repositorio.npm upgrade name o npm [-D] install name en lugar de editar package.json .npm ls name para encontrar cuál de los paquetes requeridos lo usa (generalmente actualizarlos o reemplazarlos eliminará el problema). Una construcción limpia funcionará igualmente bien en macOS, sin embargo, es más probable que las cosas salgan mal si ha instalado paquetes en conflicto previamente:
Versiones heredadas de dotnet : se puede eliminar si es necesario aquí:
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 Permisos raíz en archivos de desarrollo. Para que Dev funcione sin problemas, necesita que se instale cada archivo de configuración bajo su propio nombre de usuario, por lo que tiene acceso R/W. Esto se romperá si alguna vez se encuentra utilizando el software de instalación de sudo to root, o si lo ha hecho algún tiempo en el pasado. En ese caso, puede obtener problemas temporales mediante el uso de sudo para ejecutar el desarrollo (o la aplicación generada) con privilegios de administración. Esto es lo incorrecto. En su lugar deberías usar
chown -R `whoami` dir para cada directorio que podría tener los archivos con malos permisos. Por lo general, su directorio dev . y /usr/local .Desinstalar y reinstalar el último Dotnet es útil si Dotnet se ha instalado mal.
Para los usuarios de Apple Silicon Mac, debe usar la versión ARM64 de .NET para obtener los mejores resultados. Puede obtenerlo del sitio web oficial de Microsoft, utilizando su instalador.
Aunque la cadena de desarrollo es compleja, ahora es muy suave e idéntica para todas las plataformas. Cada uno de estos pasos se puede realizar según sea necesario:
Dotnet SDK y Node . Dotnet SDK te da f#.dotnet tool restore le brinda las herramientas de desarrollo: compilador Fable , automatización de compilación Fake , administrador de paquetes de Dotnet paket . (La administración de paquetes de nodo es a través de npm que viene con nodo).dotnet paket install instala todos los paquetes del lado de Dotnet necesariosnpm ci Versiones correctas de todos los paquetes NPM. npm install rehacerá las versiones si estas han cambiado y generar un archivo de bloqueo actualizado.npm run dev , npm run dist , npm run debug : Scripts definidos en package.json que controlan el desarrollo (con HMR) o la compilación de producción con Fable, y el embalaje usando Webpack 5.build.cmd y build.sh los pasos anteriores agregando algunos no necesarios para la limpieza del directorio: puede ejecutarlos individualmente para que tenga problemas.dotnet-tools.json .paket.dependencies en el nivel superior y paket.references en el directorio del archivo .fsproj relevante. Actualmente, los paquetes de Dotnet no están fijados en versiones, por lo que siempre se utilizan las últimas versiones compatibles. Probablemente esto esté mal, pero parece funcionar bien..d . Esto funciona bien, pero el ajuste manual es necesario para cualquier cosa compleja. Vea la interfaz de la API de electrones en ISSIE que se generó de esta manera a partir de una API de Electron publicada .d Archivos: en ese caso, el ajuste manual fue bastante desagradable porque la API de electrones es muy compleja. Electron Bundles Chromium (View) y Node.js (motor), por lo tanto, como en cada proyecto nodo.js, el archivo package.json especifica las dependencias del módulo (nodo).
Además, la sección "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"
}
Define los comandos de acceso directo en el proyecto como un conjunto de líneas de <key> : <value , de modo que cuando usamos npm run <stript_key> es equivalente a llamar <script_value> . Por ejemplo, en la raíz del proyecto, ejecutar en el npm run dev terminal es equivalente a la línea de comando:
dotnet fable watch src/Main -s --run npm run devrenderer
Esto se ejecuta Fable 4 para transmisar el proceso principal, entonces ( --run es una opción de Fable para ejecutar otro comando) ejecuta Script devrenderer para transpicar a JavaScript y ver los archivos F# en el proceso de renderizador. Después de que la transpilación del renderizador esté terminada, el script JS se ejecutará. Esto invoca webpack para empacar y lauch el código JavaScript, en Electron, y también observa los cambios en el código JavaScript, y Hot los carga en la aplicación en ejecución
Como resultado de esto, en cualquier momento guardando un archivo de proyecto F# editado por las causas (casi) inmediatas:
El sistema de compilación depende de un archivo Fake build.fsx . Fake es un DSL escrito en f# que está especializado para automatizar tareas de compilación. Build.fsx tiene objetivos que representan tareas de compilación, y normalmente estos se ejecutan a través de build.cmd o build.sh , en lugar de usar dotnet fake directamente:
build <target> ==> dotnet fake build -t <target> El código fuente consta de dos secciones distintas transpiladas por separado a JavaScript para hacer una aplicación de electrones completa.
El electrón permite el código escrito para un navegador (HTML + CSS + JavaScript) se ejecuta como una aplicación de escritorio con la capacidad adicional del acceso al sistema de archivos de escritorio a través de la comunicación entre los dos procesos.
Ambos procesos ejecutan JavaScript bajo nodo.
La fuente src/Main/Main.fs configura el arranque de electrones y es Boilerplate. Se transpila al directorio del proyecto raíz para que Electron pueda recoger automáticamente.
El código de la aplicación restante (IN)
El código que convierte la fuente del proyecto F# en renderer.js es el compilador de fábulas seguido del Bundler de Node Webpack que combina múltiples archivos JavaScript en un solo renderer.js .
El proceso de compilación está controlado por los archivos .fsproj (definiendo la fuente F#) y webpack.additions.main.js , webpack.additions.renderer.js que definen cómo Webpack combina las salidas F# tanto para los procesos de electrones principales como de electrones y dónde se coloca el código ejecutable. Esta es la placa que no necesita cambiar; Normalmente, los archivos del proyecto F# son todo lo que debe modificarse.
Hay un script en la raíz del repositorio, build_docs.sh , que creará la documentación para el proyecto utilizando FSDOCS. El proyecto debe estar listo para compilar antes de generar la documentación.
Los archivos de Markdown debajo /docs se convierten en páginas estáticas en el sitio de documentación. Cualquier comentario XML en el código se convierte en comentarios de documentación para cada función en la base de código.
Para agregar una actualización, vaya a la carpeta /docs/updates y cree un nuevo archivo de markdown con los siguientes encabezados:
---
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 Consulte otros documentos en la carpeta /docs/updates para ver ejemplos.
Todos los comentarios de XML (comenzando con /// ) en cualquier módulo y declaraciones de función se convierten en documentación en la sección de referencia API del sitio web de documentación.
Siga las reglas XML al crear comentarios de documentación en el código, es decir, no hay uso de soportes triangulares <y> que no sean para etiquetas. ¡Por favor, no use citas dobles también!
build_docs.sh también llama a dotnet fsdocs watch para iniciar un servidor local que aloja la documentación en http: // localhost: 8901/. La documentación generada para el código está en la sección "Referencia de API".
Si ha construido los documentos y desea acceder nuevamente al servidor, puede ejecutar dotnet fsdocs watch en el terminal.
Nota al margen: un script, en lugar de la
dotnet fsdocs buildse usa debido a un error indocumentado donde el compilador crea un código XML inválido para funciones con registros anónimos, asignando atributos con "<>" en sus nombres. Esto hace que la generación falle. Usar<exclude/>no soluciona el problema, por lo que una solución es llamar a un script que usa RegEx para eliminar estos atributos no válidos de la documentación XML antes de construir la documentación.
Vea un problema similar en GitHub que arroja un error similar aquí.
src| Subcarpeta o archivo | Descripción |
|---|---|
Main/main.fs | Código para el proceso principal de electrones que configura todo, normalmente no cambia |
Renderer/Common/* | Proporciona algunos tipos y servicios comunes, así como interfaces para las API de bibliotecas y las bibliotecas personalizadas. |
Renderer/Interface/* | Contiene funciones de interfaz de bajo nivel y toda la administración de archivos de bajo nivel |
Renderer/DrawBlock/* | Contiene todo el código del editor esquemático basado en SVG en F# |
Renderer/Simulator/* | Contiene la lógica para analizar y simular una hoja esquemática |
Renderer/UI/* | Contiene la lógica de la interfaz de usuario |
./renderer.fs | Archivo de nivel superior que impulsa el código del renderizador: Contiene el código de menú Elmish MVU y Electron Loop y Electron |
TestsActualmente, las pruebas son muy antiguas y no funcionarán. Se basan en la biblioteca de pruebas de F# y, en principio, el código Widthinferrer y el simulador (que se ejecuta en Dotnet) podría probarse aquí.
StaticContiene archivos estáticos utilizados en la aplicación.
DocsContiene información fuente que controla el sitio web de documentación del proyecto https://tomcl.github.io/issie/.
ISSIE permite a los usuarios crear proyectos y archivos dentro de esos proyectos. Un proyecto ISSIE es simplemente una carpeta llamada <project-name> que contiene un archivo vacío llamado <project_name>.dprj (DPRJ representa el proyecto Diagram). La carpeta del proyecto cualquier número de archivos de diseño distinto de cero, cada uno llamado <component_name>.dgm (DGM significa diagrama). Cada archivo de diseño representa una hoja de diseño de un diseño de hardware jerárquico, las hojas pueden contener, como componentes, otras hojas.
Al abrir un proyecto, ISSIE buscará inicialmente el repositorio dado los archivos .dgm , analiza y cargará su contenido, y permitirá que el usuario los abra en ISSIE o los use como componentes en otros diseños.
Para reinstalar el entorno de compilación (sin cambiar el código de proyecto) Rerun build.cmd (Windows) o build.sh (Linux y MacOS).
npm run dist generará los binarios correctos para su sistema bajo /dist .
