[Coding Guideline]: Assure visibility of `unsafe` tokens in unsafe code

[workingjubilee]

Chapter

Program Structure and Compilation

Guideline Title

Use at least Rust Edition 2024

Category

Required

Status

Draft

Release Begin

1.85

Release End

latest

FLS Paragraph ID

fls_8kqo952gjhaf

Decidability

Decidable

Scope

Crate

Tags

readability,reduce-human-error

Amplification

Use at least Rust Edition 2024 to enforce unsafe tokens must be made visible in all locations where the compiler is aware an unsafe obligation extends to the code.

Exception(s)

No response

Rationale

In Rust Edition 2024, several forms of code which involved explicit usage of unsafe tokens in new locations (attributes and extern blocks) were made mandatory. Due to backwards compatibility concerns, these did not previously require unsafe. Some cases involving unsafe attributes were still linted against in some previous Rust versions by the unsafe_code lint, after it was discovered they had safety concerns, but due to backwards compatibility concerns they did not initially require use of a visible unsafe token. In Rust Edition 2024, however, it is both possible and required to use unsafe appropriately in these contexts.

Non-Compliant Example - Prose

An extern block can cause UB if it is misdeclared. This applies even if the definitions are not called, as the wrong definition may still prevail, especially after linking is considered.

Non-Compliant Example - Code

use std::ffi;

// If another function by this name is in the compiled object's namespace,
// Rust allows undefined behavior from the program linker or loader.
// An `unsafe` token is not required in Rust 2021, though it is linted as such.
#[no_mangle]
fn something() {}

extern "C" {
    // If malloc in the compiled object's namespace accepts a usize argument, 
    // the compiler may generate code for calls to this function using this definition,
    // thus the runtime behavior is undefined.
    fn malloc(size: f32) -> *mut ffi::c_void;
}

Compliant Example - Prose

Using at least Rust Edition 2024 enforces that these things that involve safety obligations require the unsafe token.

Compliant Example - Code

use std::ffi;

#[unsafe(no_mangle)]
fn something() {}

unsafe extern "C" {
    // Here the assumption is that malloc is the one defined by C's stdlib.h
    // and that size_of::<usize>() == size_of::<size_t>()
    fn malloc(size: usize) -> *mut ffi::c_void;
    fn free(ptr: *mut ffi::c_void);
}

[github-actions]

📋 RST Preview for Coding Guideline

This is an automatically generated preview of your coding guideline in reStructuredText format.

📁 Target Location

Create a new file: src/coding-guidelines/program-structure-and-compilation/gui_ZDLZzjeOwLSU.rst.inc

Note: The .rst.inc extension prevents Sphinx from auto-discovering the file.
It will be included via the chapter's index.rst.

We add it to this path, to allow the newly added guideline to appear in the correct chapter.

🗂️ Update Chapter Index

Update src/coding-guidelines/program-structure-and-compilation/index.rst to include gui_ZDLZzjeOwLSU.rst.inc, like so:

Chapter Name Here <- chapter heading inside of `src/coding-guidelines/program-structure-and-compilation/index.rst`
=================

.. include:: gui_7y0GAMmtMhch.rst.inc -| existing guidelines
.. include:: gui_ADHABsmK9FXz.rst.inc  |
...                                    |
...                                    |
.. include:: gui_RHvQj8BHlz9b.rst.inc  |
.. include:: gui_dCquvqE1csI3.rst.inc -|
.. include:: gui_ZDLZzjeOwLSU.rst.inc <- your new guideline to add

🧪 Code Example Test Results

⚠️ 2 of 2 code example(s) failed to compile

Example	Status	Details
Non-Compliant #1	❌ Fail	error[E0601]: main function not found in crate test...
Compliant #1	❌ Fail	error[E0601]: main function not found in crate test...

🔍 Click for detailed error messages

Non-Compliant Example #1:

error[E0601]: `main` function not found in crate `test`
  --> /tmp/tmpura3olxx/test.rs:14:2
   |
14 | }
   |  ^ consider adding a `main` function to `/tmp/tmpura3olxx/test.rs`
error: aborting due to 1 previous error
For more information about this error, try `rustc --explain E0601`.

Compliant Example #1:

error[E0601]: `main` function not found in crate `test`
  --> /tmp/tmphm2x63jf/test.rs:11:2
   |
11 | }
   |  ^ consider adding a `main` function to `/tmp/tmphm2x63jf/test.rs`
error: aborting due to 1 previous error
For more information about this error, try `rustc --explain E0601`.

