From f3c46ad2a2c651d6457532fbda62f4db8cee951e Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 5 Sep 2018 15:19:14 -0700 Subject: [PATCH] Add more documentation about `Module` and `Backend`. --- lib/faerie/src/backend.rs | 2 ++ lib/module/README.md | 17 +++++++++++++++-- lib/module/src/backend.rs | 9 +++++++++ lib/simplejit/src/backend.rs | 2 ++ 4 files changed, 28 insertions(+), 2 deletions(-) diff --git a/lib/faerie/src/backend.rs b/lib/faerie/src/backend.rs index 7100bf1917..6aa948703e 100644 --- a/lib/faerie/src/backend.rs +++ b/lib/faerie/src/backend.rs @@ -85,6 +85,8 @@ impl FaerieBuilder { } /// A `FaerieBackend` implements `Backend` and emits ".o" files using the `faerie` library. +/// +/// See the `FaerieBuilder` for a convenient way to construct `FaerieBackend` instances. pub struct FaerieBackend { isa: Box, artifact: faerie::Artifact, diff --git a/lib/module/README.md b/lib/module/README.md index 6bda716324..35f973e916 100644 --- a/lib/module/README.md +++ b/lib/module/README.md @@ -1,7 +1,20 @@ -This crate provides the `Module` trait, which provides an interface for -multiple functions and data to be emitted with +This crate provides module-level functionality, which allow multiple +functions and data to be emitted with [Cranelift](https://crates.io/crates/cranelift) and then linked together. This crate is structured as an optional layer on top of cranelift-codegen. It provides additional functionality, such as linking, however users that require greater flexibility don't need to use it. + +A `Module` is a collection of functions and data objects that are linked +together. `Backend` is a trait that defines an interface for backends +that compile modules into various forms. Most users will use one of the +following `Backend` implementations: + + - `SimpleJITBackend`, provided by [cranelift-simplejit], which JITs + code to memory for direct execution. + - `FaerieBackend`, provided by [cranelift-faerie], which emits native + object files. + +[cranelift-simplejit]: https://crates.io/crates/cranelift-simplejit +[cranelift-faerie]: https://crates.io/crates/cranelift-faerie diff --git a/lib/module/src/backend.rs b/lib/module/src/backend.rs index 42e77acb2f..8138009341 100644 --- a/lib/module/src/backend.rs +++ b/lib/module/src/backend.rs @@ -10,6 +10,15 @@ use ModuleNamespace; use ModuleResult; /// A `Backend` implements the functionality needed to support a `Module`. +/// +/// Two notable implementations of this trait are: +/// - `SimpleJITBackend`, defined in [cranelift-simplejit], which JITs +/// the contents of a `Module` to memory which can be directly executed. +/// - `FaerieBackend`, defined in [cranelift-faerie], which writes the +/// contents of a `Module` out as a native object file. +/// +/// [cranelift-simplejit]: https://docs.rs/cranelift-simplejit/ +/// [cranelift-faerie]: https://docs.rs/cranelift-faerie/ pub trait Backend where Self: marker::Sized, diff --git a/lib/simplejit/src/backend.rs b/lib/simplejit/src/backend.rs index fa3dbdc0fc..ea9dd36115 100644 --- a/lib/simplejit/src/backend.rs +++ b/lib/simplejit/src/backend.rs @@ -84,6 +84,8 @@ impl SimpleJITBuilder { /// A `SimpleJITBackend` implements `Backend` and emits code and data into memory where it can be /// directly called and accessed. +/// +/// See the `SimpleJITBuilder` for a convenient way to construct `SimpleJITBackend` instances. pub struct SimpleJITBackend { isa: Box, symbols: HashMap,