English documentation updates up to v0.8.28-107-g323ad9345 (2024-11-08)

.readthedocs.yml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CMakeLists.txt

@@ -1,11 +1,11 @@
 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")
+set(ETH_CMAKE_DIR   "${CMAKE_CURRENT_LIST_DIR}/cmake"   CACHE PATH "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")
+	if(EXISTS "${PROJECT_SOURCE_DIR}/.git")
 		set(DEFAULT_BUILD_TYPE "RelWithDebInfo")
 	else()
 		set(DEFAULT_BUILD_TYPE "Release")
@@ -21,7 +21,7 @@ include(EthPolicy)
 eth_policy()
 
 # project name and version should be set after cmake_policy CMP0048
-set(PROJECT_VERSION "0.8.18")
+set(PROJECT_VERSION "0.8.29")
 # OSX target needed in order to support std::visit
 set(CMAKE_OSX_DEPLOYMENT_TARGET "10.14")
 project(solidity VERSION ${PROJECT_VERSION} LANGUAGES C CXX)
@@ -34,19 +34,34 @@ 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(STRICT_Z3_VERSION "Require the exact version of Z3 solver expected by our test suite." ON)
 option(PEDANTIC "Enable extra warnings and pedantic build flags. Treat all warnings as errors." ON)
 option(PROFILE_OPTIMIZER_STEPS "Output performance metrics for the optimiser steps." OFF)
+option(
+	IGNORE_VENDORED_DEPENDENCIES
+	"Ignore libraries provided as submodules of the repository and allow CMake to look for \
+them in the typical locations, including system-wide dirs."
+	OFF
+)
+option(
+	ONLY_BUILD_SOLIDITY_LIBRARIES
+	"Only build library targets that can be statically linked against. Do not build executables or tests."
+	OFF
+)
+mark_as_advanced(PROFILE_OPTIMIZER_STEPS)
+mark_as_advanced(IGNORE_VENDORED_DEPENDENCIES)
+mark_as_advanced(ONLY_BUILD_SOLIDITY_LIBRARIES)
 
 # Setup cccache.
 include(EthCcache)
 
 # Let's find our dependencies
 include(EthDependencies)
-include(fmtlib)
-include(jsoncpp)
-include(range-v3)
-include_directories(SYSTEM ${JSONCPP_INCLUDE_DIR})
+if (NOT IGNORE_VENDORED_DEPENDENCIES)
+  include(fmtlib)
+  include(nlohmann-json)
+  include(range-v3)
+endif()
 
 find_package(Threads)
 
@@ -66,71 +81,40 @@ 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)
+file(READ ${PROJECT_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)
+configure_file("${PROJECT_SOURCE_DIR}/cmake/templates/license.h.in" include/license.h)
 
 include(EthOptions)
 configure_project(TESTS)
-set(LATEST_Z3_VERSION "4.11.2")
-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).")
+if(EMSCRIPTEN)
+    set(TESTED_Z3_VERSION "4.12.1")
+    set(MINIMUM_Z3_VERSION "4.8.16")
+    find_package(Z3)
+    if (${Z3_FOUND})
+      add_definitions(-DEMSCRIPTEN_BUILD)
+      if (${STRICT_Z3_VERSION})
+        if (NOT ("${Z3_VERSION_STRING}" VERSION_EQUAL ${TESTED_Z3_VERSION}))
+          message(
+            FATAL_ERROR
+            "SMTChecker tests require Z3 ${TESTED_Z3_VERSION} for all tests to pass.\n"
+          )
+        endif()
+      else()
+        if ("${Z3_VERSION_STRING}" VERSION_LESS ${MINIMUM_Z3_VERSION})
+          message(
+            FATAL_ERROR
+            "Solidity requires Z3 ${MINIMUM_Z3_VERSION} or newer."
+          )
+        endif()
+      endif()
+    else()
+        message(FATAL_ERROR "Solidity requires Z3 for emscripten build.")
+    endif()
 endif()
 
 add_subdirectory(libsolutil)
@@ -140,12 +124,16 @@ add_subdirectory(libevmasm)
 add_subdirectory(libyul)
 add_subdirectory(libsolidity)
 add_subdirectory(libsolc)
