Lib.rs

Cargo Features

[dependencies]
c-scape = { version = "0.20.3", default-features = false, features = ["std", "thread", "call-main", "log", "atomic-dbg-logger", "env_logger", "max_level_off", "experimental-relocate", "eyra", "take-charge", "coexist-with-libc", "malloc-via-rust-global-alloc", "malloc-via-crates", "threadsafe-setenv", "rustc-dep-of-std", "todo", "deprecated-and-unimplemented", "eh-personality", "eh-personality-continue", "panic-handler", "panic-handler-trap", "global-allocator", "extra-syscalls", "syscall-write", "syscall-openat", "syscall-getpid", "syscall-epoll_create1", "syscall-timerfd_create", "syscall-timerfd_settime", "syscall-fdatasync", "syscall-sync", "syscall-pipe2", "cc"] }

default = coexist-with-libc, std, thread, threadsafe-setenv

These default features are set whenever c-scape is added without default-features = false somewhere in the dependency tree.

std default

Enables std of printf-compat and rustix

rustix:

This enables use of std. Disabling this enables #![no_std], and requires Rust 1.64 or newer.

thread default eyra?

Enables unstable-errno of origin

origin:

Enable unstable support for storing C errno values in the TLS header. This will likely be removed in the future and only exists to make it easier to possibly integrate a dynamic linker written in C in the near future before until a dynamic linker is written in Rust.

call-main eyra?

In "take-charge" mode, this enables code in c-scape to define the origin_start function documented here and call a C ABI-compatible extern main function.

log

Enable logging of program and thread startup and shutdown.

Enables log of origin

atomic-dbg-logger

Install atomic_dbg::log as a logger.

Enables atomic-dbg-logger of origin

env_logger

Install the env_logger crate as a logger.

Enables env_logger of origin

max_level_off

Disable logging.

Enables max_level_off of origin

experimental-relocate

Enable highly experimental support for performing startup-time relocations,
needed to support statically-linked PIE executables.

Enables experimental-relocate of origin

eyra = call-main, malloc-via-crates, take-charge, thread

A feature that pulls in all the individual features needed to use c-scape to write Rust programs completely implemented in Rust.

take-charge eyra?

One of the following two features must be enabled:

Enable this to tell c-scape to take control of the process.

Enables origin-start and signal of origin

coexist-with-libc default

Enable this to tell c-scape to let a libc be in control of the process.

Enables libc of origin

malloc-via-rust-global-alloc

One of the following two features must be enabled:

Enable this to implement malloc using Rust's global allocator.

malloc-via-crates eyra?

Enable this to implement malloc using third-party crates, which is useful to do when using the Rust global allocator is using malloc.

Enables global of rustix-dlmalloc

threadsafe-setenv default

This makes setenv and friends thread-safe by leaking memory.

rustc-dep-of-std

Special feature for use when c-scape is a dependency of std.

Enables rustc-dep-of-std of rustix and rustc-std-workspace-alloc and rustc-std-workspace-core

rustc-std-workspace-core:

Special dependencies used in rustc-dep-of-std mode.

todo

Enable todo!() stubs for not-yet-implemented functions.

deprecated-and-unimplemented

Enable unimplemented!() stubs for deprecated functions.

eh-personality

Provide a #[lang = eh_personality] function suitable for unwinding (for no-std).

If you know your program never unwinds and want smaller code size, use "eh-personality-continue" instead.

This is only needed in no-std builds, as std provides a personality. See the "personality" feature of the unwinding crate for more details.

Enables eh-personality of origin

eh-personality-continue

Provide a #[lang = eh_personality] function that just returns CONTINUE_UNWIND (for no-std). Use this if you know your program will never unwind and don't want any extra code.

Enables eh-personality-continue of origin

panic-handler

Provide a #[panic_handler] function suitable for unwinding (for no-std).

If you know your program never panics and want smaller code size, use "panic-handler-trap" instead.

This is only needed in no-std builds, as std provides a panic handler. See the "panic-handler" feature of the unwinding crate for more details.

Enables panic-handler of origin

panic-handler-trap

Provide a #[panic_handler] function that just traps (for no-std). Use this if you know your program will never panic and don't want any extra code.

Enables panic-handler-trap of origin

global-allocator

Provide a #[global_allocator] function (for no-std).

This is only needed in no-std builds, as std provides a global allocator. Alternatively, you can define the global allocator manually; see the example-crates/custom-allocator example.

Enables global of rustix-dlmalloc

extra-syscalls = syscall-close, syscall-epoll_create1, syscall-fdatasync, syscall-getpid, syscall-open, syscall-openat, syscall-pipe2, syscall-read, syscall-statx, syscall-sync, syscall-syncfs, syscall-timerfd_create, syscall-timerfd_settime, syscall-utimensat, syscall-write

This extends the syscall function with suppport for more syscalls. This is not enabled by default because it increases the code size of syscall by several kibibytes and isn't needed by most Rust programs.

syscall-read syscall-write extra-syscalls?

syscall-open syscall-openat extra-syscalls?

syscall-close syscall-getpid extra-syscalls?

syscall-statx syscall-epoll_create1 extra-syscalls?

syscall-timerfd_create extra-syscalls?

syscall-timerfd_settime extra-syscalls?

syscall-utimensat syscall-fdatasync extra-syscalls?

syscall-syncfs syscall-sync extra-syscalls?

syscall-pipe2 extra-syscalls?

Features from optional dependencies

In crates that don't use the dep: syntax, optional dependencies automatically become Cargo features. These features may have been created by mistake, and this functionality may be removed in the future.

rustix-dlmalloc global-allocator? malloc-via-crates?

cc build implicit feature

Enables cc

Enable the cc dependency to build the empty libc.a and similar libraries from the empty.s source file, instead of using the prebuilt libraries.