diff --git a/using-the-compiler.rst b/using-the-compiler.rst index add27db..cf981ec 100644 --- a/using-the-compiler.rst +++ b/using-the-compiler.rst @@ -9,70 +9,62 @@ 使用命令行编译器 ****************************** -One of the build targets of the Solidity repository is ``solc``, the solidity commandline compiler. -Using ``solc --help`` provides you with an explanation of all options. The compiler can produce various outputs, ranging from simple binaries and assembly over an abstract syntax tree (parse tree) to estimations of gas usage. -If you only want to compile a single file, you run it as ``solc --bin sourceFile.sol`` and it will print the binary. Before you deploy your contract, activate the optimizer while compiling using ``solc --optimize --bin sourceFile.sol``. If you want to get some of the more advanced output variants of ``solc``, it is probably better to tell it to output everything to separate files using ``solc -o outputDirectory --bin --ast --asm sourceFile.sol``. +.. note:: 这一节并不适用于 :ref:`solcjs ` -The commandline compiler will automatically read imported files from the filesystem, but -it is also possible to provide path redirects using ``prefix=path`` in the following way: + +``solc`` 是 Solidity 源码库的构建目标之一，它是 Solidity 的命令行编译器。你可使用 ``solc --help`` 命令来查看它的所有选项的解释。该编译器可以生成各种输出，范围从简单的二进制文件、汇编文件到用于估计“gas”使用情况的抽象语法树（解析树）。如果你只想编译一个文件，你可以运行 ``solc --bin sourceFile.sol`` 来生成二进制文件。如果你想通过 ``solc`` 获得一些更高级的输出信息，可以通过 ``solc -o outputDirectory --bin --ast --asm sourceFile.sol`` 命令将所有的输出都保存到一个单独的文件夹中。 + +Before you deploy your contract, activate the optimizer while compiling using ``solc --optimize --bin sourceFile.sol``. By default, the optimizer will optimize the contract for 200 runs. If you want to optimize for initial contract deployment and get the smallest output, set it to ``--runs=1``. If you expect many transactions and don't care for higher deployment cost and output size, set ``--runs`` to a high number. + +命令行编译器会自动从文件系统中读取并导入的文件，但同时，它也支持通过 ``prefix=path`` 选项将路径重定向。比如： :: solc github.com/ethereum/dapp-bin/=/usr/local/lib/dapp-bin/ =/usr/local/lib/fallback file.sol -This essentially instructs the compiler to search for anything starting with -``github.com/ethereum/dapp-bin/`` under ``/usr/local/lib/dapp-bin`` and if it does not -find the file there, it will look at ``/usr/local/lib/fallback`` (the empty prefix -always matches). ``solc`` will not read files from the filesystem that lie outside of -the remapping targets and outside of the directories where explicitly specified source -files reside, so things like ``import "/etc/passwd";`` only work if you add ``=/`` as a remapping. +这实质上是告诉编译器去搜索 ``/usr/local/lib/dapp-bin`` 目录下的所有以 ``github.com/ethereum/dapp-bin/`` 开头的文件，如果编译器找不到这样的文件，它会接着读取 ``/usr/local/lib/fallback`` 目录下的所有文件（空前缀意味着始终匹配）。``solc`` 不会从位于重定向目标之外和显式指定的源文件所在目录之外的文件系统读取文件，所以，类似 ``import "/etc/passwd";`` 这样的语句，编译器只会在你添加了 ``=/`` 选项之后，才会尝试到根目录下加载 ``/etc/passwd`` 文件。 -If there are multiple matches due to remappings, the one with the longest common prefix is selected. +如果重定向路径下存在多个匹配，则选择具有最长公共前缀的那个匹配。 -For security reasons the compiler has restrictions what directories it can access. Paths (and their subdirectories) of source files specified on the commandline and paths defined by remappings are allowed for import statements, but everything else is rejected. Additional paths (and their subdirectories) can be allowed via the ``--allow-paths /sample/path,/another/sample/path`` switch. +出于安全原因，编译器限制了它可以访问的目录。在命令行中指定的源文件的路径（及其子目录）和通过重定向定义的路径可用于 ``import`` 语句，其他的则会被拒绝。额外路径（及其子目录）可以通过 ``--allow-paths /sample/path,/another/sample/path`` 进行配置。 -If your contracts use :ref:`libraries `, you will notice that the bytecode contains substrings of the form ``__LibraryName______``. You can use ``solc`` as a linker meaning that it will insert the library addresses for you at those points: +如果您的合约使用 :ref:`libraries ` ，您会注意到在编译后的十六进制字节码中会包含形如 ``__LibraryName____`` 的字符串。当您将 ``solc`` 作为链接器使用时，它会在下列情况中为你插入库的地址：要么在命令行中添加 ``--libraries "Math:0x12345678901234567890 Heap:0xabcdef0123456"`` 来为每个库提供地址，或者将这些字符串保存到一个文件中（每行一个库），并使用 ``--libraries fileName`` 参数。 -Either add ``--libraries "Math:0x12345678901234567890 Heap:0xabcdef0123456"`` to your command to provide an address for each library or store the string in a file (one library per line) and run ``solc`` using ``--libraries fileName``. +如果在调用 ``solc`` 命令时使用了 ``--link`` 选项，则所有的输入文件会被解析为上面提到过的 ``__LibraryName____`` 格式的未链接的二进制数据（十六进制编码），并且就地链接。（如果输入是从stdin读取的，则生成的数据会被写入stdout）。在这种情况下，除了 ``--libraries`` 外的其他选项（包括 ``-o`` ）都会被忽略。 -If ``solc`` is called with the option ``--link``, all input files are interpreted to be unlinked binaries (hex-encoded) in the ``__LibraryName____``-format given above and are linked in-place (if the input is read from stdin, it is written to stdout). All options except ``--libraries`` are ignored (including ``-o``) in this case. - -If ``solc`` is called with the option ``--standard-json``, it will expect a JSON input (as explained below) on the standard input, and return a JSON output on the standard output. +如果在调用 ``solc`` 命令时使用了 ``--standard-json`` 选项，它将会按JSON格式解析标准输入上的输入，并在标准输出上返回JSON格式的输出。 .. _compiler-api: 编译器输入输出JSON描述 ****************************************** -These JSON formats are used by the compiler API as well as are available through ``solc``. These are subject to change, -some fields are optional (as noted), but it is aimed at to only make backwards compatible changes. -The compiler API expects a JSON formatted input and outputs the compilation result in a JSON formatted output. +下面展示的这些JSON格式是编译器API使用的，当然，在 ``solc`` 上也是可用的。有些字段是可选的（参见注释），并且它们可能会发生变化，但所有的变化都应该是后向兼容的。 + +编译器API需要JSON格式的输入，并以JSON格式输出编译结果。 -Comments are of course not permitted and used here only for explanatory purposes. +注释是不允许的，这里仅用于解释目的。 -Input Description +输入说明 ----------------- .. code-block:: none { - // Required: Source code language, such as "Solidity", "serpent", "lll", "assembly", etc. + // 必选: 源代码语言，比如“Solidity”，“serpent”，“lll”，“assembly”等 language: "Solidity", - // Required + // 必选 sources: { - // The keys here are the "global" names of the source files, - // imports can use other files via remappings (see below). + // 这里的键值是源文件的“全局”名称，可以通过remappings引入其他文件（参考下文） "myFile.sol": { - // Optional: keccak256 hash of the source file - // It is used to verify the retrieved content if imported via URLs. + // 可选: 源文件的kaccak256哈希值，可用于校验通过URL加载的内容。 "keccak256": "0x123...", - // Required (unless "content" is used, see below): URL(s) to the source file. - // URL(s) should be imported in this order and the result checked against the - // keccak256 hash (if available). If the hash doesn't match or none of the - // URL(s) result in success, an error should be raised. + // 必选（除非声明了 "content" 字段）: 指向源文件的URL。 + // URL(s) 会按顺序加载，并且结果会通过keccak256哈希值进行检查（如果有keccak256的话） + // 如果哈希值不匹配，或者没有URL返回成功，则抛出一个异常。 "urls": [ "bzzr://56ab...", @@ -82,78 +74,82 @@ Input Description }, "mortal": { - // Optional: keccak256 hash of the source file + // 可选: 该文件的keccak256哈希值 "keccak256": "0x234...", - // Required (unless "urls" is used): literal contents of the source file + // 必选（除非声明了 "urls" 字段）: 源文件的字面内容 "content": "contract mortal is owned { function kill() { if (msg.sender == owner) selfdestruct(owner); } }" } }, - // Optional + // 可选 settings: { - // Optional: Sorted list of remappings + // 可选: 重定向参数的排序列表 remappings: [ ":g/dir" ], - // Optional: Optimizer settings (enabled defaults to false) + // 可选: 优化器配置 optimizer: { + // 默认为 disabled enabled: true, - runs: 500 + // 基于你希望运行多少次代码来进行优化。 + // 较小的值可以使初始部署的费用得到更多优化，较大的值可以使高频率的使用得到优化。 + runs: 200 }, - // Metadata settings (optional) + // 指定需编译的EVM的版本。会影响代码的生成和类型检查。可用的版本为：homestead，tangerineWhistle，spuriousDragon，byzantium，constantinople + evmVersion: "byzantium", + // 可选: 元数据配置 metadata: { - // Use only literal content and not URLs (false by default) + // 只可使用字面内容，不可用URLs （默认设为 false） useLiteralContent: true }, - // Addresses of the libraries. If not all libraries are given here, it can result in unlinked objects whose output data is different. + // 库的地址。如果这里没有把所有需要的库都给出，会导致生成输出数据不同的未链接对象 libraries: { - // The top level key is the the name of the source file where the library is used. - // If remappings are used, this source file should match the global path after remappings were applied. - // If this key is an empty string, that refers to a global level. + // 最外层的 key 是使用这些库的源文件的名字。 + // 如果使用了重定向， 在重定向之后，这些源文件应该能匹配全局路径 + // 如果源文件的名字为空，则所有的库为全局引用 "myFile.sol": { "MyLib": "0x123123..." } } - // The following can be used to select desired outputs. - // If this field is omitted, then the compiler loads and does type checking, but will not generate any outputs apart from errors. - // The first level key is the file name and the second is the contract name, where empty contract name refers to the file itself, - // while the star refers to all of the contracts. + // 以下内容可以用于选择所需的输出。 + // 如果这个字段被忽略，那么编译器会加载并进行类型检查，但除了错误之外不会产生任何输出。 + // 第一级的key是文件名，第二级是合约名称，如果合约名为空，则针对文件本身（进行输出）。 + // 若使用通配符*，则表示所有合约。 // - // The available output types are as follows: + // 可用的输出类型如下所示： // abi - ABI - // ast - AST of all source files - // legacyAST - legacy AST of all source files - // devdoc - Developer documentation (natspec) - // userdoc - User documentation (natspec) - // metadata - Metadata - // ir - New assembly format before desugaring - // evm.assembly - New assembly format after desugaring - // evm.legacyAssembly - Old-style assembly format in JSON - // evm.bytecode.object - Bytecode object - // evm.bytecode.opcodes - Opcodes list - // evm.bytecode.sourceMap - Source mapping (useful for debugging) - // evm.bytecode.linkReferences - Link references (if unlinked object) - // evm.deployedBytecode* - Deployed bytecode (has the same options as evm.bytecode) - // evm.methodIdentifiers - The list of function hashes - // evm.gasEstimates - Function gas estimates - // ewasm.wast - eWASM S-expressions format (not supported atm) - // ewasm.wasm - eWASM binary format (not supported atm) + // ast - 所有源文件的AST + // legacyAST - 所有源文件的legacy AST + // devdoc - 开发者文档（natspec） + // userdoc - 用户文档（natspec） + // metadata - 元数据 + // ir - 去除语法糖（desugaring）之前的新汇编格式 + // evm.assembly - 去除语法糖（desugaring）之后的新汇编格式 + // evm.legacyAssembly - JSON的旧样式汇编格式 + // evm.bytecode.object - 字节码对象 + // evm.bytecode.opcodes - 操作码列表 + // evm.bytecode.sourceMap - 源码映射（用于调试） + // evm.bytecode.linkReferences - 链接引用（如果是未链接的对象） + // evm.deployedBytecode* - 部署的字节码（与evm.bytecode具有相同的选项） + // evm.methodIdentifiers - 函数哈希值列表 + // evm.gasEstimates - 函数的gas预估量 + // ewasm.wast - eWASM S-expressions 格式（不支持atm） + // ewasm.wasm - eWASM二进制格式（不支持atm） // - // Note that using a using `evm`, `evm.bytecode`, `ewasm`, etc. will select every - // target part of that output. Additionally, `*` can be used as a wildcard to request everything. + // 请注意，如果使用 `evm` ，`evm.bytecode` ，`ewasm` 等选项，会选择其所有的子项作为输出。 另外，`*`可以用作通配符来请求所有内容。 // outputSelection: { - // Enable the metadata and bytecode outputs of every single contract. + // 为每个合约生成元数据和字节码输出。 "*": { - "*": [ "metadata", "evm.bytecode" ] + "*": [ "metadata"，"evm.bytecode" ] }, - // Enable the abi and opcodes output of MyContract defined in file def. + // 启用“def”文件中定义的“MyContract”合约的abi和opcodes输出。 "def": { - "MyContract": [ "abi", "evm.bytecode.opcodes" ] + "MyContract": [ "abi"，"evm.bytecode.opcodes" ] }, - // Enable the source map output of every single contract. + // 为每个合约生成源码映射输出 "*": { "*": [ "evm.bytecode.sourceMap" ] }, - // Enable the legacy AST output of every single file. + // 每个文件生成legacy AST输出 "*": { "": [ "legacyAST" ] } @@ -162,93 +158,93 @@ Input Description } -Output Description +输出说明 ------------------ .. code-block:: none { - // Optional: not present if no errors/warnings were encountered + // 可选：如果没有遇到错误/警告，则不出现 errors: [ { - // Optional: Location within the source file. + // 可选：源文件中的位置 sourceLocation: { file: "sourceFile.sol", start: 0, end: 100 ], - // Mandatory: Error type, such as "TypeError", "InternalCompilerError", "Exception", etc. - // See below for complete list of types. + // 强制: 错误类型，例如 “TypeError”， “InternalCompilerError”， “Exception”等. + // 可在文末查看完整的错误类型列表 type: "TypeError", - // Mandatory: Component where the error originated, such as "general", "ewasm", etc. + // 强制: 发生错误的组件，例如“general”，“ewasm”等 component: "general", - // Mandatory ("error" or "warning") + // 强制：错误的严重级别（“error”或“warning”） severity: "error", - // Mandatory + // 强制 message: "Invalid keyword" - // Optional: the message formatted with source location + // 可选: 带错误源位置的格式化消息 formattedMessage: "sourceFile.sol:100: Invalid keyword" } ], - // This contains the file-level outputs. In can be limited/filtered by the outputSelection settings. + // 这里包含了文件级别的输出。可以通过outputSelection来设置限制/过滤。 sources: { "sourceFile.sol": { - // Identifier (used in source maps) + // 标识符（用于源码映射） id: 1, - // The AST object + // AST对象 ast: {}, - // The legacy AST object + // legacy AST 对象 legacyAST: {} } }, - // This contains the contract-level outputs. It can be limited/filtered by the outputSelection settings. + // 这里包含了合约级别的输出。 可以通过outputSelection来设置限制/过滤。 contracts: { "sourceFile.sol": { - // If the language used has no contract names, this field should equal to an empty string. + // 如果使用的语言没有合约名称，则该字段应该留空。 "ContractName": { - // The Ethereum Contract ABI. If empty, it is represented as an empty array. - // See https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI + // 以太坊合约的应用二进制接口（ABI）。如果为空，则表示为空数组。 + // 请参阅 https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI abi: [], - // See the Metadata Output documentation (serialised JSON string) + // 请参阅元数据输出文档（序列化的JSON字符串） metadata: "{...}", - // User documentation (natspec) + // 用户文档（natspec） userdoc: {}, - // Developer documentation (natspec) + // 开发人员文档（natspec） devdoc: {}, - // Intermediate representation (string) + // 中间表示形式 (string) ir: "", - // EVM-related outputs + // EVM相关输出 evm: { - // Assembly (string) + // 汇编 (string) assembly: "", - // Old-style assembly (object) + // 旧风格的汇编 (object) legacyAssembly: {}, - // Bytecode and related details. + // 字节码和相关细节 bytecode: { - // The bytecode as a hex string. + // 十六进制字符串的字节码 object: "00fe", - // Opcodes list (string) + // 操作码列表 (string) opcodes: "", - // The source mapping as a string. See the source mapping definition. + // 源码映射的字符串。 请参阅源码映射的定义 sourceMap: "", - // If given, this is an unlinked object. + // 如果这里给出了信息，则表示这是一个未链接的对象 linkReferences: { "libraryFile.sol": { - // Byte offsets into the bytecode. Linking replaces the 20 bytes located there. + // 字节码中的字节偏移；链接时，从指定的位置替换20个字节 "Library1": [ - { start: 0, length: 20 }, - { start: 200, length: 20 } + { start: 0，length: 20 }, + { start: 200，length: 20 } ] } } }, - // The same layout as above. + // 与上面相同的布局 deployedBytecode: { }, - // The list of function hashes + // 函数哈希的列表 methodIdentifiers: { "delegate(address)": "5c19a95c" }, - // Function gas estimates + // 函数的gas预估量 gasEstimates: { creation: { codeDepositCost: "420000", @@ -263,11 +259,11 @@ Output Description } } }, - // eWASM related outputs + // eWASM相关的输出 ewasm: { - // S-expressions format + // S-expressions格式 wast: "", - // Binary format (hex string) + // 二进制格式（十六进制字符串） wasm: "" } } @@ -276,19 +272,19 @@ Output Description } -Error types +错误类型 ~~~~~~~~~~~ -1. ``JSONError``: JSON input doesn't conform to the required format, e.g. input is not a JSON object, the language is not supported, etc. -2. ``IOError``: IO and import processing errors, such as unresolvable URL or hash mismatch in supplied sources. -3. ``ParserError``: Source code doesn't conform to the language rules. -4. ``DocstringParsingError``: The NatSpec tags in the comment block cannot be parsed. -5. ``SyntaxError``: Syntactical error, such as ``continue`` is used outside of a ``for`` loop. -6. ``DeclarationError``: Invalid, unresolvable or clashing identifier names. e.g. ``Identifier not found`` -7. ``TypeError``: Error within the type system, such as invalid type conversions, invalid assignments, etc. -8. ``UnimplementedFeatureError``: Feature is not supported by the compiler, but is expected to be supported in future versions. -9. ``InternalCompilerError``: Internal bug triggered in the compiler - this should be reported as an issue. -10. ``Exception``: Unknown failure during compilation - this should be reported as an issue. -11. ``CompilerError``: Invalid use of the compiler stack - this should be reported as an issue. -12. ``FatalError``: Fatal error not processed correctly - this should be reported as an issue. -13. ``Warning``: A warning, which didn't stop the compilation, but should be addressed if possible. +1. ``JSONError``: JSON输入不符合所需格式，例如，输入不是JSON对象，不支持的语言等。 +2. ``IOError``: IO和导入处理错误，例如，在提供的源里包含无法解析的URL或哈希值不匹配。 +3. ``ParserError``: 源代码不符合语言规则。 +4. ``DocstringParsingError``: 注释块中的NatSpec标签无法解析。 +5. ``SyntaxError``: 语法错误，例如 ``continue`` 在 ``for`` 循环外部使用。 +6. ``DeclarationError``: 无效的，无法解析的或冲突的标识符名称 比如 ``Identifier not found``。 +7. ``TypeError``: 类型系统内的错误，例如无效类型转换，无效赋值等。 +8. ``UnimplementedFeatureError``: 编译器当前不支持该功能，但预计将在未来的版本中支持。 +9. ``InternalCompilerError``: 在编译器中触发的内部错误——应将此报告为一个issue。 +10. ``Exception``: 编译期间的未知失败——应将此报告为一个issue。 +11. ``CompilerError``: 编译器堆栈的无效使用——应将此报告为一个issue。 +12. ``FatalError``: 未正确处理致命错误——应将此报告为一个issue。 +13. ``Warning``: 警告，不会停止编译，但应尽可能处理。 \ No newline at end of file