chore: docker reproducible builds docs (#1020)

book/generating-proofs/basics.md

@@ -19,6 +19,10 @@ You can run the above script in the `script` directory with `RUST_LOG=info cargo
 
 ## Build Script
 
+> WARNING: This may not generate a reproducible ELF which is necessary for verifying that your binary corresponds to given source code.
+>
+> When building a ELF that will be used in production, make sure to use the [reproduction build system](../writing-programs/setup.md#build-with-docker-production).
+
 If you want your program crate to be built automatically whenever you build/run your script crate, you can add a `build.rs` file inside of `script/` (at the same level as `Cargo.toml`):
 
 ```rust,noplayground

book/getting-started/install.md

@@ -8,7 +8,6 @@ build the toolchain and CLI from source.
 - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 - [Rust (Nightly)](https://www.rust-lang.org/tools/install)
 - [Docker](https://docs.docker.com/get-docker/)
-- [Go >1.22.1 (Optional)](https://go.dev/doc/install)
 
 ## Option 1: Prebuilt Binaries (Recommended)
 
@@ -86,29 +85,4 @@ You can delete your existing installation of the toolchain with:
 
 ```bash
 rustup toolchain remove succinct
-```
-
-## Option 3: Using Docker
-
-SP1 can also be used entirely within a Docker container. If you don't have it, Docker can be
-installed directly from [Docker's website](https://docs.docker.com/get-docker/).
-
-Then you can use:
-
-```bash
-cargo prove --docker
-```
-
-to automatically use the latest image of SP1 in a container.
-
-Alternatively, it is possible to build the docker image locally by running:
-
-```bash
-docker build -t succinctlabs/sp1:latest ./cli/docker
-```
-
-You can then run the `cargo prove` command by mounting your program directory into the container:
-
-```bash
-docker run -v "$(pwd):/root/program" -it succinctlabs/sp1:latest prove build
-```
+```

book/writing-programs/setup.md

@@ -2,7 +2,7 @@
 
 In this section, we will teach you how to setup a self-contained crate which can be compiled as a program that can be executed inside the zkVM.
 
-## CLI (Recommended)
+## Create Project with CLI (Recommended)
 
 The recommended way to setup your first program to prove inside the zkVM is using the method described in [Quickstart](../getting-started/quickstart.md) which will create a program folder.
 
@@ -11,25 +11,36 @@ cargo prove new <name>
 cd program
 ```
 
-### Build
+## Build with CLI (Development)
 
-To build the program, simply run:
+> WARNING: This may not generate a reproducible ELF which is necessary for verifying that your binary corresponds to given source code.
+>
+> Use the [reproducible build system](#build-with-docker-production) for production builds.
+
+To build the program while in development, simply run:
 
 ```
 cargo prove build
 ```
 
-This will compile the ELF that can be executed in the zkVM and put the executable in `elf/riscv32im-succinct-zkvm-elf`.
+This will compile the ELF that can be executed in the zkVM and put the executable in `elf/riscv32im-succinct-zkvm-elf`. 
 
-### Build with Docker
+## Build with Docker (Production)
 
-Another option is to build your program in a Docker container. This is useful if you are on a platform that does not have prebuilt binaries for the succinct toolchain, or if you are looking to get a reproducible ELF output. To do so, just use the `--docker` flag.
+For production builds of programs, you can build your program inside a Docker container which will generate a **reproducible ELF** on all platforms. To do so, just use the `--docker` flag.
 
 ```
 cargo prove build --docker
 ```
 
-## Manual
+To verify that your build is reproducible, you can compute the SHA-512 hash of the ELF on different platforms and systems with:
+
+```
+$ shasum -a 512 elf/riscv32im-succinct-zkvm-elf
+f9afb8caaef10de9a8aad484c4dd3bfa54ba7218f3fc245a20e8a03ed40b38c617e175328515968aecbd3c38c47b2ca034a99e6dbc928512894f20105b03a203
+```
+
+## Manual Project Setup
 
 You can also manually setup a project. First create a new cargo project:
 
@@ -67,13 +78,3 @@ sp1_zkvm::entrypoint!(main);
 ```
 
 These two lines of code wrap your main function with some additional logic to ensure that your program compiles correctly with the RISCV target.
-
-### Build
-
-To build the program, simply run:
-
-```
-cargo prove build
-```
-
-This will compile the ELF (RISCV binary) that can be executed in the zkVM and put the executable in `elf/riscv32im-succinct-zkvm-elf`.

cli/src/build.rs

@@ -16,9 +16,13 @@ fn get_docker_image() -> String {
 
 #[derive(Parser)]
 pub(crate) struct BuildArgs {
-    #[clap(long, action, help = "Ignore Rust version check.")]
+    #[clap(
+        long,
+        action,
+        help = "Create a binary using the reproducible build system with docker."
+    )]
     pub(crate) docker: bool,
-    #[clap(long, action, help = "Ignore Rust version check.")]
+    #[clap(long, action, help = "Ignore the rust version check.")]
     pub(crate) ignore_rust_version: bool,
 }
 
@@ -40,7 +44,9 @@ pub fn build_program(args: &BuildArgs) -> Result<Utf8PathBuf> {
             .context("failed to run docker command")?;
 
         if !docker_check.success() {
-            eprintln!("Docker is not installed or not running.");
+            eprintln!(
+                "docker is not installed or not running: https://docs.docker.com/get-docker/"
+            );
             exit(1);
         }
 
@@ -108,7 +114,6 @@ pub fn build_program(args: &BuildArgs) -> Result<Utf8PathBuf> {
             .context("Failed to run cargo command.")?;
 
         if !result.success() {
-            // Error message is already printed by cargo
             exit(result.code().unwrap_or(1))
         }
     }