{"id":20101488,"url":"https://github.com/aappleby/metron","last_synced_at":"2025-08-20T20:32:32.709Z","repository":{"id":40568452,"uuid":"223903847","full_name":"aappleby/metron","owner":"aappleby","description":"A C++ to Verilog translation tool with some basic guarantees that your code will work.","archived":false,"fork":false,"pushed_at":"2024-05-20T03:42:13.000Z","size":87892,"stargazers_count":150,"open_issues_count":3,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-05-20T07:39:38.474Z","etag":null,"topics":["c","compiler","cpp","fpga","hdl","transpiler","verilog"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aappleby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-25T08:56:57.000Z","updated_at":"2024-05-30T04:32:47.527Z","dependencies_parsed_at":"2024-05-30T04:32:47.021Z","dependency_job_id":"08e4d665-1664-418f-917e-67e08f2f850f","html_url":"https://github.com/aappleby/metron","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aappleby%2Fmetron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aappleby%2Fmetron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aappleby%2Fmetron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aappleby%2Fmetron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aappleby","download_url":"https://codeload.github.com/aappleby/metron/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230454429,"owners_count":18228392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","compiler","cpp","fpga","hdl","transpiler","verilog"],"created_at":"2024-11-13T17:25:22.812Z","updated_at":"2024-12-19T15:08:51.910Z","avatar_url":"https://github.com/aappleby.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"docs/assets/metron_icon.svg\" width=\"64\" height=\"64\"\u003e Metron C++ to Verilog Translator\n\nMetron is a tool for translating a _very_ _limited_ subset of C++ into a _very_ _limited_ subset of SystemVerilog.\n\nMetron accepts plain, unannotated C++ header files as inputs and produces synthesizable SystemVerilog files that are compatible with Icarus, Verilator, Yosys, and most commercial tools.\n\nMetron is _not_ a \"High-Level Synthesis\" tool. Metron does some basic analysis to determine if your code is semantically compatible with Verilog and then produces a line-by-line translation with only the minimal set of changes needed to make the code compatible with Verilog tooling.\n\nBecause it targets hardware implementation, Metron can't handle a lot of C++ language features - no pointers, no virtual functions, no pass-by-reference, limited data structures - but it's still sufficient to build CPUs and peripherals that will run on a FPGA.\n\n# TL;DR:\n## [Short essay about hardware vs. software programming](docs/BlueBallMachines.md)\n## [Demo](https://aappleby.github.io/metron/demo/)\n## [Tutorial](https://aappleby.github.io/metron/tutorial/)\n## [How Metron Works - Tracing \u0026 Symbolic Logic](https://aappleby.github.io/metron/TemporalLogic.html)\n\n## Metron v0.0.1 Release Notes\n\nFirst public release!\n\n- Stuff that works\n  - Testbench has tests for Verilator, Icarus, and Yosys parsing Metron output.\n  - Testbench has pretty good coverage of Metron via kcov.\n  - Testbench has test suites for two RISC-V RV32I cores.\n  - Testbench has some lock-step tests that check that Metron and Verilator outputs are bit-identical.\n  - Tutorial and demo work and have nice responsive live code windows.\n- Stuff that doesn't work, but should eventually\n  - Struct support. It was kinda working in some tools and not in others and I need to revisit it.\n  - Visual Studio support has bit-rotted somewhat.\n- Stuff that I'll be doing next\n  - Better error reporting. The error _checking_ is good, but the information printed out is pretty useless unless you're in a debugger. I should at least be printing filename + source line for all errors.\n  - More complicated examples ported from Verilog to Metron. I have a full-featured UART from OpenCores and the Ibex RISC-V CPU that I've started looking at but they're not functional yet.\n  - More chunks of GateBoy/LogicBoy made compatible with Metron.\n\n## FAQ\n\n- I'm already using Verilator to convert my Verilog to C for testing, why would I want to use Metron?\n  - Metron can help you prototype new RTL faster than writing it in Verilog.\n  - Metron doesn't require a conversion step to integrate with an existing Verilator C++ testbench.\n  - Metron modules usually simulate 2x - 5x faster than Verilated modules.\n- Wait, what? How fast do Metron models simulate?\n  - A trivial LFSR module simulates at 600+ Mhz on my 5900x\n  - A 640x480 \"Pong\" VGA video generator runs at 260+ Mhz with simulated video out via SDL2, or over 10x realtime.\n  - A simple RISC-V RV32I core simulates at 360 mhz, though with the caveat that it's a single-cycle core and probably wouldn't synthesize.\n  - The UART example in the test bench runs a loopback transmission + checksum at ~400 mhz (the Verilated version is ~130 mhz).\n- Have you heard of TLA+?\n  - Yes, and I'm aware that I'm also using the phrase \"temporal logic\", which might confuse some readers. I couldn't think of a better term for the \"How Metron Works\" page though, alas. Apolgies in advance to Leslie Lamport.\n  - It would be interesting to see how Metron programs could use (or be translated into?) TLA+ proofs, but it's out of scope for now.\n- Why C++ instead of {language}?\n  - When I started the project I wasn't sure if I'd end up needing to do a bunch of brute-force \"trace every possible path\" stuff, and C++ is my most fluent language so I stuck with it. Now that Metron's working.... yeah, it would probably be simpler if written in Python, and Rust would probably make a better source language for conversion. Might be a future project.\n\n## Building the Metron binary from source:\n\nNote: Metron doesn't use Git submodules anymore, instead it expects its dependencies to be checked out in folders alongside itself.\n```\nsudo apt install git build-essential ninja-build python3 libicu-dev libsdl2-dev\ngit clone https://github.com/CLIUtils/CLI11\ngit clone https://github.com/aappleby/metron\ncd metron\n./build.py\nninja build/metron\n```\n\n## Building everything in the repo:\nThe full test suite requires quite a bit of stuff. The versions of Verilator and Yosys available via apt are slightly too old and have some bugs, so build them from source - instructions tested on a clean install of Ubuntu 22.04:\n```\n#sudo apt install verilator    // too old, get verilated_heavy.h error\n#sudo apt install yosys        // too old, doesn't like \"module uart_hello #(parameter int repeat_msg = 0)\"\nsudo apt install iverilog      // strongly recommended to build from source\nsudo apt install fpga-icestorm // strongly recommended to build from source\nsudo apt install nextpnr-ice40 // strongly recommended to build from source\nsudo apt install libsdl2-dev\nsudo apt install gcc-riscv64-unknown-elf\nsudo apt install srecord\n```\n\n## Installing Emscripten:\n```\ncd ~\ngit clone https://github.com/emscripten-core/emsdk.git\ncd emsdk\n./emsdk install latest\n./emsdk activate latest\nsource ./emsdk_env.sh\n```\n\n## Building Yosys from source:\n```\ncd ~\nsudo apt-get install build-essential clang bison flex libreadline-dev gawk tcl-dev libffi-dev git graphviz xdot pkg-config python3 libboost-system-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev\ngit clone https://github.com/YosysHQ/yosys\ncd yosys\nmake config-gcc\nmake -j$(nproc)\nsudo make install\n```\n\n## Building Verilator from source:\n```\ncd ~\nsudo apt-get install git perl python3 make autoconf g++ flex bison ccache libgoogle-perftools-dev numactl perl-doc libfl2 libfl-dev zlib1g zlib1g-dev help2man\ngit clone https://github.com/verilator/verilator\ncd verilator\nautoconf\n./configure\nmake -j$(nproc)\nsudo make install\n```\n\n## Building Icarus from source:\n```\ncd ~\nsudo apt install build-essential bison flex gperf libreadline-dev autoconf\ngit clone https://github.com/steveicarus/iverilog\ncd iverilog\nsh autoconf.sh\n./configure\nmake -j$(nproc)\nsudo make install\n```\n\n## Building Icestorm from source:\n```\ncd ~\ngit clone https://github.com/YosysHQ/icestorm\ncd icestorm\nsudo apt install build-essential libftdi-dev\nmake\nsudo make install\n```\n\n## Building Nextpnr-iCE40 from source (note - requires Icestorm to be installed first):\n```\ncd ~\ngit clone https://github.com/YosysHQ/nextpnr\ncd nextpnr\nsudo apt install python3 python3-dev cmake libboost-dev libboost-filesystem-dev libboost-thread-dev libboost-program-options-dev libboost-iostreams-dev libboost-dev libeigen3-dev\ncmake . -DARCH=ice40\nmake -j$(nproc)\nsudo make install\n```\n\n## Running the Metron test suite:\n```\n./build.py\nninja\n./run_tests.py\n```\n\n## Running test coverage:\n```\n./build.py\nninja\n./run_tests.py --coverage\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faappleby%2Fmetron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faappleby%2Fmetron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faappleby%2Fmetron/lists"}