From 79f0c8f989e10f88896cc8a27f82323bb972ca7f Mon Sep 17 00:00:00 2001 From: Adi Seredinschi Date: Fri, 19 Feb 2021 09:51:50 +0100 Subject: [PATCH 1/4] Fix for issue #672 in the guide --- CHANGELOG.md | 62 +++++++++++++++--------------- guide/src/help.md | 2 +- guide/src/installation.md | 80 +++++++++++++++++++++++++++++++++++++-- 3 files changed, 109 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 05d9ec409f..f43d3dd481 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,64 +1,65 @@ # Changelog -[comment]: <> (## Unreleased Changes) +## Unreleased Changes -[comment]: <> (> [high level summary]) +> [high level summary] -[comment]: <> (### FEATURES) +### FEATURES -[comment]: <> (- [ibc]) +- [ibc] -[comment]: <> ( - [nothing yet]) + - [nothing yet] -[comment]: <> (- [ibc-relayer]) +- [ibc-relayer] -[comment]: <> ( - [nothing yet]) + - [nothing yet] -[comment]: <> (- [ibc-relayer-cli]) +- [ibc-relayer-cli] -[comment]: <> ( - [nothing yet]) + - [nothing yet] -[comment]: <> (### IMPROVEMENTS) +### IMPROVEMENTS -[comment]: <> (- [ibc]) +- [ibc] -[comment]: <> ( - [nothing yet]) + - [nothing yet] -[comment]: <> (- [ibc-relayer]) +- [ibc-relayer] -[comment]: <> ( - [nothing yet]) + - [nothing yet] -[comment]: <> (- [ibc-relayer-cli]) +- [ibc-relayer-cli] -[comment]: <> ( - [nothing yet]) + - [nothing yet] -[comment]: <> (### BUG FIXES) +### BUG FIXES -[comment]: <> (- [ibc]) +- [ibc] -[comment]: <> ( - [nothing yet]) + - [nothing yet] -[comment]: <> (- [ibc-relayer]) +- [ibc-relayer] -[comment]: <> ( - [nothing yet]) + - [nothing yet] -[comment]: <> (- [ibc-relayer-cli]) +- [ibc-relayer-cli] + - Hermes guide: improved installation guideline ([#672]) -[comment]: <> ( - [nothing yet]) +### BREAKING CHANGES -[comment]: <> (### BREAKING CHANGES) +- [ibc] -[comment]: <> (- [ibc]) + - [nothing yet] -[comment]: <> ( - [nothing yet]) +- [ibc-relayer] -[comment]: <> (- [ibc-relayer]) + - [nothing yet] -[comment]: <> ( - [nothing yet]) +- [ibc-relayer-cli] -[comment]: <> (- [ibc-relayer-cli]) + - [nothing yet] -[comment]: <> ( - [nothing yet]) +[#672]: https://github.com/informalsystems/ibc-rs/issues/672 ## v0.1.1 *February 17, 2021* @@ -117,7 +118,6 @@ involving packet acks in a 3-chain setup. More details below. [#643]: https://github.com/informalsystems/ibc-rs/issues/643 [#665]: https://github.com/informalsystems/ibc-rs/issues/665 [#671]: https://github.com/informalsystems/ibc-rs/pull/671 -[#672]: https://github.com/informalsystems/ibc-rs/issues/672 [#682]: https://github.com/informalsystems/ibc-rs/issues/682 ## v0.1.0 diff --git a/guide/src/help.md b/guide/src/help.md index bfccfde732..152069200d 100644 --- a/guide/src/help.md +++ b/guide/src/help.md @@ -9,7 +9,7 @@ For this purpose, we recommend a few ideas that could be of help: - [patch][patching] your local gaia chain(s) to enable some corner-case methods (e.g., channel close); -And if the above do not help: +And if the above options do not address your specific problem: - you can [request a new feature][feature]; - or consult the [list of reported issues][issues] and search by relevant keywords to see if you're dealing with a known problem; diff --git a/guide/src/installation.md b/guide/src/installation.md index 6014d43223..00667bf92e 100644 --- a/guide/src/installation.md +++ b/guide/src/installation.md @@ -1,16 +1,69 @@ # Install the relayer -In order to install and run Hermes, please follow the steps below: +There are two main approaches for obtaining Hermes: -> NOTE: This assumes you have installed all the [pre-requisites](./pre_requisites.md) on your machine. +1. Installation: + 1. If you are running on a Unix machine (Linux/MacOS), then the simplest + option is to [download the latest binary](#Install-by-downloading). + 2. Alternatively, install via + [Cargo installation instructions](#install-via-cargo). + +[comment]: <> ( Regardless of approach you choose, also follow the post-installation) + +[comment]: <> ( instructions therein.) + +2. Alternatively, [build Hermes directly from source](#build-from-source). + + +## Install by downloading + +Simply head to the GitHub [Releases][releases] page download the latest version +of Hermes binary matching your platform: +- `hermes-v0.1.1-x86_64-apple-darwin.tar.gz` (or .zip) for MacOS, +- `hermes-v0.1.1-x86_64-unknown-linux-gnu.tar.gz` (or .zip) for Linux. + +The step-by-step instruction below should carry you through the whole process: + +1. Make the directory where we'll place the binary: + ```shell + mkdir $HOME/.hermes/ + ``` + +2. Extract the binary archive: + ```shell + tar -C $HOME/.hermes/ -vxzf $ARCHIVE_NAME + ``` + +3. Update your path: + ```shell + export PATH="$HOME/.hermes:$PATH" + ``` + +> NOTE: The binary may be initially prevented from running if you're +> on MacOS. +> See the ["Open Anyway" instructions from this support forum][developer-app] +> if that is the case. + +You should now be able to run Hermes by invoking the `hermes` executable. + +```shell +hermes version +``` + +``` +hermes 0.1.1 +``` ## Install via Cargo +> NOTE: This approach assume you have installed all +> the [pre-requisites](./pre_requisites.md) on your machine. + Hermes is packaged in the `ibc-relayer-cli` Rust crate. To install the latest release of Hermes, run the following command in a terminal: ```shell -cargo install ibc-relayer-cli +cargo install ibc-relayer-cli --bin hermes ``` This will download and build the crate `ibc-relayer-cli`, and install the @@ -35,6 +88,15 @@ hermes version hermes 0.1.1 ``` + +__Troubleshooting__: +In case the `cargo install` command above fails, as a first course of action we +recommend trying to run the same command with the additional `locked` flag: + +```shell +cargo install ibc-relayer-cli --bin hermes --locked +``` + ## Build from source ### Clone the repository @@ -75,6 +137,14 @@ If the build is successful, the `hermes` executable will be located in the follo ./target/release/hermes ``` +__Troubleshooting__: +In case the `cargo build` command above fails, as a first course of action we +recommend trying to run the same command with the additional `locked` flag: + +```shell +cargo build --release --bin hermes --locked +``` + ### Running for the first time If you run the `hermes` without any additional parameters you should see the usage and help information: @@ -113,3 +183,7 @@ alias hermes='cargo run --release --bin hermes --' ### Next Steps Go to the [`Configuration`](./config.md) section to learn how to create a configuration file to be used by Hermes. + + +[releases]: https://github.com/informalsystems/ibc-rs/releases +[developer-app]: https://support.apple.com/en-gb/HT202491 \ No newline at end of file From 1d8bda8cfe382d9082ef5018f147f11173f1f739 Mon Sep 17 00:00:00 2001 From: Adi Seredinschi Date: Mon, 22 Feb 2021 09:34:21 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Romain Ruetschi --- guide/src/installation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/src/installation.md b/guide/src/installation.md index 00667bf92e..819e3e2e2f 100644 --- a/guide/src/installation.md +++ b/guide/src/installation.md @@ -26,17 +26,17 @@ The step-by-step instruction below should carry you through the whole process: 1. Make the directory where we'll place the binary: ```shell - mkdir $HOME/.hermes/ + mkdir -p $HOME/.hermes/bin ``` 2. Extract the binary archive: ```shell - tar -C $HOME/.hermes/ -vxzf $ARCHIVE_NAME + tar -C $HOME/.hermes/bin/ -vxzf $ARCHIVE_NAME ``` 3. Update your path: ```shell - export PATH="$HOME/.hermes:$PATH" + export PATH="$HOME/.hermes/bin:$PATH" ``` > NOTE: The binary may be initially prevented from running if you're @@ -186,4 +186,4 @@ Go to the [`Configuration`](./config.md) section to learn how to create a config [releases]: https://github.com/informalsystems/ibc-rs/releases -[developer-app]: https://support.apple.com/en-gb/HT202491 \ No newline at end of file +[developer-app]: https://support.apple.com/en-gb/HT202491 From b4090f0c3dd8ef862a1b33b54af7d3ed4b6715bf Mon Sep 17 00:00:00 2001 From: Adi Seredinschi Date: Mon, 22 Feb 2021 09:42:18 +0100 Subject: [PATCH 3/4] Simplified description. Added locked by default --- guide/src/installation.md | 31 +++++++++---------------------- 1 file changed, 9 insertions(+), 22 deletions(-) diff --git a/guide/src/installation.md b/guide/src/installation.md index 819e3e2e2f..4297a3c3ee 100644 --- a/guide/src/installation.md +++ b/guide/src/installation.md @@ -5,22 +5,17 @@ There are two main approaches for obtaining Hermes: 1. Installation: 1. If you are running on a Unix machine (Linux/MacOS), then the simplest option is to [download the latest binary](#Install-by-downloading). - 2. Alternatively, install via - [Cargo installation instructions](#install-via-cargo). - -[comment]: <> ( Regardless of approach you choose, also follow the post-installation) - -[comment]: <> ( instructions therein.) + 2. You can also install via [Cargo](#install-via-cargo). 2. Alternatively, [build Hermes directly from source](#build-from-source). ## Install by downloading -Simply head to the GitHub [Releases][releases] page download the latest version -of Hermes binary matching your platform: -- `hermes-v0.1.1-x86_64-apple-darwin.tar.gz` (or .zip) for MacOS, -- `hermes-v0.1.1-x86_64-unknown-linux-gnu.tar.gz` (or .zip) for Linux. +Simply head to the GitHub [Releases][releases] page and download the latest +version of Hermes binary matching your platform: +- MacOS: `hermes-v0.1.1-x86_64-apple-darwin.tar.gz` (or .zip), +- Linux: `hermes-v0.1.1-x86_64-unknown-linux-gnu.tar.gz` (or .zip). The step-by-step instruction below should carry you through the whole process: @@ -34,7 +29,8 @@ The step-by-step instruction below should carry you through the whole process: tar -C $HOME/.hermes/bin/ -vxzf $ARCHIVE_NAME ``` -3. Update your path: +3. Update your path, by adding this line in your `.bashrc` or `.zshrc` shell + configuration file: ```shell export PATH="$HOME/.hermes/bin:$PATH" ``` @@ -56,14 +52,14 @@ hermes 0.1.1 ## Install via Cargo -> NOTE: This approach assume you have installed all +> NOTE: This approach assumes you have installed all > the [pre-requisites](./pre_requisites.md) on your machine. Hermes is packaged in the `ibc-relayer-cli` Rust crate. To install the latest release of Hermes, run the following command in a terminal: ```shell -cargo install ibc-relayer-cli --bin hermes +cargo install ibc-relayer-cli --bin hermes --locked ``` This will download and build the crate `ibc-relayer-cli`, and install the @@ -88,15 +84,6 @@ hermes version hermes 0.1.1 ``` - -__Troubleshooting__: -In case the `cargo install` command above fails, as a first course of action we -recommend trying to run the same command with the additional `locked` flag: - -```shell -cargo install ibc-relayer-cli --bin hermes --locked -``` - ## Build from source ### Clone the repository From ff45fbe20ffc820b694f610ffdbb9b44922dabdb Mon Sep 17 00:00:00 2001 From: Adi Seredinschi Date: Mon, 22 Feb 2021 09:46:04 +0100 Subject: [PATCH 4/4] changelog --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96bd1c8a6e..f684422715 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,7 +34,7 @@ - [nothing yet] - [ibc-relayer-cli] - - [nothing yet] + - Hermes guide: improved installation guideline ([#672]) ### BREAKING CHANGES @@ -47,6 +47,7 @@ - [ibc-relayer-cli] - [nothing yet] +[#672]: https://github.com/informalsystems/ibc-rs/issues/672 [#689]: https://github.com/informalsystems/ibc-rs/issues/689 ## v0.1.1