cerc-io/solidity
11
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/develop' into breaking

Browse Source
This commit is contained in:
chriseth
2020-11-24 16:22:03 +01:00
parent a0a02f2307 2d235bf7b0
commit 253889cbf1
322 changed files with 1066 additions and 403 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/functions.rst
+18 -9
View File
@@ -275,7 +275,10 @@ A contract can have at most one ``receive`` function, declared using
``receive() external payable { ... }``
(without the ``function`` keyword).
This function cannot have arguments, cannot return anything and must have
``external`` visibility and ``payable`` state mutability. It is executed on a
``external`` visibility and ``payable`` state mutability.
It can be virtual, can override and can have modifiers.
The receive function is executed on a
call to the contract with empty calldata. This is the function that is executed
on plain Ether transfers (e.g. via ``.send()`` or ``.transfer()``). If no such
function exists, but a payable :ref:`fallback function <fallback-function>`
@@ -339,15 +342,22 @@ Below you can see an example of a Sink contract that uses function ``receive``.
Fallback Function
=================
A contract can have at most one ``fallback`` function, declared using ``fallback () external [payable]``
(without the ``function`` keyword).
This function cannot have arguments, cannot return anything and must have ``external`` visibility.
It is executed on a call to the contract if none of the other
A contract can have at most one ``fallback`` function, declared using either ``fallback () external [payable]``
or ``fallback (bytes calldata _input) external [payable] returns (bytes memory _output)``
(both without the ``function`` keyword).
This function must have ``external`` visibility. A fallback function can be virtual, can override
and can have modifiers.
The fallback function is executed on a call to the contract if none of the other
functions match the given function signature, or if no data was supplied at
all and there is no :ref:`receive Ether function <receive-ether-function>`.
The fallback function always receives data, but in order to also receive Ether
it must be marked ``payable``.
If the version with parameters is used, ``_input`` will contain the full data sent to the contract
(equal to ``msg.data``) and can return data in ``_output``. The returned data will not be
ABI-encoded. Instead it will be returned without modifications (not even padding).
In the worst case, if a payable fallback function is also used in
place of a receive function, it can only rely on 2300 gas being
available (see :ref:`receive Ether function <receive-ether-function>`
@@ -364,12 +374,11 @@ operations as long as there is enough gas passed on to it.
to distinguish Ether transfers from interface confusions.
.. note::
Even though the fallback function cannot have arguments, one can still use ``msg.data`` to retrieve
any payload supplied with the call.
After having checked the first four bytes of ``msg.data``,
If you want to decode the input data, you can check the first four bytes
for the function selector and then
you can use ``abi.decode`` together with the array slice syntax to
decode ABI-encoded data:
``(c, d) = abi.decode(msg.data[4:], (uint256, uint256));``
``(c, d) = abi.decode(_input[4:], (uint256, uint256));``
Note that this should only be used as a last resort and
proper functions should be used instead.
docs/grammar/Solidity.g4
+30 -6
View File
@@ -84,7 +84,8 @@ contractBodyElement:
constructorDefinition
| functionDefinition
| modifierDefinition
| fallbackReceiveFunctionDefinition
| fallbackFunctionDefinition
| receiveFunctionDefinition
| structDefinition
| enumDefinition
| stateVariableDeclaration
@@ -189,9 +190,32 @@ locals[
(Semicolon | body=block);
/**
* Definitions of the special fallback and receive functions.
* Definition of the special fallback function.
*/
fallbackReceiveFunctionDefinition
fallbackFunctionDefinition
locals[
boolean visibilitySet = false,
boolean mutabilitySet = false,
boolean virtualSet = false,
boolean overrideSpecifierSet = false,
boolean hasParameters = false
]
:
kind=Fallback LParen (parameterList { $hasParameters = true; } )? RParen
(
{!$visibilitySet}? External {$visibilitySet = true;}
| {!$mutabilitySet}? stateMutability {$mutabilitySet = true;}
| modifierInvocation
| {!$virtualSet}? Virtual {$virtualSet = true;}
| {!$overrideSpecifierSet}? overrideSpecifier {$overrideSpecifierSet = true;}
)*
( {$hasParameters}? Returns LParen returnParameters=parameterList RParen | {!$hasParameters}? )
(Semicolon | body=block);
/**
* Definition of the special receive function.
*/
receiveFunctionDefinition
locals[
boolean visibilitySet = false,
boolean mutabilitySet = false,
@@ -199,10 +223,10 @@ locals[
boolean overrideSpecifierSet = false
]
:
kind=(Fallback | Receive) LParen RParen
kind=Receive LParen RParen
(
{!$visibilitySet}? visibility {$visibilitySet = true;}
| {!$mutabilitySet}? stateMutability {$mutabilitySet = true;}
{!$visibilitySet}? External {$visibilitySet = true;}
| {!$mutabilitySet}? Payable {$mutabilitySet = true;}
| modifierInvocation
| {!$virtualSet}? Virtual {$virtualSet = true;}
| {!$overrideSpecifierSet}? overrideSpecifier {$overrideSpecifierSet = true;}
docs/installing-solidity.rst
+120 -11
View File
@@ -92,8 +92,8 @@ When using this interface it is not necessary to mount any directories.
docker run ethereum/solc:stable --standard-json < input.json > output.json
Binary Packages
===============
Linux Packages
==============
Binary packages of Solidity are available at
`solidity/releases <https://github.com/ethereum/solidity/releases>`_.
@@ -143,6 +143,16 @@ Arch Linux also has packages, albeit limited to the latest development version:
pacman -S solidity
Gentoo Linux has an `Ethereum overlay <https://overlays.gentoo.org/#ethereum>`_ that contains a Solidity package.
After the overlay is setup, ``solc`` can be installed in x86_64 architectures by:
.. code-block:: bash
emerge dev-lang/solidity
macOS Packages
==============
We distribute the Solidity compiler through Homebrew
as a build-from-source version. Pre-built bottles are
currently not supported.
@@ -179,12 +189,109 @@ Install it using ``brew``:
# eg. Install 0.4.8
brew install solidity.rb
Gentoo Linux has an `Ethereum overlay <https://overlays.gentoo.org/#ethereum>`_ that contains a solidity package.
After the overlay is setup, ``solc`` can be installed in x86_64 architectures by:
Static Binaries
===============
.. code-block:: bash
We maintain a repository containing static builds of past and current compiler versions for all
supported platforms at `solc-bin`_. This is also the location where you can find the nightly builds.
emerge dev-lang/solidity
The repository is not only a quick and easy way for end users to get binaries ready to be used
out-of-the-box but it is also meant to be friendly to third-party tools:
- The content is mirrored to https://binaries.soliditylang.org where it can be easily downloaded over
HTTPS without any authentication, rate limiting or the need to use git.
- Content is served with correct `Content-Type` headers and lenient CORS configuration so that it
can be directly loaded by tools running in the browser.
- Binaries do not require installation or unpacking (with the exception of older Windows builds
bundled with necessary DLLs).
- We strive for a high level of backwards-compatibility. Files, once added, are not removed or moved
without providing a symlink/redirect at the old location. They are also never modified
in place and should always match the original checksum. The only exception would be broken or
unusable files with a potential to cause more harm than good if left as is.
- Files are served over both HTTP and HTTPS. As long as you obtain the file list in a secure way
(via git, HTTPS, IPFS or just have it cached locally) and verify hashes of the binaries
after downloading them, you do not have to use HTTPS for the binaries themselves.
The same binaries are in most cases available on the `Solidity release page on Github`_. The
difference is that we do not generally update old releases on the Github release page. This means
that we do not rename them if the naming convention changes and we do not add builds for platforms
that were not supported at the time of release. This only happens in ``solc-bin``.
The ``solc-bin`` repository contains several top-level directories, each representing a single platform.
Each one contains a ``list.json`` file listing the available binaries. For example in
``emscripten-wasm32/list.json`` you will find the following information about version 0.7.4:
.. code-block:: json
{
"path": "solc-emscripten-wasm32-v0.7.4+commit.3f05b770.js",
"version": "0.7.4",
"build": "commit.3f05b770",
"longVersion": "0.7.4+commit.3f05b770",
"keccak256": "0x300330ecd127756b824aa13e843cb1f43c473cb22eaf3750d5fb9c99279af8c3",
"urls": [
"bzzr://16c5f09109c793db99fe35f037c6092b061bd39260ee7a677c8a97f18c955ab1",
"dweb:/ipfs/QmTLs5MuLEWXQkths41HiACoXDiH8zxyqBHGFDRSzVE5CS"
]
}
This means that:
- You can find the binary in the same directory under the name
`solc-emscripten-wasm32-v0.7.4+commit.3f05b770.js <https://github.com/ethereum/solc-bin/blob/gh-pages/emscripten-wasm32/solc-emscripten-wasm32-v0.7.4+commit.3f05b770.js>`_.
Note that the file might be a symlink, and you will need to resolve it yourself if you are not using
git to download it or your file system does not support symlinks.
- The binary is also mirrored at https://binaries.soliditylang.org/emscripten-wasm32/solc-emscripten-wasm32-v0.7.4+commit.3f05b770.js.
In this case git is not necessary and symlinks are resolved transparently, either by serving a copy
of the file or returning a HTTP redirect.
- The file is also available on IPFS at `QmTLs5MuLEWXQkths41HiACoXDiH8zxyqBHGFDRSzVE5CS`_.
- The file might in future be available on Swarm at `16c5f09109c793db99fe35f037c6092b061bd39260ee7a677c8a97f18c955ab1`_.
- You can verify the integrity of the binary by comparing its keccak256 hash to
``0x300330ecd127756b824aa13e843cb1f43c473cb22eaf3750d5fb9c99279af8c3``. The hash can be computed
on the command line using ``keccak256sum`` utility provided by `sha3sum`_ or `keccak256() function
from ethereumjs-util`_ in JavaScript.
.. warning::
Due to the strong backwards compatibility requirement the repository contains some legacy elements
but you should avoid using them when writing new tools:
- Use ``emscripten-wasm32/`` (with a fallback to ``emscripten-asmjs/``) instead of ``bin/`` if
you want the best performance. Until version 0.6.1 we only provided asm.js binaries.
Starting with 0.6.2 we switched to `WebAssembly builds`_ with much better performance. We have
rebuilt the older versions for wasm but the original asm.js files remain in ``bin/``.
The new ones had to be placed in a separate directory to avoid name clashes.
- Use ``emscripten-asmjs/`` and ``emscripten-wasm32/`` instead of ``bin/`` and ``wasm/`` directories
if you want to be sure whether you are downloading a wasm or an asm.js binary.
- Use ``list.json`` instead of ``list.js`` and ``list.txt``. The JSON list format contains all
the information from the old ones and more.
- Use https://binaries.soliditylang.org instead of https://solc-bin.ethereum.org. To keep things
simple we moved almost everything related to the compiler under the new ``soliditylang.org``
domain and this applies to ``solc-bin`` too. While the new domain is recommended, the old one
is still fully supported and guaranteed to point at the same location.
.. warning::
The binaries are also available at https://ethereum.github.io/solc-bin/ but this page
stopped being updated just after the release of version 0.7.2, will not receive any new releases
or nightly builds for any platform and does not serve the new directory structure, including
non-emscripten builds.
If you are using it, please switch to https://binaries.soliditylang.org, which is a drop-in
replacement. This allows us to make changes to the underlying hosting in a transparent way and
minimize disruption. Unlike the ``ethereum.github.io`` domain, which we do not have any control
over, ``binaries.soliditylang.org`` is guaranteed to work and maintain the same URL structure
in the long-term.
.. _IPFS: https://ipfs.io
.. _Swarm: https://swarm-gateways.net/bzz:/swarm.eth
.. _solc-bin: https://github.com/ethereum/solc-bin/
.. _Solidity release page on github: https://github.com/ethereum/solidity/releases
.. _sha3sum: https://github.com/maandree/sha3sum
.. _keccak256() function from ethereumjs-util: https://github.com/ethereumjs/ethereumjs-util/blob/master/docs/modules/_hash_.md#const-keccak256
.. _WebAssembly builds: https://emscripten.org/docs/compiling/WebAssembly.html
.. _QmTLs5MuLEWXQkths41HiACoXDiH8zxyqBHGFDRSzVE5CS: https://gateway.ipfs.io/ipfs/QmTLs5MuLEWXQkths41HiACoXDiH8zxyqBHGFDRSzVE5CS
.. _16c5f09109c793db99fe35f037c6092b061bd39260ee7a677c8a97f18c955ab1: https://swarm-gateways.net/bzz:/16c5f09109c793db99fe35f037c6092b061bd39260ee7a677c8a97f18c955ab1/
.. _building-from-source:
@@ -271,7 +378,7 @@ If you already have one IDE and only need the compiler and libraries,
you could install Visual Studio 2019 Build Tools.
Visual Studio 2019 provides both IDE and necessary compiler and libraries.
So if you have not got an IDE and prefer to develop solidity, Visual Studio 2019
So if you have not got an IDE and prefer to develop Solidity, Visual Studio 2019
may be a choice for you to get everything setup easily.
Here is the list of components that should be installed
@@ -338,10 +445,12 @@ Command-Line Build
**Be sure to install External Dependencies (see above) before build.**
Solidity project uses CMake to configure the build.
You might want to install ccache to speed up repeated builds.
You might want to install `ccache`_ to speed up repeated builds.
CMake will pick it up automatically.
Building Solidity is quite similar on Linux, macOS and other Unices:
.. _ccache: https://ccache.dev/
.. code-block:: bash
mkdir build
@@ -381,7 +490,7 @@ Alternatively, you can build for Windows on the command-line, like so:
cmake --build . --config Release
CMake options
CMake Options
=============
If you are interested what CMake options are available run ``cmake .. -LH``.
@@ -409,7 +518,7 @@ Inside the build folder you can disable them, since they are enabled by default:
# disables both Z3 and CVC4
cmake .. -DUSE_CVC4=OFF -DUSE_Z3=OFF
The version string in detail
The Version String in Detail
============================
The Solidity version string contains four parts:
@@ -428,7 +537,7 @@ A release example: ``0.4.8+commit.60cc1668.Emscripten.clang``.
A pre-release example: ``0.4.9-nightly.2017.1.17+commit.6ecb4aa3.Emscripten.clang``
Important information about versioning
Important Information About Versioning
======================================
After a release is made, the patch version level is bumped, because we assume that only