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

Implementations

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<(), ArtifactError>

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<(), ArtifactError>

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 with the given data. 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.

See the documentation for Data for the difference from define_zero_init.

pub fn define_zero_init<T: AsRef<str>>(
    &mut self,
    name: T,
    size: usize
) -> Result<(), ArtifactError>

Defines a previously declared program object with all zeros. 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>, D: Into<Data>>(
    &mut self,
    name: T,
    data: D,
    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", Data::Blob(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<(), ArtifactError>

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<(), ArtifactError>

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<(), ArtifactError>

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>, ArtifactError>

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>, ArtifactError>

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

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

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<(), ArtifactError>

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

Trait Implementations

impl Clone for Artifact

pub fn clone(&self) -> Artifact

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Artifact

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.