-add_subdirectory(tools)
+add_subdirectory(libstdlib)
 
-if (NOT EMSCRIPTEN)
-	add_subdirectory(solc)
-endif()
+if (NOT ONLY_BUILD_SOLIDITY_LIBRARIES)
+	add_subdirectory(tools)
 
-if (TESTS AND NOT EMSCRIPTEN)
-	add_subdirectory(test)
+	if (NOT EMSCRIPTEN)
+		add_subdirectory(solc)
+	endif()
+
+	if (TESTS AND NOT EMSCRIPTEN)
+		add_subdirectory(test)
+	endif()
 endif()

docs/050-breaking-changes.rst

@@ -137,7 +137,7 @@ For most of the topics the compiler will provide suggestions.
   ``payable`` or create a new internal function for the program logic that
   uses ``msg.value``.
 
-* For clarity reasons, the command line interface now requires ``-`` if the
+* For clarity reasons, the command-line interface now requires ``-`` if the
   standard input is used as source.
 
 Deprecated Elements
@@ -147,18 +147,18 @@ This section lists changes that deprecate prior features or syntax.  Note that
 many of these changes were already enabled in the experimental mode
 ``v0.5.0``.
 
-Command Line and JSON Interfaces
+Command-line and JSON Interfaces
 --------------------------------
 
