Move all examples to a common location

[thomaseizinger]

Description

For reasons such as modularity, the libp2p library is divided into several sub-crates. Users however are expected to mostly interact with libp2p through the libp2p meta-crate.

Currently, we have two kinds of examples:

• Several examples showcasing the use of the libp2p crate: https://github.com/libp2p/rust-libp2p/tree/master/examples
• Examples in individual crates, showcasing how to use a particular protocol:
  • https://github.com/libp2p/rust-libp2p/tree/master/protocols/rendezvous/examples
  • https://github.com/libp2p/rust-libp2p/tree/master/protocols/dcutr/examples
  • https://github.com/libp2p/rust-libp2p/tree/master/protocols/identify/examples

I propose to remove all examples from individual crates (including the examples/ directory from the libp2p crate) and instead, create a set of dedicated binary crates that showcase various examples.

It is important that the new examples are dedicated crates!

• Dedicated crates have their own manifest and don't share a dependency tree. This ensures that an example actually compiles with the set of specified dependencies (and features)
• Dedicated crates allow us to group multiple binaries into one example. This is useful for protocols like rendezvous where you have binaries fulfilling different roles.

Motivation

• One place to showcase how to use libp2p. Users often don't navigate down the directory tree to find a particular example of a protocol.
• Showcase the use of the libp2p API without introducing circular dependencies: Avoid circular dependencies in workspace #3053
• Dedicated example crates are directly copy-pasteable for users, thus allowing for a better way to get started.

Current Implementation

Examples are all over the place and introduce circular dependencies.

Are you planning to do it yourself in a pull request?

Maybe.

[mxinden]

The proposal sounds fine to me. I don't have a strong opinion here. I agree with adding the priority:nicetohave label here.

[yellowred]

@thomaseizinger I could help with examples. Do you think they should be in a separate repo or just as autonomous binaries in rust-libp2p/examples folder? I could start with moving the existing ones to the new home and then working on adding QUIC example.

[thomaseizinger]

@thomaseizinger I could help with examples. Do you think they should be in a separate repo or just as autonomous binaries in rust-libp2p/examples folder? I could start with moving the existing ones to the new home and then working on adding QUIC example.

I think having them in the same workspace still makes sense otherwise there is always follow-up work to do in another repository when we make API changes and they can get more easily out of sync.

Most importantly, I'd like the examples to be dedicated crates, not just "cargo examples" if you know what I mean. Currently, we need to manually list the examples and activate features otherwise they don't compile. If they are dedicated crates with a manifest, we can just list the features that are necessary for a particular example. This should also be more user-friendly because it can be copy-pasted and has more documentation value.

As we do this, I envisioned that we also do some tidy-up to remove some duplication. To start with, we can leave that to a minimum though. I think simply moving all examples into one place already has a lot of value and gives us a better foundation to work with!

[yellowred]

@thomaseizinger Sounds good. I drafter a PR for the chat example. Will move the other examples a bit later. We might tidy up some of the interfaces if possible, eg development_transport. Also I noticed that macros feature is probably required for NetworkBehaviour to be recognized, however it is not mentioned in the docs (or maybe I missed it).

[thomaseizinger]

Also I noticed that macros feature is probably required for NetworkBehaviour to be recognized, however it is not mentioned in the docs (or maybe I missed it).

The macros features has only been added recently and yes it is very much possible that we forgot to update some of the documentation.

We might tidy up some of the interfaces if possible, eg development_transport.

Yes. I'd like to rename that to something like "recommended transport"? For example, in my opinion, it shouldn't support mplex because we want to discourage people from using mplex unless necessary for legacy applications.

I am not sure how controversial that is so I'd rather not block any of this work on it :)

[yellowred]

Also I noticed that macros feature is probably required for NetworkBehaviour to be recognized, however it is not mentioned in the docs (or maybe I missed it).

The macros features has only been added recently and yes it is very much possible that we forgot to update some of the documentation.

Tokio specified what every feature flag does in the lib.rs docs https://github.com/tokio-rs/tokio/blob/master/tokio/src/lib.rs#L305. We can do the same for libp2p.

We might tidy up some of the interfaces if possible, eg development_transport.

Yes. I'd like to rename that to something like "recommended transport"? For example, in my opinion, it shouldn't support mplex because we want to discourage people from using mplex unless necessary for legacy applications.

I am not sure how controversial that is so I'd rather not block any of this work on it :)

Sure, it can be done in another PR. IMO the whole method should be abolished in favor of an example with all "recommended" features for others to copy and modify as they see fit. Another option is to rename it to default_transport(), so everybody would use it whether it is TCP or quic or something else inside. I don't know what this library is used for generally to understand the implications.

[thomaseizinger]

Also I noticed that macros feature is probably required for NetworkBehaviour to be recognized, however it is not mentioned in the docs (or maybe I missed it).

The macros features has only been added recently and yes it is very much possible that we forgot to update some of the documentation.

Tokio specified what every feature flag does in the lib.rs docs https://github.com/tokio-rs/tokio/blob/master/tokio/src/lib.rs#L305. We can do the same for libp2p.

That is not a bad idea. I wish that cargo would support adding docs to features. Docs.rs already supports listing all features: https://docs.rs/crate/libp2p/latest/features

With listing them again I am worried that we will forget updating that list but maybe that is just something we have to accept.