Expose --debug-info/settings.debug.debugInfo option

Author: cameel

Changelog.md

@@ -6,8 +6,10 @@ Language Features:
 
 Compiler Features:
  * Commandline Interface: Accept nested brackets in step sequences passed to ``--yul-optimizations``.
+ * Commandline Interface: Add ``--debug-info`` option for selecting how much extra debug information should be included in the produced EVM assembly and Yul code.
  * SMTChecker: Output values for ``block.*``, ``msg.*`` and ``tx.*`` variables that are present in the called functions.
  * Standard JSON: Accept nested brackets in step sequences passed to ``settings.optimizer.details.yulDetails.optimizerSteps``.
+ * Standard JSON: Add ``settings.debug.debugInfo`` option for selecting how much extra debug information should be included in the produced EVM assembly and Yul code.
 
 
 Bugfixes:

docs/using-the-compiler.rst

@@ -308,7 +308,18 @@ Input Description
           // "strip" removes all revert strings (if possible, i.e. if literals are used) keeping side-effects
           // "debug" injects strings for compiler-generated internal reverts, implemented for ABI encoders V1 and V2 for now.
           // "verboseDebug" even appends further information to user-supplied revert strings (not yet implemented)
-          "revertStrings": "default"
+          "revertStrings": "default",
+          // Optional: How much extra debug information to include in comments in the produced EVM
+          // assembly and Yul code. Available components are:
+          // - `location`: Annotations of the form `@src <index>:<start>:<end>` indicating the
+          //    location of the corresponding element in the original Solidity file, where:
+          //     - `<index>` is the file index matching the `@use-src` annotation,
+          //     - `<start>` is the index of the first byte at that location,
+          //     - `<end>` is the index of the first byte after that location.
+          // - `snippet`: A single-line code snippet from the location indicated by `@src`.
+          //     The snippet is quoted and follows the corresponding `@src` annotation.
+          // - `*`: Wildcard value that can be used to request everything.
+          "debugInfo": ["location", "snippet"]
         },
         // Metadata settings (optional)
         "metadata": {

libsolidity/interface/StandardCompiler.cpp

@@ -33,7 +33,6 @@
 
 #include <libsmtutil/Exceptions.h>
 
-#include <liblangutil/DebugInfoSelection.h>
 #include <liblangutil/SourceReferenceFormatter.h>
 
 #include <libsolutil/JSON.h>
@@ -798,7 +797,7 @@ std::variant<StandardCompiler::InputsAndSettings, Json::Value> StandardCompiler:
 
 	if (settings.isMember("debug"))
 	{
-		if (auto result = checkKeys(settings["debug"], {"revertStrings"}, "settings.debug"))
+		if (auto result = checkKeys(settings["debug"], {"revertStrings", "debugInfo"}, "settings.debug"))
 			return *result;
 
 		if (settings["debug"].isMember("revertStrings"))
@@ -815,6 +814,31 @@ std::variant<StandardCompiler::InputsAndSettings, Json::Value> StandardCompiler:
 				);
 			ret.revertStrings = *revertStrings;
 		}
+
+		if (settings["debug"].isMember("debugInfo"))
+		{
+			if (!settings["debug"]["debugInfo"].isArray())
+				return formatFatalError("JSONError", "settings.debug.debugInfo must be an array.");
+
+			vector<string> components;
+			for (Json::Value const& arrayValue: settings["debug"]["debugInfo"])
+				components.push_back(arrayValue.asString());
+
+			optional<DebugInfoSelection> debugInfoSelection = DebugInfoSelection::fromComponents(
+				components,
+				true /* _acceptWildcards */
+			);
+			if (!debugInfoSelection.has_value())
+				return formatFatalError("JSONError", "Invalid value in settings.debug.debugInfo.");
+
+			if (debugInfoSelection->snippet && !debugInfoSelection->location)
+				return formatFatalError(
+					"JSONError",
+					"To use 'snippet' with settings.debug.debugInfo you must select also 'location'."
+				);
+
+			ret.debugInfoSelection = debugInfoSelection.value();
+		}
 	}
 
 	if (settings.isMember("remappings") && !settings["remappings"].isArray())
