Preparing the toolchain for "official" initial release

[ian-h-chamberlain]

Hey all @rust3ds/active members! I wanted to start some discussion about what we think it will take to consider the Rust 3DS toolchain ready for a preliminary release? Obviously there is still more feature functionality we will probably want to continue adding, but it seems to me like we have a pretty stable foundation to release an initial version.

(also, I'm making this a public organization discussion since Github is deprecating Team discussions).

Below is a checklist of everything I can think of offhand, but please let me know if you can think of other things or have opinions:

• More documentation on using the toolchain ("getting started", etc. as mentioned in Getting started with setup of a Rust3DS dev environment #80, General documentation improvements #32).
  I think it would be nice to set up the wiki for ctru-rs and put stuff like this in there.
• Create an organization-level README / basic explanation of what the project is. This could link to the above wiki
• Document the public API surface as best we can. It's decent now but I think we are probably still missing some stuff, especially in the helper crates like pthread-3ds and rust-linker-fix-3ds.
• Go through the issues backlog and see if there's anything worth fixing/closing as part of the release.
• Make sure the CI pipeline works, and add a workflow for publishing releases. Automatic publishing to crates.io ideally
  • I'd like to make a common CI/CD process we can share between all of the different crates, Github has some options for this
  • For cargo-3ds, we could use something like cargo-dist to release prebuilt binaries, if we want, but it might be overkill
  • Publishing prebuilt example .3dsx might be nice too, but probably not really needed
• Pick initial numbers for each crate and coordinate publishing a release! Just for clarity, I think this is the list of crates we need to start out with:
  • ctru-rs / ctru-sys (probably these should be version locked together and released first)
  • pthread-3ds
  • rust-linker-fix-3ds (maybe rename as well, I think the crate name is just linker-fix-3ds?)
  • not citro3d-rs, I am excited to keep working on it but I don't think it's ready for release yet
• (optional) maybe announce the new release somewhere? This Month in Rust GameDev might be a good place, I'm not sure where else

That all sounds like a lot of work, but I also wanted to mention that I personally will have a lot more spare time for a while and I intend to use a chunk of it to work on this project — so I'm happy to take responsibility for leading this effort and working on the stuff I mentioned above.

Let me know what you think, and if everyone agrees I might try to create a proper project to track all this.

[Meziu]

Great! I'm down to talk about an official release, but there is a lot of work to do. 😃

More documentation on using the toolchain
I think it would be nice to set up the wiki for ctru-rs and put stuff like this in there.

Absolutely. I have small notes to write something like this already, but I'd like some help finding more things to write. We would probably need 3 sections at least:

• Required Setup (install devkitarm and cargo-3ds)
• General Guide (e.g. talking about the default panic handler extensively, how to use the library)
• Unsupported Functionality

Regarding the unsupported functionality, I'm still of the opinion that getting any kind of threading support would be necessary, as it doesn't really seem fair to release ctru-rswith halfbaked dev-only features, like std-threads.
It's also funny to see how I had previously noted lto = true as unsupported, but thanks to the fix regarding the object linking in rustc it's now available!

Create an organization-level README / basic explanation of what the project is. This could link to the above wiki

In general, we could do some work on READMEs (those cool links and icons for docs and build status are nice!).

Document the public API surface as best we can. It's decent now but I think we are probably still missing some stuff, especially in the helper crates like pthread-3ds and rust-linker-fix-3ds.

We should also keep in mind the importance of examples. I bet most people won't look at an extensive guide before reading an example, so streamlining and documenting those well should be a priority.
Regarding the helper crates, I have always had them in mind as non-user-available crates, only needed for underlying implementations of C APIs. I would instead suggest the user not to use them, and look elsewhere, like the std or libc.

Pick initial numbers for each crate and coordinate publishing a release!

In my opinion, ctru-rscan release with a generic version number (like 1.0or 0.5), and the same can be said for pthread-3dsand linker-fix-3ds. However, I would like to underline the importance of ctru-sys's version number, since we could release it with the same version number of libctru (which would double down as a "supported version" number). We'd need to be careful about doc generation though, since we wouldn't be able to easily make a patch release.

Maybe announce the new release somewhere? This Month in Rust GameDev might be a good place, I'm not sure where else

Absolutely yes! "This Month in Rust Gamedev" is already a pretty nice place where to post (mainly to showoff to standard Rust users) but we should also post on the "Nintendo Homebrew" discord and GBATemp, which is the main homebrew forum.

That all sounds like a lot of work, but I also wanted to mention that I personally will have a lot more spare time for a while and I intend to use a chunk of it to work on this project — so I'm happy to take responsibility for leading this effort and working on the stuff I mentioned above.

Thank you for your efforts. High school is currently taking a big chunk of my time so I'm not able to pump out PRs like I did in the past, but knowing you are able to look after the project is nice.

Let me know what you think, and if everyone agrees I might try to create a proper project to track all this.

I never used those, might be a nice place to start.

[Techie-Pi]

I think @Meziu said everything that needs to be said. High school is also taking a great chunk of my time, and I'm still recovering from the surgery I had last summer, so I haven't been able to work on ctru-rs a lot recently 😅

I would like to emphasize the importance of examples and "Getting started" documentation, with these kind of libraries the most difficult part is setting the development environment up and seeing how things are done. Once you understand the basics of how the library is structured is quite easy to just start doing things.

[Techie-Pi]

After rust3ds/cargo-3ds#34 I realized that some projects like cargo-3ds and citro3d-rs do not have a license, and others like pthread-3ds and rust-linker-3ds/shim-3ds do have a license field in the Cargo.toml but do not have a LICENSE file.

ctru-rs, which is the most important piece of this project, has a license field, but it also has outdated authors and no LICENSE file. I think that we should resolve this issues before the initial release to prevent problems in the future.

In my opinion, we should do the same as the wide Rust community and adopt a MIT OR Apache-2.0 license:

• It is in line with current licensing choices.
• The Rust community is already familiar with MIT OR Apache-2.0
• All the advantages that are always said about this combo (legal teams prefer Apache-2.0, Apache-2.0 prevents patent-trolling and yada yada, developers are familiar with MIT, etc.)

I would also like to mention that we could probably relicense ctru-rs if needed:

• Most of the current code was written by @Meziu @ian-h-chamberlain @AzureMaker and me.
• The Zlib license is compatible with various licenses.
• We are able to ask everyone that has ever contributed to this repo to approve the relicensing, it's not something that hasn't been done before. Some big projects with hundreds and hundreds of independent contributors have achieved this without any problems.

(TL;DR We should start thinking about licensing and license choices before the initial release, this isn't the most exciting thing, but it is something that we should definitively do)

[Meziu]

After reading the issue, I have some thoughts to share.

1. Every crate of which I am the original author is going to get released via MIT OR Apache 2.0. This includes cargo-3ds, shim-3ds and pthread-3ds. citro3d-rs is also a new entry in the org, so we’ll count that in too.
2. ctru-sys should be released under Zlib. Raw bindings should hold the same license as the library they bind. This should also be valid for citro3d-sys, though that’s not really a priority right now.
3. ctru-rs should be released under MIT OR Apache 2.0. As you said already, that’s the ecosystem’s licence of choice. A MIT project can have Zlib dependencies without any problems, AFAIK.

[Meziu]

Another thing, we can actually remove the original author file (they will still be credited) without any issues. The ctru-rs we have now is (almost) a complete rework the old 2016 project, which I archived in ctru-rs-old. Zlib only requires us to not "misrepresent" the original software, so a simple acknowledgment in the README with a link to the old project should be enough.

However, relicensing the project under MIT may not be possible, unless we can manage to contact all older contributors. Still, I'm pretty sure it's fine for us to release it unchanged. Zlib is just as permissive as MIT when it comes to using the library as a dependency.

[Meziu]

I've made some PRs about this:

• Fix licensing and credits #112
• Fix licensing shim-3ds#20
• Fix licensing pthread-3ds#25
• Fix/licensing cargo-3ds#35
• Fix licensing citro3d-rs#18

They add the LICENSE files and make small changes to the Toml Manifest.

[ian-h-chamberlain]

Thanks for cleaning this up! I had in the back of my mind this was something we should do for a while but I procrastinated and forgot to write it down as well. Definitely a needed step before we can release.