diff options
author | chriseth <c@ethdev.com> | 2016-07-21 01:46:31 +0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2016-07-21 01:46:31 +0800 |
commit | 077c8ad83d8efa3e5fbd334ab0d0135e1f4e5e3e (patch) | |
tree | ff511e1b6c85f37c2db857a7dea2451d226ea3bd /docs | |
parent | 980abfe52aac3161dc4f25574da83bfc6be977bf (diff) | |
parent | 9f7a55d2b28169cc54795eb0b93eba9ce8608dca (diff) | |
download | dexon-solidity-077c8ad83d8efa3e5fbd334ab0d0135e1f4e5e3e.tar dexon-solidity-077c8ad83d8efa3e5fbd334ab0d0135e1f4e5e3e.tar.gz dexon-solidity-077c8ad83d8efa3e5fbd334ab0d0135e1f4e5e3e.tar.bz2 dexon-solidity-077c8ad83d8efa3e5fbd334ab0d0135e1f4e5e3e.tar.lz dexon-solidity-077c8ad83d8efa3e5fbd334ab0d0135e1f4e5e3e.tar.xz dexon-solidity-077c8ad83d8efa3e5fbd334ab0d0135e1f4e5e3e.tar.zst dexon-solidity-077c8ad83d8efa3e5fbd334ab0d0135e1f4e5e3e.zip |
Merge pull request #699 from chriseth/sourceLocation
WIP: Source location as part of AST.
Diffstat (limited to 'docs')
-rw-r--r-- | docs/miscellaneous.rst | 53 |
1 files changed, 53 insertions, 0 deletions
diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 825be2ce..9b067fb1 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -95,6 +95,59 @@ is simplified to code which can also be compiled from even though the instructions contained a jump in the beginning. +.. index:: source mappings + +*************** +Source Mappings +*************** + +As part of the AST output, the compiler provides the range of the source +code that is represented by the respective node in the AST. This can be +used for various purposes ranging from static analysis tools that report +errors based on the AST and debugging tools that highlight local variables +and their uses. + +Furthermore, the compiler can also generate a mapping from the bytecode +to the range in the source code that generated the instruction. This is again +important for static analysis tools that operate on bytecode level and +for displaying the current position in the source code inside a debugger +or for breakpoint handling. + +Both kinds of source mappings use integer indentifiers to refer to source files. +These are regular array indices into a list of source files usually called +``"sourceList"``, which is part of the combined-json and the output of +the json / npm compiler. + +The source mappings inside the AST use the following +notation: + +``s:l:f`` + +Where ``s`` is the byte-offset to the start of the range in the source file, +``l`` is the length of the source range in bytes and ``f`` is the source +index mentioned above. + +The encoding in the source mapping for the bytecode is more complicated: +It is a list of ``s:l:f:j`` separated by ``;``. Each of these +elements corresponds to an instruction, i.e. you cannot use the byte offset +but have to use the instruction offset or PC (program counter). +The fields ``s``, ``l`` and ``f`` are as above and ``j`` can be either +``i``, ``o`` or ``-`` signifying whether a jump instruction goes into a +function, returns from a function or is a regular jump as part of e.g. a loop. + +In order to compress these source mappings especially for bytecode, the +following rules are used: + + - If a field is empty, the value of the preceding element is used. + - If a ``:`` is missing, all following fields are considered empty. + +This means the following source mappings represent the same information: + +``1:2:1;1:9:1;2:1:2;2:1:2;2:1:2`` + +``1:2:1;:9;2::2;;`` + + .. index:: ! commandline compiler, compiler;commandline, ! solc, ! linker .. _commandline-compiler: |