gaspersic/go-ethereum
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[DOCS] massive documentation update (#20229)

Browse Source 
This PR:

- reorganizes all documentation pages so they live in the right category
- removes lots of legacy docs
- contains many improvements to active documentation pages

Geth user documentation is now spread across five major categories:

- Install and Build: installation and compile instructions
- Using Geth: this is for pages about general geth usage.
- For dApp Developers: this is for programming guides and functionality specific
   to dapp development. All the dev guides for mobile framework and Go APIs live here.
- JSON-RPC APIs: this has its own section because there is now a sub-page for
   every name space. I have also added an overview text that explains how to set
   up the API servers.
- For Geth Developers: this is for geth contributors
This commit is contained in:
Felix Lange
2019-11-05 13:46:00 +01:00
committed by GitHub
parent 86b20d897e
commit 7416b05b81
76 changed files with 3537 additions and 4680 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/_install-and-build/Backup--restore.md
View File

@ -1,39 +1,28 @@
---
title: Backup & restore
title: Backup & Restore
sort_key: C
---
**DO NOT FORGET YOUR PASSWORD** and **BACKUP YOUR KEYSTORE**
<!--
This whole page can be nuked, _except_ for the info about
where the keystore is located and advise the user
to back up his keystore. That section should be moved
into both accounts-info but also to any getting-started guide.
-->
Most important info first: **REMEMBER YOUR PASSWORD** and **BACKUP YOUR KEYSTORE**.
# Backup & restore
## Data Directory
## Data directory
Everything `geth` persists gets written inside its data directory (except for the PoW Ethash DAG, see note below).
The default data directory locations are platform specific:
Everything `geth` persists gets written inside its data directory. The default data
directory locations are platform specific:
* Mac: `~/Library/Ethereum`
* Linux: `~/.ethereum`
* Windows: `%APPDATA%\Ethereum`
Accounts are stored in the `keystore` subdirectory. The contents of this directories should be transportable between nodes, platforms, implementations (C++, Go, Python).
Accounts are stored in the `keystore` subdirectory. The contents of this directories
should be transportable between nodes, platforms, implementations (C++, Go, Python).
To configure the location of the data directory, the `--datadir` parameter can be specified. See [CLI Options](../interface/command-line-options) for more details.
To configure the location of the data directory, the `--datadir` parameter can be
specified. See [CLI Options](../interface/command-line-options) for more details.
_**note:** the [ethash dag](../legacy/mining) is stored at `~/.ethash` (Mac/Linux) or `%APPDATA%\Ethash` (Windows) so that it can be reused by all clients. You can store this in a different location by using a symbolic link._
## Upgrades
Sometimes the internal database formats need updating (for example, when upgrade from before 0.9.20). This can be run with the following command (geth should not be otherwise running):
```
geth upgradedb
```
Note the [ethash dag](../interface/mining) is stored at `~/.ethash` (Mac/Linux) or
`%APPDATA%\Ethash` (Windows) so that it can be reused by all clients. You can store this
in a different location by using a symbolic link.
## Cleanup
@ -43,24 +32,29 @@ Geth's blockchain and state databases can be removed with:
geth removedb
```
This is useful for deleting an old chain and sync'ing to a new one. It only affects data directories that can be re-created on synchronisation and does not touch the keystore.
This is useful for deleting an old chain and sync'ing to a new one. It only affects data
directories that can be re-created on synchronisation and does not touch the keystore.
## Blockchain import/export
## Blockchain Import/Export
Export the blockchain in binary format with:
```
geth export <filename>
```
Or if you want to back up portions of the chain over time, a first and last block can be specified. For example, to back up the first epoch:
Or if you want to back up portions of the chain over time, a first and last block can be
specified. For example, to back up the first epoch:
```
geth export <filename> 0 29999
```
Note that when backing up a partial chain, the file will be appended rather than truncated.
Note that when backing up a partial chain, the file will be appended rather than
truncated.
Import binary-format blockchain exports with:
```
geth import <filename>
```
@ -68,4 +62,4 @@ geth import <filename>
_See https://github.com/ethereum/wiki/wiki/Blockchain-import-export for more info_
And finally: **DO NOT FORGET YOUR PASSWORD** and **BACKUP YOUR KEYSTORE**
And finally: **REMEMBER YOUR PASSWORD** and **BACKUP YOUR KEYSTORE**

1
docs/_install-and-build/Build-from-Source.md
View File

@ -1,5 +1,6 @@
---
title: Build from source
sort_key: B
---
<!-- TODO: Maybe move? -->

141
docs/_install-and-build/Developers-Guide.md
View File

@ -1,141 +0,0 @@
---
title: Developers' guide
---
**NOTE: These instructions are for people who want to contribute Go source code changes.
If you just want to run ethereum, use the normal [Installation Instructions](installing-geth)**
This document is the entry point for developers of the Go implementation of Ethereum. Developers here refer to the hands-on: who are interested in build, develop, debug, submit a bug report or pull request or contribute code to go-ethereum.
## Building and Testing
### Go Environment
We assume that you have [`go` installed](https://golang.org/doc/install), and `GOPATH` is set.
**Note**:You must have your working copy under `$GOPATH/src/github.com/ethereum/go-ethereum`.
Since `go` does not use relative path for import, working in any other directory will have no effect, since the import paths will be appended to `$GOPATH/src`, and if the lib does not exist, the version at master HEAD will be downloaded.
Most likely you will be working from your fork of `go-ethereum`, let's say from `github.com/nirname/go-ethereum`. Clone or move your fork into the right place:
```
git clone git@github.com:nirname/go-ethereum.git $GOPATH/src/github.com/ethereum/go-ethereum
```
### Managing Vendored Dependencies
All other dependencies are tracked in the vendor/ directory. We use [govendor](https://github.com/kardianos/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 version, run `govendor fetch +v`.
You can also use govendor to run certain commands on all go-ethereum packages, excluding vendored
code. Example: to recreate all generated code, run `govendor generate +l`.
### Building Executables
Switch to the go-ethereum repository root directory.
You can build all code using the go tool, placing the resulting binary in `$GOPATH/bin`.
```text
go install -v ./...
```
go-ethereum exectuables can be built individually. To build just geth, use:
```text
go install -v ./cmd/geth
```
read about cross compilation of go-ethereum [here](../developers/cross-compiling-ethereum).
### Git flow
To make life easier try [git flow](http://nvie.com/posts/a-successful-git-branching-model/) it sets this all up and streamlines your work flow.
### 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**: here all tests with prefix _TestMethod_ will be run, so if you got TestMethod, TestMethod1, then both!
Running benchmarks, eg.:
```
go test -v -cpu 4 -bench . -run BenchmarkJoin
```
for more see [go test flags](http://golang.org/cmd/go/#hdr-Description_of_testing_flags)
### Metrics and monitoring
`geth` can do node behaviour monitoring, aggregation and show performance metric charts.
read about [metrics and monitoring](../doc/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 trace that is 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 stacktraces for these other instances, you need to start them up 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=30301 -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, etc) but have the stacktrace too, 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 to help out with the source code! We welcome contributions from
anyone on the internet, and are grateful for even the smallest of fixes!
GitHub is used to track issues and contribute code, suggestions, feature requests or
documentation.
If you'd like to contribute to go-ethereum, please fork, fix, commit and send a pull
request (PR) for the maintainers to review and merge into the main code base. If you wish
to submit more complex changes though, please check up with the core devs first on [our
gitter channel](https://gitter.im/ethereum/go-ethereum) to ensure those changes are in
line with the general philosophy of the project and/or get some early feedback which can
make both your efforts much lighter as well as our review and merge procedures quick and
simple.
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](../developers/code-review-guidelines).
We encourage a PR early approach, meaning you create the PR the earliest even without the
fix/feature. This will let core devs and other volunteers know you picked up an issue.
These early PRs should indicate 'in progress' status.
## Dev Tutorials (mostly outdated)
* [private networks, local clusters and monitoring](../doc/setting-up-private-network-or-local-cluster)
* [p2p 101](../developers/peer-to-peer): a tutorial about setting up and creating a p2p server and p2p sub protocol.
* [how to whisper](../whisper/whisper-overview): an introduction to whisper.

1
docs/_install-and-build/Installing-Geth.md
View File

@ -1,5 +1,6 @@
---
title: Installing Geth
sort_key: A
---
You can install the Go implementation of Ethereum using a variety of ways. These include installing it via your favorite package manager; downloading a standalone pre-built bundle; running as a docker container; or building it yourself. This document details all of the possibilities to get you joining the Ethereum network using whatever means you prefer.

167
docs/_install-and-build/cross-compile.md Normal file
View File

@ -0,0 +1,167 @@
---
title: Cross-Compiling Geth
sort_key: C
---
**Note: All of these and much more have been merged into the project Makefile. You can
cross build via `make geth-<os>-<platform>` without needing to know any of these details
from below.**
Developers usually have a preferred platform that they feel most comfortable working in,
with all the necessary tools, libraries and environments set up for an optimal workflow.
However, there's often need to build for either a different CPU architecture, or an
entirely different operating system; but maintaining a development environment for each
and switching between the them quickly becomes unwieldy.
Here we present a very simple way to cross compile Ethereum to various operating systems
and architectures using a minimal set of prerequisites and a completely containerized
approach, guaranteeing that your development environment remains clean even after the
complex requirements and mechanisms of a cross compilation.
The currently supported target platforms are:
- ARMv7 Android and iOS
- 32 bit, 64 bit and ARMv5 Linux
- 32 bit and 64 bit Mac OSX
- 32 bit and 64 bit Windows
Please note, that cross compilation does not replace a release build. Although resulting
binaries can usually run perfectly on the desired platform, compiling on a native system
with the specialized tools provided by the official vendor can often result in more a
finely optimized code.
## Cross compilation environment
Although the `go-ethereum` project is written in Go, it does include a bit of C code
shared between all implementations to ensure that all perform equally well, including a
dependency to the GNU Multiple Precision Arithmetic Library. Because of these, Go cannot
by itself compile to a different platform than the host. To overcome this limitation, we
will use [`xgo`](https://github.com/karalabe/xgo), a Go cross compiler package based on
Docker containers that has been architected specifically to allow both embedded C snippets
as well as simpler external C dependencies during compilation.
The `xgo` project has two simple dependencies: Docker (to ensure that the build
environment is completely contained) and Go. On most platforms these should be available
from the official package repositories. For manually installing them, please consult their
install guides at [Docker](https://docs.docker.com/installation/) and
[Go](https://golang.org/doc/install) respectively. This guide assumes that these two
dependencies are met.
To install and/or update xgo, simply type:
$ go get -u github.com/karalabe/xgo
You can test whether `xgo` is functioning correctly by requesting it to cross
compile itself and verifying that all cross compilations succeeded or not.
$ xgo github.com/karalabe/xgo
...
$ ls -al
-rwxr-xr-x 1 root root 2792436 Sep 14 16:45 xgo-android-21-arm
-rwxr-xr-x 1 root root 2353212 Sep 14 16:45 xgo-darwin-386
-rwxr-xr-x 1 root root 2906128 Sep 14 16:45 xgo-darwin-amd64
-rwxr-xr-x 1 root root 2388288 Sep 14 16:45 xgo-linux-386
-rwxr-xr-x 1 root root 2960560 Sep 14 16:45 xgo-linux-amd64
-rwxr-xr-x 1 root root 2437864 Sep 14 16:45 xgo-linux-arm
-rwxr-xr-x 1 root root 2551808 Sep 14 16:45 xgo-windows-386.exe
-rwxr-xr-x 1 root root 3130368 Sep 14 16:45 xgo-windows-amd64.exe
## Building Ethereum
Cross compiling Ethereum is analogous to the above example, but an additional flags is
required to satisfy the dependencies:
- `--deps` is used to inject arbitrary C dependency packages and pre-build them
Injecting the GNU Arithmetic Library dependency and selecting `geth` would be:
$ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
github.com/ethereum/go-ethereum/cmd/geth
...
$ ls -al
-rwxr-xr-x 1 root root 23213372 Sep 14 17:59 geth-android-21-arm
-rwxr-xr-x 1 root root 14373980 Sep 14 17:59 geth-darwin-386
-rwxr-xr-x 1 root root 17373676 Sep 14 17:59 geth-darwin-amd64
-rwxr-xr-x 1 root root 21098910 Sep 14 17:59 geth-linux-386
-rwxr-xr-x 1 root root 25049693 Sep 14 17:59 geth-linux-amd64
-rwxr-xr-x 1 root root 20578535 Sep 14 17:59 geth-linux-arm
-rwxr-xr-x 1 root root 16351260 Sep 14 17:59 geth-windows-386.exe
-rwxr-xr-x 1 root root 19418071 Sep 14 17:59 geth-windows-amd64.exe
As the cross compiler needs to build all the dependencies as well as the main project
itself for each platform, it may take a while for the build to complete (approximately 3-4
minutes on a Core i7 3770K machine).
### Fine tuning the build
By default Go, and inherently `xgo`, checks out and tries to build the master branch of a
source repository. However, more often than not, you'll probably want to build a different
branch from possibly an entirely different remote repository. These can be controlled via
the `--remote` and `--branch` flags.
To build the `develop` branch of the official `go-ethereum` repository instead of the
default `master` branch, you just need to specify it as an additional command line flag
(`--branch`):
$ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
--branch=develop \
github.com/ethereum/go-ethereum/cmd/geth
Additionally, during development you will most probably want to not only build a custom
branch, but also one originating from your own fork of the repository instead of the
upstream one. This can be done via the `--remote` flag:
$ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
--remote=https://github.com/karalabe/go-ethereum \
--branch=rpi-staging \
github.com/ethereum/go-ethereum/cmd/geth
By default `xgo` builds binaries for all supported platforms and architectures, with
Android binaries defaulting to the highest released Android NDK platform. To limit the
build targets or compile to a different Android platform, use the `--targets` CLI
parameter.
$ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
--targets=android-16/arm,windows/* \
github.com/ethereum/go-ethereum/cmd/geth
### Building locally
If you would like to cross compile your local development version, simply specify a local
path (starting with `.` or `/`), and `xgo` will use all local code from `GOPATH`, only
downloading missing dependencies. In such a case of course, the `--branch`, `--remote` and
`--pkg` arguments are no-op:
$ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
./cmd/geth
## Using the Makefile
Having understood the gist of `xgo` based cross compilation, you do not need to actually
memorize and maintain these commands, as they have been incorporated into the official
[Makefile](https://github.com/ethereum/go-ethereum/blob/master/Makefile) and can be
invoked with a trivial `make` request:
* `make geth-cross`: Cross compiles to every supported OS and architecture
* `make geth-<os>`: Cross compiles supported architectures of a particular OS (e.g. `linux`)
* `make geth-<os>-<arch>`: Cross compiles to a specific OS/architecture (e.g. `linux`, `arm`)
We advise using the `make` based commands opposed to manually invoking `xgo` as we do
maintain the Makefile actively whereas we cannot guarantee that this document will be
always readily updated to latest advancements.
### Tuning the cross builds
A few of the `xgo` build options have also been surfaced directly into the Makefile to
allow fine tuning builds to work around either upstream Go issues, or to enable some
fancier mechanics.
- `make ... GO=<go>`: Use a specific Go runtime (e.g. `1.5.1`, `1.5-develop`, `develop`)
- `make ... MODE=<mode>`: Build a specific target type (e.g. `exe`, `c-archive`).
Please note that these are not yet fully finalized, so they may or may not change in the
future as our code and the Go runtime features change.