[Docs] Use cargo-rx to run examples within the project

[rnag]

• I have looked for existing issues (including closed) about this

Feature Request

Hi 👋

I feel this is a great project, even though I haven't looked too much into its internals and use case. I just wanted to let you know about a project cargo-rx I have come up with for abstracting away cargo run --example.

As of the latest version, it supports running Cargo crates (with binary targets) within the examples/ folder, thanks to a related issue that was opened, rnag/cargo-rx#19.

I would suggest updating the relevant documentation in the axum project to mention that rx can be used in place of cargo run --example. Check it out and let me what you think about it. I can also help you update the docs if you're interested.

The rx command-line tool correctly identifies all 46 (runnable) targets within the project's examples/ folder.

Here is some example usage:

$ rx
$ rx chat

Here is a selection window from the console (note the example name to run can also be searched/filtered)

Motivation

No other motivation other than awareness, and plus I feel it would be truly beneficial for other developers and users, especially those that check out or clone the project locally.

Proposal

Update documentation in examples/README.md, and elsewhere as needed. I can also help to update the docs as needed.

Alternatives

The (current) alternative that can be used is cargo run, passing --manifest-path and/or --bin as needed. However, that is hit-or-miss and requires knowing the specific example to run, or else cd-ing into each example directory one at a time.

[davidpdrsn]

Cool project but I don't think we can use it for the axum repo. The repo is used by a lot of people with different setups and we can't expect people to install non-standard tools, unless we have a good reason to do so.

You can already do cargo run -p which prints out all the targets:

❯ cargo run -p
error: "--package <SPEC>" requires a SPEC format value, which can be any package ID specifier in the dependency graph.
Run `cargo help pkgid` for more information about SPEC format.

Possible packages/workspace members:
    axum
    axum-core
    axum-extra
    axum-macros
    example-anyhow-error-response
    example-chat
    example-consume-body-in-extractor-or-middleware
    example-cors
    example-customize-extractor-error
    example-customize-path-rejection
    example-error-handling-and-dependency-injection
    example-form
    example-global-404-handler
    example-graceful-shutdown
    example-handle-head-request
    example-hello-world
    example-http-proxy
    example-hyper-1-0
    example-jwt
    example-key-value-store
    listen-multiple-addrs
    example-low-level-openssl
    example-low-level-rustls
    example-multipart-form
    example-oauth
    example-parse-body-based-on-content-type
    example-print-request-response
    example-prometheus-metrics
    example-query-params-with-empty-strings
    example-readme
    example-rest-grpc-multiplex
    example-reverse-proxy
    example-routes-and-handlers-close-together
    example-sessions
    example-simple-router-wasm
    example-sqlx-postgres
    example-sse
    example-static-file-server
    example-stream-to-file
    example-templates
    example-testing
    example-testing-websockets
    example-tls-rustls
    example-todos
    example-tokio-postgres
    example-tracing-aka-logging
    example-unix-domain-socket
    example-validator
    example-versioning
    example-websockets

I think that's good enough.

[rnag]

No worries @davidpdrsn ! And just to clarify I did not mean it should be required, only that including a suggestion in examples/README.md could be helpful in case others want to use an alternate approach.

Also, rx provides a few benefits to default approach with cargo run -p:

• the examples can be run at root level of project, i.e. without cd into examples folder first
• fuzzy auto-completion and search for example to run, in case the name is forgotten somehow
• remember last-run example, so can easily be run again

I have additionally tested out cargo-rx on Mac/Windows extensively, so I would say it's not platform-dependent at all.

However, I understand that not all projects can utilize it due to high volume of users and with users with different setups etc. In that case, please do let me know if any plans change in the future.