From b11a770dfacbbf4f5accd9e33f64718175c350b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Henry?= Date: Thu, 22 Sep 2016 11:42:14 +0200 Subject: [PATCH] Update README.md: - fix build instructions - add some information about the JSON/RPC interface --- Makefile | 2 +- README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 101 insertions(+), 22 deletions(-) diff --git a/Makefile b/Makefile index 3f4dc5fa1..630033490 100644 --- a/Makefile +++ b/Makefile @@ -9,5 +9,5 @@ clean: test: ${MAKE} -C test -build_deps: +build-deps: @./scripts/install_build_deps.sh all diff --git a/README.md b/README.md index cd987e62f..768cfdf33 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,71 @@ - TEZOS ===== -To compile: +See https://www.tezos.com/ for more information about the project. + + +Build instructions +------------------ + +To compile Tezos, you need an OCaml compiler (version 4.03.0) and all the +libraries listed in `src/tezos-deps.opam`. To install all the required +dependencies, we strongly recommand to install +[OPAM](https://opam.ocaml.org/), the OCaml package manager, and then to +run the following command: ``` make build-deps +``` + +Then, to compile the project, simply run: + +``` make ``` -========= +This should produce three binaries: -To run a single instance : +* `tezos-node`: the tezos daemon itself; +* `tezos-client`: a minimal command-line client; +* `tezos-protocol-compiler`: a protocol compiler used for developing new version of the economical protocol. + +Currently Tezos is developped/tested under Linux only. +It should work on mac OS, but this has not been tested recently. +The Windows port is in progress. + + + +Running the node in a sandbox +----------------------------- + +To run a single instance of a Tezos node in a sandbox mode: + +``` +./tezos-node -sandbox /path/to/a/custom/data/dir -rpc-port 8732 +``` + +This "sandboxed" node will not participate to the P2P network, but +it accepts RPC from the local host on port 8732. See below from more +details on the RPC interface. + + +Running the node +---------------- + +There is not an official running Tezos network yet. But you might run +a local test network. To run a node that accept incoming connections, +simply run: ``` ./tezos-node ``` -All useful data are stored in `${HOME}/.tezos-node`. +It will listen to incoming connection on `0.0.0.0:9732` (and `[::]:9732`). +All useful data are stored into `${HOME}/.tezos-node/`, e.g. a default +configuration file was generated: `${HOME}/.tezos-node/config`. -To run a test instance, without connecting to the gossup network : - -``` -./tezos-node -sandbox /path/to/a/custom/data/dir -``` - -Useful data will be stored in the directory `/path/to/a/custom/data/dir` -instead of `${HOME}/.tezos-node`. - -========= - -To create other instances on the same machine, it is possible to -duplicate and edit `${HOME}/.tezos/config` while taking care not to +To create multiple nodes on the same machine, it is possible to +duplicate and edit `${HOME}/.tezos-node/config` while taking care not to share paths for accessing the database or any other data file (cf. options `db.store` ; `db.context` ; `net.peers` and `protocol.dir`). @@ -41,13 +75,13 @@ exist, the following command will generate it and replace the default values with the values from the command line arguments: ``` -./tezos-node -base-dir ${DIR} -net-port 2023 -net-addr 127.0.0.1 +./tezos-node -base-dir ${DIR} -net-port 9733 -net-addr 127.0.0.1 ``` The Tezos server has a built-in mechanism to discover peers on the local net -(using UDP packets broadcasted on port 7732) +(using UDP packets broadcasted on port 7732). -If this mechanism isn't sufficient, one can provide Tezos with a list of +If this mechanism is not sufficient, one can provide Tezos with a list of initial peers, either by editing the option `net.bootstrap.peers` in the `config` file, or by specifying a command line parameter: @@ -64,3 +98,48 @@ in the config file. Tezos never modifies the content of an existing ./tezos-node -config-file ${DIR}/config ``` + +JSON/RPC interface +------------------ + +The tezos node provides a JSON/RPC interface. It is not active by +default and it should be explicitely activated with the `rpc-port` +option. This RPC interface is self-documented and the `tezos-client` +is able to pretty-print the list of available RPCs. For instance, for +the list of RPC provided by the Shell: + +``` +./tezos-client rpc list +``` + +And, for the list of RPC attached to the "genesis" bloc, +including the RPC provided by the associated economical-protocol version: + +``` +./tezos-client rpc list /blocks/genesis/ +``` + +You might also get the JSON schema describing the expected input and output +of a RPC. For instance: + +``` +./tezos-client rpc schema /block/genesis/hash +``` + +Note: you might get the same information, but as a raw JSON object, +with a simple HTTP request: + +``` +wget --post-data '{ "recursive": true }' -O - http://127.0.0.1:8732/describe +wget --post-data '{ "recursive": true }' -O - http://127.0.0.1:8732/describe/blocks/genesis +wget -O - http://127.0.0.1:8732/describe/blocks/genesis/hash +``` + + + +The minimal CLI client +---------------------- + +Work in progress. + +See `./tezos-client -help` for the current list of available commands. \ No newline at end of file