Trait foundry_compilers::ArtifactOutput

source · 
pub trait ArtifactOutput {
    type Artifact: Artifact + DeserializeOwned + Serialize + Debug + Send + Sync;


Show 17 methods    // Required methods
    fn contract_to_artifact(
        &self,
        _file: &Path,
        _name: &str,
        contract: Contract,
        source_file: Option<&SourceFile>
    ) -> Self::Artifact;
    fn standalone_source_file_to_artifact(
        &self,
        _path: &Path,
        _file: &VersionedSourceFile
    ) -> Option<Self::Artifact>;

    // Provided methods
    fn on_output<C>(
        &self,
        contracts: &VersionedContracts,
        sources: &VersionedSourceFiles,
        layout: &ProjectPathsConfig<C>,
        ctx: OutputContext<'_>
    ) -> Result<Artifacts<Self::Artifact>> { ... }
    fn handle_artifacts(
        &self,
        _contracts: &VersionedContracts,
        _artifacts: &Artifacts<Self::Artifact>
    ) -> Result<()> { ... }
    fn output_file_name(name: impl AsRef<str>) -> PathBuf { ... }
    fn output_file_name_versioned(
        name: impl AsRef<str>,
        version: &Version
    ) -> PathBuf { ... }
    fn conflict_free_output_file(
        already_taken: &HashSet<String>,
        conflict: PathBuf,
        contract_file: impl AsRef<Path>,
        artifacts_folder: impl AsRef<Path>
    ) -> PathBuf { ... }
    fn output_file(
        contract_file: impl AsRef<Path>,
        name: impl AsRef<str>
    ) -> PathBuf { ... }
    fn output_file_versioned(
        contract_file: impl AsRef<Path>,
        name: impl AsRef<str>,
        version: &Version
    ) -> PathBuf { ... }
    fn contract_name(file: impl AsRef<Path>) -> Option<String> { ... }
    fn output_exists(
        contract_file: impl AsRef<Path>,
        name: impl AsRef<str>,
        root: impl AsRef<Path>
    ) -> bool { ... }
    fn read_cached_artifact(path: impl AsRef<Path>) -> Result<Self::Artifact> { ... }
    fn read_cached_artifacts<T, I>(
        files: I
    ) -> Result<BTreeMap<PathBuf, Self::Artifact>>
       where I: IntoIterator<Item = T>,
             T: Into<PathBuf> { ... }
    fn get_artifact_path(
        ctx: &OutputContext<'_>,
        already_taken: &HashSet<String>,
        file: &Path,
        name: &str,
        artifacts_folder: &Path,
        version: &Version,
        versioned: bool
    ) -> PathBuf { ... }
    fn output_to_artifacts<C>(
        &self,
        contracts: &VersionedContracts,
        sources: &VersionedSourceFiles,
        ctx: OutputContext<'_>,
        layout: &ProjectPathsConfig<C>
    ) -> Artifacts<Self::Artifact> { ... }
    fn is_dirty(
        &self,
        _artifact_file: &ArtifactFile<Self::Artifact>
    ) -> Result<bool> { ... }
    fn handle_cached_artifacts(
        &self,
        _artifacts: &Artifacts<Self::Artifact>
    ) -> Result<()> { ... }

}
Expand description

Handler invoked with the output of solc

Implementers of this trait are expected to take care of crate::Contract to crate::ArtifactOutput::Artifact conversion and how that Artifact type is stored on disk, this includes artifact file location and naming.

Depending on the crate::Project contracts and their compatible versions, The project compiler may invoke different solc executables on the same solidity file leading to multiple crate::CompilerOutputs for the same .sol file. In addition to the solidity file to contract relationship (1-N*) crate::VersionedContracts also tracks the contract to (artifact + solc version) relationship (1-N+).

Required Associated Types§

source

type Artifact: Artifact + DeserializeOwned + Serialize + Debug + Send + Sync

Represents the artifact that will be stored for a Contract

Required Methods§

source

fn contract_to_artifact( &self, _file: &Path, _name: &str, contract: Contract, source_file: Option<&SourceFile> ) -> Self::Artifact

Convert a contract to the artifact type

This is the core conversion function that takes care of converting a Contract into the associated Artifact type. The SourceFile is also provided

source

fn standalone_source_file_to_artifact( &self, _path: &Path, _file: &VersionedSourceFile ) -> Option<Self::Artifact>

