English documentation updates up to v0.8.17-65-g2201526a9 (2022-09-28)

CMakeLists.txt

@@ -0,0 +1,145 @@
+cmake_minimum_required(VERSION 3.13.0)
+
+set(ETH_CMAKE_DIR   "${CMAKE_CURRENT_LIST_DIR}/cmake"   CACHE PATH "The the path to the cmake directory")
+list(APPEND CMAKE_MODULE_PATH ${ETH_CMAKE_DIR})
+
+# Set the build type, if none was specified.
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+	if(EXISTS "${CMAKE_SOURCE_DIR}/.git")
+		set(DEFAULT_BUILD_TYPE "RelWithDebInfo")
+	else()
+		set(DEFAULT_BUILD_TYPE "Release")
+	endif()
+	set(CMAKE_BUILD_TYPE "${DEFAULT_BUILD_TYPE}" CACHE STRING "Choose the type of build, options are: Debug Release RelWithDebInfo MinSizeRel" FORCE)
+	set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "RelWithDebInfo" "MinSizeRel")
+endif()
+
+include(EthToolchains)
+
+# Set cmake_policies
+include(EthPolicy)
+eth_policy()
+
+# project name and version should be set after cmake_policy CMP0048
+set(PROJECT_VERSION "0.8.18")
+# OSX target needed in order to support std::visit
+set(CMAKE_OSX_DEPLOYMENT_TARGET "10.14")
+project(solidity VERSION ${PROJECT_VERSION} LANGUAGES C CXX)
+
+include(TestBigEndian)
+TEST_BIG_ENDIAN(IS_BIG_ENDIAN)
+if (IS_BIG_ENDIAN)
+	message(FATAL_ERROR "${PROJECT_NAME} currently does not support big endian systems.")
+endif()
+
+option(SOLC_LINK_STATIC "Link solc executable statically on supported platforms" OFF)
+option(SOLC_STATIC_STDLIBS "Link solc against static versions of libgcc and libstdc++ on supported platforms" OFF)
+option(STRICT_Z3_VERSION "Use the latest version of Z3" ON)
+option(PEDANTIC "Enable extra warnings and pedantic build flags. Treat all warnings as errors." ON)
+
+# Setup cccache.
+include(EthCcache)
+
+# Let's find our dependencies
+include(EthDependencies)
+include(fmtlib)
+include(jsoncpp)
+include(range-v3)
+include_directories(SYSTEM ${JSONCPP_INCLUDE_DIR})
+
+find_package(Threads)
+
+if(NOT PEDANTIC)
+  message(WARNING "-- Pedantic build flags turned off. Warnings will not make compilation fail. This is NOT recommended in development builds.")
+endif()
+# Figure out what compiler and system are we using
+include(EthCompilerSettings)
+
+# Include utils
+include(EthUtils)
+
+# Create license.h from LICENSE.txt and template
+# Converting to char array is required due to MSVC's string size limit.
+file(READ ${CMAKE_SOURCE_DIR}/LICENSE.txt LICENSE_TEXT HEX)
+string(REGEX MATCHALL ".." LICENSE_TEXT "${LICENSE_TEXT}")
+string(REGEX REPLACE ";" ",\n\t0x" LICENSE_TEXT "${LICENSE_TEXT}")
+set(LICENSE_TEXT "0x${LICENSE_TEXT}")
+
+configure_file("${CMAKE_SOURCE_DIR}/cmake/templates/license.h.in" include/license.h)
+
+include(EthOptions)
+configure_project(TESTS)
+set(LATEST_Z3_VERSION "4.11.0")
+set(MINIMUM_Z3_VERSION "4.8.0")
+find_package(Z3)
+if (${Z3_FOUND})
+  if (${STRICT_Z3_VERSION})
+    if (NOT ("${Z3_VERSION_STRING}" VERSION_EQUAL ${LATEST_Z3_VERSION}))
+      message(
+        FATAL_ERROR
+        "SMTChecker tests require Z3 ${LATEST_Z3_VERSION} for all tests to pass.\n\
+Build with -DSTRICT_Z3_VERSION=OFF if you want to use a different version. \
+You can also use -DUSE_Z3=OFF to build without Z3. In both cases use --no-smt when running tests."
+      )
+    endif()
+  else()
+    if ("${Z3_VERSION_STRING}" VERSION_LESS ${MINIMUM_Z3_VERSION})
+      message(
+        FATAL_ERROR
+        "Solidity requires Z3 ${MINIMUM_Z3_VERSION} or newer. You can also use -DUSE_Z3=OFF to build without Z3."
+      )
+    endif()
+  endif()
+endif()
+
+if(${USE_Z3_DLOPEN})
+  add_definitions(-DHAVE_Z3)
+  add_definitions(-DHAVE_Z3_DLOPEN)
+  find_package(Python3 COMPONENTS Interpreter)
+  if(${Z3_FOUND})
+    get_target_property(Z3_HEADER_HINTS z3::libz3 INTERFACE_INCLUDE_DIRECTORIES)
+  endif()
+  find_path(Z3_HEADER_PATH z3.h HINTS ${Z3_HEADER_HINTS})
+  if(Z3_HEADER_PATH)
+    set(Z3_FOUND TRUE)
+  else()
+    message(SEND_ERROR "Dynamic loading of Z3 requires Z3 headers to be present at build time.")
+  endif()
+  if(NOT ${Python3_FOUND})
+    message(SEND_ERROR "Dynamic loading of Z3 requires Python 3 to be present at build time.")
+  endif()
+  if(${SOLC_LINK_STATIC})
+    message(SEND_ERROR "solc cannot be linked statically when dynamically loading Z3.")
+  endif()
+elseif (${Z3_FOUND})
+  add_definitions(-DHAVE_Z3)
+  message("Z3 SMT solver found. This enables optional SMT checking with Z3.")
+endif()
+
+find_package(CVC4 QUIET)
+if (${CVC4_FOUND})
+  add_definitions(-DHAVE_CVC4)
+  message("CVC4 SMT solver found. This enables optional SMT checking with CVC4.")
+endif()
+
+if (NOT (${Z3_FOUND} OR ${CVC4_FOUND}))
+  message("No SMT solver found (or it has been forcefully disabled). Optional SMT checking will not be available.\
+  \nPlease install Z3 or CVC4 or remove the option disabling them (USE_Z3, USE_CVC4).")
+endif()
+
+add_subdirectory(libsolutil)
+add_subdirectory(liblangutil)
+add_subdirectory(libsmtutil)
+add_subdirectory(libevmasm)
+add_subdirectory(libyul)
+add_subdirectory(libsolidity)
+add_subdirectory(libsolc)
+add_subdirectory(tools)
+
+if (NOT EMSCRIPTEN)
+	add_subdirectory(solc)
+endif()
+
+if (TESTS AND NOT EMSCRIPTEN)
+	add_subdirectory(test)
+endif()

