💾Developers' Guide

NOTE: These instructions are for those who want to contribute Go source code changes. If you only want to run Elastos.ELA.SideChain.ESC, use the normal Installation Instructions.

This document serves as the entry point for developers of the Go implementation of Ethereum. Here, they can get more information on how to build, develop, debug, submit a bug report, pull requests, or contribute code to the Elastos.ELA.SideChain.ESC.

Building and Testing

Go Environment

This guide will assume that you have go v1.8 installed and GOPATH is set.

Note: You must have your working copy under: $GOPATH/src/github.com/elastos/Elastos.ELA.SideChain.ESC.

Since go doesn't use a relative path for import, working in any other directory will have no effect, since the import paths will be appended to $GOPATH/src.If the lib doesn't exist, the version at master HEAD will be downloaded.

You'll most likely be working from your fork of Elastos.ELA.SideChain.ESC, let's say from github.com/elastos/Elastos.ELA.SideChain.ESC. Clone or move your fork into the right place:

git clone [e-mail]:nirname/Elastos.ELA.SideChain.ESC.git $GOPATH/src/github.com/elastos/Elastos.ELA.SideChain.ESC

Managing Vendored Dependencies

All other dependencies are tracked in the vendor/ directory - we use govendor to manage them.

If you want to add a new dependency, run govendor fetch <import-path>, then commit the result.

If you want to update all dependencies to their latest upstream versions, run govendor fetch +v.

You can also use govendor to run certain commands on all Elastos.ELA.SideChain.ESC packages, excluding vendored code. Example: to recreate all generated code, run govendor generate +l.

Building Executables

Switch to the Elastos.ELA.SideChain.ESC repository root directory.

You can build all code using the go tool, placing the resulting binary in $GOPATH/bin.

go install -v ./...

Elastos.ELA.SideChain.ESC exectuables can be built individually. To build only geth, use:

go install -v ./cmd/geth

Read about the cross-compilation of Elastos.ELA.SideChain.ESC here.

Git flow

To make things easier, try git flow - it sets this all up and streamlines your workflow.

Testing

Testing one library:

go test -v -cpu 4 ./eth  

Using options -cpu (number of cores allowed) and -v (logging even if no error) is recommended.

Testing only some methods:

go test -v -cpu 4 ./eth -run TestMethod

Note: All tests with the prefix TestMethod will be run, so if you receive TestMethod, TestMethod1, then you received both!

Running benchmarks, i.e.:

go test -v -cpu 4 -bench . -run BenchmarkJoin

For more information, please refer to go test flags

Metrics and monitoring

geth can execute node behavior monitoring, aggregation, and show performance metric charts. Read more about metrics and monitoring.

Getting Stack Traces

If geth is started with the --pprof option, a debugging HTTP server is made available on port 6060. You can bring up http://localhost:6060/debug/pprof to see the heap, running routines, etc. By clicking full goroutine stack dump (clicking http://localhost:6060/debug/pprof/goroutine?debug=2) you can generate a trace that's useful for debugging.

Note that if you run multiple instances of geth, this port will only work for the first instance that was launched. If you want to generate stack traces for these other instances, you need to start them up by choosing an alternative pprof port. Make sure you are redirecting stderr to a logfile.

geth -port=30300 -verbosity 5 --pprof --pprofport 6060 2>> /tmp/00.glog
geth -port=20630 -verbosity 5 --pprof --pprofport 6061 2>> /tmp/01.glog
geth -port=30302 -verbosity 5 --pprof --pprofport 6062 2>> /tmp/02.glog

Alternatively, if you want to kill the clients (in case they hang or stalled syncing) but have the stack trace as well, you can use the -QUIT signal with kill:

killall -QUIT geth 

This will dump stack traces for each instance to their respective log file.

Contributing

Thank you for considering helping out with the source code! We welcome contributions from anyone across the web and are grateful for any suggestions you may have, big or small.

GitHub is used to track issues and contribute code, suggestions, feature requests, or documentation.

If you'd like to contribute to Elastos.ELA.SideChain.ESC, please fork, fix, commit and send a pull request (PR) for the maintainers to review and merge into the main codebase.

PRs need to be based on and opened against the master branch (unless by explicit agreement, you contribute to a complex feature branch).

Your PR will be reviewed according to the Code Review Guidelines.

We encourage an early PR approach, meaning you create the PR at the earliest time, even without the fix/feature. This will let core developers and other volunteers know you picked up an issue. These early PRs should be indicated as having an 'in progress' status.

Dev Tutorials (mostly outdated)

• Private networks, local clusters and monitoring

• P2P 101: a tutorial about setting up and creating a p2p server and p2p sub protocol.

• How to Whisper: an introduction to whisper.