Struct Project

pub struct Project<C: Compiler = MultiCompiler, T: ArtifactOutput<CompilerContract = C::CompilerContract> = ConfigurableArtifacts> {

    pub compiler: C,
    pub paths: ProjectPathsConfig<C::Language>,
    pub settings: C::Settings,
    pub additional_settings: BTreeMap<String, C::Settings>,
    pub restrictions: BTreeMap<PathBuf, RestrictionsWithVersion<<C::Settings as CompilerSettings>::Restrictions>>,
    pub cached: bool,
    pub build_info: bool,
    pub no_artifacts: bool,
    pub artifacts: T,
    pub ignored_error_codes: Vec<u64>,
    pub ignored_file_paths: Vec<PathBuf>,
    pub compiler_severity_filter: Severity,
    pub offline: bool,
    pub slash_paths: bool,
    pub sparse_output: Option<Box<dyn FileFilter>>,
    /* private fields */
}

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

Fields

compiler: C

paths: ProjectPathsConfig<C::Language>

The layout of the project

settings: C::Settings

The compiler settings

additional_settings: BTreeMap<String, C::Settings>

Additional settings for cases when default compiler settings are not enough to cover all possible restrictions.

restrictions: BTreeMap<PathBuf, RestrictionsWithVersion<<C::Settings as CompilerSettings>::Restrictions>>

Mapping from file path to requirements on settings to compile it.

This file will only be included into compiler inputs with profiles which satisfy the restrictions.

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

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

ignored_file_paths: Vec<PathBuf>

Errors/Warnings which match these file paths are not going to be logged

compiler_severity_filter: Severity

The minimum severity level that is treated as a compiler error

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

sparse_output: Option<Box<dyn FileFilter>>

Optional sparse output filter used to optimize compilation.

Implementations

impl Project

pub fn builder() -> ProjectBuilder

Convenience function to call ProjectBuilder::default().

Examples

Configure with ConfigurableArtifacts artifacts output and MultiCompiler compiler:

use foundry_compilers::Project;

let config = Project::builder().build(Default::default())?;

To configure any a project with any ArtifactOutput use either:

use foundry_compilers::Project;

let config = Project::builder().build(Default::default())?;

or use the builder directly:

use foundry_compilers::{multi::MultiCompiler, ConfigurableArtifacts, ProjectBuilder};

let config = ProjectBuilder::<MultiCompiler>::default().build(Default::default())?;

impl<T: ArtifactOutput<CompilerContract = C::CompilerContract>, C: Compiler> Project<C, T>

pub fn artifacts_handler(&self) -> &T

Returns the handler that takes care of processing all artifacts

pub fn settings_profiles(&self) -> impl Iterator<Item = (&str, &C::Settings)>

impl<C: Compiler, T: ArtifactOutput<CompilerContract = C::CompilerContract>> Project<C, T>

where C::Settings: Into<SolcSettings>,

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

Returns standard-json-input to compile the target contract

impl<T: ArtifactOutput<CompilerContract = C::CompilerContract>, C: Compiler> Project<C, T>

pub fn artifacts_path(&self) -> &Path

Returns the path to the artifacts directory

pub fn sources_path(&self) -> &Path

Returns the path to the sources directory

pub fn cache_path(&self) -> &Path

Returns the path to the cache file

pub fn build_info_path(&self) -> &Path

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

pub fn root(&self) -> &Path

Returns the root directory of the project

pub fn read_cache_file(&self) -> Result<CompilerCache<C::Settings>>

Convenience function to read the cache file. See also CompilerCache::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)

Emit the cargo rerun-if-changed instruction.

This 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.

Examples

use foundry_compilers::{Project, ProjectPathsConfig};

// Configure the project with all its paths, solc, cache etc.
// where the root dir is the current Rust project.
let paths = ProjectPathsConfig::hardhat(env!("CARGO_MANIFEST_DIR").as_ref())?;
let project = Project::builder().paths(paths).build(Default::default())?;
let output = project.compile()?;

// Tell Cargo to rerun this build script that if a source file changes.
project.rerun_if_sources_changed();

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

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

Convenience function to compile a single solidity file with the project’s settings.

Examples

use foundry_compilers::Project;

let project = Project::builder().build(Default::default())?;
let output = project.compile_file("example/Greeter.sol")?;

pub fn compile_files<P, I>( &self, files: I, ) -> Result<ProjectCompileOutput<C, 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.

Examples

use foundry_compilers::Project;

let project = Project::builder().build(Default::default())?;
let output = project.compile_files(["examples/Foo.sol", "examples/Bar.sol"])?;

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.

Examples

use foundry_compilers::Project;

let project = Project::builder().build(Default::default())?;
let _ = project.compile()?;
assert!(project.artifacts_path().exists());
assert!(project.cache_path().exists());

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

pub fn find_contract_path(&self, target_name: &str) -> Result<PathBuf>

where T: Clone, C: Clone,

Finds the path of the contract with the given name. Throws error if multiple or no contracts with the same name are found.

pub fn update_output_selection( &mut self, f: impl FnOnce(&mut OutputSelection) + Copy, )

Invokes CompilerSettings::update_output_selection on the project’s settings and all additional settings profiles.

Trait Implementations

impl<T: ArtifactOutput<CompilerContract = C::CompilerContract>, C: Compiler> ArtifactOutput for Project<C, T>

type Artifact = <T as ArtifactOutput>::Artifact

Represents the artifact that will be stored for a Contract

type CompilerContract = <C as Compiler>::CompilerContract

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

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

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

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

fn output_file_name( name: &str, version: &Version, profile: &str, with_version: bool, with_profile: bool, ) -> PathBuf

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

fn output_file( contract_file: &Path, name: &str, version: &Version, profile: &str, with_version: bool, with_profile: bool, ) -> PathBuf

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

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

The inverse of contract_file_name

fn read_cached_artifact(path: &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: &Path, name: &str, contract: C::CompilerContract, source_file: Option<&SourceFile>, ) -> Self::Artifact

Convert a contract to the artifact type

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

Convert the compiler output into a set of artifacts

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.

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

Handler allowing artifacts handler to enforce artifact recompilation.

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

Invoked with all artifacts that were not recompiled.

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

Returns the appropriate file name for the conflicting file.

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

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

impl<C: Clone + Compiler, T: Clone + ArtifactOutput<CompilerContract = C::CompilerContract>> Clone for Project<C, T>

where C::Language: Clone, C::Settings: Clone,

fn clone(&self) -> Project<C, T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C, T> Debug for Project<C, T>

where C: Debug + Compiler, T: Debug + ArtifactOutput<CompilerContract = C::CompilerContract>,

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

Formats the value using the given formatter.