-* The command line option ``--formal`` (used to generate Why3 output for
+* The command-line option ``--formal`` (used to generate Why3 output for
   further formal verification) was deprecated and is now removed.  A new
   formal verification module, the SMTChecker, is enabled via ``pragma
   experimental SMTChecker;``.
 
-* The command line option ``--julia`` was renamed to ``--yul`` due to the
+* The command-line option ``--julia`` was renamed to ``--yul`` due to the
   renaming of the intermediate language ``Julia`` to ``Yul``.
 
-* The ``--clone-bin`` and ``--combined-json clone-bin`` command line options
+* The ``--clone-bin`` and ``--combined-json clone-bin`` command-line options
   were removed.
 
 * Remappings with empty prefix are disallowed.

docs/060-breaking-changes.rst

@@ -12,7 +12,7 @@ For the full list check
 Changes the Compiler Might not Warn About
 =========================================
 
-This section lists changes where the behaviour of your code might
+This section lists changes where the behavior of your code might
 change without the compiler telling you about it.
 
 * The resulting type of an exponentiation is the type of the base. It used to be the smallest type
@@ -105,23 +105,23 @@ Interface Changes
 =================
 
 This section lists changes that are unrelated to the language itself, but that have an effect on the interfaces of
-the compiler. These may change the way how you use the compiler on the command line, how you use its programmable
+the compiler. These may change the way how you use the compiler on the command-line, how you use its programmable
 interface, or how you analyze the output produced by it.
 
 New Error Reporter
 ~~~~~~~~~~~~~~~~~~
 
-A new error reporter was introduced, which aims at producing more accessible error messages on the command line.
-It is enabled by default, but passing ``--old-reporter`` falls back to the the deprecated old error reporter.
+A new error reporter was introduced, which aims at producing more accessible error messages on the command-line.
+It is enabled by default, but passing ``--old-reporter`` falls back to the deprecated old error reporter.
 
 Metadata Hash Options
 ~~~~~~~~~~~~~~~~~~~~~
 
 The compiler now appends the `IPFS <https://ipfs.io/>`_ hash of the metadata file to the end of the bytecode by default
 (for details, see documentation on :doc:`contract metadata <metadata>`). Before 0.6.0, the compiler appended the
-`Swarm <https://ethersphere.github.io/swarm-home/>`_ hash by default, and in order to still support this behaviour,
-the new command line option ``--metadata-hash`` was introduced. It allows you to select the hash to be produced and
-appended, by passing either ``ipfs`` or ``swarm`` as value to the ``--metadata-hash`` command line option.
+`Swarm <https://ethersphere.github.io/swarm-home/>`_ hash by default, and in order to still support this behavior,
+the new command-line option ``--metadata-hash`` was introduced. It allows you to select the hash to be produced and
+appended, by passing either ``ipfs`` or ``swarm`` as value to the ``--metadata-hash`` command-line option.
 Passing the value ``none`` completely removes the hash.
 
 These changes can also be used via the :ref:`Standard JSON Interface<compiler-api>` and effect the metadata JSON generated by the compiler.

docs/080-breaking-changes.rst

@@ -10,18 +10,18 @@ For the full list check
 Silent Changes of the Semantics
 ===============================
 
-This section lists changes where existing code changes its behaviour without
+This section lists changes where existing code changes its behavior without
 the compiler notifying you about it.
 
 * Arithmetic operations revert on underflow and overflow. You can use ``unchecked { ... }`` to use
-  the previous wrapping behaviour.
+  the previous wrapping behavior.
 
   Checks for overflow are very common, so we made them the default to increase readability of code,
   even if it comes at a slight increase of gas costs.
 
 * ABI coder v2 is activated by default.
 
-  You can choose to use the old behaviour using ``pragma abicoder v1;``.
+  You can choose to use the old behavior using ``pragma abicoder v1;``.
   The pragma ``pragma experimental ABIEncoderV2;`` is still valid, but it is deprecated and has no effect.
   If you want to be explicit, please use ``pragma abicoder v2;`` instead.
 
@@ -57,7 +57,7 @@ New Restrictions
 
 This section lists changes that might cause existing contracts to not compile anymore.
 
-* There are new restrictions related to explicit conversions of literals. The previous behaviour in
+* There are new restrictions related to explicit conversions of literals. The previous behavior in
   the following cases was likely ambiguous:
 
   1. Explicit conversions from negative literals and literals larger than ``type(uint160).max`` to
@@ -106,7 +106,7 @@ This section lists changes that might cause existing contracts to not compile an
 
 * The global functions ``log0``, ``log1``, ``log2``, ``log3`` and ``log4`` have been removed.
 
-  These are low-level functions that were largely unused. Their behaviour can be accessed from inline assembly.
+  These are low-level functions that were largely unused. Their behavior can be accessed from inline assembly.
 
 * ``enum`` definitions cannot contain more than 256 members.
 
@@ -155,7 +155,7 @@ Interface Changes
   ``storage-layout`` are sub-objects now. Before 0.8.0 they used to be serialised as strings.
 
 * The "legacy AST" has been removed (``--ast-json`` on the commandline interface and ``legacyAST`` for standard JSON).
-  Use the "compact AST" (``--ast-compact--json`` resp. ``AST``) as replacement.
+  Use the "compact AST" (``--ast-compact-json`` resp. ``AST``) as replacement.
 
 * The old error reporter (``--old-reporter``) has been removed.
 
@@ -173,4 +173,4 @@ How to update your code
 - Change ``msg.sender.transfer(x)`` to ``payable(msg.sender).transfer(x)`` or use a stored variable of ``address payable`` type.
 - Change ``x**y**z`` to ``(x**y)**z``.
 - Use inline assembly as a replacement for ``log0``, ..., ``log4``.
-- Negate unsigned integers by subtracting them from the maximum value of the type and adding 1 (e.g. ``type(uint256).max - x + 1``, while ensuring that `x` is not zero)
+- Negate unsigned integers by subtracting them from the maximum value of the type and adding 1 (e.g. ``type(uint256).max - x + 1``, while ensuring that ``x`` is not zero)

docs/Makefile

@@ -34,7 +34,6 @@ help:
 	@echo "  epub       to make an epub"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
 	@echo "  text       to make text files"
 	@echo "  man        to make manual pages"
 	@echo "  texinfo    to make Texinfo files"
@@ -116,12 +115,6 @@ latexpdf:
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo

docs/README.md

@@ -0,0 +1,23 @@
+# Solidity Language Docs
+
+## Local environment setup
+
+1. Install python https://www.python.org/downloads/
+1. Install sphinx (the tool used to generate the docs) https://www.sphinx-doc.org/en/master/usage/installation.html
+
+Go to `/docs` and run `./docs.sh` to install dependencies and build the project:
+
+```sh
+cd docs
+./docs.sh
+```
+
+That will output the generated htmls under _build/
+
+## Serve environment
+
+```py
+python3 -m http.server -d _build/html --cgi 8080
+```
+
+Visit dev server at http://localhost:8080