Java: Revises DEVELOPER.md file. (#403)

* Revises `DEVELOPER.md` file. * Updates `cd` command to reduce potential for confusion * Adds clarification * Reverts heading format changes per code review comment Signed-off-by: Roger Neate <[email protected]>
valkey-io · Jul 9, 2024 · 04ec816 · 04ec816
1 parent 62ca39e
commit 04ec816
Showing 1 changed file with 34 additions and 21 deletions.
diff --git a/java/DEVELOPER.md b/java/DEVELOPER.md
@@ -8,9 +8,11 @@ The Valkey GLIDE Java wrapper consists of both Java and Rust code. Rust bindings
 
 ### Build from source
 
+**Note:** See the [Troubleshooting](#troubleshooting) section below for possible solutions to problems.
+
 #### Prerequisites
 
-Software Dependencies
+**Software Dependencies**
 
 -   git
 -   GCC
@@ -21,25 +23,6 @@ Software Dependencies
 -   rustup
 -   Java 11
 
-**Install protobuf compiler**
-
-To install protobuf for MacOS, run:
-```bash
-brew install protobuf
-# Check that the protobuf compiler version 26.1 or higher is installed
-protoc --version
-```
-
-For the remaining systems, do the following:
-```bash
-PB_REL="https://github.com/protocolbuffers/protobuf/releases"
-curl -LO $PB_REL/download/v26.1/protoc-26.1-linux-x86_64.zip
-unzip protoc-26.1-linux-x86_64.zip -d $HOME/.local
-export PATH="$PATH:$HOME/.local/bin"
-# Check that the protobuf compiler version 26.1 or higher is installed
-protoc --version
-```
-
 **Dependencies installation for Ubuntu**
 
 ```bash
@@ -52,6 +35,8 @@ source "$HOME/.cargo/env"
 rustc --version
 ```
 
+Continue with **Install protobuf compiler** below.
+
 **Dependencies installation for CentOS**
 
 ```bash
@@ -60,6 +45,9 @@ sudo yum install -y java-11-openjdk-devel git gcc pkgconfig openssl openssl-deve
 # Install rust
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
+
+Continue with **Install protobuf compiler** below.
+
 **Dependencies installation for MacOS**
 
 ```bash
@@ -69,6 +57,27 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 source "$HOME/.cargo/env"
 ```
 
+Continue with **Install protobuf compiler** below.
+
+**Install protobuf compiler**
+
+To install protobuf for MacOS, run:
+```bash
+brew install protobuf
+# Check that the protobuf compiler version 26.1 or higher is installed
+protoc --version
+```
+
+For the remaining systems, do the following:
+```bash
+PB_REL="https://github.com/protocolbuffers/protobuf/releases"
+curl -LO $PB_REL/download/v26.1/protoc-26.1-linux-x86_64.zip
+unzip protoc-26.1-linux-x86_64.zip -d $HOME/.local
+export PATH="$PATH:$HOME/.local/bin"
+# Check that the protobuf compiler version 26.1 or higher is installed
+protoc --version
+```
+
 #### Building and installation steps
 
 Before starting this step, make sure you've installed all software dependencies.
@@ -151,7 +160,11 @@ For Java, we use Spotless and SpotBugs.
 ### Troubleshooting
 
 Some troubleshooting issues:
-- Failed to find `cargo` after `rustup`: `gradle` daemon may need to be restarted via `./gradlew --stop` to recognize the new `$PATH`. If that doesn't work, you may need to restart your machine.
+- If the build fails after following the installation instructions, the `gradle` daemon may need to be 
+  restarted (`./gradlew --stop`) so that it recognizes changes to environment variables (e.g. `$PATH`). If that doesn't work,
+  you may need to restart your machine. In particular, this may solve the following problems:
+    - Failed to find `cargo` after `rustup`.
+    - No Protobuf compiler (protoc) found.
 - If build fails because of rust compiler fails, make sure submodules are updated using `git submodule update`.
 - If protobuf 26.0 or earlier is detected, upgrade to the latest protobuf release.