docs/050-breaking-changes.rst

@@ -89,8 +89,8 @@ For most of the topics the compiler will provide suggestions.
 
 * Explicit data location for all variables of struct, array or mapping types is
   now mandatory. This is also applied to function parameters and return
-  variables.  For example, change ``uint[] x = m_x`` to ``uint[] storage x =
-  m_x``, and ``function f(uint[][] x)`` to ``function f(uint[][] memory x)``
+  variables.  For example, change ``uint[] x = z`` to ``uint[] storage x =
+  z``, and ``function f(uint[][] x)`` to ``function f(uint[][] memory x)``
   where ``memory`` is the data location and might be replaced by ``storage`` or
   ``calldata`` accordingly.  Note that ``external`` functions require
   parameters with a data location of ``calldata``.
@@ -483,7 +483,7 @@ New version:
             return data;
         }
 
-        using address_make_payable for address;
+        using AddressMakePayable for address;
         // Data location for 'arr' must be specified
         function g(uint[] memory /* arr */, bytes8 x, OtherContract otherContract, address unknownContract) public payable {
             // 'otherContract.transfer' is not provided.
@@ -500,7 +500,7 @@ New version:
             // 'address payable' should be used whenever possible.
             // To increase clarity, we suggest the use of a library for
             // the conversion (provided after the contract in this example).
-            address payable addr = unknownContract.make_payable();
+            address payable addr = unknownContract.makePayable();
             require(addr.send(1 ether));
 
             // Since uint32 (4 bytes) is smaller than bytes8 (8 bytes),
@@ -516,8 +516,8 @@ New version:
 
     // We can define a library for explicitly converting ``address``
     // to ``address payable`` as a workaround.
-    library address_make_payable {
-        function make_payable(address x) internal pure returns (address payable) {
+    library AddressMakePayable {
+        function makePayable(address x) internal pure returns (address payable) {
             return address(uint160(x));
         }
     }

docs/060-breaking-changes.rst

@@ -53,6 +53,8 @@ For most of the topics the compiler will provide suggestions.
   If the name contains a dot, its prefix up to the dot may not conflict with any declaration outside the inline
   assembly block.
 
+* In inline assembly, opcodes that do not take arguments are now represented as "built-in functions" instead of standalone identifiers. So ``gas`` is now ``gas()``.
+
 * State variable shadowing is now disallowed.  A derived contract can only
   declare a state variable ``x``, if there is no visible state variable with
   the same name in any of its bases.
@@ -174,3 +176,6 @@ This section gives detailed instructions on how to update prior code for every b
   ``override`` to every overriding function. For multiple inheritance, add ``override(A, B, ..)``,
   where you list all contracts that define the overridden function in the parentheses. When
   multiple bases define the same function, the inheriting contract must override all conflicting functions.
+
+* In inline assembly, add ``()`` to all opcodes that do not otherwise accept an argument.
+  For example, change ``pc`` to ``pc()``, and ``gas`` to ``gas()``.

docs/_static/js/toggle.js

@@ -4,15 +4,16 @@ document.addEventListener('DOMContentLoaded', function() {
         var mode = (isDay ? "Day" : "Night");
         localStorage.setItem("css-mode", mode);
 
-        var daysheet = $('link[href="_static/pygments.css"]')[0].sheet;
+        var url_root = DOCUMENTATION_OPTIONS.URL_ROOT == "./" ? "" : DOCUMENTATION_OPTIONS.URL_ROOT;
+        var daysheet = $(`link[href="${url_root}_static/pygments.css"]`)[0].sheet;
         daysheet.disabled = !isDay;
 
-        var nightsheet = $('link[href="_static/css/dark.css"]')[0];
+        var nightsheet = $(`link[href="${url_root}_static/css/dark.css"]`)[0];
         if (!isDay && nightsheet === undefined) {
             var element = document.createElement("link");
             element.setAttribute("rel", "stylesheet");
             element.setAttribute("type", "text/css");
-            element.setAttribute("href", "_static/css/dark.css");
+            element.setAttribute("href", `${url_root}_static/css/dark.css`);
             document.getElementsByTagName("head")[0].appendChild(element);
             return;
         }

docs/abi-spec.rst

@@ -13,13 +13,13 @@ The Contract Application Binary Interface (ABI) is the standard way to interact
 from outside the blockchain and for contract-to-contract interaction. Data is encoded according to its type,
 as described in this specification. The encoding is not self describing and thus requires a schema in order to decode.
 
-We assume the interface functions of a contract are strongly typed, known at compilation time and static.
+We assume that the interface functions of a contract are strongly typed, known at compilation time and static.
 We assume that all contracts will have the interface definitions of any contracts they call available at compile-time.
 
 This specification does not address contracts whose interface is dynamic or otherwise known only at run-time.
 
 .. _abi_function_selector:
-.. index:: selector
+.. index:: ! selector; of a function
 
 Function Selector
 =================
@@ -29,7 +29,7 @@ first (left, high-order in big-endian) four bytes of the Keccak-256 hash of the
 the function. The signature is defined as the canonical expression of the basic prototype without data
 location specifier, i.e.
 the function name with the parenthesised list of parameter types. Parameter types are split by a single
-comma - no spaces are used.
+comma — no spaces are used.
 
 .. note::
     The return type of a function is not part of this signature. In
@@ -133,7 +133,7 @@ The encoding is designed to have the following properties, which are especially
    previous version of the ABI, the number of reads scaled linearly with the total number of dynamic
    parameters in the worst case.
 
-2. The data of a variable or array element is not interleaved with other data and it is
+2. The data of a variable or an array element is not interleaved with other data and it is
    relocatable, i.e. it only uses relative "addresses".
 
 
@@ -191,9 +191,9 @@ on the type of ``X`` being
 
 - ``T[]`` where ``X`` has ``k`` elements (``k`` is assumed to be of type ``uint256``):
 
-  ``enc(X) = enc(k) enc([X[0], ..., X[k-1]])``
+  ``enc(X) = enc(k) enc((X[0], ..., X[k-1]))``
 
-  i.e. it is encoded as if it were an array of static size ``k``, prefixed with
+  i.e. it is encoded as if it were a tuple with ``k`` elements of the same type (resp. an array of static size ``k``), prefixed with
   the number of elements.
 
 - ``bytes``, of length ``k`` (which is assumed to be of type ``uint256``):
@@ -252,7 +252,7 @@ Given the contract:
     }
 
 
-Thus for our ``Foo`` example if we wanted to call ``baz`` with the parameters ``69`` and
+Thus, for our ``Foo`` example if we wanted to call ``baz`` with the parameters ``69`` and
 ``true``, we would pass 68 bytes total, which can be broken down into:
 
 - ``0xcdcd77c0``: the Method ID. This is derived as the first 4 bytes of the Keccak hash of
@@ -308,7 +308,7 @@ In total:
 Use of Dynamic Types
 ====================
 
-A call to a function with the signature ``f(uint,uint32[],bytes10,bytes)`` with values
+A call to a function with the signature ``f(uint256,uint32[],bytes10,bytes)`` with values
 ``(0x123, [0x456, 0x789], "1234567890", "Hello, world!")`` is encoded in the following way:
 
 We take the first four bytes of ``sha3("f(uint256,uint32[],bytes10,bytes)")``, i.e. ``0x8be65246``.
@@ -348,7 +348,7 @@ All together, the encoding is (newline after function selector and each 32-bytes
       000000000000000000000000000000000000000000000000000000000000000d
       48656c6c6f2c20776f726c642100000000000000000000000000000000000000
 
-Let us apply the same principle to encode the data for a function with a signature ``g(uint[][],string[])``
+Let us apply the same principle to encode the data for a function with a signature ``g(uint256[][],string[])``
 with values ``([[1, 2], [3]], ["one", "two", "three"])`` but start from the most atomic parts of the encoding:
 
 First we encode the length and data of the first embedded dynamic array ``[1, 2]`` of the first root array ``[[1, 2], [3]]``:
@@ -417,7 +417,7 @@ thus ``e = 0x00000000000000000000000000000000000000000000000000000000000000e0``.
 
 
 Note that the encodings of the embedded elements of the root arrays are not dependent on each other
-and have the same encodings for a function with a signature ``g(string[],uint[][])``.
+and have the same encodings for a function with a signature ``g(string[],uint256[][])``.
 
 Then we encode the length of the first root array:
 
@@ -503,6 +503,7 @@ efficient search and arbitrary legibility by defining events with two arguments
 indexed, one not — intended to hold the same value.
 
 .. _abi_errors:
+.. index:: error, selector; of an error
 
 Errors
 ======
@@ -596,7 +597,7 @@ Errors look as follows:
 
 .. note::
   There can be multiple errors with the same name and even with identical signature
-  in the JSON array, for example if the errors originate from different
+  in the JSON array; for example, if the errors originate from different
   files in the smart contract or are referenced from another smart contract.
   For the ABI, only the name of the error itself is relevant and not where it is
   defined.
@@ -645,15 +646,15 @@ would result in the JSON:
 Handling tuple types
 --------------------
 
-Despite that names are intentionally not part of the ABI encoding they do make a lot of sense to be included
+Despite the fact that names are intentionally not part of the ABI encoding, they do make a lot of sense to be included
 in the JSON to enable displaying it to the end user. The structure is nested in the following way:
 
 An object with members ``name``, ``type`` and potentially ``components`` describes a typed variable.
 The canonical type is determined until a tuple type is reached and the string description up
 to that point is stored in ``type`` prefix with the word ``tuple``, i.e. it will be ``tuple`` followed by
 a sequence of ``[]`` and ``[k]`` with
 integers ``k``. The components of the tuple are then stored in the member ``components``,
-which is of array type and has the same structure as the top-level object except that
+which is of an array type and has the same structure as the top-level object except that
 ``indexed`` is not allowed there.
 
 As an example, the code
@@ -737,10 +738,10 @@ Strict Encoding Mode
 ====================
 
 Strict encoding mode is the mode that leads to exactly the same encoding as defined in the formal specification above.
-This means offsets have to be as small as possible while still not creating overlaps in the data areas and thus no gaps are
+This means that offsets have to be as small as possible while still not creating overlaps in the data areas, and thus no gaps are
 allowed.
 
-Usually, ABI decoders are written in a straightforward way just following offset pointers, but some decoders
+Usually, ABI decoders are written in a straightforward way by just following offset pointers, but some decoders
 might enforce strict mode. The Solidity ABI decoder currently does not enforce strict mode, but the encoder
 always creates data in strict mode.
 
@@ -776,7 +777,7 @@ More specifically:
   encoding of its elements **with** padding.
 - Dynamically-sized types like ``string``, ``bytes`` or ``uint[]`` are encoded
   without their length field.
-- The encoding of ``string`` or ``bytes`` does not apply padding at the end
+- The encoding of ``string`` or ``bytes`` does not apply padding at the end,
   unless it is part of an array or struct (then it is padded to a multiple of
   32 bytes).
 
@@ -804,7 +805,7 @@ Encoding of Indexed Event Parameters
 ====================================
 
 Indexed event parameters that are not value types, i.e. arrays and structs are not
-stored directly but instead a keccak256-hash of an encoding is stored. This encoding
+stored directly but instead a Keccak-256 hash of an encoding is stored. This encoding
 is defined as follows:
 
 - the encoding of a ``bytes`` and ``string`` value is just the string contents