matthewturk / jupyterlab_dosbox Goto Github PK

View Code? Open in Web Editor NEW

6.0 3.0 1.0 168 KB

A jupyterlab extension to run Dosbox emulation in WASM

License: BSD 3-Clause "New" or "Revised" License

TypeScript 65.20% JavaScript 2.01% Python 32.07% CSS 0.27% Shell 0.46%

jupyterlab dosbox

jupyterlab_dosbox's Introduction

jupyterlab_dosbox

Run DosBox in jupyterlab. Built on js-dos and uses the js-dos 7.xx modules.

This exposes a pretty simple interface to a WASM-compiled DosBox instance. You can get screenshots, coredumps, and you can send commands. It will download some wasm assets off the web using pooch.

As of right now, the DosBox instance does not listen to key and mouse events!

The examples in the examples directory show how to get a coredump, take a screenshot, and send zip files.

There are a bunch of rough edges! But, you can browse the files in your filesystem with a file browser panel on the left, and you can inspect the memory.

Some things that are on the roadmap:

Better interaction with the instance, including trapping and sending appropriate browser events
Saving and restoring file system and memory instances (i.e., machine state)
Better interface for inspecting core dumps
Sound and video capture
All-around polish on the interface (like, why aren't there any icons?!)

Requirements

JupyterLab >= 3.0
Pooch
numpy, for memory access

Install

pip install jupyterlab_dosbox

Contributing

Development install

Note: You will need NodeJS to build the extension package.

The jlpm command is JupyterLab's pinned version of yarn that is installed with JupyterLab. You may use yarn or npm in lieu of jlpm below.

# Clone the repo to your local environment
# Change directory to the jupyterlab_dosbox directory
# Install package in development mode
pip install -e .
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Rebuild extension Typescript source after making changes
jlpm run build

You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm run watch
# Run JupyterLab in another terminal
jupyter lab

With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).

By default, the jlpm run build command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:

jupyter lab build --minimize=False

Uninstall

pip uninstall jupyterlab_dosbox

jupyterlab_dosbox's People

Contributors

Stargazers

Watchers

Forkers

cualquiercosa327

jupyterlab_dosbox's Issues

Tie in to the debugger

It should be possible to set up calls to DEBUG_EnableDebugger during runtime, to pause execution. It may also be possible to proxy the creation of debug breakpoints (i.e., for int 21h) as well. A full set of proxies to the standard DEBUG.COM might be a bit heavy to implement, but could be quite useful.

Recording via mediastream API

The MediaStream recording API should be straightforward to use:

https://developer.mozilla.org/en-US/docs/Web/API/MediaStream_Recording_API

Set up event listeners

Right now, the event listeners are disabled. I tried turning them on for just the canvas, but it behaves somewhat unpredictably, and gets some random garbage characters. This should be a high priority.

Figure out the whole "state" thing

There's a lot of state that we ... just don't deal with in this extension. File browser tabs that should probably go away when the widget gets disposed, for one thing! And for another, the widget tabs themselves shouldn't re-create unless we're sure the state is correct.

Seems like a good opportunity to learn what the various "dispose" methods do, and figure out how to handle them.

Create icons for the file browser

Right now, we only have BLANK browser icons! How embarrassing! Let's fix that.

Weird resizing animation

When the initial view is added, it resizes strangely. I think this should probably be fixed somehow, but I don't know yet why it's happening. Possibly an issue because we're using DosDirect rather than a worker thread.

Implement IRunningItem for dosbox sessions

Using the model of the RunningTerminal from @jupyterlab/terminal-extension, an entry for each DOSBox instance could be added to the sidebar.

Screenshot does not update till cell finishes run

I am a python newbie so this might be a user error. The issue I have is with db.screenshot() updating within a loop. Currently it appears the new screenshot is only captured when cell completes so the loop never sees the change. Here is the code I am using.

db.screenshot()
plt.imshow(db.last_screenshot)
previous_sc_txt = pytesseract.image_to_string(db.last_screenshot)
string = remove_last_line_from_string(previous_sc_txt)
print()
print("------------------------------------------------------------------")
print("Previous Text")
print()
print(previous_sc_txt)
print("------------------------------------------------------------------")
print()
user_command = input("Enter Action")
db.send_command(user_command)
time.sleep(1)
db.screenshot()
plt.imshow(db.last_screenshot)
last_sc_txt = 1
loop_count = 0
screen_change = 0
while screen_change == 0:
clear_output(wait=True)
time.sleep(1)
db.screenshot()
plt.imshow(db.last_screenshot)
# print(pytesseract.image_to_string(db.last_screenshot))
last_sc_txt = pytesseract.image_to_string(db.last_screenshot)
string = remove_last_line_from_string(last_sc_txt)
print()
print("------------------------------------------------------------------")
print("Current Text - ")
print(loop_count)
print()
print(last_sc_txt)
print("------------------------------------------------------------------")
print()
loop_count += 1
screen_change = string_diff(previous_sc_txt, last_sc_txt)

Callbacks and pausing for core dumps

Right now the process of obtaining a coredump is async, without any kind of notifications. There are patterns that could be used to somewhat sync-ify this, as per the documentation.