Fix some formatting issues, mostly around comments and whitespace.
This commit is contained in:
@@ -1,28 +1,28 @@
|
||||
//! # The compiler backend: generation of machine code, both static and JIT.
|
||||
//!
|
||||
//!
|
||||
//! This module is responsible for taking our intermediate representation from
|
||||
//! [`crate::ir`] and turning it into Cranelift and then into object code that
|
||||
//! can either be saved to disk or run in memory. Because the runtime functions
|
||||
//! for NGR are very closely tied to the compiler implentation, we also include
|
||||
//! information about these functions as part of the module.
|
||||
//!
|
||||
//!
|
||||
//! ## Using the `Backend`
|
||||
//!
|
||||
//!
|
||||
//! The backend of this compiler can be used in two modes: a static compilation
|
||||
//! mode, where the goal is to write the compiled object to disk and then link
|
||||
//! it later, and a JIT mode, where the goal is to write the compiled object to
|
||||
//! memory and then run it. Both modes use the same `Backend` object, because
|
||||
//! they share a lot of behaviors. However, you'll want to use different variants
|
||||
//! based on your goals:
|
||||
//!
|
||||
//!
|
||||
//! * Use `Backend<ObjectModule>`, constructed via [`Backend::object_file`],
|
||||
//! if you want to compile to an object file on disk, which you're then going
|
||||
//! to link to later.
|
||||
//! * Use `Backend<JITModule>`, constructed via [`Backend::jit`], if you want
|
||||
//! to do just-in-time compilation and are just going to run things immediately.
|
||||
//!
|
||||
//!
|
||||
//! ## Working with Runtime Functions
|
||||
//!
|
||||
//!
|
||||
//! For now, runtime functions are pretty easy to describe, because there's
|
||||
//! only one. In the future, though, the [`RuntimeFunctions`] object is there to
|
||||
//! help provide a clean interface to them all.
|
||||
@@ -45,7 +45,7 @@ use target_lexicon::Triple;
|
||||
const EMPTY_DATUM: [u8; 8] = [0; 8];
|
||||
|
||||
/// An object representing an active backend.
|
||||
///
|
||||
///
|
||||
/// Internally, this object holds a bunch of state useful for compiling one
|
||||
/// or more functions into an object file or memory. It can be passed around,
|
||||
/// but cannot currently be duplicated because some of that state is not
|
||||
@@ -64,7 +64,7 @@ pub struct Backend<M: Module> {
|
||||
|
||||
impl Backend<JITModule> {
|
||||
/// Create a new JIT backend for compiling NGR into memory.
|
||||
///
|
||||
///
|
||||
/// The provided output buffer is not for the compiled code, but for the output
|
||||
/// of any `print` expressions that are evaluated. If set to `None`, the output
|
||||
/// will be written to `stdout` as per normal, but if a String buffer is provided,
|
||||
@@ -95,7 +95,7 @@ impl Backend<JITModule> {
|
||||
|
||||
/// Given a compiled function ID, get a pointer to where that function was written
|
||||
/// in memory.
|
||||
///
|
||||
///
|
||||
/// The data at this pointer should not be mutated unless you really, really,
|
||||
/// really know what you're doing. It can be run by casting it into a Rust
|
||||
/// `fn() -> ()`, and then calling it from normal Rust.
|
||||
@@ -106,7 +106,7 @@ impl Backend<JITModule> {
|
||||
|
||||
impl Backend<ObjectModule> {
|
||||
/// Generate a backend for compiling into an object file for the given target.
|
||||
///
|
||||
///
|
||||
/// This backend will generate a single output file per `Backend` object, although
|
||||
/// that file may have multiple functions defined within it. Data between those
|
||||
/// functions (in particular, strings) will be defined once and shared between
|
||||
@@ -139,11 +139,11 @@ impl Backend<ObjectModule> {
|
||||
|
||||
impl<M: Module> Backend<M> {
|
||||
/// Define a string within the current backend.
|
||||
///
|
||||
///
|
||||
/// Note that this is a Cranelift [`DataId`], which then must be redeclared inside the
|
||||
/// context of any functions or data items that want to use it. That being said, the
|
||||
/// string value will be defined once in the file and then shared by all referencers.
|
||||
///
|
||||
///
|
||||
/// This function will automatically add a null character (`'\0'`) to the end of the
|
||||
/// string, to ensure that strings are non-terminated for interactions with other
|
||||
/// languages.
|
||||
@@ -163,7 +163,7 @@ impl<M: Module> Backend<M> {
|
||||
}
|
||||
|
||||
/// Define a global variable within the current backend.
|
||||
///
|
||||
///
|
||||
/// These variables can be shared between functions, and will be exported from the
|
||||
/// module itself as public data in the case of static compilation. There initial
|
||||
/// value will be null.
|
||||
@@ -179,7 +179,7 @@ impl<M: Module> Backend<M> {
|
||||
}
|
||||
|
||||
/// Get a pointer to the output buffer for `print`ing, or `null`.
|
||||
///
|
||||
///
|
||||
/// As suggested, returns `null` in the case where the user has not provided an
|
||||
/// output buffer; it is your responsibility to check for this case and do
|
||||
/// something sensible.
|
||||
@@ -192,7 +192,7 @@ impl<M: Module> Backend<M> {
|
||||
}
|
||||
|
||||
/// Get any captured output `print`ed by the program during execution.
|
||||
///
|
||||
///
|
||||
/// If an output buffer was not provided, or if the program has not done any
|
||||
/// printing, then this function will return an empty string.
|
||||
pub fn output(self) -> String {
|
||||
|
||||
Reference in New Issue
Block a user