End user experience

[TylerBloom]

I know this project is still very much under construction, but I think it is a good idea to think about who we expect/intend to use this project and how we expect them to use it. I'll start by sharing what my thoughts are.

I imagine two groups of people might want to use this project. The first group is ROM authors. They are the people who will write a main function and logic for a game and then be able to run some command(s) and have a ROM that people can either play in an emulator or physical device. The second group is library authors who develop libraries for the first group. For example, people might want to build a simple game engine to help make building games easier, a library to help manage all of the static assets for a game (like sprite maps), or a library to help with testing.

The second group, library authors, will need/want a mostly safe API to interact with the various parts of memory. They will want to provide higher-level controls over things like the DMA registers, interrupts, audio registers, etc. For these users, we should be able to model most of the different parts of the Gameboy. In theory, this is the group of people that could replace GBDK in Rust (or make Rust binding to GBDK).

The first group, ROM authors, will need/want two things. Some people might want to build everything by themselves. They will want a nice, safe API to interact with. Some people will want to use the tools and libraries others have built (in Rust). Regardless, ROM authors will want a nice way to interact to compile their code into a ROM. I think the cargo-shuttle project is a good example that we can use as a model.

Shuttle is a service for describing the infrastructure that your web service needs inside your code. They provide libraries for interacting with their runtime and extra services (e.g. secret management, databases, etc), and they provide a cargo plugin for managing, compiling, and deploying your projects. We should consider something similar. Instead of forcing users to compile their Rust project, get the LLVM IR, generate C code with that IR, compile that C code into Z80 assembly, assemble that into GBZ80 object code, and finally link everything together in the final ROM, we should eventually provide a tool that does all of that for our users. This will make managing all of the intermediate files easier because we are doing it programmatically. Also, if we decide to update the build process (maybe because we are replacing a tool/step), ensuring our users use the new process will be much easier.

Again, this project is still growing quickly, but I think it is a good idea to have an end goal. This way, we are building in a direction and our future users will have a better experience. Let me know what you think!

[zlfn]

For ROM authors

I agree we need to consider end user experience. For now, user have to download/build all build dependencies manually, but I was planning to provide pre-built binaries.

Instead of forcing users to compile their Rust project, get the LLVM IR, generate C code with that IR, compile that C code into Z80 assembly, assemble that into GBZ80 object code, and finally link everything together in the final ROM, we should eventually provide a tool that does all of that for our users.

There is already a binary crate in this project that does this. https://github.com/zlfn/rust-gb/blob/main/xtask/build-rom/src/main.rs
This crate allows you to run the whole process just by typing cargo build-rom. It also provides the process of compiling ROMs from c or llvm-ir for debugging.
Currently, the cargo-xtask pattern is used to provide the cargo build-rom command, but this may be replaced with a binary sometime.

The end goal of the user experience is to install rust-gb through cargo install, so that users can build Rust crates to Game Boy ROM with cargo build-rom commands. But I'm not sure if I can upload the LLVM binary to crates.io. Maybe users have to use a command like cargo install-rustgb.

For Library authors

I hope users can upload the library to crates.io like any Rust crate, and manage them with Cargo.toml.

Biggest issue at the moment is that I bundle Rust code to make it one LLVM-IR file. With this structure, users can't use external crates.

[TylerBloom]

The end goal of the user experience is to install rust-gb through cargo install, so that users can build Rust crates to Game Boy ROM with cargo build-rom commands. But I'm not sure if I can upload the LLVM binary to crates.io. Maybe users have to use a command like cargo install-rustgb.

Loading the LLVM binary will be difficult. That said, you should be able to do that through the application that in installed or you can have users install it themselves and make a note that they need to install LLVM 17 in the usage guide.

The reason I bring this up is that I have had a really hard time getting this project to work. I'm working on a PR to help with the notes, but, currently, the project is very hard to use. That's understandable because it is still a working prototype, but making the project easier to use for new users should be something we focus on soon.

Biggest issue at the moment is that I bundle Rust code to make it one LLVM-IR file. With this structure, users can't use external crates.

This is a big issue. There are several projects that currently exist that would be helpful for users (heapless, zerocopy, bytemuck, dervie_more, and more). To make this project useable for others, this is a problem that definitely needs to be solved.

[zlfn]

Loading the LLVM binary will be difficult. That said, you should be able to do that through the application that in installed or you can have users install it themselves and make a note that they need to install LLVM 17 in the usage guide.

First of all, I agree that the project build process is very complicated. Even for me, I have to the build entire LLVM to set up a build environment. Maybe we can publish LLVM-CBE and LLVM's pre-built files and allow users to download them through curl or etc.

This is a big issue. There are several projects that currently exist that would be helpful for users (heapless, zerocopy, bytemuck, dervie_more, and more). To make this project useable for others, this is a problem that definitely needs to be solved.

I also want to fix this, but I need to find a way to replace the build step that consists of rustc with cargo build, and deal with multiple llvm-ir files that are created.
However, even if we fix this issue, we probably won't be able to use external crates that aren't designed for rust-gb. One more major problem is that we can't use all of core. Whenever I need a function of core, I refer to Rust's source code and reprogram it back to C one by one.

This problem arises because we don't get to use a few of the obvious features from modern CPUs like u64 and f32 in Game Boy and SDCC and it also because it's hard to upload the entire core binary to Game Boy ROM. Other crates have never taken this into account, so I think even no_std crates are not available. I actually tried to use format_no_std crate and failed.

[TylerBloom]

One more major problem is that we can't use all of core

Hmm... that is a problem, but I imagine that is caused by the standard library (core, alloc, std) are shipped to users pre-compiled. I think this would have fairly large effects downstream. If you can not use any functions from core (are types accessible?), then writing nearly any application will become much more difficult. And, like you said, crates would have to be designed for this build system. Almost every crate uses functions from core.

[zlfn]

@TylerBloom
I just updated README.md and published llvm-cbe binary to my server. You can now setup rust-gb development environment with several commands. (Tested in Arch and Ubuntu docker) I'd appreciate it if you could test it and let me know the results.

git clone https://github.com/zlfn/rust-gb
cd rust-gb
mise install
curl https://mirror.zlfn.space/rust-gb/setup.sh | sh

I'm still doing a few tests about core. As of now, we can't use f32, f64 and u64, which is pretty problematic.
But I found SDCC supports float, long long as an additional header file, so it might be possible to compile a core if there are no other issues (All double have to be post-processed to float).

Also, instead of bundling Rust files, bundling llvm-ir files with llvm-link will likely compile without bundling processing, so I'll try it and post the follow-up in issue #9 .

[zlfn]

#10
I tried compiling core today, but unfortunately, due to incompleteness of llvm-cbe, it was impossible to compile.
We need a contribute to llvm-cbe and Rust, so for now, I'll use the C implementation as it is now, and move on to the core compilation when llvm-cbe and Rust are ready.