English documentation updates up to v0.8.30-94-gaef512f87 (2025-08-01)

.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.31")
 # 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,39 @@ 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)
+else ()
+  message(WARNING "-- Ignoring vendored dependencies. Will use installed versions if found. Versions may differ from the ones the compiler was tested with. Make sure to run the test suite and thoroughly test the resulting binaries before using them in production.")
+  find_package(fmt REQUIRED)
+  find_package(nlohmann_json REQUIRED)
+  find_package(range-v3 REQUIRED)
+endif()
 
 find_package(Threads)
 
@@ -66,71 +86,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.13.3")
+    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 +129,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