@@ -1034,6 +1058,8 @@ Json::Value StandardCompiler::compileSolidity(StandardCompiler::InputsAndSetting
 	compilerStack.setRemappings(move(_inputsAndSettings.remappings));
 	compilerStack.setOptimiserSettings(std::move(_inputsAndSettings.optimiserSettings));
 	compilerStack.setRevertStringBehaviour(_inputsAndSettings.revertStrings);
+	if (_inputsAndSettings.debugInfoSelection.has_value())
+		compilerStack.selectDebugInfo(_inputsAndSettings.debugInfoSelection.value());
 	compilerStack.setLibraries(_inputsAndSettings.libraries);
 	compilerStack.useMetadataLiteralSources(_inputsAndSettings.metadataLiteralSources);
 	compilerStack.setMetadataHash(_inputsAndSettings.metadataHash);
@@ -1364,7 +1390,9 @@ Json::Value StandardCompiler::compileYul(InputsAndSettings _inputsAndSettings)
 		_inputsAndSettings.evmVersion,
 		AssemblyStack::Language::StrictAssembly,
 		_inputsAndSettings.optimiserSettings,
-		DebugInfoSelection::Default()
+		_inputsAndSettings.debugInfoSelection.has_value() ?
+			_inputsAndSettings.debugInfoSelection.value() :
+			DebugInfoSelection::Default()
 	);
 	string const& sourceName = _inputsAndSettings.sources.begin()->first;
 	string const& sourceContents = _inputsAndSettings.sources.begin()->second;

libsolidity/interface/StandardCompiler.h

@@ -26,6 +26,8 @@
 #include <libsolidity/interface/CompilerStack.h>
 #include <libsolutil/JSON.h>
 
+#include <liblangutil/DebugInfoSelection.h>
+
 #include <optional>
 #include <utility>
 #include <variant>
@@ -78,6 +80,7 @@ class StandardCompiler
 		std::vector<ImportRemapper::Remapping> remappings;
 		RevertStrings revertStrings = RevertStrings::Default;
 		OptimiserSettings optimiserSettings = OptimiserSettings::minimal();
+		std::optional<langutil::DebugInfoSelection> debugInfoSelection;
 		std::map<std::string, util::h160> libraries;
 		bool metadataLiteralSources = false;
 		CompilerStack::MetadataHash metadataHash = CompilerStack::MetadataHash::IPFS;

solc/CommandLineInterface.cpp

@@ -631,6 +631,8 @@ bool CommandLineInterface::compile()
 		m_compiler->setViaIR(m_options.output.experimentalViaIR);
 		m_compiler->setEVMVersion(m_options.output.evmVersion);
 		m_compiler->setRevertStringBehaviour(m_options.output.revertStrings);
+		if (m_options.output.debugInfoSelection.has_value())
+			m_compiler->selectDebugInfo(m_options.output.debugInfoSelection.value());
 		// TODO: Perhaps we should not compile unless requested
 
 		m_compiler->enableIRGeneration(m_options.compiler.outputs.ir || m_options.compiler.outputs.irOptimized);
@@ -973,7 +975,9 @@ bool CommandLineInterface::assemble(yul::AssemblyStack::Language _language, yul:
 			m_options.output.evmVersion,
 			_language,
 			m_options.optimiserSettings(),
-			DebugInfoSelection::Default()
+			m_options.output.debugInfoSelection.has_value() ?
+				m_options.output.debugInfoSelection.value() :
+				DebugInfoSelection::Default()
 		);
 
 		if (!stack.parseAndAnalyze(src.first, src.second))

solc/CommandLineParser.cpp

@@ -67,6 +67,7 @@ static string const g_strImportAst = "import-ast";
 static string const g_strInputFile = "input-file";
 static string const g_strYul = "yul";
 static string const g_strYulDialect = "yul-dialect";
+static string const g_strDebugInfo = "debug-info";
 static string const g_strIPFS = "ipfs";
 static string const g_strLicense = "license";
 static string const g_strLibraries = "libraries";
