The purpose of the examples folders

[HasturDev]

So I attempted to use some of the examples folders on a fresh install of linux and it seems that they don't work out of the box. I fixed one to build each file out of the box as though it was a standalone main.rs on a fresh linux system. Should I create a fork and push this or is the examples purpose supposed to be something different? https://github.com/HasturDev/pingora/tree/main/pingora-proxy/examples

[johnhurt]

I had the same question when I started working in rust. The examples folder is a cargo-specific thing. It lets the create author include runnable examples without creating multiple full-fledged cargo projects for each. The good thing about it is those projects are type checked and guaranteed to compile with the version of the crate they are with. You can run each example pretty easily with cargo run --example load_balancer for load_balancer.rs.

The bad part is you can't run those examples easily outside of the crate's context.

[johnhurt]

Yeah, we have one walk through like that in our QuickStart guide, but more would be nice.

[HasturDev]

Alright then I'll take these, turn them into a walk through folder, pr and see what you guys think

[johnhurt]

Awesome! That would be amazing 🤩

[JosiahParry]

fwiw this aspect of rust development is something i still find quite challenging after even 2 years. The examples aren't useful without being able to actually run them locally. They lead to more confusion than anything. The cargo run --example works only if you clone the whole repository which is not what one will be doing when they use the crate.

all that to say, @HasturDev, I agree with you and am finding the pingora docs / examples wanting.

[HasturDev]

Cool I did all the stuff and created a starting tutorial so everyone would know how I write them and request or add anything. I put all the files inside the tutorials folder and once this is merged I'll work on making sure that these files all get tutorials for them

#461

[HasturDev]

So I did the push, but it error'd out in a way that I don't understand @johnhurt do you know what the issue might be?