From c349fec5ca92eed6578950073be30e6ae8a9ccec Mon Sep 17 00:00:00 2001 From: Conor Schaefer Date: Tue, 28 Nov 2023 11:44:35 -0800 Subject: [PATCH] docs: recommend installing binaries for pcli & pd Updates the guide docs to prefer installing prebuilt binaries, linking out to instructions on compiling from source as an alternative. We also clarify that Windows is not a first-class build target. Closes #3320. --- docs/guide/src/SUMMARY.md | 3 +- docs/guide/src/dev/build.md | 82 +++++++++++++++++++++++ docs/guide/src/dev/devnet-quickstart.md | 2 +- docs/guide/src/pcli/install.md | 87 +++++-------------------- docs/guide/src/pcli/pclientd.md | 1 + docs/guide/src/pcli/update.md | 18 ++--- docs/guide/src/pd.md | 2 +- docs/guide/src/pd/build.md | 24 ------- docs/guide/src/pd/install.md | 32 +++++++++ docs/guide/src/penumbra_version.md | 1 + 10 files changed, 142 insertions(+), 110 deletions(-) create mode 100644 docs/guide/src/dev/build.md create mode 100644 docs/guide/src/pcli/pclientd.md create mode 100644 docs/guide/src/pd/install.md create mode 100644 docs/guide/src/penumbra_version.md diff --git a/docs/guide/src/SUMMARY.md b/docs/guide/src/SUMMARY.md index 227eb35934..82dee1a8ad 100644 --- a/docs/guide/src/SUMMARY.md +++ b/docs/guide/src/SUMMARY.md @@ -9,13 +9,14 @@ - [Using Governance](./pcli/governance.md) - [Using `pcli` with `pclientd`](./pcli/pclientd.md) - [Running a `pd` fullnode](./pd.md) - - [Building `pd`](./pd/build.md) + - [Installing `pd`](./pd/install.md) - [Joining a Testnet](./pd/join-testnet.md) - [Local RPC with `pclientd`](./pclientd.md) - [Configuring `pclientd`](./pclientd/configure.md) - [Making RPC requests](./pclientd/rpc.md) - [Building Transactions](./pclientd/build_transaction.md) - [Development](./dev.md) + - [Compiling from source](./dev/build.md) - [Devnet Quickstart](./dev/devnet-quickstart.md) - [SQLite compilation setup](./dev/sqlx.md) - [Building documentation](./dev/docs.md) diff --git a/docs/guide/src/dev/build.md b/docs/guide/src/dev/build.md new file mode 100644 index 0000000000..06da1d49ee --- /dev/null +++ b/docs/guide/src/dev/build.md @@ -0,0 +1,82 @@ +# Compiling from source + +Penumbra is written in Rust. To build it, you will need a recent +stable version of Rust, as well as a few OS-level dependencies. +We don't support building on Windows. If you need to use Windows, +consider using [WSL] instead. + +### Installing the Rust toolchain + +This requires that you install a recent (>= 1.73) stable version +of the Rust compiler, installation instructions for which you can find +[here](https://www.rust-lang.org/learn/get-started). Don't forget to reload your shell so that +`cargo` is available in your `$PATH`! + +You can verify the rust compiler version by running `rustc --version` which should indicate version 1.73 or later. + +### Installing build prerequisites + +#### Linux + +You may need to install some additional packages in order to build `pcli`, +depending on your distribution. For a bare-bones Ubuntu installation, you can +run: + +```bash +sudo apt-get install build-essential pkg-config libssl-dev clang git-lfs +``` + +For a minimal Fedora/CentOS/RHEL image, you can run: + +```bash +sudo dnf install openssl-devel clang git cargo rustfmt git-lfs +``` + +#### macOS + +You may need to install the command-line developer tools if you have never done +so: +```bash +xcode-select --install +``` + +You'll also need to install Git LFS, which you can do [via Homebrew](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage?platform=mac): + +```bash +brew install git-lfs +``` + +### Making sure that `git-lfs` is installed + +Running `git lfs install` will make sure that git-lfs is correctly installed on your machine. + +### Cloning the repository + +Once you have installed the above packages, you can clone the repository: + +```bash +git clone https://github.com/penumbra-zone/penumbra +``` + +To build the versions of `pcli`, `pd`, etc. compatible with the current testnet, +navigate to the `penumbra/` folder, fetch the latest from the repository, and check out the +latest tag for the current +[testnet](https://github.com/penumbra-zone/penumbra/releases): + +```bash +cd penumbra && git fetch && git checkout {{ #include ../penumbra_version.md }} +``` + +If you want to build the most recent version compatible with the "preview" environment, +then run `git checkout main` instead. + +### Building the binaries + +Then, build all the project binaries using `cargo`: + +```bash +cargo build --release +``` + +[protoc-install]: https://grpc.io/docs/protoc-installation/ +[WSL]: https://learn.microsoft.com/en-us/windows/wsl/install diff --git a/docs/guide/src/dev/devnet-quickstart.md b/docs/guide/src/dev/devnet-quickstart.md index 3d59383404..923d9203f9 100644 --- a/docs/guide/src/dev/devnet-quickstart.md +++ b/docs/guide/src/dev/devnet-quickstart.md @@ -3,7 +3,7 @@ This page describes a quickstart method for running `pd`+`cometbft` to test changes during development. -To start, you'll need to [install CometBFT `v0.37`](../pd/build.md#installing-cometbft). +To start, you'll need to [install CometBFT `v0.37`](../pd/install.md#installing-cometbft). ## Generating configs diff --git a/docs/guide/src/pcli/install.md b/docs/guide/src/pcli/install.md index a9142b8d56..fef933a4df 100644 --- a/docs/guide/src/pcli/install.md +++ b/docs/guide/src/pcli/install.md @@ -1,79 +1,24 @@ -# Installing `pcli` +# Installing pcli -### Installing the Rust toolchain +Download prebuilt binaries from the [Penumbra releases page on Github](https://github.com/penumbra-zone/penumbra/releases). +Make sure to use the most recent version available, as the version of `pcli` must +match the software currently running on the network. -This requires that you install a recent (>= 1.73) stable version -of the Rust compiler, installation instructions for which you can find -[here](https://www.rust-lang.org/learn/get-started). Don't forget to reload your shell so that -`cargo` is available in your `\$PATH`! +Make sure choose the correct platform for your machine. After downloading the `.tar.xz` file, +extract it, and copy its contents to your `$PATH`. For example: -You can verify the rust compiler version by running `rustc --version` which should indicate version 1.73 or later. - -`pcli` requires `rustfmt` as part of the build process --- depending on your -OS/install method for Rust, you may have to install that separately. - -### Installing build prerequisites - -#### Linux - -You may need to install some additional packages in order to build `pcli`, -depending on your distribution. For a bare-bones Ubuntu installation, you can -run: - -```bash -sudo apt-get install build-essential pkg-config libssl-dev clang git-lfs ``` +curl -O -L https://github.com/penumbra-zone/penumbra/releases/download/{{ #include ../penumbra_version.md }}/pcli-x86_64-unknown-linux-gnu.tar.xz +unxz pcli-x86_64-unknown-linux-gnu.tar.xz +tar -xf pcli-x86_64-unknown-linux-gnu.tar +sudo mv pcli-x86_64-unknown-linux-gnu/pcli /usr/local/bin/ -For a minimal Fedora/CentOS/RHEL image, you can run: - -```bash -sudo dnf install openssl-devel clang git cargo rustfmt git-lfs -``` - -#### macOS - -You may need to install the command-line developer tools if you have never done -so: -```bash -xcode-select --install -``` - -You'll also need to install Git LFS, which you can do [via Homebrew](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage?platform=mac): - -```bash -brew install git-lfs -``` - -### Making sure that `git-lfs` is installed - -Running `git lfs install` will make sure that git-lfs is correctly installed on your machine. - -### Cloning the repository - -Once you have installed the above tools, you can clone the repository: - -```bash -git clone https://github.com/penumbra-zone/penumbra -``` - -To build the version of `pcli` compatible with the current testnet, navigate to -the penumbra folder, fetch the latest from the repository, and check out the -latest tag for the current -[testnet](https://github.com/penumbra-zone/penumbra/releases): - -```bash -cd penumbra && git fetch && git checkout v0.63.1 -``` - -### Building the `pcli` client software - -Then, build the `pcli` tool using `cargo`: - -```bash -cargo build --release --bin pcli +# confirm the pcli binary is installed by running: +pcli --version ``` -Because you are building a work-in-progress version of the client, you may see compilation warnings, -which you can safely ignore. +Only macOS and Linux are supported. If you need to use Windows, +consider using [WSL]. If you prefer to build from source, +see the [compilation guide](../dev/build.md). -[protoc-install]: https://grpc.io/docs/protoc-installation/ +[WSL]: https://learn.microsoft.com/en-us/windows/wsl/install diff --git a/docs/guide/src/pcli/pclientd.md b/docs/guide/src/pcli/pclientd.md new file mode 100644 index 0000000000..caa563e4f5 --- /dev/null +++ b/docs/guide/src/pcli/pclientd.md @@ -0,0 +1 @@ +# Using pcli with pclientd diff --git a/docs/guide/src/pcli/update.md b/docs/guide/src/pcli/update.md index 2dd58f78b0..e56a818db0 100644 --- a/docs/guide/src/pcli/update.md +++ b/docs/guide/src/pcli/update.md @@ -1,19 +1,13 @@ ## Updating `pcli` -Make sure you've followed the [installation steps](https://guide.penumbra.zone/main/pcli/install.html#cloning-the-repository). Then, to update to the latest testnet [release](https://github.com/penumbra-zone/penumbra/releases): +Follow the [installation steps](install.md) to install the +most recent version of `pcli`, which is `{{ #include ../penumbra_version.md }}`. -``` -cd penumbra && git fetch && git checkout v0.63.1 -``` - -Once again, build `pcli` with cargo: +After installing the updated version, reset the view data used by `pcli`: ``` -cargo build --release --bin pcli +pcli view reset ``` -No wallet needs to be [generated](https://guide.penumbra.zone/main/pcli/wallet.html#generating-a-wallet). Instead, keep one's existing wallet and reset view data. - -``` -cargo run --quiet --release --bin pcli view reset -``` +No wallet needs to be [generated](wallet.md#generating-a-wallet). The existing wallet +will be used automatically. diff --git a/docs/guide/src/pd.md b/docs/guide/src/pd.md index 313b23b978..481d782f38 100644 --- a/docs/guide/src/pd.md +++ b/docs/guide/src/pd.md @@ -3,6 +3,6 @@ This section describes how to build and run `pd`, the node implementation for Penumbra: -- [Building `pd`](./pd/build.md) describes how to build `pd`; +- [Installing `pd`](./pd/install.md) describes how to build `pd`; - [Joining a Testnet](./pd/join-testnet.md) describes how to join the current testnet; - [Creating a Testnet](./dev/devnet-quickstart.md) describes how to create a custom testnet, for instance for local development. diff --git a/docs/guide/src/pd/build.md b/docs/guide/src/pd/build.md index 1d318301e7..b8ba3bddc6 100644 --- a/docs/guide/src/pd/build.md +++ b/docs/guide/src/pd/build.md @@ -1,25 +1 @@ # Building pd - -The node software `pd` is part of the same repository as `pcli`, so follow -[those instructions](../pcli/install.md) to clone the repo and install dependencies. - -To build `pd`, run - -```bash -cargo build --release --bin pd -``` - -Because you are building a work-in-progress version of the node software, you may see compilation warnings, -which you can safely ignore. - -### Installing CometBFT - -You'll need to have [CometBFT installed](https://docs.cometbft.com/v0.37/guides/install) -on your system to join your node to the testnet. - -**NOTE**: Previous versions of Penumbra used Tendermint, but as of Testnet 62 (released 2023-10-10), -only CometBFT `v0.37.2` is supported. **Do not use** any version of Tendermint, which may not work with `pd`. - -You can download `v0.37.2` [from the CometBFT releases page](https://github.com/cometbft/cometbft/releases/tag/v0.37.2) -to install a binary. If you prefer to compile from source instead, -make sure you are compiling version `v0.37.2`. diff --git a/docs/guide/src/pd/install.md b/docs/guide/src/pd/install.md new file mode 100644 index 0000000000..bacb08a8d7 --- /dev/null +++ b/docs/guide/src/pd/install.md @@ -0,0 +1,32 @@ +# Installing pd + +Download prebuilt binaries from the [Penumbra releases page on Github](https://github.com/penumbra-zone/penumbra/releases). +Make sure to use the most recent version available, as the version of `pd` must +match the software currently running on the network. + +Make sure choose the correct platform for your machine. After downloading the `.tar.xz` file, +extract it, and copy its contents to your `$PATH`. For example: + +``` +curl -O -L https://github.com/penumbra-zone/penumbra/releases/download/{{ #include ../penumbra_version.md }}/pd-x86_64-unknown-linux-gnu.tar.xz +unxz pd-x86_64-unknown-linux-gnu.tar.xz +tar -xf pd-x86_64-unknown-linux-gnu.tar +sudo mv pd-x86_64-unknown-linux-gnu/pd /usr/local/bin/ + +# confirm the pd binary is installed by running: +pd --version +``` + +If you prefer to build from source, see the [compilation guide](../dev/build.md). + +### Installing CometBFT + +You'll need to have [CometBFT installed](https://docs.cometbft.com/v0.37/guides/install) +on your system to join your node to the testnet. + +You can download `v0.37.2` [from the CometBFT releases page](https://github.com/cometbft/cometbft/releases/tag/v0.37.2) +to install a binary. If you prefer to compile from source instead, +make sure you are compiling version `v0.37.2`. + +**NOTE**: Previous versions of Penumbra used Tendermint, but as of Testnet 62 (released 2023-10-10), +only CometBFT `v0.37.2` is supported. **Do not use** any version of Tendermint, which will not work with `pd`. diff --git a/docs/guide/src/penumbra_version.md b/docs/guide/src/penumbra_version.md new file mode 100644 index 0000000000..2ad86d47ca --- /dev/null +++ b/docs/guide/src/penumbra_version.md @@ -0,0 +1 @@ +v0.63.2