About the annotation in library crates

[xfq]

https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations

If the crate has an std feature, specify this in the first line:

appears identical to the code snippet shown afterward, failing to clearly illustrate the condition. Is this an oversight or a deliberate design choice?

[sffc]

It appears that it changed in 263fdc2#diff-608d8e7dbd13ab7d89b8525eadee573ada2f652cd62b4bc3c99265b1c1937666

CC @robertbastian

[robertbastian]

Yeah that should be

    #![cfg_attr(not(any(test, doc, feature = "std")), no_std)]

[polarathene]

@robertbastian Could you provide context for the addition of the feature constraint?

icu4x/ffi/capi/src/lib.rs

Lines 5 to 6 in 51de0b8

	// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
	#![cfg_attr(not(any(test, feature = "std")), no_std)]

icu4x/ffi/capi/src/lib.rs

Lines 53 to 55 in 51de0b8

	// Renamed so you can't accidentally use it
	#[cfg(target_arch = "wasm32")]
	extern crate std as rust_std;

Wouldn't it be better to take this approach?:

#![cfg_attr(not(any(test, doc)), no_std)]

#[cfg(feature = "std")]
extern crate std;

If you want to ensure that core/alloc is used instead when viable, wouldn't these lints for clippy be a more meaningful way to communicate the concern to anyone when they're encountered?:

// Warn if alloc/core types are imported through std.
#![warn(
    clippy::std_instead_of_core,
    clippy::std_instead_of_alloc,
    // Only relevant if you don't (always) need alloc.
    clippy::alloc_instead_of_core,
)]

---

That advice to use clippy is referenced from this comment.

The other advice to shift the feature gate is from this discussion (notably for the consistency in prelude behaviour):

Tl;dr: don't use #![cfg_attr(not(feature = "std"), no_std)] to have an std feature, always use:

#![no_std]

#[cfg(feature = "std")]
extern crate std;

One line at the top of the crate, and (while wordy) it makes sense. If I don't have the std feature, then I'm no_std.

However, this has a side-effect that can make working with the alloc crate a massive pain: enabling or disabling the std feature changes the [implicit prelude](https://doc.rust-lang.org/reference/names/preludes.html#standard-library-prelude) between `std::prelude` and `core::prelude`. This creates an inconsistency between the std and no_std parts of your library where, for example, you need to explicitly import alloc::format in some code, and don't in others.

Instead, if you declare your crate as unconditionally no_std, with a feature flag to include the std crate, you'll always have the core::prelude, making your code much more consistent between the two features.

Shouldn't these changes then also address the workaround for the wasm32 target with std being renamed to rust_std? 🤔

[polarathene]

FWIW: The referenced commit mentions:

• std::io::ErrorKind is not in core

  In April 2026 core::io::ErrorKind was merged for Rust 1.97 (release due in July 2026).

• icu_capi keeps its std feature, as that's required to build a static library with panic=unwind.
  I'm not sure what the use case for this is, but we use it as a baseline in the size benchmark.

  • panic=unwind will fail to compile without the std crate. Having a std feature in the default feature set is fine to enable that AFAIK.
  • If you needed to support panic=unwind without std, I think you can do so via the unwinding crate? (lacks support for some targets like ARM32)

[robertbastian]

@robertbastian Could you provide context for the addition of the feature constraint?

I don't think I can, these snippets predate me joining the project.

Wouldn't it be better to take this approach?:

I think the only difference is the prelude that is loaded, and it's convenient to use the std prelude when in std mode. Being explicit is also useful, however.

If you want to ensure that core/alloc is used instead when viable, wouldn't these lints for clippy be a more meaningful way to communicate the concern to anyone when they're encountered?:

We already use alloc_instead_of_core, we could adopt the others as well.

[robertbastian]

• "std::io::ErrorKind is not in core". In April 2026 core::io::ErrorKind was merged for Rust 1.97 (release due in July 2026).

This is great news! However, due to our MSRV policy, the earliest we could use 1.97 is in January 2027.

[sffc]

The extern crate std as rust_std; was a workaround from many Rust versions ago where we were getting std types instead of core types. I don't remember exactly in what context. It seems like the Rust maintainers have been improving this area a lot, so this might not be needed anymore.

[polarathene]

The extern crate std as rust_std; was a workaround from many Rust versions ago where we were getting std types instead of core types.

That's because of the problem I covered earlier in an above comment, see the quoted sections.

You presently have #![no_std] as a conditional on the std feature not being used. When really it should always be #![no_std] and only opt-in to extern crate std when the std feature is used. This way you would consistently (regardless of std feature) use the core types and prelude, while the std prelude is excluded and must explicitly import from std when the core prelude doesn't already cover that type (or you need the std version of that type which may have some extra methods available in std).

I don't know about the wasm32 target condition, but for the std feature (which is fine in default set), you should take the proper approach for consistency, you can then drop the rename workaround?

[robertbastian]

You presently have #![no_std] as a conditional on the std feature not being used. When really it should always be #![no_std] and only opt-in to extern crate std when the std feature is used. This way you would consistently (regardless of std feature) use the core types and prelude, while the std prelude is excluded and must explicitly import from std when the core prelude doesn't already cover that type (or you need the std version of that type which may have some extra methods available in std).

I'd be happy to accept a PR to migrate our std features to this. I consider it an improvement to not have std types in the prelude in crates that only conditionally use std.

[polarathene]

This comment can be ignored in favor of PR: #8155 (review)

Collapsed content had a few queries, but I've since gone ahead and made changes based on what context I could figure out.

Collapsed for brevity

I'd be happy to accept a PR to migrate our std features to this.

Proposing the following, which I think addresses the concern if test/doc must have std present (even if not using a std default feature):

-#![cfg_attr(not(any(test, doc)), no_std)]
+#![no_std]
+#[cfg(any(test, doc, feature = "std"))]
extern crate std;

This way std prelude is no longer conditionally present, no_std/std builds should be consistent with this change.

Rest of this comment is just citing some context.

---

icu4x/ffi/capi/src/lib.rs

Lines 53 to 55 in 51de0b8

	// Renamed so you can't accidentally use it
	#[cfg(target_arch = "wasm32")]
	extern crate std as rust_std;

icu4x/ffi/freertos/src/lib.rs

Lines 63 to 67 in 51de0b8

	// Needed for rust runtime stuff
	//
	// renamed so you can't accidentally use it
	#[cfg(not(target_os = "none"))]
	extern crate std as rust_std;

I'm not familiar with the project but I don't see any rust_std imports? So I'm assuming in both cases the target constraint to conditionally gate std are redundant? Potentially they were added as a side-effect of the mentioned prelude inconsistency? 🤷‍♂️

---

I'm not too familiar with the test/doc scenarios, although I have come across this testing article with mention of no_std (although it's old, 2019):

