issie
Autumn-Spring 2024-2025
Issie (simulador esquemático interativo com editor integrado) é um aplicativo para design e simulação de circuitos digitais. É direcionado a estudantes e entusiastas que desejam entender os conceitos de eletrônica digital de uma maneira simples e divertida. A ISSIE foi projetada para ser favorável ao iniciante e orientar os usuários a seus objetivos por meio de mensagens de erro e pistas visuais claras. A ISSIE é desenvolvida e usada ativamente no ensino no Imperial College London.
Para obter mais informações técnicas sobre o projeto, continue lendo. Esta documentação é parcialmente baseada na excelente documentação do Visual2, dada a semelhança na pilha de tecnologia usada.
Para o site da ISSIE, vá aqui.
O aplicativo é escrito principalmente em F#, que é transpilado para JavaScript através do compilador de fábulas. O elétron é então usado para converter o aplicativo Web desenvolvido em um aplicativo de plataforma cruzada. A Electron fornece acesso a APIs de nível de plataforma (como acesso ao sistema de arquivos) que não estariam disponíveis para o navegador de baunilha.
O WebPack 5 é o Módulo Module responsável pela concatenação JavaScript e pelo processo automatizado de construção: a compilação Electron-Webpack é automatizada usando os scripts pré-existentes no diretório Scripts.
Os recursos de desenho são fornecidos (agora) por uma biblioteca de editor esquemática personalizada implementada em F# e especializada em componentes digitais.
A escolha do F# como a principal linguagem de programação para o aplicativo foi ditada por alguns fatores:
Se você deseja apenas executar o aplicativo, acesse a página de lançamentos e faça o download e execute o mais recente binário pré -construído para sua plataforma (Windows ou MacOS). A ISSIE exigirá no total cerca de 200m de espaço em disco.
Issie.exe de nível superior nos arquivos descompactados. A ISSIE instala e é executada sem fazer alterações no sistema - todo o seu código está dentro do diretório que você baixar. Você pode excluir isso e substituí -lo por uma versão posterior do ISSIE. Cada folha de design é armazenada em um arquivo nomeado semelhante no diretório do projeto. O backup do subdiretório contém um grande número de instantâneos de backup para recuperação de design. Eles não são necessários para a operação ISSIE para que você possa excluí -los - ou mesmo todo o diretório backup , se desejar.
Os binários da ISSIE não serão executados (em alguns casos) a partir de um local de arquivo em rede (encontrado em muitas máquinas de cluster). Se você tiver esse problema, navegue até o diretório de nível superior que contém os binários da ISSIE em uma janela de comando e digite issie.exe --no-sandbox . Veja #125 para obter detalhes.
Depois de abrir o ISSIE e estiver pronto para ir, fique à vontade para abrir um dos projetos de demonstração da janela de inicialização. Estes estão lá para mostrar como é um projeto ISSIE completo e permite que você se divirta com ele sem precisar projetar e construí -lo do zero. Toda vez que você reabrir um projeto de demonstração, ele será redefinido para seu estado inicial.
Se você deseja começar como desenvolvedor, siga estas etapas.
Faça o download e instale (se você já possui essas ferramentas instaladas, basta verificar as restrições da versão).
npm Package Manager, portanto, isso não precisa ser instalado separadamente.Faça o download e descompacte o repositório da ISSIE, ou clone -o localmente, ou bifurcá -lo no Github e cloná -lo localmente.
Verifique se você tem, .NET 8.X SDK, NODE V20.X: Se você deseja fazer mais do que fazer binários também: vs 2022 (ou mais recente vs vs code + ionide, ou piloto) instalado.
node -v mostra a versão do nó. dotnet --version mostra a versão do Dotnet.Navegue pelo diretório raiz do ramo mestre repo (que contém esse readme), em um intérprete de linha de comando ou inicie um do menu de contexto de diretório.
Execute build.cmd no Windows ou build.sh em Linux ou MacOS ( chmod 755 build.sh fornecerá a permissão do Script). Isso baixará e instalará todas as dependências, iniciará o aplicativo no modo dev com o HMR.
File -> reload pagenpm run dev . Execute npm run debug para o modo de depuração (isso será muito mais lento que o dev).npm run dist .packet.json e, portanto, precisa refazer o arquivo de bloqueio paket-lock.json use npm install .build killzombies , os processos de nó órfãos e dotnets que ocasionalmente ocorrem usando essa cadeia de construção após terminações incomuns (talvez não mais necessárias?)npm run dist na janela de comando para gerar binários no diretório .dist . Para o MacOS, você precisará instalar o Python 3 para compilar binários nativos - você será promovido automaticamente para fazer isso, mas precisará executar npm run dist novamente.NB - Paralelamente à compilação acima, o código ISSIE sempre compilará sem erros (mas não executados) no DOTNET, por exemplo, construindo -o no Visual Studio. A compilação deve ser idêntica, mas, quando não tiver certeza de por que há um erro, é muito útil criar o código atual no .NET com VS ou VSC e ficar mais fácil de encontrar mensagens de erro. Da mesma forma, o VS ou o VSC pode ser usado com confiança para refatorar o código, testando com compilação. O edifício sob o VS ou o VSC não pode funcionar porque o código depende das APIs de elétrons e nó para funcionar.
package-lock.json contém versões exatas do pacote e é baixado do repo. Normalmente você não precisa mudar isso. A construção padrão acima executará npm ci que verifica e audita os pacotes, mas não altera o arquivo de bloqueio.package.json1 ), use npm install para recriar um arquivo de bloqueio, que pode ser empurrado para o repositório.npm upgrade name ou npm [-D] install name em vez de editar package.json .npm ls name para descobrir quais pacotes necessários o usarão (geralmente atualizando ou substituindo -os removerá o problema). Uma construção limpa funcionará igualmente bem no macOS, no entanto, é mais provável que as coisas dêem errado se você já instalou pacotes conflitantes:
Versões herdadas do dotnet - podem ser removidas, se necessário, como aqui:
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 Permissões root em arquivos de dev. Para que o Dev funcione sem problemas, você precisa de todos os arquivos de configuração para serem instalados em seu próprio nome de usuário, para ter acesso a R/W. Isso quebrará se você se encontrar usando sudo para instalar o software ou se você fez isso em algum momento no passado. Nesse caso, você pode obter questões redondas temporariamente usando sudo para executar o desenvolvimento (ou o aplicativo gerado) com privilégios de administrador. Esta é a coisa errada a se fazer. Em vez disso, você deve usar
chown -R `whoami` dir para cada diretório que pode ter os arquivos com permissões ruins. Normalmente, seu diretório dev . e /usr/local .Desinstalar e reinstalar o mais recente dotnet é útil se o dotnet estiver instalado errado.
Para os usuários do Apple Silicon Mac, você deve usar a versão ARM64 do .NET para obter os melhores resultados. Você pode obtê -lo no site oficial da Microsoft, usando o instalador deles.
Embora a cadeia de desenvolvimento seja complexa, agora é muito suave e idêntica para todas as plataformas. Cada uma dessas etapas pode ser executada conforme necessário:
Dotnet SDK e Node instalados. Dotnet SDK fornece F#.dotnet tool restore recebe as ferramentas de desenvolvimento: compilador Fable , automação de construção Fake , gerenciador de pacotes paket Dotnet. (O gerenciamento de pacotes do nó é via npm , que vem com o nó).dotnet paket install instala todos os pacotes do lado dotnet necessáriosnpm ci Versões corretas de todos os pacotes NPM. npm install refazer as versões se elas tiverem alterado e gerar um arquivo de bloqueio atualizado.npm run dev , npm run dist , npm run debug : Scripts definidos no package.json que controlam o desenvolvimento (com HMR) ou a compilação de produção com a Fable e a embalagem usando o WebPack 5.build.cmd e build.sh empacotam as etapas acima, adicionando uma limpeza de diretório normalmente não necessária - você pode executá -los individualmente para que tenha problemas.dotnet-tools.json .paket.dependencies no nível superior e paket.references no diretório do arquivo .fsproj relevante. Atualmente, os pacotes dotnet não são fixados em versões, portanto as versões compatíveis mais recentes são sempre usadas. Isso provavelmente está errado, mas parece funcionar bem..d . Isso funciona bem, mas o ajuste manual é necessário para qualquer coisa complexa. Consulte a interface da API Electron em ISSIE, que foi gerada dessa maneira a partir de uma API de elétrons publicada .d arquivos - nesse caso, o ajuste manual era bastante desagradável porque a API de elétrons é muito complexa. Os pacotes de elétrons cromium (exibir) e node.js (motor), portanto, como em todos os projetos node.js, o arquivo package.json especifica as dependências do módulo (nó).
Além disso, a seção "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 os comandos de atalho no projeto como um conjunto de linhas <key> : <value , de modo que, quando usamos npm run <stript_key> é equivalente a chamar <script_value> . Por exemplo, na raiz do projeto, a execução no Terminal npm run dev é equivalente à linha de comando:
dotnet fable watch src/Main -s --run npm run devrenderer
Isso executa o Fable 4 para transpilar o processo principal, então ( --run é uma opção de fábula para executar outro comando) executa o Script devrenderer para transpilar para JavaScript e assistir os arquivos F# no processo de renderizador. Depois que a transpilação do renderizador terminar o script Start.js será executado. Isso chama webpack para embalar e Lauch o código JavaScript, em Electron, e também observa as alterações no código JavaScript, e as cargas quentes no aplicativo em execução
Como resultado disso, a qualquer momento, economizando um arquivo de projeto de renderizador F# editado causas (quase) imediatas:
O sistema de compilação depende de um arquivo Fake build.fsx . Fake é um DSL escrito em F# especializado para automatizar tarefas de construção. Build.fsx possui alvos representando tarefas de construção e, normalmente, elas são executadas via build.cmd ou build.sh , em vez de usar dotnet fake diretamente:
build <target> ==> dotnet fake build -t <target> O código -fonte consiste em duas seções distintas transpiladas separadamente ao JavaScript para fazer uma aplicação completa de elétrons.
Assim, o Electron permite que o código seja escrito para um navegador (HTML + CSS + JavaScript) seja executado como um aplicativo de desktop com a capacidade adicional do acesso ao sistema de arquivos de desktop por meio da comunicação entre os dois processos.
Ambos os processos executam JavaScript no nó.
A fonte src/Main/Main.fs configura a start-up de elétrons e é caldeira. Ele é transpilado para o diretório do projeto raiz, para que possa ser retirado automaticamente pelo elétron.
O código de aplicativo restante (in)
O código que transforma a fonte do projeto F# em renderer.js é o compilador de fábula seguido pelo nó webpack packler que combina vários arquivos JavaScript em um único renderer.js .
O processo de compilação é controlado pelos arquivos .fsproj (definindo a fonte F#) e webpack.additions.main.js , webpack.additions.renderer.js , que definem como o webpack combina as saídas F# para os processos de aplicativos de elétrons e eletrônicos e onde o código executável é colocado. Este é o Boilerplate que você não precisa mudar; Normalmente, os arquivos de projeto F# são tudo o que precisa ser modificado.
Há um script na raiz do repositório, build_docs.sh , que criará a documentação para o projeto usando FSDOCs. O projeto deve estar pronto para a compilação antes de gerar a documentação.
Os arquivos de marcação em /docs são transformados em páginas estáticas no site de documentação. Quaisquer comentários XML no código são transformados em comentários de documentação para todas as funções na base de código.
Para adicionar uma atualização, vá para a pasta /docs/updates e crie um novo arquivo de marcação com os seguintes cabeçalhos:
---
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 Veja outros documentos na pasta /docs/updates para exemplos.
Todos os comentários XML (começando com /// ) em qualquer módulo e declarações de função são transformados em documentação na seção de referência da API do site de documentação.
Siga as regras XML ao criar comentários de documentação no código, ou seja, sem uso de colchetes triangulares <e> além de tags. Por favor, não use cotações duplas também!
build_docs.sh também chama dotnet fsdocs watch para iniciar um servidor local que hospeda a documentação em http: // localhost: 8901/. A documentação gerada para o código está na seção "Referência da API".
Se você construiu os documentos e deseja acessar o servidor novamente, poderá executar dotnet fsdocs watch no terminal.
Nota lateral: um script, em vez da
dotnet fsdocs buildé usada devido a um bug sem documentos, onde o compilador cria código XML inválido para funções com registros anônimos, atribuindo atributos com "<>" em seus nomes. Isso faz com que a geração falhe. Usando<exclude/>não corrige o problema; portanto, uma solução alternativa é chamar um script que usa o Regex para remover esses atributos inválidos da documentação XML antes de criar a documentação.
Veja um problema semelhante no Github que lança um erro semelhante aqui.
src| Subpasta ou arquivo | Descrição |
|---|---|
Main/main.fs | Código para o principal processo de elétrons que define tudo - normalmente não mudou |
Renderer/Common/* | Fornece alguns tipos e utilitários comuns, bem como interfaces para APIs de bibliotecas e bibliotecas personalizadas |
Renderer/Interface/* | Contém funções de interface de baixo nível e todo o gerenciamento de arquivos de baixo nível |
Renderer/DrawBlock/* | Contém todo o código do editor esquemático baseado em SVG em F# |
Renderer/Simulator/* | Contém a lógica para analisar e simular uma folha esquemática |
Renderer/UI/* | Contém a lógica da interface do usuário |
./renderer.fs | Arquivo de nível superior que aciona o código do renderizador: contém loop de mvu elmish e código de menu Electron |
TestsAtualmente, os testes são muito antigos e não funcionam. Eles são baseados na biblioteca de testes F# expectro e, em princípio, o código WidthInferrer e simulador (que é executado no DOTNET) pode ser testado aqui.
StaticContém arquivos estáticos usados no aplicativo.
Docs docsContém informações de origem que controla o site de documentação do projeto https://tomcl.github.io/issie/.
A ISSIE permite que os usuários criem projetos e arquivos nesses projetos. Um projeto ISSIE é simplesmente uma pasta chamada <project-name> que contém um arquivo vazio chamado <project_name>.dprj (DPRJ significa Projeto Diagrama). A pasta do projeto qualquer número diferente de zero de arquivos de design, cada um denominados <component_name>.dgm (DGM significa diagrama). Cada arquivo de design representa uma folha de design de um design de hardware hierárquico, as folhas podem conter, como componentes, outras folhas.
Ao abrir um projeto, a ISSIE pesquisará inicialmente o repositório fornecido por arquivos .dgm , analisará e carregará seu conteúdo e permitirá que o usuário os abra na ISSIE ou os use como componentes em outros designs.
Para reinstalar o ambiente de construção (sem alterar o código do projeto) Rerun build.cmd (Windows) ou build.sh (Linux e MacOS).
npm run dist gerará os binários corretos para o seu sistema sob /dist .
