issie
Autumn-Spring 2024-2025
Issie (интерактивный схема -симулятор с интегрированным редактором) - это приложение для проектирования и моделирования цифровых цепей. Он предназначен для студентов и любителей, которые хотят понять концепции цифровой электроники простым и забавным способом. Issie разработан, чтобы быть для начинающих, и направлять пользователей к своим целям с помощью четких сообщений об ошибках и визуальных подсказок. Issie разрабатывается и активно используется в преподавании в Имперском колледже Лондона.
Для получения дополнительной технической информации о проекте читайте дальше. Эта документация частично основана на превосходной документации Visual2, учитывая сходство в используемом технологическом стеке.
Для веб -сайта Issie идите сюда.
Приложение в основном записано в F#, которое переносится в JavaScript через компилятор Fable. Затем электрон используется для преобразования разработанного веб-приложения в кроссплатформенное приложение. Electron предоставляет доступ к API на уровне платформы (например, доступ к файловой системе), который не будет доступен для ванильных браузеров.
WebPack 5-это модульный бочонки, ответственный за конкатенацию JavaScript и автоматизированный процесс строительства: сборка электрон-Webpack автоматизирована с использованием ранее существовавших сценариев в каталоге сценариев.
Возможности рисования предоставляются (сейчас) библиотекой пользовательской схемы, реализованной в F# и специализированной для цифровых компонентов.
Выбор F# в качестве основного языка программирования для приложения был продиктован несколькими факторами:
Если вы просто хотите запустить приложение, перейдите на страницу релизов, загрузите и запустите последний предварительно построенный двоичный файл для вашей платформы (Windows или MacOS). Issie потребует в общей сложности около 200 м дискового пространства.
Issie.exe в неразличиваемых файлах. Issie устанавливает и работает без внесения системных изменений - весь его код находится в каталоге, который вы загружаете. Вы можете удалить это и заменить его более поздней версией Issie. Каждый проектный лист хранится в аналогичном файле в рамках каталога проекта. backup подкаталога содержит большое количество резервных снимков для восстановления дизайна. Они не нужны для операции Issie, поэтому вы можете удалить их - или даже весь каталог backup , если хотите.
Issie Binary не будет работать (в некоторых случаях) из сетевого местоположения файла (найдено на многих кластерных машинах). Если у вас есть эта проблема, перейдите в каталог верхнего уровня, содержащий двоичные файлы Essie в командном окне, и введите issie.exe --no-sandbox . Смотрите #125 для деталей.
После того, как вы откроете Issie и будете готовы к работе, не стесняйтесь открывать один из демонстрационных проектов из стартового окна. Они есть, чтобы показать вам, как выглядит полный проект Issie, и позволит вам повеселиться с ним без необходимости проектирования и создания его с нуля. Каждый раз, когда вы открываете демонстрационный проект, он будет сброшен в свое начальное состояние.
Если вы хотите начать как разработчик, выполните эти шаги.
Загрузите и установите (если у вас уже установлены эти инструменты, просто проверьте ограничения версии).
npm , поэтому его не нужно устанавливать отдельно.Загрузите и раскачивайте репо и клонировать его локально, или разделите его на GitHub, а затем клонируйте его локально.
Проверьте, что у вас есть, .net 8.X SDK, Узел V20.X: Если вы хотите сделать больше, чем сделать двоичные файлы, также: VS 2022 (или последняя VS Code + Ionide или Rider).
node -v показывает версию узла. dotnet --version показывает версию Dotnet.Перейдите из корневого каталога Master Branch Repo (который содержит этот Readme), в интерпретаторе командной строки или запустите один из контекстного меню каталога.
Запустите build.cmd под Windows или build.sh под Linux или MacOS ( chmod 755 build.sh даст сценарию разрешение на выполнение). Это загрузит и установит все зависимости, а затем запустит приложение в режиме DEV с HMR.
File -> reload pagenpm run dev . Запустите npm run debug режим отладки (это будет намного медленнее, чем DEV).npm run dist .packet.json и, следовательно, вам нужно переделать файл блокировки paket-lock.json используйте npm install .build killzombies завершит процессы Orphan Node и Dotnet, которые иногда происходят с использованием этой цепочки сборки после необычных завершений (возможно, больше не нужны?)npm run dist в командном окне, чтобы сгенерировать бинарные файлы под .dist Directory. Для MacOS вам нужно будет установить Python 3 для составления нативных двоичных файлов - вы будете автоматически воспринимать это, но тогда потребуется снова запустить npm run dist .NB - параллельно с вышеупомянутой компиляцией, код ISSIE всегда будет компилировать без ошибок (но не работать) под DotNet, например, создавая его из Visual Studio. Компиляция должна быть идентичной, но, если не уверена, почему возникает ошибка, очень полезно создать текущий код под .NET с VS или VSC и легче найти сообщения об ошибках. Аналогичным образом, VS или VSC можно с уверенностью использовать для рефакторного кода, тестирование с компиляцией. Строительство под VS или VSC не может работать, потому что код зависит от работы электронов и узлов для работы.
package-lock.json содержит точные версии пакетов и загружается из репо. Обычно вам не нужно это менять. Стандартная сборка выше будет запущен 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 Корневые разрешения в файлах dev. Для того, чтобы DEV работал гладко, вам нужен каждый файл конфигурации, который будет установлен под вашим собственным именем пользователя, поэтому у вас есть доступ R/W. Это сломается, если вы когда -нибудь используете sudo для корневой установки программного обеспечения, или если вы сделали это некоторое время в прошлом. В этом случае вы можете временно решить проблемы, используя sudo для запуска разработки (или сгенерированного приложения) с привилегиями администратора. Это неправильно. Вместо этого вы должны использовать
chown -R `whoami` dir для каждого каталога, в котором могут быть файлы с плохими разрешениями. Обычно ваш каталог разработчиков . и /usr/local .Удаление и переустановка новейшего Dotnet полезно, если Dotnet был установлен неправильно.
Для пользователей Apple Silicon Mac вы должны использовать версию ARM64 .NET, чтобы получить наилучшие результаты. Вы можете получить его с официального веб -сайта Microsoft, используя их установщик.
Хотя цепочка разработки сложна, теперь она очень гладкая и идентична для всех платформ. Каждый из этих шагов может быть выполнен по мере необходимости:
Dotnet SDK и Node . Dotnet SDK дает вам F#.dotnet tool restore получает вам инструменты Dev: компилятор Fable , автоматизация Fake сборки, диспетчер пакетов paket Dotnet. (Управление пакетами узлов проходит через npm , который поставляется с узлом).dotnet paket install устанавливает все необходимые пакеты на стороне dotnetnpm ci Скачания и аудиты Правильные версии всех пакетов NPM. npm install повредит версии, если они изменились и генерируют обновленный файл блокировки.npm run dev , npm run dist , npm run debug : Сценарии, определенные в package.json , которые управляют разработкой (с HMR) или производственным компиляцией Fable, и упаковки с использованием WebPack 5.build.cmd и build.sh Пытают вышеуказанные шаги, добавляя некоторые не необходимые очистки каталога - вы можете запустить их по отдельности, если у вас есть проблемы.dotnet-tools.json .paket.dependencies на верхнем уровне и paket.references Ссылки в каталоге соответствующего файла .fsproj . В настоящее время пакеты Dotnet не прикрепляются к версиям, поэтому всегда используются последние совместимые версии. Это, вероятно, неправильно, но, кажется, работает хорошо..d . Это работает хорошо, но ручная корректировка необходима для чего -либо сложного. См. Электронный интерфейс API в Issie, который был сгенерирован таким образом из опубликованных файлов Electron API .d - в этом случае ручная регулировка была довольно неприятной, потому что электронный API очень сложный. Электронные пакеты хром (представление) и node.js (двигатель), поэтому, как и в каждом проекте Node.js, файл package.json указывает зависимости модуля (Node).
Кроме того, раздел "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
Это запускает Fable 4, чтобы транспилировать основной процесс, затем ( --run является опцией Fable для запуска другой команды) запускает devrenderer Script, чтобы транспилировать в JavaScript и посмотреть файлы F# в процессе рендеринга. После того, как транспиляция рендеринга будет завершена. Сценарий js будет запущен. Это вызывает webpack , чтобы упаковать и заслужить код JavaScript под Electron, а также наблюдает за изменениями в коде JavaScript, и Hot загружает их в запущенное приложение
В результате этого, в любое время сохранение отредактированного файла проекта F# рендеринга вызывает (почти) немедленное:
Система сборки зависит от Fake файла build.fsx . Фальшивка - это DSL, написанная на F#, специализирующуюся на автоматизации задач сборки. Build.fsx имеет цели, представляющие задачи сборки, и обычно они запускаются через build.cmd или build.sh , вместо того, чтобы использовать dotnet fake напрямую:
build <target> ==> dotnet fake build -t <target> Исходный код состоит из двух отдельных разделов, трансфиль, отдельно в JavaScript, чтобы сделать полное электронное применение.
Таким образом, электрон позволяет запускать код для браузера (HTML + CSS + JavaScript), чтобы запускать в качестве настольного приложения с дополнительной возможностью доступа к файловой системе настольных компьютеров посредством связи между двумя процессами.
Оба процесса запускают JavaScript под узлом.
Источник src/Main/Main.fs настраивает запуск электрона и является шаблоном. Он переносится в каталог Root Project, поэтому он может автоматически подбирать Electron.
Оставшийся код приложения (в)
Код, который превращает источник проекта F# в renderer.js является компилятором Fable, за которым следует бундлер Node Webpack, который объединяет несколько файлов JavaScript в одну renderer.js .
Процесс компиляции контролируется файлами .fsproj (определение F# Source) и webpack.additions.main.js , webpack.additions.renderer.js , которые определяют, как ставит Webpack, объединяет выходы F# для электронных и электронных приложений и того, как устанавливается исполняемый код. Это шаблон, который вам не нужно менять; Обычно файлы проекта F# - это все, что нужно изменить.
В корне build_docs.sh есть сценарий, который будет создавать документацию для проекта с использованием FSDOC. Проект должен быть готовым к компиляции перед созданием документации.
Файлы разметки под /docs превращаются в статические страницы на сайте документации. Любые комментарии XML в коде превращаются в комментарии документации для каждой функции в кодовой базе.
Чтобы добавить обновление, перейдите в папку /docs/updates и создайте новый файл разметки со следующими заголовками:
---
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 при создании комментариев к документации в коде, то есть не использование треугольных кронштейнов <и>, кроме тегов. Пожалуйста, не используйте двойные цитаты!
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/* | Содержит весь код схематического редактора на основе SVG в F# |
Renderer/Simulator/* | Содержит логику для анализа и имитации схематического листа |
Renderer/UI/* | Содержит логику пользовательского интерфейса |
./renderer.fs | Файл верхнего уровня, который управляет кодом рендеринга: содержит цикл MVU Elmish и код меню электронов |
Tests папкуВ настоящее время тесты очень старые и не будут работать. Они основаны на библиотеке тестирования F# ожидания, и, в принципе, можно проверить код ширины и симулятора (который работает под Dotnet).
Static папкаСодержит статические файлы, используемые в приложении.
Docs папкаСодержит информацию источника, которая управляет веб -сайтом документации проекта https://tomcl.github.io/issie/.
Issie позволяет пользователям создавать проекты и файлы в этих проектах. Проект Issie-это просто папка с именем <project-name> , которая содержит пустой файл с именем <project_name>.dprj (DPRJ означает Diagram Project). Папка проекта Любое ненулевое количество файлов проектирования, каждая из которых называется <component_name>.dgm (DGM означает диаграмму). Каждый файл дизайна представляет один проектный лист иерархического оборудования, листы могут содержать, как компоненты, другие листы.
При открытии проекта Issie изначально будет искать заданный репозиторий для файлов .dgm , разрабатывать и загружать их контент и позволит пользователю открывать их в Issie или использовать их в качестве компонентов в других проектах.
Чтобы переустановить среду сборки (без изменения кода проекта) повторно build.cmd (windows) или build.sh (linux и macos).
npm run dist генерирует правильные двоичные файлы для вашей системы под /dist .
