Skip to content

Latest commit

 

History

History
822 lines (473 loc) · 23.8 KB

02-command-line-interface.md

File metadata and controls

822 lines (473 loc) · 23.8 KB

Command Line Interface (CLI)

The CLI of Slang is designed to mimic that of solc. There are several main input/output (I/O) modes in the Slang interface:

The basic CLI is simpler and suitable for using from the shell. The standard JSON mode is similar to client-server interaction, thus more suitable for using from other applications.

All toolkits using Slang must be operating in standard JSON mode and follow its specification. It will make the toolkits more robust and future-proof, as the standard JSON mode is the most versatile and used for the majority of popular projects.

This page focuses on the basic CLI mode. For more information on the standard JSON mode, see this page.

Basic CLI

Basic CLI mode is the simplest way to compile a file with the source code.

To compile a basic Solidity contract, run the simple example from the --bin section.

The rest of this section describes the available CLI options and their usage. You may also check out slang --help for a quick reference.

All examples on this page are executable and verified against the compiler on every change. Unless stated otherwise, they compile this contract, Simple.sol:

{{#include 02-command-line-interface.in/Simple.sol}}

The examples use the following notation:

  • $ precedes the command being run; the lines below it show the command's output.
  • [..] matches any text within a line — used for values that differ between runs or environments, such as timings and hashes.
  • ... on its own line elides a run of output lines.
  • ? failed marks a command that exits with a non-zero code.

All commands on this page run in one shared working directory, so sections that emit files use per-section output directories (./build-llvm-ir/, ./build-asm/, …) to keep each listing scoped to its own artifacts.

--bin

Emits the full bytecode.

$ slang 'Simple.sol' --bin

======= Simple.sol:Simple =======
Binary:
34156008575f5ffd5b630000007080630000001b6080396080f3fe60043610603557346035575f3560e01c635a8ac02d8114602e57633df4ddf40360355760015b60805260206080f35b5060026025565b5f5ffdfea2646970667358221220[..]65736c616e67430002000034

--bin-runtime

Emits the runtime part of the bytecode.

$ slang 'Simple.sol' --bin-runtime

======= Simple.sol:Simple =======
Binary of the runtime part:
60043610603557346035575f3560e01c635a8ac02d8114602e57633df4ddf40360355760015b60805260206080f35b5060026025565b5f5ffdfea2646970667358221220[..]65736c616e67430002000034

--asm

Emits the text assembly produced by LLVM.

$ slang 'Simple.sol' --asm

======= Simple.sol:Simple =======
Deploy LLVM EVM assembly:
	.file	"LLVMDialectModule"
	.text
	.globl	__entry                         ; -- Begin function __entry
__entry:                                ; @__entry
; %bb.0:
	CALLVALUE
	ISZERO
...

Runtime LLVM EVM assembly:
	.file	"LLVMDialectModule"
	.text
	.globl	__entry                         ; -- Begin function __entry
__entry:                                ; @__entry
; %bb.0:
	PUSH1           0x4
	CALLDATASIZE
...

--metadata

Emits the contract metadata in the Solidity metadata format, which is hashed into the CBOR trailer of the bytecode. The compiler entry names Slang, and the settings carry the code generation settings: the optimizer mode and sizeFallback, and llvmOptions when --llvm-options is passed.

$ slang 'Simple.sol' --metadata

======= Simple.sol:Simple =======
Metadata:
{"compiler":{"name":"slang","version":"[..]"},"language":"Solidity","output":{"abi":[{"inputs":[],"name":"first","outputs":[{"internalType":"uint64","name":"","type":"uint64"}],"stateMutability":"pure","type":"function"},{"inputs":[],"name":"second","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"pure","type":"function"}]},"settings":{"compilationTarget":{"Simple.sol":"Simple"},"evmVersion":"osaka","libraries":{},"metadata":{"bytecodeHash":"ipfs"},"optimizer":{"mode":"3","sizeFallback":false},"remappings":[],"solidityVersion":"[..]"},"sources":{"Simple.sol":{"keccak256":"0x402fe0b38cc9d81e8c9f6d07854cca27fbb307f06d8a129998026907a10c7ca1","urls":["dweb:/ipfs/QmehmUFKCtytG8WcWQ676KvqwURfkVYK89VHZEvSzyLc2Z"]}},"version":1}

--ast-json

Emits the AST of each Solidity file.

$ slang 'Simple.sol' --ast-json

======= Simple.sol =======
JSON AST:
{"id":1,"type":"SourceUnit","range":{"start":32,"end":319},"file":"Simple.sol","members":[[..]]}

======= Simple.sol:Simple =======

The AST body is abbreviated here; it spans several thousand characters even for this small contract.

--abi

Emits the contract ABI specification.

$ slang 'Simple.sol' --abi

======= Simple.sol:Simple =======
Contract JSON ABI:
[{"inputs":[],"name":"first","outputs":[{"internalType":"uint64","name":"","type":"uint64"}],"stateMutability":"pure","type":"function"},{"inputs":[],"name":"second","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"pure","type":"function"}]

--hashes

Emits the contract function signatures.

$ slang 'Simple.sol' --hashes

======= Simple.sol:Simple =======
Function signatures:
3df4ddf4: first()
5a8ac02d: second()

--storage-layout

Emits the contract storage layout. Each astId is a Slang node identifier.

$ slang 'Simple.sol' --storage-layout

======= Simple.sol:Simple =======
Contract Storage Layout:
{"storage":[{"astId":[..],"contract":"Simple.sol:Simple","label":"field_1","offset":0,"slot":"0","type":"t_uint256"},{"astId":[..],"contract":"Simple.sol:Simple","label":"field_2","offset":0,"slot":"1","type":"t_uint256"},{"astId":[..],"contract":"Simple.sol:Simple","label":"field_3","offset":0,"slot":"2","type":"t_uint256"}],"types":{"t_uint256":{"encoding":"inplace","label":"uint256","numberOfBytes":"32"}}}

--transient-storage-layout

Emits the contract transient storage layout.

$ slang 'Simple.sol' --transient-storage-layout

======= Simple.sol:Simple =======
Contract Transient Storage Layout:
{"storage":[],"types":null}

--userdoc

Emits the contract user documentation.

Currently not supported. Usage:

slang 'Simple.sol' --userdoc

--devdoc

Emits the contract developer documentation.

Currently not supported. Usage:

slang 'Simple.sol' --devdoc

--debug-info

Emits the ELF-wrapped DWARF debug info of the deploy code.

$ slang 'Simple.sol' --debug-info

======= Simple.sol:Simple =======
Debug info:
7f454c46010201ff[..]

--debug-info-runtime

Emits the ELF-wrapped DWARF debug info of the runtime code.

$ slang 'Simple.sol' --debug-info-runtime

======= Simple.sol:Simple =======
Debug info of the runtime part:
7f454c46010201ff[..]

--emit-llvm-ir

Emits LLVM IR (both unoptimized and optimized).

When used with --output-dir, writes .ll files to the output directory. Without --output-dir, outputs to stdout.

Usage with --output-dir:

$ slang 'Simple.sol' --emit-llvm-ir --output-dir './build-llvm-ir/'
Compiler run successful. Artifact(s) can be found in directory "./build-llvm-ir/".

$ ls './build-llvm-ir/'
Simple_sol_Simple.optimized.ll
Simple_sol_Simple.unoptimized.ll
Simple_sol_Simple_deployed.optimized.ll
Simple_sol_Simple_deployed.unoptimized.ll

Usage with stdout:

$ slang 'Simple.sol' --emit-llvm-ir --bin

======= Simple.sol:Simple =======
Binary:
...
Deploy LLVM IR (unoptimized):
; ModuleID = 'Simple.sol:Simple'
...
Deploy LLVM IR:
; ModuleID = 'Simple.sol:Simple'
...

--benchmarks

Emits benchmarks of the compilation pipeline.

$ slang 'Simple.sol' --bin --benchmarks
Benchmarks:
Compiler_ReadInput: [..]us
Slang_RunStandardJSON: [..]us
Compiler_BuildProject: [..]us
Compiler_Compile: [..]us
Compiler_Link: [..]us
Slang_ParseAndBind: [..]us
Compiler_CreateMLIRContext: [..]us
Compiler_EmitSol:Simple.sol:Simple: [..]us
Compiler_RunSolPasses:Simple.sol:Simple: [..]us
...
Compiler_MLIRToLLVMIR:Simple.sol:Simple: [..]us
Compiler_EmitSol:Simple.sol:Simple_deployed: [..]us
Compiler_RunSolPasses:Simple.sol:Simple_deployed: [..]us
...
Compiler_MLIRToLLVMIR:Simple.sol:Simple_deployed: [..]us

======= Simple.sol:Simple =======
Binary:
[..]
Benchmarks:
    Simple.sol:Simple:runtime/ParseBitcode/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple_deployed:runtime/InitVerify/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple_deployed:runtime/OptimizeVerify/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple_deployed:runtime/EmitBytecode/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple:runtime/WorkerRoundtrip(0)/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple:deploy/ParseBitcode/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple:deploy/InitVerify/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple:deploy/OptimizeVerify/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple:deploy/EmitBytecode/M3B3/SpillArea(0): [..]us
    Simple.sol:Simple:deploy/WorkerRoundtrip(0)/M3B3/SpillArea(0): [..]us

Input Files

Slang supports multiple input files. The following command compiles two Solidity files and prints the bytecode:

slang 'Simple.sol' 'Complex.sol' --bin

Solidity import remappings are passed the same way as input files, but they are distinguished by a = symbol between source and destination. The following command compiles a Solidity file with a remapping and prints the bytecode:

slang 'Simple.sol' 'github.com/ethereum/dapp-bin/=/usr/local/lib/dapp-bin/' --bin

Slang applies remappings following solc's semantics. Visit the solc documentation to learn more about the processing of remappings.

--libraries

Specifies the libraries to link with compiled contracts. The option accepts multiple string arguments. The safest way is to wrap each argument in single quotes, and separate them with a space.

The specifier has the following format: <ContractPath>:<ContractName>=<LibraryAddress>.

Usage:

slang 'Simple.sol' --bin --libraries 'Simple.sol:Simple=0x1234567890abcdef1234567890abcdef12345678'

--base-path, --include-path, --allow-paths

These options are accepted for solc compatibility. Slang ignores them and resolves imports only against the sources it is given.

Visit the solc documentation to learn more about the processing of these options.

--output-dir

Specifies the output directory for build artifacts. Can only be used in basic CLI mode.

Usage in basic CLI mode:

$ slang 'Simple.sol' --bin --asm --output-dir './build/'
Compiler run successful. Artifact(s) can be found in directory "./build/".

$ ls './build/'
Simple_sol_Simple.asm
Simple_sol_Simple.bin
Simple_sol_Simple_deployed.asm
Simple_sol_Simple_llvm.asm
Simple_sol_Simple_llvm.asm-runtime

--overwrite

Overwrites the output files if they already exist in the output directory. By default, Slang does not overwrite existing files.

Can only be used in combination with the --output-dir option.

Usage:

$ slang 'Simple.sol' --bin --output-dir './build/' --overwrite
Compiler run successful. Artifact(s) can be found in directory "./build/".

Here ./build/ already contains the artifacts emitted in the --output-dir section, so the flag has existing files to overwrite.

If the --overwrite option is not specified and the output files already exist, Slang refuses to overwrite them and exits with an error:

$ slang 'Simple.sol' --bin --output-dir './build-overwrite/'
Compiler run successful. Artifact(s) can be found in directory "./build-overwrite/".

$ slang 'Simple.sol' --bin --output-dir './build-overwrite/'
? failed
Error: Refusing to overwrite an existing file "./build-overwrite/Simple_sol_Simple.bin" (use --overwrite to force).

--version

Prints the version of Slang and the hash of the LLVM commit it was built with.

Usage:

slang --version

--help

Prints the help message.

Usage:

slang --help

Other I/O Modes

The mode-altering CLI options are mutually exclusive. This means that only one of the options below can be enabled at a time:

--standard-json

For the standard JSON mode usage, see the Standard JSON page.

Slang Compilation Settings

The options in this section configure the Slang compilation pipeline.

--solidity-version

Sets the Solidity version the sources are compiled as. Slang accepts the syntax and built-ins available in that version, and every pragma solidity must allow it. The version is also recorded in the metadata.

Versions from 0.8.0 up to the latest one Slang supports are accepted. The default is the latest one every pragma solidity allows, or the latest one Slang supports if the pragmas allow no common version.

Usage:

slang 'Simple.sol' --bin --solidity-version '0.8.20'

--threads

Sets the number of threads used for parallel compilation. Each thread compiles a separate translation unit in a child process. By default, the number of threads equals the number of CPU cores.

Large projects can consume a lot of RAM during compilation on machines with a high number of cores. If you encounter memory issues, consider reducing the number of threads.

Usage:

slang 'Simple.sol' --bin --threads 4

--optimization / -O

Sets the optimization level of the LLVM optimizer. Available values are:

Level Meaning Hints
0 No optimization For fast compilation during development (unsupported)
1 Performance: basic For optimization research
2 Performance: default For optimization research
3 Performance: aggressive Best performance for production
s Size: default For optimization research
z Size: aggressive Best size for contracts with size constraints

For most cases, it is fine to keep the default value of 3. You should only use the level z if you are ready to deliberately sacrifice performance and optimize for size.

Optimization can affect exact gas consumption, memory expansion, and the preservation of source operations. See Optimizer and Assembly Semantics.

Large contracts may hit the EVM bytecode size limit. In this case, it is recommended to use the --optimization-size-fallback option rather than setting the level to z.

Usage:

slang 'Simple.sol' --bin -O3

This option can also be set with an environment variable SLANG_OPTIMIZATION, which is useful for toolkits where arbitrary Slang-specific options are not supported:

SLANG_OPTIMIZATION='3' slang 'Simple.sol' --bin

--optimization-size-fallback

Sets the optimization level to z for contracts that failed to compile due to overrunning the bytecode size constraints.

Under the hood, this option automatically triggers recompilation of contracts with level z. Contracts that were successfully compiled with the original --optimization setting are not recompiled.

For deployment, it is recommended to have this option enabled in order to mitigate potential issues with EVM bytecode size constraints on a per-contract basis. If your environment does not have bytecode size limitations, it is better to disable it to prevent unnecessary recompilations. A good example is running forge test.

Usage:

slang 'Simple.sol' --bin -O3 --optimization-size-fallback

This option can also be set with an environment variable SLANG_OPTIMIZATION_SIZE_FALLBACK, which is useful for toolkits where arbitrary Slang-specific options are not supported:

SLANG_OPTIMIZATION_SIZE_FALLBACK= slang 'Simple.sol' --bin -O3

--metadata-hash

Specifies the hash format used for contract metadata.

Usage with ipfs:

$ slang 'Simple.sol' --bin --metadata-hash 'ipfs'

======= Simple.sol:Simple =======
Binary:
34156008575f5ffd5b630000007080630000001b6080396080f3fe60043610603557346035575f3560e01c635a8ac02d8114602e57633df4ddf40360355760015b60805260206080f35b5060026025565b5f5ffdfea2646970667358221220[..]65736c616e67430002000034

The byte array starting with a2 at the end of the bytecode is a CBOR-encoded compiler version data and the hash of the contract metadata.

The last two bytes of the metadata (0x0034) are not a part of the CBOR payload, but the length of it, which must be known to correctly decode the payload.

JSON representation of the CBOR payload:

{
    // Optional: included if `--metadata-hash` is set to `ipfs`.
    "ipfs": "1220bec8fa0149a786c5810200ef5a436a154cff832af68ace5beeabcbb82166cb92",

    // Required: the Slang version as three bytes: major, minor and patch.
    "slang": "000200"
}

For more information on these formats, see the CBOR and IPFS documentation.

--no-cbor-metadata

Disables the CBOR metadata that is appended at the end of bytecode. This option is useful for debugging and research purposes.

It is not recommended to use this option in production, as it is not possible to verify contracts deployed without metadata.

Usage:

slang 'Simple.sol' --no-cbor-metadata

--llvm-options

Specifies additional options for the LLVM framework. The argument must be a single quoted string following a = separator.

Usage:

slang 'Simple.sol' --bin --llvm-options='-key=value'

The --llvm-options option is experimental and must only be used by experienced users. All supported options will be documented in the future.

solc Compilation Settings

The options in this section mirror the solc options of the same name.

--via-ir

Accepted for compatibility and ignored with a warning: Slang has a single compilation pipeline.

Usage:

$ slang 'Simple.sol' --bin --via-ir
Warning: viaIR is ignored: Slang has a single compilation pipeline.


======= Simple.sol:Simple =======
Binary:
34156008575f5ffd5b630000007080630000001b6080396080f3fe60043610603557346035575f3560e01c635a8ac02d8114602e57633df4ddf40360355760015b60805260206080f35b5060026025565b5f5ffdfea2646970667358221220[..]65736c616e67430002000034

--evm-version

Specifies the EVM version Slang will produce bytecode for. For instance, with version osaka, Slang will be producing clz instructions, whereas for older EVM versions it will not.

Only the following EVM versions are supported:

  • cancun
  • prague
  • osaka

The default is solc's default for the Solidity version, which is osaka for the latest one. A Solidity version older than 0.8.25 defaults to an EVM version Slang does not support yet, so it is compiled for cancun with a warning.

Usage:

slang 'Simple.sol' --bin --evm-version 'osaka'

--metadata-literal

Stores referenced sources as literal data in the metadata output.

Usage:

slang 'Simple.sol' --bin --metadata --metadata-literal

--no-import-callback

Disables the default import resolution callback. Accepted for solc compatibility and ignored.

This parameter is used by some tooling that resolves all imports by itself, such as Hardhat.

Usage:

slang 'Simple.sol' --no-import-callback

Multi-Language Support

Slang supports input in multiple programming languages:

The following sections outline how to use Slang with these languages.

--yul (or --strict-assembly)

Enables the Yul mode. In this mode, input is expected to be in the Yul language. The output works the same way as with Solidity input.

Yul input is optimized through LLVM and is not emitted as a verbatim EVM opcode sequence. See Optimizer and Assembly Semantics.

Yul input is currently not supported. The example passes this Yul object, Simple.yul:

{{#include 02-command-line-interface.in/Simple.yul}}

Usage:

$ slang --yul 'Simple.yul' --bin
? 1
Error: Yul is not supported yet.

--llvm-ir

Enables the LLVM IR mode. In this mode, input is expected to be in the LLVM IR language. The output works the same way as with Solidity input.

In this mode, every input file is treated as runtime code, while deploy code will be generated automatically by Slang. It is not possible to write deploy code manually yet, but it will be supported in the future.

Unlike solc, Slang is an LLVM-based compiler toolchain, so it uses LLVM IR as an intermediate representation. It is not recommended to write LLVM IR manually, but it can be useful for debugging and optimization purposes. LLVM IR is more low-level than Yul and EVM assembly in the Slang IR hierarchy.

The example input Simple.ll is the optimized runtime module of Simple.sol above, as produced by --emit-llvm-ir.

Usage:

$ slang --llvm-ir 'Simple.ll' --bin

======= Simple.ll =======
Binary:
5b63000000488063000000115f395ff3fe34600b57600336116016575b5f5ffd5b5060016031565b5f3560e01c633df4ddf48114600f57635a8ac02d03600b5760025b60805260206080f3fea165736c616e6743000200000b

Debugging

IR Output Flags

For selective IR output, use the following flags with --output-dir:

These flags respect the --overwrite option. Without --overwrite, the compiler will refuse to overwrite existing files.

SLANG_OUTPUT_DIR Environment Variable

For debugging purposes, all intermediate build artifacts can be dumped to a directory using the SLANG_OUTPUT_DIR environment variable. This is useful for toolkits where arbitrary Slang-specific options are not supported.

When this environment variable is set, Slang will output all intermediate representations to the specified directory, always overwriting existing files.

The intermediate build artifacts include:

Name Extension
LLVM IR ll
LLVM Assembly asm

Usage:

$ SLANG_OUTPUT_DIR='./debug/' slang 'Simple.sol' --bin
...
$ ls './debug/'
Simple_sol_Simple.asm
Simple_sol_Simple.optimized.ll
Simple_sol_Simple.unoptimized.ll
Simple_sol_Simple_deployed.asm
Simple_sol_Simple_deployed.optimized.ll
Simple_sol_Simple_deployed.unoptimized.ll

The output file name is constructed as follows: <ContractPath>_<ContractName>[_runtime].<Modifiers>.<Extension>.

Additionally, it is possible to dump the standard JSON input file with the SLANG_STANDARD_JSON_DEBUG environment variable:

SLANG_STANDARD_JSON_DEBUG='./debug/input.json' slang 'Simple.sol' --bin
cat './debug/input.json' | jq .

--llvm-verify-each

Enables the verification of the LLVM IR after each optimization pass. This option is useful for debugging and research purposes.

Usage:

slang 'Simple.sol' --bin --llvm-verify-each

--llvm-debug-logging

Enables the debug logging of the LLVM IR optimization passes. This option is useful for debugging and research purposes.

Usage:

slang 'Simple.sol' --bin --llvm-debug-logging