Lib.rs

Cargo Features

[dependencies]
c-scape = { version = "0.15.44", default-features = false, features = ["std", "thread", "call-main", "define-mem-functions", "use-compiler-builtins", "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", "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, use-compiler-builtins

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?

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.

define-mem-functions eyra?

Should c-scape provide C ABI definitions of memcpy etc. (using compiler_builtins::mem) or should it rely on compiler_builtins being linked in and providing those definitions?

use-compiler-builtins default

Should c-scape's memcpy etc. use compiler-builtins?

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, define-mem-functions, 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-signal, origin-start, origin-thread 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-unimplemented functions.

deprecated-and-unimplemented

Enable unimplemented!() stubs for deprecated functions.

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 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.