Learning A Library

Hello Everyone!

So my apologies if this is a st00pid question but this is a topic I find I have trouble with for some reason. For the past day or so I have taken a shot at learning how to use ggez, a library for making simple 2d games with rust, and i just cant seem to figure it out. Im not expecting to be a guru with ggez at this point, but I guess I just feel like maybe I am going about this in the completely wrong way. So, my question is: what is your process for learning a new library? what is your mindset going in? how do you prepare for such a task? I know there is not one definite answer to this , but im curious to know alternative approaches. Thanks fellows!

2 Likes

Different people learn differently, what works for me is learning from examples so my usual process is:

  • look at docs, follow doc examples
  • look at project's ./examples/
  • look at who else is using the crate (using reverse dependencies tab, e.g. https://crates.io/crates/ggez/reverse_dependencies)
  • ask questions on project's discord chat or contact the author directly

And by "looking" I mean actually compiling and running and tweaking the code to explore what is possible.

There are also cases when looking at dependant crates reveals a better crate for my needs, when I don't have to write my own wrapper and reuse someone else's.

You can also look at miniquad/macroquad, maybe they provide a better abstraction level for your needs.

2 Likes

If the library is small/medium (ie, it itself doesn't have a tonne of deps), I go straight to the source code. Understanding how the thing works inside is a faster way to understand what API is possible, and where to look for it.

For large libraries, they usually have "guide-level" docs -- annotated examples of building something small, but end-to-end.

3 Likes

So first things first, you absolutely don't need to understand a library in order to use it. For larger codebases (e.g. 100k+) you won't be expected to know all of its nooks and crannies, even if you were the original author.

My preferred way to learn a library is to pull up the API docs or examples and look for the "main" object. Normally there'll be a handful of central concepts that the rest of the library is written around, then you can click around its methods and see what other things it interacts with. Assuming everything was given appropriate names, you can build up a pretty good mental map of the library that way.

For example in the the zip crate (for reading/writing zip files) the two main types are the ZipArchive (for reading) and the ZipWriter (for writing). From there I can start writing a file by passing it a name and some FileOptions, then I use the std::io::Write implementation to write data to that file (because that's what the docs tell me to do), then when I'm done writing all files I'll call the ZipWriter::finish() method to flush everything to disk and do any final cleanup. Those three methods cover the vast majority of my zip archive writing needs.

If you find it hard to understand API docs, something as large and popular as GGEZ will almost certainly also have a bunch of blog posts and tutorials written about it. These will take different approaches and be written by different authors, so there's a good chance you'll find something that clicks.

2 Likes

One non-obvious thing I do when examining any Rust library is glance at its Cargo.toml file – especially the [features] section, which is often important but isn't automatically documented anywhere else. (Crates with decent documentation will usually document the features somewhere, but it's hard to predict where.)

1 Like

Thats not a bad idea at all actually. Never really thought of breaking a library down in such a way. Good pointer.

@qaopm @matklad @Michael-F-Bryan @mbrubeck thank you all for the tips and such. Its refreshing to have been met with a willingness to help, more so than you might even imagine. So again, thanks yall. Ill keep hacking away at it until things start to click, with a slightly different approach perhaps this time.

1 Like