{"id":13595096,"url":"https://github.com/RalfJung/cargo-careful","last_synced_at":"2025-04-09T10:32:48.545Z","repository":{"id":59905186,"uuid":"539980905","full_name":"RalfJung/cargo-careful","owner":"RalfJung","description":"Execute Rust code carefully, with extra checking along the way","archived":false,"fork":false,"pushed_at":"2024-08-10T11:23:44.000Z","size":134,"stargazers_count":403,"open_issues_count":2,"forks_count":15,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-08T11:13:54.995Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RalfJung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-22T12:53:28.000Z","updated_at":"2025-04-03T08:52:36.000Z","dependencies_parsed_at":"2024-01-16T22:18:51.343Z","dependency_job_id":"90873df0-1032-4c0c-b2a6-08c8df5dc243","html_url":"https://github.com/RalfJung/cargo-careful","commit_stats":{"total_commits":94,"total_committers":6,"mean_commits":"15.666666666666666","dds":"0.13829787234042556","last_synced_commit":"1758706665265e893037c36386954ecea4467f3d"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RalfJung%2Fcargo-careful","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RalfJung%2Fcargo-careful/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RalfJung%2Fcargo-careful/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RalfJung%2Fcargo-careful/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RalfJung","download_url":"https://codeload.github.com/RalfJung/cargo-careful/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247829512,"owners_count":21002997,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T16:01:43.884Z","updated_at":"2025-04-09T10:32:48.528Z","avatar_url":"https://github.com/RalfJung.png","language":"Rust","funding_links":[],"categories":["Rust","Programming Languages","Dynamic Checkers"],"sub_categories":[],"readme":"# cargo-careful\n\n`cargo careful` is a tool to run your Rust code extra carefully -- opting into a bunch of\nnightly-only extra checks that help detect Undefined Behavior, and using a standard library with\ndebug assertions.\nThe standard library does check for some Undefined Behavior when the program is built\nwith debug assertions, but some of these checks are disabled because their performance\nimpact was considered too high.\nFor example, it will find the alignment issue in the following snippet:\n\n```rust\nfn main() {\n    let arr = [1u8, 2, 3, 4];\n    for n in [0, 1] {\n        let val = unsafe { arr.as_ptr().add(n).cast::\u003cu16\u003e().read() };\n        println!(\"The value is {val}!\");\n    }\n}\n```\n\nTo use `cargo careful`, first install it:\n\n```\ncargo install cargo-careful\n```\n\nand then run the following in your project:\n\n```\ncargo +nightly careful test\n```\n\nYou can also `cargo +nightly careful run` to execute a binary crate. All `cargo test` and `cargo\nrun` flags are supported.\n\nRunning `cargo careful` requires a recent nightly toolchain. Nightly versions from the last 3 months\nare supported.\n\nThe first time you run `cargo careful`, it needs to run some setup steps, which requires the\n`rustc-src` rustup component -- the tool will offer to install it for you if needed.\n\n## What does it do?\n\n### Detect Undefined Behavior\n\nThe most important thing `cargo careful` does is that it builds the standard library with debug\nassertions.\nThe standard library does check for some Undefined Behavior when the program is built\nwith debug assertions, but some of these checks are disabled because their performance\nimpact was considered too high.\nFurthermore, `cargo careful` sets some flags that tell rustc to insert extra run-time checks.\n\nHere are some of the checks this enables:\n\n- `ptr.read()`/`ptr.write(v)` check that the pointer is aligned and non-null.\n- The collection types perform plenty of internal consistency checks.\n- `mem::zeroed` and the deprecated `mem::uninitialized` panic if the type does not allow that kind\n  of initialization (with a check that is stricter than the default). (This is `-Zstrict-init-checks`.)\n- Extra UB-checking is done during const-evaluation. (This is `-Zextra-const-ub-checks`.)\n\nThat said, there is a lot of Undefined Behavior that is *not* detected by `cargo careful`; check out\n[Miri](https://github.com/rust-lang/miri) if you want to be more exhaustively covered.\nThe advantage of `cargo careful` over Miri is that it works on all code, supports using arbitrary system and C FFI functions, and is much faster.\n\n### RUSTFLAGS\n\n`cargo careful` honors the `CARGO_ENCODED_RUSTFLAGS` and `RUSTFLAGS` environment variables as well\nas the `build.rustflags` cargo setting (in that order, the first one being set is used). It\ncurrently does *not* honor the `target.rustflags` settings as that would require re-implementing all\nthe target `cfg` logic from cargo. The flags are applied to *both* the sysroot build and the program\nitself.\n\n### Sanitizing\n\n`cargo careful` can additionally build and run your program and standard library\nwith a sanitizer. This feature is experimental and disabled by default.\n\nThe [underlying `rustc` feature](https://doc.rust-lang.org/nightly/unstable-book/compiler-flags/sanitizer.html)\ndoesn't play well with [procedural macros](https://doc.rust-lang.org/reference/procedural-macros.html).\nIf you see error messages involving procedural macros during the build, they\ncan sometimes be solved by specifying a target (which can be the same as the host),\ne.g., `--target=x86_64-unknown-linux-gnu`.\n\nTo use a sanitizer, pass the command-line flag `-Zcareful-sanitizer=\u003cyour_sanitizer\u003e` to `cargo careful`.\nThe list of supported sanitizers and targets can be found\n[here](https://doc.rust-lang.org/nightly/unstable-book/compiler-flags/sanitizer.html).\nIf you pass `-Zcareful-sanitizer` without specifying a sanitizer, [`AddressSanitizer`](https://clang.llvm.org/docs/AddressSanitizer.html)\nwill be used.\n\nBy default, when using `AddressSanitizer`, `cargo careful` will disable memory leak checking by\nsetting `ASAN_OPTIONS=detect_leaks=0` in your program's environment, as memory leaks are not\nusually a soundness or correctness issue. If you set the `ASAN_OPTIONS` environment variable\nyourself (to any value, including an empty string), that will override this behavior.\n\n### Main Thread Checker\n\n`cargo careful` automatically enables [Apple's Main Thread Checker](https://developer.apple.com/documentation/xcode/diagnosing-memory-thread-and-crash-issues-early#Detect-improper-UI-updates-on-background-threads) on macOS, iOS, tvOS and watchOS targets, whenever the user has Xcode installed.\n\nThis helps diagnosing issues with executing thread-unsafe functionality off the main thread on those platforms.\n\n### `cfg` flag\n\n`cargo careful` sets the `careful` configuration flag, so you can use Rust's compile-time\nconditional mechanisms (`#[cfg(careful)]`, `#[cfg_attr(careful, ...)]`, `cfg!(careful)`) to check\nwhether code is being run carefully.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRalfJung%2Fcargo-careful","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRalfJung%2Fcargo-careful","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRalfJung%2Fcargo-careful/lists"}