issie
Autumn-Spring 2024-2025
Issie (simulator skematik interaktif dengan editor terintegrasi) adalah aplikasi untuk desain dan simulasi sirkuit digital. Ini ditargetkan untuk siswa dan penggemar yang ingin mendapatkan pemahaman konsep elektronik digital dengan cara yang sederhana dan menyenangkan. Issie dirancang untuk menjadi ramah-pemula dan memandu pengguna menuju tujuan mereka melalui pesan kesalahan yang jelas dan petunjuk visual. Issie dikembangkan dan secara aktif digunakan dalam mengajar di Imperial College London.
Untuk info teknis lebih lanjut tentang proyek ini, baca terus. Dokumentasi ini sebagian didasarkan pada dokumentasi Visual2 yang sangat baik, mengingat kesamaan dalam tumpukan teknologi yang digunakan.
Untuk situs web Issie, buka di sini.
Aplikasi ini sebagian besar ditulis dalam F#, yang akan ditranspilasi ke JavaScript melalui Fable Compiler. Elektron kemudian digunakan untuk mengonversi aplikasi web yang dikembangkan menjadi aplikasi lintas platform. Elektron menyediakan akses ke API tingkat platform (seperti akses ke sistem file) yang tidak akan tersedia untuk aplikasi web vanilla browser.
Webpack 5 adalah modul bundler yang bertanggung jawab atas gabungan javascript dan proses pembangunan otomatis: build elektron-webpack otomatis menggunakan skrip yang sudah ada sebelumnya di bawah direktori skrip.
Kemampuan gambar disediakan (sekarang) oleh pustaka editor skematik khusus yang diimplementasikan dalam F# dan khusus untuk komponen digital.
Pilihan F# sebagai bahasa pemrograman utama untuk aplikasi telah ditentukan oleh beberapa faktor:
Jika Anda hanya ingin menjalankan aplikasi, buka halaman rilis dan unduh dan jalankan biner prebuilt terbaru untuk platform Anda (Windows atau MacOS). Issie akan membutuhkan total sekitar 200m ruang disk.
Issie.exe tingkat atas di file unzip. ISSIE menginstal dan berjalan tanpa membuat perubahan sistem - semua kodenya ada di dalam direktori yang Anda unduh. Anda dapat menghapus ini dan menggantinya dengan versi Issie selanjutnya. Setiap lembar desain disimpan dalam file yang disebutkan sama di bawah direktori proyek. backup subdirektori di sana berisi sejumlah besar snapshot cadangan untuk pemulihan desain. Ini tidak diperlukan untuk operasi Issie sehingga Anda dapat menghapusnya - atau bahkan seluruh direktori backup , jika Anda mau.
Binari Issie tidak akan berjalan (dalam beberapa kasus) dari lokasi file jaringan (ditemukan pada banyak mesin cluster). Jika Anda memiliki masalah ini, navigasikan ke direktori tingkat atas yang berisi binari Issie di jendela perintah dan ketik issie.exe --no-sandbox . Lihat #125 untuk detailnya.
Setelah Anda membuka Issie dan siap untuk pergi, jangan ragu untuk membuka salah satu proyek demo dari jendela pemula. Ini ada untuk menunjukkan kepada Anda seperti apa proyek Issie yang lengkap dan memungkinkan Anda untuk bersenang -senang dengannya tanpa harus merancang dan membangunnya dari awal. Setiap kali Anda membuka kembali proyek demo, ia akan diatur ulang ke keadaan awalnya.
Jika Anda ingin memulai sebagai pengembang, ikuti langkah -langkah ini.
Unduh dan instal (jika Anda sudah menginstal alat ini cukup periksa kendala versi).
npm Package Manager, jadi ini tidak perlu diinstal secara terpisah.Unduh & unzip Repo Issie, atau klon secara lokal, atau potong di GitHub dan kemudian klon secara lokal.
Periksa Anda memiliki, .net 8.x SDK, Node V20.x: Jika Anda ingin melakukan lebih dari membuat binari, juga: vs 2022 (atau kode vs vs + ionida terbaru, atau pengendara) yang diinstal.
node -v menunjukkan versi simpul. dotnet --version menunjukkan versi dotnet.Navigasi dari direktori root cabang master repo (yang berisi readme ini), dalam penerjemah baris perintah, atau mulai satu dari menu konteks direktori.
Jalankan build.cmd di bawah windows atau build.sh di bawah linux atau macOS ( chmod 755 build.sh akan memberikan izin menjalankan skrip). Ini akan mengunduh dan menginstal semua dependensi kemudian meluncurkan aplikasi dalam mode dev dengan HMR.
File -> reload pagenpm run dev . Jalankan npm run debug untuk mode debug (ini akan jauh lebih lambat dari Dev).npm run dist .packet.json dan karenanya perlu membuat ulang file kunci paket-lock.json Gunakan npm install .build killzombies akan mengakhiri proses node yatim dan dotnet yang kadang -kadang terjadi menggunakan rantai build ini setelah pemutusan yang tidak biasa (mungkin tidak lagi diperlukan?)npm run dist In Window Perintah untuk Menghasilkan Binari Di Bawah .dist Directory. Untuk macOS Anda perlu menginstal Python 3 untuk mengkompilasi biner asli - Anda akan dipaksa secara otomatis untuk melakukan ini tetapi kemudian perlu menjalankan npm run dist lagi.NB - Secara paralel dengan kompilasi di atas, kode Issie akan selalu dikompilasi tanpa kesalahan (tetapi tidak dijalankan) di bawah Dotnet, misalnya dengan membangunnya dari Visual Studio. Kompilasi harus identik tetapi ketika tidak yakin mengapa ada kesalahan, akan sangat membantu untuk membangun kode saat ini di bawah .NET dengan VS atau VSC dan mendapatkan lebih mudah untuk menemukan pesan kesalahan. Demikian pula, VS atau VSC dapat digunakan dengan percaya diri untuk kode refactor, pengujian dengan kompilasi. Membangun di bawah VS atau VSC tidak dapat berfungsi karena kode tergantung pada elektron dan node API untuk bekerja.
package-lock.json berisi versi paket yang tepat dan diunduh dari repo. Biasanya Anda tidak perlu mengubah ini. Bangunan standar di atas akan menjalankan npm ci yang memeriksa dan mengaudit paket tetapi tidak mengubah file kunci.package.json1 ), gunakan npm install untuk membuat ulang file kunci, yang dapat didorong ke repo.npm upgrade name atau npm [-D] install name alih-alih mengedit package.json .npm ls name untuk menemukan paket mana yang diperlukan yang menggunakannya (biasanya meningkatkan atau menggantinya akan menghapus masalah). Build yang bersih akan bekerja sama dengan baik pada macOS, namun hal -hal yang lebih mungkin salah jika Anda sebelumnya telah memasang paket yang bertentangan:
Versi warisan dotnet - dapat jika perlu dihapus seperti di sini:
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 Izin root dalam file dev. Agar Dev bekerja dengan lancar, Anda perlu setiap file konfigurasi untuk diinstal di bawah nama pengguna Anda sendiri, sehingga Anda memiliki akses R/W. Ini akan rusak jika Anda pernah menemukan diri Anda menggunakan sudo untuk root install software, atau jika Anda telah melakukan ini beberapa saat di masa lalu. Dalam hal ini Anda dapat mendapatkan masalah bulat sementara dengan menggunakan sudo untuk menjalankan pengembangan (atau aplikasi yang dihasilkan) dengan hak istimewa admin. Ini adalah hal yang salah untuk dilakukan. Sebaliknya Anda harus menggunakan
chown -R `whoami` dir untuk setiap direktori yang mungkin memiliki file dengan izin buruk. Biasanya direktori dev Anda . dan /usr/local .Menghapus dan menginstal ulang dotnet terbaru sangat membantu jika dotnet telah diinstal salah.
Untuk pengguna Apple Silicon Mac, Anda harus menggunakan versi .net ARM64 untuk mendapatkan hasil terbaik. Anda bisa mendapatkannya dari situs web resmi Microsoft, menggunakan penginstal mereka.
Meskipun rantai dev kompleks, sekarang sangat halus dan identik untuk semua platform. Masing -masing langkah ini dapat dilakukan sesuai kebutuhan:
Dotnet SDK dan Node diinstal. Dotnet SDK memberi Anda F#.dotnet tool restore memberi Anda alat dev: Fable Compiler, Fake Build Palsu, paket Dotnet Package Manager. (Manajemen paket simpul adalah melalui npm yang dilengkapi dengan node).dotnet paket install menginstal semua paket sisi dotnet yang dibutuhkannpm ci mengunduh dan mengaudit versi yang benar dari semua paket NPM. npm install akan mengulang versi jika ini telah berubah dan menghasilkan file kunci yang diperbarui.npm run dev , npm run dist , npm run debug : Script yang didefinisikan dalam package.json yang mengontrol pengembangan (dengan HMR) atau kompilasi produksi dengan fable, dan berkemas menggunakan Webpack 5.build.cmd dan build.sh skrip mengemas langkah -langkah di atas menambahkan beberapa biasanya tidak perlu pembersihan direktori - Anda dapat menjalankannya secara individual agar Anda memiliki masalah.dotnet-tools.json .paket.dependencies di tingkat atas dan paket.references dalam direktori file .fsproj yang relevan. Saat ini paket dotnet tidak disematkan ke versi sehingga versi terbaru yang kompatibel selalu digunakan. Ini mungkin salah tetapi tampaknya bekerja dengan baik..d . Ini bekerja dengan baik, tetapi penyesuaian manual diperlukan untuk apa pun yang kompleks. Lihat antarmuka API elektron di Issie yang dihasilkan dengan cara ini dari file .d elektron API yang diterbitkan - dalam hal itu penyesuaian manual cukup tidak menyenangkan karena elektron API sangat kompleks. Bundel elektron kromium (tampilan) dan node.js (mesin), oleh karena itu seperti dalam setiap proyek node.js, file package.json menentukan dependensi modul (node).
Selain itu, bagian "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"
}
Mendefinisikan perintah shortcut in-project sebagai satu set <key> : <value line, sehingga ketika kita menggunakan npm run <stript_key> setara dengan memanggil <script_value> . Misalnya, dalam akar proyek, berjalan di terminal npm run dev setara dengan baris perintah:
dotnet fable watch src/Main -s --run npm run devrenderer
Ini menjalankan Fable 4 untuk mentranspile proses utama, kemudian ( --run adalah opsi Fable untuk menjalankan perintah lain) menjalankan skrip devrenderer untuk ditranspile ke JavaScript dan menonton file F# dalam proses renderer. Setelah transpilasi renderer selesai, skrip JS akan dijalankan. Ini memunculkan webpack untuk mengemas dan melenyapkan kode JavaScript, di bawah elektron, dan juga menonton perubahan dalam kode JavaScript, dan memuat panas ini pada aplikasi yang sedang berjalan
Akibatnya, kapan saja menyimpan penyebab file proyek F# renderer yang diedit (hampir):
Sistem Build tergantung pada file Fake build.fsx . Fake adalah DSL yang ditulis dalam F# yang berspesialisasi untuk mengotomatisasi tugas pembuatan. Build.fsx memiliki target yang mewakili tugas build, dan biasanya ini dijalankan melalui build.cmd atau build.sh , alih -alih menggunakan dotnet fake secara langsung:
build <target> ==> dotnet fake build -t <target> Kode sumber terdiri dari dua bagian berbeda ditranspilasi secara terpisah ke JavaScript untuk membuat aplikasi elektron lengkap.
Elektron dengan demikian memungkinkan kode yang ditulis untuk browser (HTML + CSS + JavaScript) dijalankan sebagai aplikasi desktop dengan kemampuan tambahan akses sistem file desktop melalui komunikasi antara kedua proses.
Kedua proses menjalankan JavaScript di bawah Node.
Sumber src/Main/Main.fs mengkonfigurasi start-up elektron dan boilerplate. Ini ditranspilikan ke direktori proyek root sehingga dapat secara otomatis diambil dengan elektron.
Kode aplikasi yang tersisa (dalam)
Kode yang mengubah sumber proyek F# menjadi renderer.js adalah fable compiler yang diikuti oleh node webpack bundler yang menggabungkan beberapa file javascript menjadi renderer.js tunggal.
Proses kompilasi dikendalikan oleh file .fsproj (mendefinisikan sumber f#) dan webpack.additions.main.js , webpack.additions.renderer.js yang menentukan bagaimana webpack menggabungkan output f# untuk proses aplikasi utama elektron dan elektron dan di mana kode yang dapat dieksekusi dimasukkan. Ini adalah boilerplate yang tidak perlu Anda ubah; Biasanya semua file proyek F# adalah yang perlu dimodifikasi.
Ada skrip di akar repositori, build_docs.sh , yang akan membangun dokumentasi untuk proyek menggunakan FSDOCS. Proyek harus siap dikompilasi sebelum menghasilkan dokumentasi.
File Markdown Di Bawah /docs Diubah Menjadi Halaman Statis di Situs Dokumentasi. Setiap komentar XML dalam kode diubah menjadi komentar dokumentasi untuk setiap fungsi dalam basis kode.
Untuk menambahkan pembaruan, buka folder /docs/updates dan buat file markdown baru dengan header berikut:
---
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 Lihat dokumen lain di folder /docs/updates untuk contoh.
Semua komentar XML (dimulai dengan /// ) di bawah modul dan deklarasi fungsi apa pun diubah menjadi dokumentasi di bawah bagian Referensi API dari situs web dokumentasi.
Harap ikuti aturan XML saat membuat komentar dokumentasi dalam kode, yaitu tidak ada penggunaan braket segitiga <dan> selain untuk tag. Tolong jangan gunakan kutipan ganda juga!
build_docs.sh juga memanggil dotnet fsdocs watch untuk memulai server lokal yang menampung dokumentasi di http: // localhost: 8901/. Dokumentasi yang dihasilkan untuk kode berada di bawah bagian "Referensi API".
Jika Anda telah membangun dokumen dan ingin mengakses server lagi, Anda dapat menjalankan dotnet fsdocs watch di terminal.
Catatan: Sebuah skrip, bukan
dotnet fsdocs buildyang biasa digunakan karena bug tidak berdokumen di mana kompiler membuat kode XML yang tidak valid untuk fungsi dengan catatan anonim, menetapkan atribut dengan "<>" dalam nama mereka. Ini menyebabkan generasi gagal. Menggunakan<exclude/>tidak memperbaiki masalah, jadi solusi adalah memanggil skrip yang menggunakan Regex untuk menghapus atribut yang tidak valid ini dari dokumentasi XML sebelum membangun dokumentasi.
Lihat masalah serupa di GitHub yang melempar kesalahan serupa di sini.
src| Subfolder atau file | Keterangan |
|---|---|
Main/main.fs | Kode untuk proses elektron utama yang mengatur semuanya - biasanya tidak berubah |
Renderer/Common/* | Menyediakan beberapa jenis dan utilitas umum, serta antarmuka ke API perpustakaan dan perpustakaan khusus |
Renderer/Interface/* | Berisi fungsi antarmuka tingkat rendah, dan semua manajemen file tingkat rendah |
Renderer/DrawBlock/* | Berisi semua kode editor skematik berbasis SVG di F# |
Renderer/Simulator/* | Berisi logika untuk menganalisis dan mensimulasikan lembar skematis |
Renderer/UI/* | Berisi logika UI |
./renderer.fs | File tingkat atas yang menggerakkan kode renderer: berisi elmish mvu loop dan kode menu elektron |
Tests folderSaat ini tes sudah sangat tua, dan tidak akan berhasil. Mereka didasarkan pada perpustakaan pengujian F# Expecto dan pada prinsipnya Widthinferrer dan kode simulator (yang berjalan di bawah dotnet) dapat diuji di sini.
StaticBerisi file statis yang digunakan dalam aplikasi.
DocsBerisi informasi sumber yang mengontrol situs web dokumentasi proyek https://tomcl.github.io/issie/.
Issie memungkinkan pengguna untuk membuat proyek dan file dalam proyek tersebut. Proyek ISSIE hanyalah folder bernama <project-name> yang berisi file kosong bernama <project_name>.dprj (DPRJ adalah singkatan dari Proyek Diagram). Folder Proyek Jumlah file desain yang tidak nol, masing-masing bernama <component_name>.dgm (DGM adalah singkatan dari diagram). Setiap file desain mewakili satu lembar desain dari desain perangkat keras hierarkis, lembaran dapat berisi, sebagai komponen, lembaran lainnya.
Saat membuka proyek, ISSIE pada awalnya akan mencari repositori yang diberikan untuk file .dgm , parse dan memuat konten mereka, dan memungkinkan pengguna untuk membukanya di ISSIE atau menggunakannya sebagai komponen dalam desain lain.
Untuk menginstal ulang lingkungan build (tanpa mengubah kode proyek) Rerun build.cmd (windows) atau build.sh (linux dan macOS).
npm run dist akan menghasilkan binari yang benar untuk sistem Anda di bawah /dist .
