Struct ethers_solc::Project

pub struct Project<T: ArtifactOutput = ConfigurableArtifacts> {

    pub paths: ProjectPathsConfig,
    pub solc: Solc,
    pub solc_config: SolcConfig,
    pub cached: bool,
    pub build_info: bool,
    pub no_artifacts: bool,
    pub auto_detect: bool,
    pub artifacts: T,
    pub ignored_error_codes: Vec<u64>,
    pub compiler_severity_filter: Severity,
    pub allowed_paths: AllowedLibPaths,
    pub include_paths: IncludePaths,
    pub offline: bool,
    pub slash_paths: bool,
    /* private fields */
}

Represents a project workspace and handles solc compiling of all contracts in that workspace.

Fields

paths: ProjectPathsConfig

The layout of the project

solc: Solc

Where to find solc

solc_config: SolcConfig

How solc invocation should be configured.

cached: bool

Whether caching is enabled

build_info: bool

Whether to output build information with each solc call.

no_artifacts: bool

Whether writing artifacts to disk is enabled

auto_detect: bool

Whether writing artifacts to disk is enabled

artifacts: T

Handles all artifacts related tasks, reading and writing from the artifact dir.

ignored_error_codes: Vec<u64>

Errors/Warnings which match these error codes are not going to be logged

compiler_severity_filter: Severity

The minimum severity level that is treated as a compiler error

allowed_paths: AllowedLibPaths

The paths which will be allowed for library inclusion

include_paths: IncludePaths

The paths which will be used with solc’s --include-path attribute

offline: bool

Offline mode, if set, network access (download solc) is disallowed

slash_paths: bool

Windows only config value to ensure the all paths use / instead of \\, same as solc

This is a noop on other platforms

Implementations

impl Project

pub fn builder() -> ProjectBuilder

Convenience function to call ProjectBuilder::default()

Example

Configure with ConfigurableArtifacts artifacts output

use ethers_solc::Project;
let config = Project::builder().build().unwrap();

To configure any a project with any ArtifactOutput use either

use ethers_solc::Project;
let config = Project::builder().build().unwrap();

or use the builder directly

use ethers_solc::{ConfigurableArtifacts, ProjectBuilder};
let config = ProjectBuilder::<ConfigurableArtifacts>::default().build().unwrap();

impl<T: ArtifactOutput> Project<T>

pub fn artifacts_path(&self) -> &PathBuf

Returns the path to the artifacts directory

pub fn sources_path(&self) -> &PathBuf

Returns the path to the sources directory

pub fn cache_path(&self) -> &PathBuf

Returns the path to the cache file

pub fn build_info_path(&self) -> &PathBuf

Returns the path to the build-info directory nested in the artifacts dir

pub fn root(&self) -> &PathBuf

Returns the root directory of the project

pub fn artifacts_handler(&self) -> &T

Returns the handler that takes care of processing all artifacts

pub fn read_cache_file(&self) -> Result<SolFilesCache>

Convenience function to read the cache file. See also SolFilesCache::read_joined()

pub fn set_solc_jobs(&mut self, jobs: usize)

Sets the maximum number of parallel solc processes to run simultaneously.

Panics

if jobs == 0

pub fn sources(&self) -> Result<Sources>

Returns all sources found under the project’s configured sources path

pub fn rerun_if_sources_changed(&self)

This emits the cargo rerun-if-changed instruction. Which tells Cargo to re-run the build script if a file inside the project’s sources directory has changed.

Use this if you compile a project in a build.rs file.

Example build.rs file

use ethers_solc::{Project, ProjectPathsConfig};
// configure the project with all its paths, solc, cache etc. where the root dir is the current rust project.
let project = Project::builder()
    .paths(ProjectPathsConfig::hardhat(env!("CARGO_MANIFEST_DIR")).unwrap())
    .build()
    .unwrap();
let output = project.compile().unwrap();
// Tell Cargo that if a source file changes, to rerun this build script.
project.rerun_if_sources_changed();

pub fn compile(&self) -> Result<ProjectCompileOutput<T>>

Attempts to compile the contracts found at the configured source location, see ProjectPathsConfig::sources.

NOTE: this does not check if the contracts were successfully compiled, see CompilerOutput::has_error instead.

NB: If the svm feature is enabled, this function will automatically detect solc versions across files.

Example

use ethers_solc::Project;
let project = Project::builder().build().unwrap();
let output = project.compile().unwrap();

pub fn svm_compile(&self, sources: Sources) -> Result<ProjectCompileOutput<T>>

Available on crate feature svm-solc and non-WebAssembly only.

Compiles a set of contracts using svm managed solc installs

This will autodetect the appropriate Solc version(s) to use when compiling the provided Sources. Solc auto-detection follows semver rules, see also Graph::get_input_node_versions

Errors

This returns an error if contracts in the Sources set are incompatible (violate semver rules) with their imports, for example source contract A(=0.8.11) imports dependency C(<0.8.0), which are incompatible.

Example

