doc: add "Comparison to other Projects in the Ecosystem" to lib.rs

This is especially interesting as the `std` implementation of Rust is upcoming.

Author: phip1611

uefi/src/lib.rs

@@ -115,6 +115,74 @@
 //! Contributions in the form of a PR are also highly welcome. Check our
 //! [contributing guide][contributing] for details.
 //!
+//! # Comparison to other Projects in the Ecosystem
+//!
+//! ## Rust `std` implementation
+//!
+//! There is an ongoing effort for a [`std` implementation][rustc-uefi-std] of
+//! the Rust standard library, which allows you to write UEFI programs that look
+//! very similar to normal Rust programs running on top of an OS.
+//!
+//! It is still under development. You can track the progress in the
+//! corresponding [tracking issue][uefi-std-tr-issue].
+//!
+//! Using the `std` implementation simplifies the overall process of producing
+//! the binary. For example, our [`#[entry]`][entry-macro] macro won't be
+//! required any longer. As the `std` implementation evolves over time, you'll
+//! need fewer and fewer abstractions of this crate. For everything not covered
+//! by the `std` implementation, you can obtain relevant structures to work with
+//! our crate via:
+//! - `std::os::uefi::env::boot_services()`
+//! - `std::os::uefi::env::get_system_handle()`
+//! - `std::os::uefi::env::get_system_table()`
+//!
+//! ### Example
+//!
+//! A minimal Rust app utilizing the uefi `std` implementation and leveraging
+//! functionality from `uefi` might look like as follows:
+//!
+//! ```ignore
+//! #![feature(uefi_std)]
+//! #![feature(uefi_std)]
+//!
+//! use std::os::uefi as uefi_std;
+//! use uefi::{Handle, Status};
+//! use uefi::runtime::ResetType;
+//!
+//! /// Performs the necessary setup code for the `uefi` crate.
+//! fn setup_uefi_crate() {
+//!     let st = uefi_std::env::system_table();
+//!     let ih = uefi_std::env::image_handle();
+//!
+//!     // Mandatory setup code for `uefi` crate.
+//!     unsafe {
+//!         uefi::table::set_system_table(st.as_ptr().cast());
+//!
+//!         let ih = Handle::from_ptr(ih.as_ptr().cast()).unwrap();
+//!         uefi::boot::set_image_handle(ih);
+//!     }
+//! }
+//!
+//! fn main() {
+//!     println!("Hello World from uefi_std");
+//!     setup_uefi_crate();
+//!     println!("UEFI-Version is {}", uefi::system::uefi_revision());
+//!     uefi::runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
+//! }
+//! ```
+//!
+//! ## `r-efi`
+//!
+//! [`r-efi`] provides Raw UEFI bindings without high-level convenience similar
+//! to our `uefi-raw` crate, which is part of this  project, but more
+//! feature-complete. It targets a lower-level than our `uefi` crate does.
+//!
+//! # MSRV
+//! <!-- Keep in Sync with README! -->
+//!
+//! The minimum supported Rust version is currently 1.70.
+//! Our policy is to support at least the past two stable releases.
+//!
 //! # License
 //! <!-- Keep in Sync with README! -->
 //!
@@ -129,18 +197,23 @@
 //! Both "EFI" and "UEFI" can be used interchangeably, such as "UEFI image" or
 //! "EFI image". We prefer "UEFI" in our crate and its documentation.
 //!
+//!
 //! [LICENSE]: https://github.com/rust-osdev/uefi-rs/blob/main/uefi/LICENSE
 //! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/
 //! [UEFI]: https://uefi.org/
 //! [Zulip]: https://rust-osdev.zulipchat.com
 //! [`BootServices`]: table::boot::BootServices
 //! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc
 //! [`SystemTable`]: table::SystemTable
+//! [`r-efi`]: https://crates.io/crates/r-efi
+//! [`entry-macro`]: uefi_macros::entry
 //! [`unsafe_protocol`]: proto::unsafe_protocol
 //! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md
 //! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues
 //! [spec]: https://uefi.org/specifications
 //! [unstable features]: https://doc.rust-lang.org/unstable-book/
+//! [rustc-uefi-std]: https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html
+//! [uefi-std-tr-issue]: https://github.com/rust-lang/rust/issues/100499
 
 #![cfg_attr(all(feature = "unstable", feature = "alloc"), feature(allocator_api))]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]