Roadmap

[happytomatoe]

@DavidSouther Is there a roadmap for this product?

[DavidSouther]

This is a question for @Shimon-Schocken.

The project is first and foremost an educational accompaniment to The Elements of Computing Systems and courses that use that book - beyond that, extensions or features like application delivery environments, are rather beyond our focus. The "File System UI" pull requests you see @netalondon working on our the "last step" in having this work as a "stand alone" application like the original Java desktop program. I think there's also the "Breakpoint" feature you're working on, and a request in #386 to implement the "Data Flow Animation" feature.

After that, we've discussed but have not settled on any plans for a few things. We'd like to expand the CLI program into some form of "assignment auto grader". We've explored building a VSCode extension, though that would probably involve building an entire Hack language server for HDL, Hack, Hack VM, and Jack projects.

Are there specific ideas you have, or areas you'd like to contribute?

[happytomatoe]

I am just solving my own problems. That's all I am doing.
@Shimon-Schocken Do you have statistics for Coursera where people fall off?
@DavidSouther Do you have statistics from google analytics. Any statistics that can help us identify pain points? I just don't know if my subjective view corresponds to what you see.

Would be to great to list:

1. Add more guidance on README page

• AFAIK this application is fully functional only in Chrome (I didn't test opera or Safari). Adding polyfills in another PR probably solves only the tooltip. On firefox VM emulator is very slow. The web app is also only for some type of screens.
• Jack compiler in Java has better error messages

2. IMO Probably the hardest part of the course is debugging assembler. What can simplify this:

• Breakpoints. I won't commit to everything that I've wrote in the TODO list. Is that ok?
• Add some kind of tooltip/debug button that can show comments in cpu emulator.
  I don't know how others solve the issue of debugging the assembler. That's how I do it
  

3. Should we do something the Jack editor? IMO it's slow even for small projects. I guess that's because we are saving all opened files on each key storke.
4. One small thing - should we change the Jack compiler so that it fails if assembly code is too large(>short max)(It is done in this way in Java Jack compiler)? I guess that presents an interesting challenge. But maybe it's for hardcore people.

BTW One feature that I wanted to add is to make panels resizable. qq - how about using an existing solution for that? If I will write this this from scratch I will introduce bugs. I tried adding this but it doesn't work. Is that an option to add some popular css framework? Or do you use only Pico css?

Just FYI -

• There is already a Nand2Tetris plugin for VSCode that adds a syntax highlighting for Jack. There is also one for sublime that does the same.
• I've created a cli app to convert an image to Jack code as I don't know how to draw things. Is that something that someone will be interested in?

[DavidSouther]

Do you have statistics from google analytics.

We do have tracking, but we don't at this time have much expertise in evaluating or using that data. What I can see is that of 1600 users over the past 30 days, 1200 used the Chip page, 300 used the CPU page, and a little over 200 used the ASM page. I can pretty comfortably say that you're putting the Jack side of the project through its paces - fewer than 100 active sessions used the compiler, with an average engagement time on that page of about 30 seconds.

AFAIK this application is fully functional only in Chrome (I didn't test opera or Safari). Adding polyfills in another PR probably solves only the tooltip. On firefox VM emulator is very slow. The web app is also only for some type of screens.

We don't use any particularly fancy features of JS or CSS. I believe Neta and I both primarily use Chrome, but it should be relatively functional in Edge and Opera. Of the 1600 active users, 1500 are on desktop, 1300 on a webkit browser (Chrome, Edge, Opera) and under 150 each on Safari and Firefox. The design uses several responsive breakpoints, but we have found it simply infeasible to make this work reasonably on a mobile device. Tablet sizes are cramped but somewhat functional. If anyone has a specific bug on one of those platforms, please open an issue.

Jack compiler in Java has better error messages

We use a parser compiler called Ohm that has not the best error messages. I've got a couple bugs on their project to look at ways to get more error messages, basically it stops at the first error and doesn't report more after that. Semantic errors we have a bit more control over, and would like to get at least to parity with the Java compiler. We'd love any contributions.

• https://github.com/nand2tetris/web-ide/tree/main/simulator/src/jack
• https://github.com/nand2tetris/web-ide/blob/main/simulator/src/languages/jack.ts
• https://github.com/nand2tetris/web-ide/blob/main/simulator/src/languages/grammars/jack.ohm

IMO Probably the hardest part of the course is debugging assembler. What can simplify this:

• Breakpoints. I won't commit to everything that I've wrote in the TODO list. Is that ok?
• Add some kind of tooltip/debug button that can show comments in cpu emulator. I don't know how others solve the issue of debugging the assembler. That's how I do it

Great points. 
For breakpoints, I know you have a PR and there's an issue that tracks it. For comments, that's harder for the reasons I detailed in #437, but "harder" means "someone doing the work". I know when I was debugging my assembler translator, I did lots of unit tests of small chunks of code. I don't think I spend much time in the VM emulator itself. That's just me, though!

Should we do something the Jack editor? IMO it's slow even for small projects. I guess that's because we are saving all opened files on each key stroke.


Probably. Again, you are the first person that I know of who's spent significant time with this Jack compiler, and you're also building programs with it much larger than we usually see students build. That's awesome! But also not an area we've had a lot of attention at. I will probably have some time next month that I can dedicate to looking into that.


One small thing - should we change the Jack compiler so that it fails if assembly code is too large(>short max)(It is done in this way in Java Jack compiler)? I guess that presents an interesting challenge. But maybe it's for hardcore people.

I'd rather we just fix the speed issue!

One feature that I wanted to add is to make panels resizable. qq - how about using an existing solution for that? If I will write this this from scratch I will introduce bugs. I tried adding this but it doesn't work. Is that an option to add some popular css framework? Or do you use only Pico css?

That's basically the feature that makes us consider moving to VSCode & an IDE plugin architecture. We don't want to write an IDE, we want to write a suite of tools that work with Hack & Jack. It's already enough headache writing this File System emulator/wrapper/etc thing. We generally prefer simpler internal dependencies, but if someone had a clean way to drop that in, it would absolutely be considered!

There is already a Nand2Tetris plugin for VSCode that adds a syntax highlighting for Jack. There is also one for sublime that does the same.

Yes, we're aware of (and have spoken to the authors of) those plugins. Their syntax highlighting files are already included in our VSCode extension. I was referring to a much more feature-full experience: Side panel with chip emulators; Debuggers connected to the VSCode debugging panel; compilers for each language providing intellisense, project completion, etc.


I've created a cli app to convert an image to Jack code as I don't know how to draw things. Is that something that someone will be interested in?

This is really cool! There's the standalone bitmap editor, which predates the web ide by a few years. We've included it directly, and haven't had time to migrate it to React yet. https://github.com/nand2tetris/web-ide/blob/main/web/public/bitmap_editor.html. Something like the bitmap converter would be a really neat feature to add!

[DavidSouther]

I can actually drill down a step further - I think you aren't only the first NAND2Tetris compiler user, you're the only NAND2Tetris compiler user! :)

[happytomatoe]

@DavidSouther Great to hear))

