Struct faerie::artifact::Artifact

pub struct Artifact {
    pub name: String,
    pub target: Triple,
    pub is_library: bool,
    // some fields omitted
}

An abstract binary artifact, which contains code, data, imports, and relocations

Fields

name: String

The name of this artifact

target: Triple

The machine target this is intended for

is_library: bool

Whether this is a static library or not

Methods

impl Artifact

pub fn new(target: Triple, name: String) -> Self

Create a new binary Artifact, with target and optional name

pub fn imports<'a>(
    &'a self
) -> Box<dyn Iterator<Item = (&'a str, &'a ImportKind)> + 'a>

Get an iterator over this artifact's imports

pub fn declare_with<T: AsRef<str>, D: Into<Decl>>(
    &mut self,
    name: T,
    decl: D,
    definition: Vec<u8>
) -> Result<(), Error>

Declare and define a new symbolic reference with the given decl and given definition. This is sugar for declare and then define

pub fn declare<T: AsRef<str>, D: Into<Decl>>(
    &mut self,
    name: T,
    decl: D
) -> Result<(), ArtifactError>

Declare a new symbolic reference, with the given decl. Note: All declarations must precede their definitions.

pub fn declarations<T: AsRef<str>, D: Iterator<Item = (T, Decl)>>(
    &mut self,
    declarations: D
) -> Result<(), Error>

Declare a sequence of name, Decl pairs

pub fn define<T: AsRef<str>>(
    &mut self,
    name: T,
    data: Vec<u8>
) -> Result<(), ArtifactError>

Defines a previously declared program object. NB: If you attempt to define an import, this will return an error. If you attempt to define something which has not been declared, this will return an error.

pub fn define_with_symbols<T: AsRef<str>>(
    &mut self,
    name: T,
    data: Vec<u8>,
    symbols: BTreeMap<String, u64>
) -> Result<(), ArtifactError>

Same as define but also allows to add custom symbols referencing a section decl.

Examples

Create a MachO file with a section called .my_section. This section has the content de ad be ef, with the symbol a_symbol referencing to be.

let mut artifact = Artifact::new(target_lexicon::triple!("x86_64-apple-darwin"), "example".to_string());

artifact.declare(".my_section", Decl::section(SectionKind::Data)).unwrap();

let mut section_symbols = BTreeMap::new();
section_symbols.insert("a_symbol".to_string(), 2);
artifact.define_with_symbols(".my_section", vec![0xde, 0xad, 0xbe, 0xef], section_symbols).unwrap();

let _blob = artifact.emit().unwrap();

pub fn import<T: AsRef<str>>(
    &mut self,
    import: T,
    kind: ImportKind
) -> Result<(), Error>

Declare import to be an import with kind. This is just sugar for declare("name", Decl::FunctionImport) or declare("data", Decl::DataImport)

pub fn link<'a>(&mut self, link: Link<'a>) -> Result<(), Error>

Link a relocation at link.at from link.from to link.to NB: If either link.from or link.to is undeclared, then this will return an error. If link.from is an import you previously declared, this will also return an error.

pub fn link_with<'a>(
    &mut self,
    link: Link<'a>,
    reloc: Reloc
) -> Result<(), Error>

A variant of link with a Reloc provided. Has all of the same invariants as link.

pub fn undefined_symbols(&self) -> Vec<String>

Get set of non-import declarations that have not been defined. This must be an empty set in order to emit the artifact.

pub fn emit(&self) -> Result<Vec<u8>, Error>

Emit a blob of bytes representing the object file in the format specified in the target the Artifact was constructed with.

pub fn emit_as(&self, format: BinaryFormat) -> Result<Vec<u8>, Error>

Emit a blob of bytes representing an object file in the given format.

pub fn write(&self, sink: File) -> Result<(), Error>

Emit and write to disk a blob of bytes representing the object file in the format specified in the target the Artifact was constructed with.

pub fn write_as(&self, sink: File, format: BinaryFormat) -> Result<(), Error>

Emit and write to disk a blob of bytes representing an object file in the given format.

Trait Implementations

impl Clone for Artifact

fn clone(&self) -> Artifact

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Artifact

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.