From a4394648076f880d82f4088f3e5f1f64fcf4437e Mon Sep 17 00:00:00 2001 From: Cyrill Leutwiler Date: Fri, 25 Apr 2025 13:17:24 +0200 Subject: [PATCH 1/3] update docs for resolc 0.1.0-dev.14 Signed-off-by: Cyrill Leutwiler --- docs/known_issues/index.md | 3 +- docs/revive_compiler/usage.md | 86 ++++++++++++++++++++++++++++++++++- 2 files changed, 86 insertions(+), 3 deletions(-) diff --git a/docs/known_issues/index.md b/docs/known_issues/index.md index f420103..b8386f8 100644 --- a/docs/known_issues/index.md +++ b/docs/known_issues/index.md @@ -15,13 +15,12 @@ The following compiler issues are known and we are working on it. Please do not ### Release -resolc `0.1.0-dev.13` +resolc `0.1.0-dev.14` ### Missing features - [Libraries with public functions are not supported](https://github.com/paritytech/revive/issues/91) - [Automatic import resolution is not supported](https://github.com/paritytech/revive/issues/98) -- The emulated EVM linear contract memory is limited to 64kb in size. Will be fixed with support for metered dynamic memory. - [EIP-4844 opcodes are not supported](https://github.com/paritytech/revive/issues/64) - IPFS metadata hashes are not supported - [Compiled contract artifacts can exceed the pallet static memory limit and fail to deploy](https://github.com/paritytech/revive/issues/96). diff --git a/docs/revive_compiler/usage.md b/docs/revive_compiler/usage.md index 3aac95d..65d502b 100644 --- a/docs/revive_compiler/usage.md +++ b/docs/revive_compiler/usage.md @@ -3,7 +3,91 @@ sidebar_position: 2 --- # Usage +The compiler can be used via the `resolc` CLI interface or supported tooling. + +## Tooling +https://github.com/paritytech/foundry-polkadot +https://github.com/paritytech/hardhat-polkadot ## CLI -## JSON modes +The usage of `resolc` is kept similar to the Ethereum Solidity `solc` compiler. Standard and combined JSON input is supported. We aim to keep it as close to a drop-in replacement to `solc` as possible. However, due to fundamental differences of our contracts stack, there are a few things and options worthwhile to know about in `resolc` which do not exist in Ethereum. + +:::tip + +For a detailed reference about the CLI, please see `resolc --help`. + +::: + +### LLVM optimization levels +``` + -O, --optimization +``` + +`resolc` exposes the optimization level setting for the LLVM backend. The performance and size of compiled contracts varies wiedly between different optimization levels. + +Valid levels are the following: +- `0`: No optimizations are applied +- `1`: Basic optimizations for execution time. +- `2`: Advanced optimizations for execution time. +- `3`: Aggressive optimizations for execution time. +- `s`: Optimize for code size. +- `z`: Aggressively optimize for code size. + +By default, `-O3` is applied. + +### Stack size +``` + --stack-size +``` + +PVM is a register machine with a traditional stack memory space for local variables. This controls the total amount of stack space the contract can use. + +You are incentiviced to keep this value as small as possible: +1. Increasing the heap size will increase startup costs. +2. The stack size contributes to the total memory size a contract can use, which includes the contracts code size + +Default value: 32768 + +:::warning + +If the contract uses more stack memory than configured, it will compile fine but eventually revert execution at runtime! + +::: + +### Heap size +``` + --heap-size +``` + +Unlike the EVM, due to the lack of dynamic memory metering, PVM contracts emulate the EVM heap memory with a static buffer. Consequentially, instead of infinite memory with exponentially growing gas costs, PVM contracts have a finite amount of memory with constant gas costs available. + +You are incentiviced to keep this value as small as possible: 1.Increasing the heap size will increase startup costs. 2.The heap size contributes to the total memory size a contract can use, which includes the contracts code size + +Default value: 65536 + +:::warning + +If the contract uses more heap memory than configured, it will compile fine but eventually revert execution at runtime! + +::: + +### solc +``` + --solc +``` + +Specify the path to the `solc` executable. By default, the one in `${PATH}` is used. + +### Debug artifacts +``` + --debug-output-dir +``` + +Dump all intermediary compiler artifacts to files in the specified directory. This includes the YUL IR, optimized and unoptimized LLVM IR, the ELF shared object and the PVM assembly. Useful for debugging and development purposes. + +### Debug info +``` + -g +``` +Generate source based debug information in the output code file. Useful for debugging and development purposes and disabled by default. From 2d6e4a6d9413039650332e644ceb1598145a32ec Mon Sep 17 00:00:00 2001 From: Cyrill Leutwiler Date: Fri, 25 Apr 2025 13:21:13 +0200 Subject: [PATCH 2/3] tooling Signed-off-by: Cyrill Leutwiler --- docs/revive_compiler/usage.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/revive_compiler/usage.md b/docs/revive_compiler/usage.md index 65d502b..d987a38 100644 --- a/docs/revive_compiler/usage.md +++ b/docs/revive_compiler/usage.md @@ -5,10 +5,6 @@ sidebar_position: 2 # Usage The compiler can be used via the `resolc` CLI interface or supported tooling. -## Tooling -https://github.com/paritytech/foundry-polkadot -https://github.com/paritytech/hardhat-polkadot - ## CLI The usage of `resolc` is kept similar to the Ethereum Solidity `solc` compiler. Standard and combined JSON input is supported. We aim to keep it as close to a drop-in replacement to `solc` as possible. However, due to fundamental differences of our contracts stack, there are a few things and options worthwhile to know about in `resolc` which do not exist in Ethereum. @@ -91,3 +87,6 @@ Dump all intermediary compiler artifacts to files in the specified directory. Th -g ``` Generate source based debug information in the output code file. Useful for debugging and development purposes and disabled by default. + +## Tooling +We provide customized distributions of [hardhat](https://github.com/paritytech/hardhat-polkadot) and [foundry](https://github.com/paritytech/foundry-polkadot) supporting contract compilation via `resolc`. Please refer to their respective docomuntation to learn more. From 55908b1ecc18c08a2d4cdc753c01349ab0d46d85 Mon Sep 17 00:00:00 2001 From: Cyrill Leutwiler Date: Fri, 25 Apr 2025 15:04:56 +0200 Subject: [PATCH 3/3] fix format Signed-off-by: Cyrill Leutwiler --- docs/revive_compiler/usage.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/revive_compiler/usage.md b/docs/revive_compiler/usage.md index d987a38..fa24fc7 100644 --- a/docs/revive_compiler/usage.md +++ b/docs/revive_compiler/usage.md @@ -58,7 +58,9 @@ If the contract uses more stack memory than configured, it will compile fine but Unlike the EVM, due to the lack of dynamic memory metering, PVM contracts emulate the EVM heap memory with a static buffer. Consequentially, instead of infinite memory with exponentially growing gas costs, PVM contracts have a finite amount of memory with constant gas costs available. -You are incentiviced to keep this value as small as possible: 1.Increasing the heap size will increase startup costs. 2.The heap size contributes to the total memory size a contract can use, which includes the contracts code size +You are incentiviced to keep this value as small as possible: +1.Increasing the heap size will increase startup costs. +2.The heap size contributes to the total memory size a contract can use, which includes the contracts code size Default value: 65536