use ethers_solc::{artifacts::Source, Project, utils};
let project = Project::builder().build().unwrap();
let files = utils::source_files("./src");
let sources = Source::read_all(files).unwrap();
let output = project.svm_compile(sources).unwrap();

pub fn compile_file( &self, file: impl Into<PathBuf> ) -> Result<ProjectCompileOutput<T>>

Available on crate feature svm-solc and non-WebAssembly only.

Convenience function to compile a single solidity file with the project’s settings. Same as Self::svm_compile() but with the given file as input.

Example

use ethers_solc::Project;
let project = Project::builder().build().unwrap();
let output = project.compile_file("example/Greeter.sol").unwrap();

pub fn compile_files<P, I>(&self, files: I) -> Result<ProjectCompileOutput<T>>

where I: IntoIterator<Item = P>, P: Into<PathBuf>,

Convenience function to compile a series of solidity files with the project’s settings. Same as Self::compile() but with the given files as input.

Example

use ethers_solc::Project;
let project = Project::builder().build().unwrap();
let output = project
    .compile_files(
        vec!["examples/Foo.sol", "examples/Bar.sol"]
    ).unwrap();

pub fn compile_sparse<F: FileFilter + 'static>( &self, filter: F ) -> Result<ProjectCompileOutput<T>>

Convenience function to compile only (re)compile files that match the provided FileFilter. Same as Self::compile() but with only with those files as input that match FileFilter::is_match().

Example - Only compile Test files

use ethers_solc::{Project, TestFileFilter};
let project = Project::builder().build().unwrap();
let output = project
    .compile_sparse(
        TestFileFilter::default()
    ).unwrap();

Example - Apply a custom filter

use std::path::Path;
use ethers_solc::Project;
let project = Project::builder().build().unwrap();
let output = project
    .compile_sparse(
        |path: &Path| path.ends_with("Greeter.sol")
    ).unwrap();

pub fn compile_with_version( &self, solc: &Solc, sources: Sources ) -> Result<ProjectCompileOutput<T>>

Compiles the given source files with the exact Solc executable

First all libraries for the sources are resolved by scanning all their imports. If caching is enabled for the Project, then all unchanged files are filtered from the sources and their existing artifacts are read instead. This will also update the cache file and cleans up entries for files which may have been removed. Unchanged files that for which an artifact exist, are not compiled again.

Example

use ethers_solc::{Project, Solc};
let project = Project::builder().build().unwrap();
let sources = project.paths.read_sources().unwrap();
project
    .compile_with_version(
        &Solc::find_svm_installed_version("0.8.11").unwrap().unwrap(),
        sources,
    )
    .unwrap();

pub fn cleanup(&self) -> Result<(), SolcIoError>

Removes the project’s artifacts and cache file

If the cache file was the only file in the folder, this also removes the empty folder.

Example

use ethers_solc::Project;
let project = Project::builder().build().unwrap();
let _ = project.compile().unwrap();
assert!(project.artifacts_path().exists());
assert!(project.cache_path().exists());

project.cleanup();
assert!(!project.artifacts_path().exists());
assert!(!project.cache_path().exists());

pub fn flatten(&self, target: &Path) -> Result<String>

Flattens the target solidity file into a single string suitable for verification.

This method uses a dependency graph to resolve imported files and substitute import directives with the contents of target files. It will strip the pragma version directives and SDPX license identifiers from all imported files.

NB: the SDPX license identifier will be removed from the imported file only if it is found at the beginning of the file.

pub fn standard_json_input( &self, target: impl AsRef<Path> ) -> Result<StandardJsonCompilerInput>

Returns standard-json-input to compile the target contract

Trait Implementations

impl<T: ArtifactOutput> ArtifactOutput for Project<T>

type Artifact = <T as ArtifactOutput>::Artifact

Represents the artifact that will be stored for a Contract

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

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

fn write_contract_extras(&self, contract: &Contract, file: &Path) -> Result<()>

Write additional files for the contract

fn write_extras( &self, contracts: &VersionedContracts, artifacts: &Artifacts<Self::Artifact> ) -> Result<()>

Writes additional files for the contracts if the included in the Contract, such as ir, ewasm, iropt.

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

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

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

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

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

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

The inverse of contract_file_name

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

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

Read the artifact that’s stored at the given path

fn read_cached_artifacts<P, I>( files: I ) -> Result<BTreeMap<PathBuf, Self::Artifact>>

where I: IntoIterator<Item = P>, P: Into<PathBuf>,

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

fn contract_to_artifact( &self, file: &str, name: &str, contract: Contract, source_file: Option<&SourceFile> ) -> Self::Artifact

Convert a contract to the artifact type

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

Convert the compiler output into a set of artifacts

fn standalone_source_file_to_artifact( &self, path: &str, file: &VersionedSourceFile ) -> Option<Self::Artifact>

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

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

Returns the appropriate file name for the conflicting file.

impl<T: ArtifactOutput> AsRef<Project<T>> for TempProject<T>

Available on crate feature project-util only.

fn as_ref(&self) -> &Project<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Debug + ArtifactOutput> Debug for Project<T>

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

Formats the value using the given formatter.