Fix some formatting issues, mostly around comments and whitespace.

This commit is contained in:
2023-05-09 21:29:38 -07:00
parent d0c7e02928
commit c870eeeca3
15 changed files with 95 additions and 95 deletions

View File

@@ -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 {