We use a parser compiler called Ohm that has not the best error messages.

Why do we use that?

BTW I've added web page for Jack image converter. . Though I am using tailwind css to create the look and feel. Personal question - which AI copilot do you use?

To wrap up - I guess it's better to start thinking about VSCode extension. Though I guess you will still need an emulator even if you have a compiler.

[DavidSouther]

Ohm has an easy getting started and an excellent AST operations tool. It also takes a very different approach from how students are usually guided to create their own parsers, and therefor less likely that students who come to the project Github will be able to directly use the project's code in their homework. It worked, it works, and it takes time and effort to replace it. It's also not clear that, even if we could receive multiple errors, we wouldn't still show just the first as a less daunting experience to students. This might be their first time really working with some editors, and we want to keep the focus on learning the HDL concepts, not the tool.

The converter tools looks really neat! If you'd like to add a LICENSE to it, we can consider using it or moving it into the web ide if that's comfortable for you.

I don't use AI copilots; I find that today's GenAI tooling creates a situation that "robs Peter to pay Paul" - while it saves time in some areas of coding, it takes significantly more time during the review phase and adds an entirely new aspect of the software development lifecycle and creative process of just getting the prompts for the tool at all.

Looking at the VSCode extension, the bulk of the code in the simulator folder is the NAND2Tetris engine and core. It will be used for any surface we target - CLI, Web, Language Server. The extension work will necessarily include that work as the emulator parts.

[happytomatoe]

Sir, is that ok with you if I will write a lexer and a parser for compiler from scratch as I still have to do a project for that?

This might be their first time really working with some editors, and we want to keep the focus on learning the HDL concepts, not the tool.

If your goal is to complete the projects you will learn the tool anyway to some extent.

It's also not clear that, even if we could receive multiple errors, we wouldn't still show just the first as a less daunting experience to students.

I guess what you are trying to say is that compiler doesn't show more than 1 error message per file. AFAIK That's what compiler cli shows.

License added. I moved the sources. Let me know if you want me to make some changes.

About copilots - another funny moment - I had situation with 1 of the clients that I worked for - they bought github copilot licenses. If you've activated licence on your computer and didn't use Github copilot at least once a month, you could have a meeting discussing how they failed the initiative)) Hahaha.

[DavidSouther]

You can of course implement anything you want! :) As for including it into the source repo here, we'd need to see a high quality bar and would prefer to keep all the compiler tooling in the same system, that is, right now it's all in Ohm with a shared Base language. This has numerous benefits for the team as we maintain the project, albeit with the recognized missing features.

Some discussion of error recovery is at ohmjs/ohm#492

you will learn the tool anyway

Yep. Keeping that learning curve shallow is still the goal.

Thanks for updating the license; I'll try to look at it closer this weekend!

[happytomatoe]

@DavidSouther out of curiosity - have you also tried other parser generators?

[happytomatoe]

I guess Ohm is not very popular if comparing with others.

[DavidSouther]

I'm not sure that table supports "not very popular" as an assertion? Regardless, it's not unpopular, and the decision was made 3 or 4 years ago. Ohm and Antlr are the ones that still receive updates; nearley, jison, and pegjs are unmaintained for several years.