Unfortunately, testing is a bit more complicated for no_std applications such as our kernel. The problem is that Rust's test framework implicitly uses the built-in test library, which depends on the standard library. This means that we can’t use the default test framework for our #[no_std] kernel.

We can see this when we try to run cargo test in our project:

cargo test
   Compiling blog_os v0.1.0 (/…/blog_os)
error[E0463]: can't find crate for `test`

Since the test crate depends on the standard library, it is not available for our bare metal target. While porting the test crate to a #[no_std] context is possible, it is highly unstable and requires some hacks, such as redefining the panic macro.

I suppose that depends how you're testing 🤔 Pretty sure the proposed change above should keep the test/doc support working as intended, they just become additive to std instead of toggling no_std (and the preludes).

---

Looking at some tests, I see the use of extern crate std in function bodies like this:

icu4x/utils/zerotrie/tests/derive_test.rs

Lines 125 to 129 in 2010554

	#[test]
	#[cfg(all(feature = "databake", feature = "alloc"))]
	fn bake_ZeroTrieExtendedCapacity_ZeroVec() {
	use databake::*;
	extern crate std;

My understanding is such tests in a tests/ folder will already have std prelude implicitly, as there is no #![no_std] in the file 🤔 (I don't see any discussion about the use of extern crate std in the PR that contributed it)

Meanwhile in other files there are tests modules instead where extern crate std is added to the top:

icu4x/utils/zerotrie/src/byte_phf/builder.rs

Lines 145 to 151 in 2010554

	#[cfg(test)]
	mod tests {
	use super::*;
	extern crate std;
	use std::print;
	use std::println;

icu4x/utils/zerotrie/src/byte_phf/mod.rs

Lines 284 to 288 in 2010554

	#[cfg(all(test, feature = "alloc"))]
	mod tests {
	use super::*;
	use alloc::vec::Vec;
	extern crate std;

My understanding is that's fine, and if the crate itself doesn't require a std feature (which is the case for zerotrie it appears), then there's no need for toggling std for docs either?

You'd just keep the std usage confined to tests with the extern crate std added to each tests module, or you could have one single instance at the crate root lib.rs like:

// Required for `cargo test`:
#[cfg(test)]
extern crate std;

With other crates that currently opt-out of no_std for tests/docs generically and have no std feature it's less obvious but I'd assume they too would not need a doc constraint, so the above with only a test constraint should be fine?

I don't think there's a case where this would make sense right?:

#[cfg(any(test, doc))]
extern crate std;

[polarathene]

I'd be happy to accept a PR to migrate our std features to this.

Done: #8155 (review)

I am pressed for time and don't really have a machine I can use for juggling more work on atm, but hopefully that PR is of some value 😅

---

EDIT: The style guide docs dropped the feature = std cfg from the snippet in this PR, might have been unintentional?