Updated 11 May 2015 - Olympic Edition
INTRODUCTION
This tutorial describes how to build the C++ GUI Ethereum Implementation, 'AlethZero', on OSX Mavericks. You can find a list of updates at the bottom of this post.
Since August 2014, new PoC binaries are released regularly on
https://github.com/ethereum/cpp-ethereum/releases. This makes building from source a little less necessary than it used to if you just want to have a very brief look at Ethereum, and is a good thing. That said, because the C++ client feature set, Solidity and the API are expected to be in development even after the Ethereum Frontier release,
you will definitely want to be building from source regardless, very often (maybe even everyday if you are a developer). The below guide should help you establish a simple workflow to do so.
For convenience, if you're worried about messing things up on your computer (a real possibility), you can always use a
Parallels virtual machine installed from your recovery partition - they offer a 14 day trial.
If you're finding yourself having difficulties, please post your question in the C++ category:
https://forum.ethereum.org/categories/cpp-implementation, or join us on
IRC and ask directly.
Finally, for all documentation please refer to the wiki:
https://github.com/ethereum/cpp-ethereum/wiki.
INSTALLING THE CLIENT
Most of the below is thanks to the amazing hard work by
@caktux (
https://github.com/caktux/homebrew-ethereum), who built a 'brew tap' (an automated set of install scripts so to speak).
Keep in mind it is important that you do not use sudo. Sudoing is not required in most cases (after all, you installed most of your OSX apps without requiring it) and could lead to path issues down the line.Install BrewFirst, install brew. Installing brew will also install the xcode tools that are needed.
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Now run brew doctor
brew doctor
Install the caktux formulae for Ethereumbrew tap ethereum/ethereum
Installing Cpp EthereumImportant note: the following command installs all dependencies and the latest version of the development branch for ethereum C++. This step can take a long time, especially on a Macbook Air (read: one hour or more!). In particular, it is normal for this process to appear to be 'stuck' with a line of text starting with "/b2 --prefix=/usr/local/Cellar/boost". Good news: it will only take a long time once, to compile boost. Updates will be considerably faster.
brew install cpp-ethereum --devel --with-gui --successful
brew linkapps cpp-ethereum
That's it! You're all set.
TOP TIP
If you develop heavily with Ethereum, one of your life existential questions will quickly become 'which version am I really on'. Sure, brew deployment is automated these days, but many a time I've been left wondering if I was running the 'right' git commit version of a devel release, in case the buildbot had temporarily gone on strike.
The easiest way is to do this is to check the git commit. When running
brew reinstall
you should see a message along the lines of:
==> Cloning https://github.com/ethereum/cpp-ethereum.git
Updating /Library/Caches/Homebrew/cpp-ethereum--git
==> Checking out revision 9071de1133439bebb7f706b34c53a943cf448ae6
Armed with this information you can simply check the hash against your favorite git client. I use
Sourcetree, so in this case, I'd click 'jump to -> commit', paste "9071de1133439bebb7f706b34c53a943cf448ae6" and voila, if all went well, the client will take me to the last commit of the branch i select (develop or master).
Those who really enjoy stats can have a look at the buildbot output itself, which for brew devel C++ is located at
https://build.ethdev.com/builders/OSX C++ develop brew.
UPGRADING
To upgrade, simply:
brew update && brew upgrade
brew reinstall cpp-ethereum --devel --with-gui --successful
brew linkapps cpp-ethereum
If
brew reinstall
fails with a message stating "reference is not a tree", then execute
rm -rf /Library/Caches/Homebrew/cpp-ethereum--git
and try again.
If you have opted to create a shortcut to AlethZero in your OS X dock, you will have to remove and re-add it for the link to still be valid.
BACKING UP
Downloading the chain and processing it can take hours. I often like to play with new releases and try things out, so a back up is a must. To back the chain up, you'll have to use Eth, AlethZero little CLI cousin:
eth -E ~/name_of_file
This will export the chain in a compact format.
eth -I ~/name_of_file
... will of course reimport the chain (after validating it). It's not the fastest thing but it's still better than relying on your network connection.
TROUBLESHOOTING
The readme for the homebrew tap by
@caktux should cover most issues:
https://github.com/caktux/homebrew-ethereuma) I press 'Go' and nothing happensBefore anything else, keep an eye on the log window, look for error messages, but give it time! It take a good 5 minutes from the UPnP connection on my machine to start downloading blocks - and a couple of hours to catch up on the full chain.
If you're not seeing any peers after a few minutes, make sure UPnP is on on your router, and working. Check for UPnP related messages in the AlethZero log window.
If that doesn't help, the bootstrap node is sometimes down, it's expected on a testnet. The simplest way is to press 'Go' anyway (to start the network), then identify a node on
https://stats.ethdev.com/ that has plenty of peers (the Go bootnodes are good for this. Click "Network > Connect to Peer" and input the IP of the node and the correct port (30303), as such: xxx:xxx:xxx:xxx:30303.
b) It's 'not working'!First, upgrade. You might think that that version you installed last night is good enough but it's likely a new one is already out, and very often, the version number will not change after a merge from a debug branch, only the commit hash. So before trying anything else, please go through the 'upgrade' procedure described just above, and try again.
If you're still experiencing issues, close the client, backup ~/Library/Application Support/Ethereum/keys.* and ~/Library/Application Support/Ethereum/web3. Note that if all your keys have their own password then you only need .web3. Now delete the ~/Library/Preferences/com.ethereum.alethzero.plist file (it contains your layout preferences), as well as the ~/Library/Application Support/Ethereum/ folder (which contains the chain database and your keys). Afterwards and in order to really wipe the plist file, you'll have to run
killall -u $USER cfprefsd
to clear the OSX cache. Reopen the client and try again.
Still no luck? Please raise an issue on
https://github.com/ethereum/cpp-ethereum/issues and include as much information as possible (ideally a debug log from OSX, a copy of your log pane in AlethZero, your OS and version, your hardware, etc.). You can include files by using
pastebin.
c) I can't see the same block number as the other peersYou're on the wrong chain. You need to upgrade, as the protocol number probably has changed. See 'Upgrading' above. If you're on a devel branch, it's likely you'll have to find yourself checking for updates every day - keep an eye on the
IRC channel for announcements.
d) Brew is throwing errors during brew doctor or won't install a certain dependencyIf you are an existing developer, it's likely you'll have brew already installed alongside a lot of the dependencies AlethZero uses. In particular, if you have made modifications to certain dependencies, or 'locked' a brewed application to a certain version number, this can cause issues.
In order to solve this, locate the formula that's causing problems in cd /usr/local/Library/Formula/, then execute
git reset --hard
followed by
brew update
. Note that this could very likely 'break' other apps on your system so tread carefully. In fact, we recommend you to use a VM in this particular case.
LOCKING TO A VERSION
This is no longer supported by brew.
WHAT'S NEXT?
Go read the tutorial on how to create your
first Dapp! Also, have a look at the wiki:
https://github.com/ethereum/cpp-ethereum/wiki (keep in mind the various APIs are changing a lot even between minor version updates, although the documented APIs on the wiki should be relatively up to date)
---------
Update History:
05/09/2014 - Initial release
07/09/2014 - Update re: chain switching issue and layout preference location on the file system.
08/09/2014 - updated brew install with --devel --successful flag instead of --devel --stable
19/09/2014 - added better upgrade instructions
20/09/2014 - minor edits
21/09/2014 - added a bit more around upgrades
22/09/2014 - further updates
02/10/2014 - corrected brew url install following update
08/10/2014 - updated for POC7
19/10/2014 - added note on how to clear cache for plist file
20/10/2014 - added a little more info on how to solve common issues
10/05/2015 - updated for Olympic
11/05/2015 - minor update on configuration and obtaining peers
12/05/2015 - fixed reference to cpp-ethereum--git regarding 'not a tree' issue
13/05/2015 - fixed references to keys
14/05/2015 - added tips on backups
Comments
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
They changed the URL.Nice meeting you and the Meetup at The Escalator with Vitalik earlier this eve! [email protected]
Is there any way to clear out the installation (where does it put files for owned wallets, etc...) so I can try a fresh installation to see if that works?
rm -rf /Library/Caches/Homebrew/ethereum--git
and then reinstalling:http://monosnap.com/image/UxXPAA8SadNbVIzNBjK1PZm86UUUdS
brew doctor, brew update, and brew upgrade preceded the above.
Also that bug:
Serpent Error (file "main", line 1, char 9): Empty def
Will it ever be fixed?
I am really keen to start doing some project, but it looks the tool is just not ready even for playing with....
First tap the ethereum brew: For the stable version: For the latest cutting edge developer version: Add the
--with-gui
option to brew AlethZero and the Mix IDE.Then open AlethZero.app or the Mix.app IDE from your Applications folder.
You can also run eth (CLI) or neth (ncurses interface).
For options and patches, see: https://github.com/ethereum/homebrew-ethereum