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

@@ -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)

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

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
 

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

docs/guide/src/pcli/pclientd.md

@@ -0,0 +1 @@
+# Using pcli with pclientd

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.

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.

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`.

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`.

docs/guide/src/penumbra_version.md

@@ -0,0 +1 @@
+v0.63.2