This converts a SourceFile that doesn’t contain any contract definitions (interfaces, contracts, libraries) to an artifact.

We do this because not all SourceFiles emitted by solc have at least 1 corresponding entry in the contracts section of the solc output. For example for an errors.sol that only contains custom error definitions and no contract, no Contract object will be generated by solc. However, we still want to emit an Artifact for that file that may include the ast, docs etc., because other tools depend on this, such as slither.

Provided Methods§

source

fn on_output<C>( &self, contracts: &VersionedContracts, sources: &VersionedSourceFiles, layout: &ProjectPathsConfig<C>, ctx: OutputContext<'_> ) -> Result<Artifacts<Self::Artifact>>

Handle the aggregated set of compiled contracts from the solc crate::CompilerOutput.

This will be invoked with all aggregated contracts from (multiple) solc CompilerOutput. See crate::AggregatedCompilerOutput

source

fn handle_artifacts( &self, _contracts: &VersionedContracts, _artifacts: &Artifacts<Self::Artifact> ) -> Result<()>

Invoked after artifacts has been written to disk for additional processing.

source

fn output_file_name(name: impl AsRef<str>) -> PathBuf

Returns the file name for the contract’s artifact Greeter.json

source

fn output_file_name_versioned( name: impl AsRef<str>, version: &Version ) -> PathBuf

Returns the file name for the contract’s artifact and the given version Greeter.0.8.11.json

source

fn conflict_free_output_file( already_taken: &HashSet<String>, conflict: PathBuf, contract_file: impl AsRef<Path>, artifacts_folder: impl AsRef<Path> ) -> PathBuf

Returns the appropriate file name for the conflicting file.

This should ensure that the resulting PathBuf is conflict free, which could be possible if there are two separate contract files (in different folders) that contain the same contract:

src/A.sol::A src/nested/A.sol::A

Which would result in the same PathBuf if only the file and contract name is taken into account, Self::output_file.

This return a unique output file

source

fn output_file( contract_file: impl AsRef<Path>, name: impl AsRef<str> ) -> PathBuf

Returns the path to the contract’s artifact location based on the contract’s file and name

This returns contract.sol/contract.json by default

source

fn output_file_versioned( contract_file: impl AsRef<Path>, name: impl AsRef<str>, version: &Version ) -> PathBuf

Returns the path to the contract’s artifact location based on the contract’s file, name and version

This returns contract.sol/contract.0.8.11.json by default

source

fn contract_name(file: impl AsRef<Path>) -> Option<String>

The inverse of contract_file_name

Expected to return the solidity contract’s name derived from the file path sources/Greeter.sol -> Greeter

source

fn output_exists( contract_file: impl AsRef<Path>, name: impl AsRef<str>, root: impl AsRef<Path> ) -> bool

Whether the corresponding artifact of the given contract file and name exists

source

fn read_cached_artifact(path: impl AsRef<Path>) -> Result<Self::Artifact>

Read the artifact that’s stored at the given path

§Errors

Returns an error if - The file does not exist - The file’s content couldn’t be deserialized into the Artifact type

source

fn read_cached_artifacts<T, I>( files: I ) -> Result<BTreeMap<PathBuf, Self::Artifact>>
where I: IntoIterator<Item = T>, T: Into<PathBuf>,

Read the cached artifacts that are located the paths the iterator yields

See Self::read_cached_artifact()

source

fn get_artifact_path( ctx: &OutputContext<'_>, already_taken: &HashSet<String>, file: &Path, name: &str, artifacts_folder: &Path, version: &Version, versioned: bool ) -> PathBuf

Generates a path for an artifact based on already taken paths by either cached or compiled artifacts.

source

fn output_to_artifacts<C>( &self, contracts: &VersionedContracts, sources: &VersionedSourceFiles, ctx: OutputContext<'_>, layout: &ProjectPathsConfig<C> ) -> Artifacts<Self::Artifact>

Convert the compiler output into a set of artifacts

Note: This does only convert, but NOT write the artifacts to disk, See Self::on_output()

source

fn is_dirty( &self, _artifact_file: &ArtifactFile<Self::Artifact> ) -> Result<bool>

Handler allowing artifacts handler to enforce artifact recompilation.

source

fn handle_cached_artifacts( &self, _artifacts: &Artifacts<Self::Artifact> ) -> Result<()>

Invoked with all artifacts that were not recompiled.

Object Safety§

This trait is not object safe.

Implementors§