Note: Code examples are tested with rustc --edition=2021.
Hidden lines (prefixed with # ) are included in compilation.
Examples without a fn main() are automatically wrapped.

📝 How to Use This

1. Fork the repository (if you haven't already) and clone it locally
2. Create a new branch from main:

   git checkout main
   git pull origin main
   git checkout -b guideline/your-descriptive-branch-name

3. Create the guideline file:

   mkdir -p src/coding-guidelines/program-structure-and-compilation

4. Copy the RST content below into a new file named gui_ZDLZzjeOwLSU.rst.inc
5. Update the chapter index - Add an include directive to src/coding-guidelines/program-structure-and-compilation/index.rst:

   .. include:: gui_ZDLZzjeOwLSU.rst.inc

   Keep the includes in alphabetical order by guideline ID.
6. Build locally to verify the guideline renders correctly:

   ./make.py

7. Commit and push your changes:

   git add src/coding-guidelines/program-structure-and-compilation/
   git commit -m "Add guideline: <your guideline title>"
   git push origin guideline/your-descriptive-branch-name

8. Open a Pull Request against main

📄 Click to expand RST content

.. SPDX-License-Identifier: MIT OR Apache-2.0
   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors

.. guideline:: Use at least Rust Edition 2024
    :id: gui_ZDLZzjeOwLSU
    :category: required
    :status: draft
    :release: 1.85-latest
    :fls: fls_8kqo952gjhaf
    :decidability: decidable
    :scope: crate
    :tags: readability,reduce-human-error

    Use at least Rust Edition 2024 to enforce ``unsafe`` tokens must be made visible in all locations where the compiler is aware an ``unsafe`` obligation extends to the code.

    .. rationale::
        :id: rat_eQV3s9ggNegr
        :status: draft

        In Rust Edition 2024, several forms of code which involved explicit usage of ``unsafe`` tokens in new locations (attributes and ``extern`` blocks) were made mandatory. Due to backwards compatibility concerns, these did not previously require ``unsafe``. Some cases involving ``unsafe`` attributes were still linted against in some previous Rust versions by the ``unsafe_code`` lint, after it was discovered they had safety concerns, but due to backwards compatibility concerns they did not initially require use of a visible ``unsafe`` token. In Rust Edition 2024, however, it is both possible and required to use ``unsafe`` appropriately in these contexts.

    .. non_compliant_example::
        :id: non_compl_ex_FdmuPXGZr4EO
        :status: draft

        An ``extern`` block can cause UB if it is misdeclared. This applies even if the definitions are not called, as the wrong definition may still prevail, especially after linking is considered.

        .. rust-example::

            use std::ffi;

            // If another function by this name is in the compiled object's namespace,
            // Rust allows undefined behavior from the program linker or loader.
            // An `unsafe` token is not required in Rust 2021, though it is linted as such.
            #[no_mangle]
            fn something() {}

            extern "C" {
                // If malloc in the compiled object's namespace accepts a usize argument, 
                // the compiler may generate code for calls to this function using this definition,
                // thus the runtime behavior is undefined.
                fn malloc(size: f32) -> *mut ffi::c_void;
            }


    .. compliant_example::
        :id: compl_ex_wR1FEyLRKmrq
        :status: draft

        Using at least Rust Edition 2024 enforces that these things that involve safety obligations require the ``unsafe`` token.

        .. rust-example::

            use std::ffi;

            #[unsafe(no_mangle)]
            fn something() {}

            unsafe extern "C" {
                // Here the assumption is that malloc is the one defined by C's stdlib.h
                // and that size_of::<usize>() == size_of::<size_t>()
                fn malloc(size: usize) -> *mut ffi::c_void;
                fn free(ptr: *mut ffi::c_void);
            }

---

_{🤖 This comment was automatically generated from the issue content. It will be updated when you edit the issue body.}

[workingjubilee]

Oh it does that after every edit huh... well.

I'm recommending this as mandatory, but you could allow, as an alternative, using a fairly annoying set of lints enabled together, on a specific earlier Rust version before Rust 1.85.

You could also say each specific reason as its own thing, I just lumped them together because the "we finally make this an error" landed in a somewhat lumpy way.

[PLeVasseur]

Oh it does that after every edit huh... well.

Oh... that's not intentional. The intent was to have a single comment that gets updated. 🙃

Will try to debug.

edit: Should be fixed now to update the comment rather than make a new one. I'll go delete these extra comments which are older.

[rcseacord]

@workingjubilee i think this rule is very good but I think I would come at it from a different angle. "Use at least Rust Edition 2024" feels like something that will become dated/obsolete very quickly. And I would think the compliant solution for this would be testing in the source code for an early version of Rust and then immediately failing.

Instead, I would change the title and the focus to "Ensure unsafe tokens are visible in all locations where the compiler is aware an unsafe obligation extends to the code." or something like that.

I think you can then mention that Rust Edition 2024 and later enforce conformance with this rule and maybe also list the annoying set of linters enabled together, on a specific earlier version before Rust 1.85.

I sort of feel like the code could be correct without the use of any linters? We're really talking about a property of the source code I think, not the build environment.

[rcseacord]

Things like "Rust Edition 2024 enforces that these things that involve safety obligations require the unsafe token" is obviously a little vague. We should probably have a precise enumeration.