@@ -252,6 +253,7 @@ bool CommandLineOptions::operator==(CommandLineOptions const& _other) const noex
 		output.evmVersion == _other.output.evmVersion &&
 		output.experimentalViaIR == _other.output.experimentalViaIR &&
 		output.revertStrings == _other.output.revertStrings &&
+		output.debugInfoSelection == _other.output.debugInfoSelection &&
 		output.stopAfter == _other.output.stopAfter &&
 		input.mode == _other.input.mode &&
 		assembly.targetMachine == _other.assembly.targetMachine &&
@@ -595,6 +597,13 @@ General Information)").c_str(),
 			po::value<string>()->value_name(joinHumanReadable(g_revertStringsArgs, ",")),
 			"Strip revert (and require) reason strings or add additional debugging information."
 		)
+		(
+			g_strDebugInfo.c_str(),
+			po::value<string>()->default_value(toString(DebugInfoSelection::Default())),
+			("Debug info components to be included in the produced EVM assembly and Yul code. "
+			"Value can be all, none or a comma-separated list containing one or more of the "
+			"following components: " + joinHumanReadable(DebugInfoSelection::componentMap() | ranges::views::keys) + ".").c_str()
+		)
 		(
 			g_strStopAfter.c_str(),
 			po::value<string>()->value_name("stage"),
@@ -935,6 +944,12 @@ bool CommandLineParser::processArgs()
 				serr() << "Option --" << option << " is only valid in compiler and assembler modes." << endl;
 				return false;
 			}
+
+		if (!m_args[g_strDebugInfo].defaulted())
+		{
+			serr() << "Option --" << g_strDebugInfo << " is only valid in compiler and assembler modes." << endl;
+			return false;
+		}
 	}
 
 	if (m_args.count(g_strColor) > 0)
@@ -961,6 +976,23 @@ bool CommandLineParser::processArgs()
 		m_options.output.revertStrings = *revertStrings;
 	}
 
+	if (!m_args[g_strDebugInfo].defaulted())
+	{
+		string optionValue = m_args[g_strDebugInfo].as<string>();
+		m_options.output.debugInfoSelection = DebugInfoSelection::fromString(optionValue);
+		if (!m_options.output.debugInfoSelection.has_value())
+		{
+			serr() << "Invalid value for --" << g_strDebugInfo << " option: " << optionValue << endl;
+			return false;
+		}
+
+		if (m_options.output.debugInfoSelection->snippet && !m_options.output.debugInfoSelection->location)
+		{
+			serr() << "To use 'snippet' with --" << g_strDebugInfo << " you must select also 'location'." << endl;
+			return false;
+		}
+	}
+
 	if (!parseCombinedJsonOption())
 		return false;
 

solc/CommandLineParser.h

@@ -24,8 +24,12 @@
 #include <libsolidity/interface/DebugSettings.h>
 #include <libsolidity/interface/FileReader.h>
 #include <libsolidity/interface/ImportRemapper.h>
+
 #include <libyul/AssemblyStack.h>
+
+#include <liblangutil/DebugInfoSelection.h>
 #include <liblangutil/EVMVersion.h>
+
 #include <libsolutil/JSON.h>
 
 #include <boost/program_options.hpp>
@@ -174,6 +178,7 @@ struct CommandLineOptions
 		langutil::EVMVersion evmVersion;
 		bool experimentalViaIR = false;
 		RevertStrings revertStrings = RevertStrings::Default;
+		std::optional<langutil::DebugInfoSelection> debugInfoSelection;
 		CompilerStack::State stopAfter = CompilerStack::State::CompilationSuccessful;
 	} output;
 

test/cmdlineTests/debug_info_in_yul_and_evm_asm_print_all/args

@@ -0,0 +1 @@
+--ir --ir-optimized --asm --optimize --debug-info all

test/cmdlineTests/debug_info_in_yul_and_evm_asm_print_all/input.sol

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: GPL-2.0
+pragma solidity >=0.0;
+
+contract C {
+    function f() public {}
+}