diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/contracts.rst | 37 | ||||
| -rw-r--r-- | docs/contributing.rst | 55 | ||||
| -rw-r--r-- | docs/index.rst | 3 | ||||
| -rw-r--r-- | docs/installing-solidity.rst | 187 | ||||
| -rw-r--r-- | docs/introduction-to-smart-contracts.rst | 12 | ||||
| -rw-r--r-- | docs/security-considerations.rst | 4 | ||||
| -rw-r--r-- | docs/types.rst | 9 | ||||
| -rw-r--r-- | docs/units-and-global-variables.rst | 6 |
8 files changed, 222 insertions, 91 deletions
diff --git a/docs/contracts.rst b/docs/contracts.rst index dfdcaf18..a22a3544 100644 --- a/docs/contracts.rst +++ b/docs/contracts.rst @@ -195,45 +195,47 @@ return parameter list for functions. uint public data; } -An other contract ``D`` can call ``c.getData()`` to retrieve the value of data in state -storage and is not able to call ``f``. Contract ``E`` is derived from ``C`` and can call -``compute``. +In the following example, ``D``, can call ``c.getData()`` to retrieve the value of +``data`` in state storage, but is not able to call ``f``. Contract ``E`` is derived from +``C`` and, thus, can call ``compute``. :: contract C { + uint private data; + function f(uint a) private returns(uint b) { return a + 1; } function setData(uint a) { data = a; } - function getData() public returns(uint) {return data;} - function compute(uint a, uint b) internal returns (uint) { return a+b;} - uint private data; + function getData() public returns(uint) { return data; } + function compute(uint a, uint b) internal returns (uint) { return a+b; } } + contract D { function readData() { C c = new C(); - local = c.f(7); // error: member "f" is not visible + uint local = c.f(7); // error: member "f" is not visible c.setData(3); - uint local = c.getData(); - local = c.compute(3,5); // error: member "compute" is not visible + local = c.getData(); + local = c.compute(3, 5); // error: member "compute" is not visible } } + contract E is C { function g() { C c = new C(); - uint val = compute(3,5); // acces to internal member (from derivated to parent contract) + uint val = compute(3, 5); // acces to internal member (from derivated to parent contract) } } - .. index:: ! accessor;function, ! function;accessor Accessor Functions ================== The compiler automatically creates accessor functions for -all public state variables. For the contract given below the compiler will +all public state variables. For the contract given below, the compiler will generate a function called ``data`` that does not take any arguments and returns a ``uint``, the value of the state variable ``data``. The initialization of state variables can @@ -245,6 +247,7 @@ be done at declaration. uint public data = 42; } + contract Caller { C c = new C(); function f() { @@ -254,8 +257,8 @@ be done at declaration. The accessor functions have external visibility. If the symbol is accessed internally (i.e. without ``this.``), -it is evaluated as state variable and if it is accessed externally -(i.e. with ``this.``), it is evaluated as function. +it is evaluated as a state variable and if it is accessed externally +(i.e. with ``this.``), it is evaluated as a function. :: @@ -444,6 +447,12 @@ In particular, the following operations will consume more gas than the stipend p Please ensure you test your fallback function thoroughly to ensure the execution cost is less than 2300 gas before deploying a contract. +.. warning:: + Contracts that receive Ether but do not define a fallback function + throw an exception, sending back the Ether (this was different + before Solidity v0.4.0). So if you want your contract to receive Ether, + you have to implement a fallback function. + :: contract Test { diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..cef6dfd2 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,55 @@ +############ +Contributing +############ + +Help is always appreciated! + +To get started, you can try :ref:`building-from-source` in order to familiarize +yourself with the components of Solidity and the build process. Also, it may be +useful to become well-versed at writing smart-contracts in Solidity. + +In particular, we need help in the following areas: + +* Improving the documentation +* Responding to questions from other users on `StackExchange + <http://ethereum.stackexchange.com/>`_ and the `Solidity Gitter + <https://gitter.im/ethereum/solidity>`_ +* Fixing and responding to `Solidity's GitHub issues + <https://github.com/ethereum/solidity/issues>`_ + +How to Report Issues +==================== + +To report an issue, please use the +`GitHub issues tracker <https://github.com/ethereum/solidity/issues>`_. When +reporting issues, please mention the following details: + +* Which version of Solidity you are using +* Which platform are you running on +* How to reproduce the issue +* What was the result of the issue +* What the expected behaviour is + +Workflow for Pull Requests +========================== + +In order to contribute, please fork off of the ``develop`` branch and make your +changes there. Your commit messages should detail *why* you made your change, as +opposed to *what* you did. + +If you need to pull in any changes from ``develop`` after making your fork (for +example, to resolve potential merge conflicts), please avoid using ``git merge`` +and instead, ``git rebase`` your branch. + +Additionally, if you are writing a new feature, please ensure you write appropriate +Boost test cases and place them under ``test/``. + +However, if you are making a larger change, please consult with the Gitter +channel, first. + +Finally, please make sure you respect the `coding standards +<https://raw.githubusercontent.com/ethereum/cpp-ethereum/develop/CodingStandards.txt>`_ +for this project. Also, even though we do CI testing, please test your code and +ensure that it builds locally before submitting a pull request. + +Thank you for your help! diff --git a/docs/index.rst b/docs/index.rst index a330172e..a5ab3f86 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -66,7 +66,7 @@ Discontinued: Solidity Tools -------------------------------- +-------------- * `Solidity REPL <https://github.com/raineorshine/solidity-repl>`_ Try Solidity instantly with a command-line Solidity console. @@ -113,4 +113,5 @@ Contents security-considerations.rst style-guide.rst common-patterns.rst + contributing.rst frequently-asked-questions.rst diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst index ba40c99f..ad27e528 100644 --- a/docs/installing-solidity.rst +++ b/docs/installing-solidity.rst @@ -1,3 +1,7 @@ +.. index:: ! installing + +.. _installing-solidity: + ################### Installing Solidity ################### @@ -8,8 +12,10 @@ Browser-Solidity If you just want to try Solidity for small contracts, you can try `browser-solidity <https://ethereum.github.io/browser-solidity>`_ which does not need any installation. If you want to use it -without connection to the Internet, you can also just save the page -locally or clone http://github.com/ethereum/browser-solidity. +without connection to the Internet, you can go to +https://github.com/ethereum/browser-solidity/tree/gh-pages and +download the .ZIP file as explained on that page. + npm / Node.js ============= @@ -22,7 +28,7 @@ package available. To install it, simply use -:: +.. code:: bash npm install solc @@ -32,102 +38,151 @@ Details about the usage of the Node.js package can be found in the Binary Packages =============== -Binary packages of Solidity together with its IDE Mix are available through -the `C++ bundle <https://github.com/ethereum/webthree-umbrella/releases>`_ of -Ethereum. +Binary packages of Solidity available at +`solidity/releases <https://github.com/ethereum/solidity/releases>`_. -Building from Source -==================== +We also have PPAs for Ubuntu. For the latest stable version. -Building Solidity is quite similar on MacOS X, Ubuntu and probably other Unices. -This guide starts explaining how to install the dependencies for each platform -and then shows how to build Solidity itself. +.. code:: bash -MacOS X -------- + sudo add-apt-repository ppa:ethereum/ethereum + sudo apt-get update + sudo apt-get install solc +If you want to use the cutting edge developer version: -Requirements: +.. code:: bash -- OS X Yosemite (10.10.5) -- Homebrew -- Xcode + sudo add-apt-repository ppa:ethereum/ethereum + sudo add-apt-repository ppa:ethereum/ethereum-dev + sudo apt-get update + sudo apt-get install solc -Set up Homebrew: +Homebrew is missing pre-built bottles at the time of writing, +following a Jenkins to TravisCI migration, but Homebrew +should still work just fine as a means to build-from-source. +We will re-add the pre-built bottles soon. -.. code-block:: bash +.. code:: bash brew update brew upgrade + brew tap ethereum/ethereum + brew install solidity + brew linkapps solidity + + +.. _building-from-source: + +Building from Source +==================== + +Clone the Repository +-------------------- + +To clone the source code, execute the following command: + +.. code:: bash + + git clone --recursive https://github.com/ethereum/solidity.git + cd solidity + +If you want to help developing Solidity, +you should fork Solidity and add your personal fork as a second remote: + +.. code:: bash + + cd solidity + git remote add personal git@github.com:[username]/solidity.git - brew install boost --c++11 # this takes a while - brew install cmake cryptopp gmp jsoncpp -Ubuntu Trusty (14.04) +Prerequisites - macOS --------------------- -Below are the instructions to install the minimal dependencies required -to compile Solidity on Ubuntu 14.04 (Trusty Tahr). +For macOS, ensure that you have the latest version of +`Xcode installed <https://developer.apple.com/xcode/download/>`_. +This contains the `Clang C++ compiler <https://en.wikipedia.org/wiki/Clang>`_, the +`Xcode IDE <https://en.wikipedia.org/wiki/Xcode>`_ and other Apple development +tools which are required for building C++ applications on OS X. +If you are installing Xcode for the first time, or have just installed a new +version then you will need to agree to the license before you can do +command-line builds: + +.. code:: bash + + sudo xcodebuild -license accept + +Our OS X builds require you to `install the Homebrew <http://brew.sh>`_ +package manager for installing external dependencies. +Here's how to `uninstall Homebrew +<https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/FAQ.md#how-do-i-uninstall-homebrew>`_, +if you ever want to start again from scratch. -.. code-block:: bash - sudo apt-get -y install build-essential git cmake libgmp-dev libboost-all-dev \ - libjsoncpp-dev +Prerequisites - Windows +----------------------- - sudo add-apt-repository -y ppa:ethereum/ethereum - sudo add-apt-repository -y ppa:ethereum/ethereum-dev - sudo apt-get -y update - sudo apt-get -y upgrade # this will update cmake to version 3.x - sudo apt-get -y install libcryptopp-dev libjsoncpp-dev +You will need to install the following dependencies for Windows builds of Solidity: -Ubuntu Xenial (16.04) ++------------------------------+-------------------------------------------------------+ +| Software | Notes | ++==============================+=======================================================+ +| `Git for Windows`_ | Command-line tool for retrieving source from Github. | ++------------------------------+-------------------------------------------------------+ +| `CMake`_ | Cross-platform build file generator. | ++------------------------------+-------------------------------------------------------+ +| `Visual Studio 2015`_ | C++ compiler and dev environment. | ++------------------------------+-------------------------------------------------------+ + +.. _Git for Windows: https://git-scm.com/download/win +.. _CMake: https://cmake.org/download/ +.. _Visual Studio 2015: https://www.visualstudio.com/products/vs-2015-product-editions + + +External Dependencies --------------------- -Below are the instructions to install the minimal dependencies required -to compile Solidity on Ubuntu 16.04 (Xenial Xerus). +We now have a "one button" script which installs all required external dependencies +on macOS, Windows and on numerous Linux distros. This used to be a multi-step +manual process, but is now a one-liner: -One of the dependencies (Crypto++ Library, with version >= 5.6.2) can be -installed either by adding the Ethereum PPA (Option 1) or by backporting -``libcrypto++`` from Ubuntu Development to Ubuntu Xenial (Option 2). +.. code:: bash -.. code-block:: bash + ./scripts/install_deps.sh - sudo apt-get -y install build-essential git cmake libgmp-dev libboost-all-dev \ - libjsoncpp-dev +Or, on Windows: - # (Option 1) For those willing to add the Ethereum PPA: - sudo add-apt-repository -y ppa:ethereum/ethereum - sudo add-apt-repository -y ppa:ethereum/ethereum-dev - sudo apt-get -y update - sudo apt-get -y upgrade - sudo apt-get -y install libcryptopp-dev +.. code:: bat - ## (Option 2) For those willing to backport libcrypto++: - #sudo apt-get -y install ubuntu-dev-tools - #sudo pbuilder create - #mkdir ubuntu - #cd ubuntu - #backportpackage --workdir=. --build --dont-sign libcrypto++ - #sudo dpkg -i buildresult/libcrypto++6_*.deb buildresult/libcrypto++-dev_*.deb - #cd .. + scripts\install_deps.bat -Building --------- -Run this if you plan on installing Solidity only: +Command-Line Build +------------------ -.. code-block:: bash +Building Solidity is quite similar on Linux, macOS and other Unices: + +.. code:: bash - git clone --recursive https://github.com/ethereum/solidity.git - cd solidity mkdir build cd build cmake .. && make -If you want to help developing Solidity, -you should fork Solidity and add your personal fork as a second remote: +And even on Windows: -.. code-block:: bash +.. code:: bash - cd solidity - git remote add personal git@github.com:username/solidity.git + mkdir build + cd build + cmake -G "Visual Studio 14 2015 Win64" .. + +This latter set of instructions should result in the creation of +**solidity.sln** in that build directory. Double-clicking on that file +should result in Visual Studio firing up. We suggest building +**RelWithDebugInfo** configuration, but all others work. + +Alternatively, you can build for Windows on the command-line, like so: + +.. code:: bash + + cmake --build . --config RelWithDebInfo diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst index fbce4244..6fcd4854 100644 --- a/docs/introduction-to-smart-contracts.rst +++ b/docs/introduction-to-smart-contracts.rst @@ -220,7 +220,7 @@ only the person holding the keys to the account can transfer money from it. Blocks ====== -One major obstacle to overcome is what, in Bitcoin terms, is called "double-spend attack": +One major obstacle to overcome is what, in Bitcoin terms, is called a "double-spend attack": What happens if two transactions exist in the network that both want to empty an account, a so-called conflict? @@ -444,13 +444,13 @@ receives the address of the new contract on the stack. .. index:: selfdestruct -Selfdestruct -============ +``selfdestruct`` +================ The only possibility that code is removed from the blockchain is -when a contract at that address performs the ``SELFDESTRUCT`` operation. +when a contract at that address performs the ``selfdestruct`` operation. The remaining Ether stored at that address is sent to a designated target and then the storage and code is removed. -Note that even if a contract's code does not contain the ``SELFDESTRUCT`` -opcode, it can still perform that operation using delegatecall or callcode. +Note that even if a contract's code does not contain a call to ``selfdestruct``, +it can still perform that operation using ``delegatecall`` or ``callcode``. diff --git a/docs/security-considerations.rst b/docs/security-considerations.rst index f8d099e4..7e846674 100644 --- a/docs/security-considerations.rst +++ b/docs/security-considerations.rst @@ -103,7 +103,9 @@ and stall those. Please be explicit about such cases in the documentation of you Sending and Receiving Ether =========================== -- If a contract receives Ether (without a function being called), the fallback function is executed. The contract can only rely +- If a contract receives Ether (without a function being called), the fallback function is executed. + If it does not have a fallback function, the Ether will be rejected (by throwing an exception). + During the execution of the fallback function, the contract can only rely on the "gas stipend" (2300 gas) being available to it at that time. This stipend is not enough to access storage in any way. To be sure that your contract can receive Ether in that way, check the gas requirements of the fallback function (for example in the "details" section in browser-solidity). diff --git a/docs/types.rst b/docs/types.rst index d6445ed9..737fbe7d 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -661,13 +661,18 @@ Explicit Conversions -------------------- If the compiler does not allow implicit conversion but you know what you are -doing, an explicit type conversion is sometimes possible:: +doing, an explicit type conversion is sometimes possible. Note that this may +give you some unexpected behaviour so be sure to test to ensure that the +result is what you want! Take the following example where you are converting +a negative ``int8`` to a ``uint``: + +:: int8 y = -3; uint x = uint(y); At the end of this code snippet, ``x`` will have the value ``0xfffff..fd`` (64 hex -characters), which is -3 in two's complement representation of 256 bits. +characters), which is -3 in the two's complement representation of 256 bits. If a type is explicitly converted to a smaller type, higher-order bits are cut off:: diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index d1d578ed..9ee334cf 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -18,7 +18,7 @@ Suffixes like ``seconds``, ``minutes``, ``hours``, ``days``, ``weeks`` and ``years`` after literal numbers can be used to convert between units of time where seconds are the base unit and units are considered naively in the following way: - * ``1 == 1 second`` + * ``1 == 1 seconds`` * ``1 minutes == 60 seconds`` * ``1 hours == 60 minutes`` * ``1 days == 24 hours`` @@ -109,6 +109,10 @@ This means that the following are all identical:: If padding is needed, explicit type conversions can be used: ``sha3("\x00\x12")`` is the same as ``sha3(uint16(0x12))``. +Note that constants will be packed using the minimum number of bytes required to store them. +This means that, for example, ``sha3(0) == sha3(uint8(0))`` and +``sha3(0x12345678) == sha3(uint32(0x12345678))``. + It might be that you run into Out-of-Gas for ``sha256``, ``ripemd160`` or ``ecrecover`` on a *private blockchain*. The reason for this is that those are implemented as so-called precompiled contracts and these contracts only really exist after they received the first message (although their contract code is hardcoded). Messages to non-existing contracts are more expensive and thus the execution runs into an Out-of-Gas error. A workaround for this problem is to first send e.g. 1 Wei to each of the contracts before you use them in your actual contracts. This is not an issue on the official or test net. .. _address_related: |