/ README.org
README.org
1 #+TITLE: Emacs Solidity Mode 2 #+AUTHOR: Lefteris Karapetsas 3 4 [[LICENSE][file:https://img.shields.io/badge/License-GPL%20v3-blue.svg]] [[http://melpa.org/#/solidity-mode][file:http://melpa.org/packages/solidity-mode-badge.svg]] 5 6 A simple language mode for the Solidity language. It is a constant work in progress as the 7 language itself also progresses. For information about Solidity check the [[https://github.com/ethereum/wiki/wiki/Solidity-Tutorial][Tutorial]] and the [[https://github.com/ethereum/wiki/wiki/Solidity-Features][Features]] 8 wiki pages. 9 10 11 * Installation 12 You can simply load the file in your emacs but the recommended way to install it is either via el-get or MELPA. 13 14 ** El-get 15 If you don't know how to use el-get you can find more information on its [[https://github.com/dimitri/el-get][webpage]]. First [[https://github.com/dimitri/el-get#basic-setup][install el-get]] and then (in emacs), press =Alt+x= (this is in emacs notation written as =M-x= ) and then type =el-get-install=. This will prompt you for a package, type =solidity-mode= and hit enter, this should install all you need. 16 17 ** Melpa 18 You can also obtain solidity-mode from [[http://melpa.org/#/][Melpa]] as can be seen [[http://melpa.org/#/solidity-mode][here]]. 19 20 1. Install melpa and make sure emacs is started with it. 21 2. Press =Alt+x= (this is in emacs notation written as =M-x= ) and then type =package-refresh-contents=. 22 3. Press =Alt+x= and then type =package-install=. This will prompt you for a package. 23 3. type =solidity-mode= and hit enter, this should install all you need. 24 25 * Configuration 26 By default solidity-mode associates itself with any files ending in =.sol=. 27 28 If using =el-get= then you should have a specific package initializing lisp file. If not then you can put these 29 anywhere in your =init.el=. 30 31 ** Generic configuration 32 Regardless of where you installed solidity mode from, you need to require the package: 33 #+BEGIN_SRC lisp 34 (require 'solidity-mode) 35 #+END_SRC 36 (append that line to your =~/.emacs= file) 37 38 You can also set the way the comments are inserted by emacs with commands like =comment-region=. The default is 39 =/* .. */= and you can turn it to using =//= instead by putting the following into your emacs config: 40 41 #+BEGIN_SRC lisp 42 (setq solidity-comment-style 'slash) 43 ;; or 44 (setq solidity-comment-style 'star) ;; this is the default 45 #+END_SRC 46 47 ** Keymap 48 You can modify the default keybindings of the solidity mode keymap by adding 49 a new key combination for each command you want to change. For example 50 51 #+BEGIN_SRC lisp 52 (define-key solidity-mode-map (kbd "C-c C-g") 'solidity-estimate-gas-at-point) 53 #+END_SRC 54 55 ** Interface with linters 56 *** Provide path to solc binary 57 The =solc= binary is assumed to be part of the PATH. Wherever that is not the case you would have to manually 58 set the location of the binary like below: 59 #+BEGIN_SRC emacs-lisp 60 (setq solidity-solc-path "/home/lefteris/ew/cpp-ethereum/build/solc/solc") 61 #+END_SRC 62 63 Note: This better be set before requiring solidity mode. 64 65 *** Provide path to solium binary 66 The =solium= binary is assumed to be part of the user's =PATH=. If this is not the case 67 then set its location like below: 68 #+BEGIN_SRC emacs-lisp 69 (setq solidity-solium-path "/home/lefteris/.npm-global/bin/solium") 70 #+END_SRC 71 72 73 ** [Optional] Flycheck interface 74 Solidity mode can also interface with [[https://github.com/flycheck/flycheck][flycheck]] if you have it. Make sure to 75 download and install the flycheck package. Then configure it to either work on 76 all modes or enable it only for solidity mode. 77 78 Flycheck can interface with solc and/or with [[http://solium.readthedocs.io/en/latest/][solium]]. We only support integration 79 with solium >= =v0.2.0= 80 81 You have to specifically set the path 82 to both executables and activate the checker integration by setting the following: 83 84 To activate flycheck you need the =solidity-flycheck= package and to add this in your 85 emacs file: 86 87 #+BEGIN_SRC emacs-lisp 88 (require 'solidity-flycheck) 89 #+END_SRC 90 91 To activate =solc= checker 92 #+BEGIN_SRC emacs-lisp 93 (setq solidity-flycheck-solc-checker-active t) 94 #+END_SRC 95 96 To activate =solium= checker 97 #+BEGIN_SRC emacs-lisp 98 (setq solidity-flycheck-solium-checker-active t) 99 #+END_SRC 100 101 102 Keep in mind that you need to provide the path to either solc or solium unless 103 emacs can already find it in your environment's =PATH=. Even if you can call it 104 from the command line it does not mean that EMACS can see it as emacs may be started 105 by systemd at which point =PATH= is not fully populated. 106 107 *** Configuring solc checker 108 109 You can configure flycheck's solc invocation with the following arguments 110 111 **** std contracts 112 By default this is false. If you want to include the standard contracts just add the following to your emacs init file 113 114 #+BEGIN_SRC emacs-lisp 115 (setq flycheck-solidity-solc-addstd-contracts t) 116 #+END_SRC 117 118 *** Configuring solium checker 119 You can configure flycheck's solium incocation with the following arguments 120 121 **** solium RC file 122 By default solium looks at the current directory of the file you are editing in order to find =.soliumrc.json=. Having this 123 file is required. But you can point to an external configuration file by putting the following anywhere in your emacs init file. 124 125 #+BEGIN_SRC emacs-lisp 126 (setq flycheck-solidity-solium-soliumrcfile "/home/path/to/common/.soliumrc.json") 127 #+END_SRC 128 129 *** Chaining both checkers 130 If you enable both checkers then their results are chained. The variable =solidity-flycheck-chaining-error-level= controls 131 how they are chained. Its value can be either =t=, =error=, =warning= or =info= and that controls the maximum error level 132 of the solc checker after which solium will not run. If =t= is given solium will always run. The default is =warning=, so 133 if anything over than a warning is found in solc solium will not run. 134 135 ** [Optional] Autocompletion 136 To achieve solidity autcompletion you will need the =company-solidity= package, a simple [[http://company-mode.github.io/][company-mode]] back-end for Solidity. 137 To use it make sure that company-mode is installed and then: 138 139 #+BEGIN_SRC emacs-lisp 140 (require 'company-solidity) 141 #+END_SRC 142 143 *** What it does 144 Give completion suggestions for Solidity keywords, global variables, and address methods. 145 146 *** What it isn't 147 Smart. The completion suggestions are *not context dependent*. 148 149 *** Something to watch out for 150 =company-mode= treats =.= as the end of a word, and will cut off compeletion suggestions when you type a =.=. So, when you've typed =msg= you will get =msg.sender=, =msg.value= etc. as completion suggestions. However, as soon as you type =msg.=, the suggestions will disappear. 151 152 *** Local Variables 153 If you want autocomplete suggestions to include local variables, in addition to Solidity keywords, add the following to your =init.el=: 154 155 #+BEGIN_SRC emacs-lisp 156 (add-hook 'solidity-mode-hook 157 (lambda () 158 (set (make-local-variable 'company-backends) 159 (append '((company-solidity company-capf company-dabbrev-code)) 160 company-backends)))) 161 #+END_SRC 162 163 * Commands 164 165 ** Gas estimate of function under point 166 You can get an estimate of the function under the cursor, by placing the curson 167 on top of the function name and typing =C-c C-g=. 168 169 This will call =solidity-estimate-gas-at-point= and provide a max gas estimate, 170 if possible, for the function. 171 * Features 172 + Syntax highlighting 173 + Autocompletion 174 + Indentation 175 + On the fly syntax checking with flycheck 176 + Gas estimation for function under point