diff options
Diffstat (limited to 'docs/layout-of-source-files.rst')
| -rw-r--r-- | docs/layout-of-source-files.rst | 78 |
1 files changed, 66 insertions, 12 deletions
diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index 445162f5..1128685d 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -9,24 +9,78 @@ Source files can contain an arbitrary number of contract definitions and include Importing other Source Files ============================ +Syntax and Semantics +-------------------- -Other source files can be referenced using `import "filename";` and the symbols -defined there will also be available in the current source file. +Solidity supports import statements that are very similar to those available in JavaScript +(from ES6 on), although Solidity does not know the concept of a "default export". -.. warning:: +At a global level, you can use import statements of the following form: - Import will not work automatically for the commandline-compiler. - Furthermore, this system of importing other files is not completely fleshed out - yet, so please expect changes. +`import "filename";` will import all global symbols from "filename" (and symbols imported there) into the current global scope (different than in ES6 but backwards-compatible for Solidity). + +`import * as symbolName from "filename";` creates a new global symbol `symbolName` whose members are all the global symbols from `"filename"`. + +`import {symbol1 as alias, symbol2} from "filename";` creates new global symbols `alias` and `symbol2` which reference `symbol1` and `symbal2` from `"filename"`, respectively. + +Another syntax is not part of ES6, but probably convenient: + +`import "filename" as symbolName;` is equivalent to `import * as symbolName from "filename";`. + +Paths +----- + +In the above, `filename` is always treated as a path with `/` as directory separator, +`.` as the current and `..` as the parent directory. Path names that do not start +with `.` are treated as absolute paths. + +To import a file `x` from the same directory as the current file, use `import "./x" as x;`. +If you use `import "x" as x;` instead, a different file could be referenced +(in a global "include directory"). + +It depends on the compiler (see below) how to actually resolve the paths. +In general, the directory hierarchy does not need to strictly map onto your local +filesystem, it can also map to resources discovered via e.g. ipfs, http or git. + +Use in actual Compilers +----------------------- + +When the compiler is invoked, it is not only possible to specify how to +discover the first element of a path, but it is possible to specify path prefix +remappings so that e.g. `github.com/ethereum/dapp-bin/library` is remapped to +`/usr/local/dapp-bin/library` and the compiler will read the files from there. If +remapping keys are prefixes of each other, the longest is tried first. This +allows for a "fallback-remapping" with e.g. `""` maps to +`"/usr/local/include/solidity"`. + +**solc**: + +For solc (the commandline compiler), these remappings are provided as `key=value` +arguments, where the `=value` part is optional (and defaults to key in that +case). All remapping values that are regular files are compiled (including +their dependencies). This mechanism is completely backwards-compatible (as long +as no filename contains a =) and thus not a breaking change. + +So as an example, if you clone +`github.com/ethereum/dapp-bin/` locally to `/usr/local/dapp-bin`, you can use +the following in your source file: + +`import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;` + +and then run the compiler as + +`solc github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ source.sol` + +**browser-solidity**: The `browser-based compiler <https://chriseth.github.io/browser-solidity>`_ -has quite advanced support for multiple files and can even import files -directly from github, by using e.g. -```import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol";``` +provides an automatic remapping for github and will also automatically retrieve +the file over the network: +You can import the iterable mapping by e.g. +`import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;`. + +Other source code providers may be added in the future. -If you want to use multiple source files with the (commandline compiler)[../commandline-compiler/] solc, -you have to specify all files you will use as arguments to solc, -the compiler will not yet search your filesystem on its own. .. index:: ! comment, natspec |