issie
Autumn-Spring 2024-2025
ISSIE (محاكاة تخطيطي تفاعلية مع محرر متكامل) هو تطبيق لتصميم الدائرة الرقمية ومحاكاة. يستهدف الطلاب والهواة الذين يرغبون في فهم مفاهيم الإلكترونيات الرقمية بطريقة بسيطة وممتعة. تم تصميم ISSI لتكون صديقة للمبتدئين وتوجيه المستخدمين نحو أهدافهم من خلال رسائل الخطأ الواضحة والقرائن المرئية. تم تطوير ISSIE واستخدامه بنشاط في التدريس في College College London.
لمزيد من المعلومات الفنية حول المشروع ، اقرأ. تعتمد هذه الوثائق جزئيًا على وثائق Visual2 الممتازة ، بالنظر إلى التشابه في مكدس التكنولوجيا المستخدمة.
لموقع ISSIE ، اذهب إلى هنا.
يتم كتابة التطبيق في الغالب في F#، والذي يتم نقله إلى JavaScript عبر برنامج التحويل البرمجي. ثم يتم استخدام الإلكترون لتحويل تطبيق الويب المتقدم إلى تطبيق منصة. يوفر Electron الوصول إلى واجهات برمجة التطبيقات على مستوى النظام الأساسي (مثل الوصول إلى نظام الملفات) والذي لن يكون متاحًا لتناول ويب متصفح الفانيليا.
WebPack 5 هو Bundler Module Bundler المسؤول عن تسلسل JavaScript وعملية البناء الآلية: يتم تلقائي بنية الإلكترون webpack باستخدام البرامج النصية الموجودة مسبقًا ضمن دليل البرامج النصية.
يتم توفير قدرات الرسم (الآن) بواسطة مكتبة محرر تخطيطي مخصص تم تنفيذها في F# ومتخصصة للمكونات الرقمية.
تم إملاء اختيار F# كلغة برمجة رئيسية للتطبيق بعوامل قليلة:
إذا كنت ترغب فقط في تشغيل التطبيق ، فانتقل إلى صفحة الإصدارات وقم بتنزيل وتشغيل أحدث ثنائي من أجل النظام الأساسي (Windows أو MacOS). سوف تتطلب ISSIE ما مجموعه حوالي 200 متر من مساحة القرص.
Issie.exe على المستوى الأعلى في الملفات غير المدمجة. يقوم Issie بتثبيت وتشغيل دون إجراء تغييرات في النظام - كل رمزه موجود داخل الدليل الذي تقوم بتنزيله. يمكنك حذف هذا واستبداله بإصدار لاحق من Issie. يتم تخزين كل ورقة تصميم في ملف مسمى بالمثل ضمن دليل المشروع. يحتوي backup للدليل الفرعي على عدد كبير من لقطات النسخ الاحتياطي لاستعادة التصميم. هذه ليست ضرورية لتشغيل ISSIE حتى تتمكن من حذفها - أو حتى دليل backup بأكمله ، إذا كنت ترغب في ذلك.
لن يتم تشغيل ثنائيات ISSIE (في بعض الحالات) من موقع ملف متصل بالشبكة (الموجود في العديد من آلات الكتلة). إذا كان لديك هذه المشكلة ، انتقل إلى الدليل الأعلى الذي يحتوي على ثنائيات ISSIE في نافذة الأوامر واكتب issie.exe --no-sandbox . انظر #125 للحصول على التفاصيل.
بمجرد فتح Issie وتكون جاهزًا للذهاب ، لا تتردد في فتح أحد المشاريع التجريبية من نافذة بدء التشغيل. هذه موجودة لتظهر لك الشكل الذي يبدو عليه مشروع ISSIE الكامل ويمكنك من الاستمتاع به دون الحاجة إلى تصميمه وبناءه من نقطة الصفر. في كل مرة تقوم فيها بإعادة فتح مشروع تجريبي ، سيتم إعادة تعيينه إلى حالته الأولية.
إذا كنت ترغب في البدء كمطور ، اتبع هذه الخطوات.
قم بتنزيل وتثبيت (إذا كان لديك بالفعل هذه الأدوات المثبتة ، فقط تحقق من قيود الإصدار).
npm ، لذلك لا يلزم تثبيته بشكل منفصل.قم بتنزيل وإلغاء ضغط ISSIE REPO ، أو استنساخه محليًا ، أو شوكة على Github ثم استنساخه محليًا.
تحقق من أن لديك ، .NET 8.x SDK ، Node V20.x: إذا كنت ترغب في القيام بأكثر من صنع الثنائيات ، أيضًا: VS 2022 (أو أحدث كود + أيوند ، أو راكب) مثبتة.
node -v تعرض إصدار العقدة. dotnet --version version إصدار dotnet.انتقل من دليل REPO Master Branch Root (الذي يحتوي على هذا 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 ستنهي عمليات العقدة اليتيمة وعمليات dotnet التي تحدث أحيانًا باستخدام سلسلة البناء هذه بعد الإنهاءات غير العادية (ربما لم تعد هناك حاجة إليها؟)npm run dist in Window Command لإنشاء الثنائيات تحت .dist Directory. بالنسبة إلى MacOS ، ستحتاج إلى تثبيت Python 3 لتجميع الثنائيات الأصلية - ستكون محترمًا تلقائيًا للقيام بذلك ولكنك ستحتاج بعد ذلك إلى تشغيل npm run dist مرة أخرى.NB - بالتوازي مع التجميع أعلاه ، سيتم تجميع رمز ISSIE دائمًا دون أخطاء (ولكن لا يتم تشغيلها) تحت Dotnet ، على سبيل المثال عن طريق بنائه من Visual Studio. يجب أن يكون التجميع متطابقًا ، ولكن عندما يكون هناك خطأ في وجود خطأ ، يكون من المفيد للغاية إنشاء الكود الحالي ضمن .NET مع VS أو VSC ويسهل العثور على رسائل خطأ. وبالمثل ، يمكن استخدام VS أو VSC بثقة إلى رمز Refactor ، والاختبار مع التجميع. لا يمكن للبناء تحت 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 لكل دليل قد يحتوي على الملفات ذات الأذونات السيئة. عادة دليل DEV الخاص بك . و /usr/local .يعد إلغاء تثبيت وإعادة تثبيت أحدث dotnet مفيدًا إذا تم تثبيت dotnet بشكل خاطئ.
بالنسبة لمستخدمي Apple Silicon Mac ، يجب عليك استخدام إصدار ARM64 من .NET من أجل الحصول على أفضل النتائج. يمكنك الحصول عليها من موقع Microsoft الرسمي ، باستخدام المثبت الخاص بهم.
على الرغم من أن سلسلة DEV معقدة ، إلا أنها الآن سلسة ومماثلة لجميع المنصات. يمكن تنفيذ كل خطوة من هذه الخطوات حسب الحاجة:
Dotnet SDK Node . Dotnet SDK يمنحك f#.dotnet tool restore تحصل على أدوات Dev: Fable Shows ، و Fake Build Automation ، و paket Dotnet Package Manager. (إدارة حزمة العقدة هي عبر npm التي تأتي مع العقدة).dotnet paket install يثبت جميع حزم Dotnet-Side المطلوبةnpm ci بتنزيل الإصدارات الصحيحة من جميع حزم NPM. سيعيد npm install الإصدارات إذا كانت هذه قد تغيرت وإنشاء ملف قفل محدث.npm run dev و npm run dist و npm run debug : البرامج النصية المحددة في package.json والتي تتحكم في التطور (مع HMR) أو تجميع الإنتاج مع Fable ، والتعبئة باستخدام WebPack 5.build.cmd و build.sh Scripts الخطوات المذكورة أعلاه إضافة بعض تنظيف الدليل غير ضروري عادة - يمكنك تشغيلها بشكل فردي بالترتيب إذا كانت لديك مشاكل.dotnet-tools.json .paket.dependencies في المستوى الأعلى و paket.references في دليل ملف .fsproj ذي الصلة. لا يتم تثبيت حزم dotnet حاليًا للإصدارات ، لذا يتم استخدام أحدث الإصدارات المتوافقة دائمًا. ربما يكون هذا خطأ ولكن يبدو أنه يعمل بشكل جيد..d TypeScript. هذا يعمل بشكل جيد ، ولكن هناك حاجة إلى تعديل يدوي لأي شيء معقد. راجع واجهة API للإلكترون في ISSI التي تم إنشاؤها بهذه الطريقة من ملفات API .d المنشورة - في هذه الحالة ، كان التعديل اليدوي غير سارة لأن API الإلكترون معقد للغاية. حزم الإلكترون chromium (view) و 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"
}
يحدد أوامر اختصار In-Project كمجموعة من <key> : <value ، بحيث عندما نستخدم npm run <stript_key> فإنه يعادل الاتصال <script_value> . على سبيل المثال ، في جذر المشروع ، فإن تشغيل npm run dev Terminal يعادل سطر الأوامر:
dotnet fable watch src/Main -s --run npm run devrenderer
يعمل هذا على تشغيل Fable 4 لتنقل العملية الرئيسية ، ثم ( --run هو خيار Fable لتشغيل أمر آخر) يقوم بإدارة البرنامج النصي devrenderer إلى Transpile إلى JavaScript ومشاهدة ملفات F# في عملية العارض. بعد الانتهاء من الانتهاء من Transpilation START.JS سيتم تشغيل البرنامج النصي. هذا يستدعي webpack لتعبئة رمز JavaScript و lauch ، ضمن الإلكترون ، وكذلك الساعات للتغييرات في رمز JavaScript ، ويقوم بتحميلها الساخن على تطبيق التشغيل
نتيجة لهذا ، في أي وقت توفير ملف مشروع F# تم تحريره (تقريبًا):
يعتمد نظام الإنشاء على ملف Fake build.fsx . FAPE هو DSL مكتوب في f# وهو متخصص لأتمتة مهام البناء. Build.fsx لديها أهداف تمثل مهام البناء ، وعادة ما يتم تشغيلها عبر build.cmd أو build.sh ، بدلاً من استخدام dotnet fake مباشرة:
build <target> ==> dotnet fake build -t <target> يتكون الرمز المصدر من قسمين متميزين يتم نقلهما بشكل منفصل إلى JavaScript لإجراء تطبيق إلكترون كامل.
يسمح Electron بالتالي بالرمز المكتوب لمتصفح (HTML + CSS + JavaScript) لتشغيله كتطبيق لسطح المكتب مع إمكانية الوصول إلى نظام ملفات سطح المكتب عبر الاتصال بين العمليتين.
تعمل كلتا العمليتين على تشغيل JavaScript تحت العقدة.
يقوم مصدر src/Main/Main.fs بتكوين بدء تشغيل الإلكترون وهو Boilerplate. يتم نقله إلى دليل مشروع الجذر بحيث يمكن التقاطه تلقائيًا بواسطة الإلكترون.
رمز التطبيق المتبقي (في)
الكود الذي يحول مصدر مشروع F# إلى renderer.js هو برنامج التحويل البرمجي المليء بالحرارة متبوعًا بمجموعة Bundler Node WebPack التي تجمع بين ملفات JavaScript المتعددة في renderer.js .
يتم التحكم في عملية الترجمة بواسطة ملفات .fsproj (تحديد مصدر F#) و webpack.additions.main.js ، webpack.additions.renderer.js التي تحدد كيفية تجمع WebPack بين مخرجات F# لكل من عمليات تطبيقات الإلكترون الرئيسية والإلكترون وحيث يتم وضع الرمز التنفيذي. هذا هو Boilerplate الذي لا تحتاج إلى تغييره ؛ عادةً ما تكون ملفات مشروع F# هي كل ما يجب تعديله.
يوجد برنامج نصي في جذر المستودع ، build_docs.sh ، والذي سيبني الوثائق للمشروع باستخدام FSDOCs. يجب تجميع المشروع قبل إنشاء الوثائق.
يتم تحويل ملفات Markdown Under /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 عند إنشاء تعليقات الوثائق في الكود ، أي عدم استخدام الأقواس الثلاثي <و> بخلاف العلامات. من فضلك لا تستخدم عروض أسعار مزدوجة كذلك!
تقوم 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/* | يوفر بعض الأنواع والمرافق الشائعة ، بالإضافة إلى واجهات واجهات برمجة التطبيقات للمكتبات والمكتبات المخصصة |
Renderer/Interface/* | يحتوي على وظائف واجهة منخفضة المستوى ، وجميع إدارة الملفات منخفضة المستوى |
Renderer/DrawBlock/* | يحتوي على جميع رمز المحرر التخطيطي المستند إلى SVG في F# |
Renderer/Simulator/* | يحتوي على المنطق لتحليل ومحاكاة ورقة تخطيطي |
Renderer/UI/* | يحتوي على منطق واجهة المستخدم |
./renderer.fs | ملف المستوى الأعلى الذي يدفع رمز العارض: يحتوي على رمز القائمة الإلكترون Elmish MVU ورمز الإلكترون |
Testsالاختبارات حاليًا قديمة جدًا ، ولن تعمل. وهي تستند إلى مكتبة اختبار F# Experto ، ومن حيث المبدأ ، يمكن اختبار رمز Widthinferrer و Simulator (الذي يتم تشغيله تحت Dotnet) هنا.
Staticيحتوي على ملفات ثابتة المستخدمة في التطبيق.
Docsيحتوي على معلومات المصدر التي تتحكم في موقع توثيق المشروع على الويب https://tomcl.github.io/issie/.
يتيح ISSIE للمستخدمين إنشاء مشاريع وملفات داخل هذه المشاريع. مشروع ISSIE هو ببساطة مجلد اسمه <project-name> يحتوي على ملف فارغ يسمى <project_name>.dprj (DPRJ يرمز إلى مشروع الرسم البياني). مجلد المشروع أي عدد غير صفري من ملفات التصميم ، كل اسمه <component_name>.dgm . يمثل كل ملف تصميم ورقة تصميم واحدة من تصميم الأجهزة الهرمية ، يمكن أن تحتوي الأوراق ، كمكونات ، أوراق أخرى.
عند فتح مشروع ما ، ستقوم ISSI في البداية بالبحث في المستودع المحدد عن ملفات .dgm ، تحليل محتواها وتحميلها ، والسماح للمستخدم بفتحها في ISSIE أو استخدامها كمكونات في تصميمات أخرى.
لإعادة تثبيت بيئة الإنشاء (دون تغيير رمز المشروع) Rerun build.cmd (Windows) أو build.sh (Linux و MacOS).
سيقوم npm run dist بإنشاء الثنائيات الصحيحة لنظامك تحت /dist .
