Updated 11 May 2015 - Olympic Edition
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
, 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 Brew
First, 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 doctorInstall the caktux formulae for Ethereum
brew tap ethereum/ethereumInstalling Cpp Ethereum
Important 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.
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
you should see a message along the lines of:
==> Cloning https://github.com/ethereum/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
To upgrade, simply:
brew update && brew upgrade
brew reinstall cpp-ethereum --devel --with-gui --successful
brew linkapps cpp-ethereum
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.
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.
The readme for the homebrew tap by @caktux
should cover most issues: https://github.com/caktux/homebrew-ethereuma) I press 'Go' and nothing happens
Before 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 peers
You'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 dependency
If 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
. 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.
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)
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