PMM-12899 update the documentation

build/local/README.md

@@ -12,6 +12,7 @@ The build process is mostly based on bash scripts, which control the build flow.
 
 The build process is designed to be run on a Linux host. We believe it can be run on other flavors of Linux, including MacOS, with little to no modification (TBC).
 
+
 ## Prerequisites
 
 Below is a list of prerequisites that are required to build PMM locally.
@@ -26,9 +27,51 @@ Below is a list of prerequisites that are required to build PMM locally.
 - yq: 4.42.0+ (tested on 4.42.1)
 - jq: 1.6+ (tested on 1.6)
 
-## Build Steps
+
+## How to build PMM
 
 1. Install the prerequisites
-2. Clone the PMM repository
-3. Change to the `build/local` directory
-4. Run the `build.sh` script
+2. Clone the PMM repository to the user's home directory, e.g.: `git clone https://github.com/percona/pmm /home/user/pmm`. 
+3. Change to the `build/local` directory in the cloned repo.
+4. Run `build.sh --help` to print the help message and check the usage.
+5. Run `build.sh` with parameters of your choice to build PMM v3.
+
+Usually, you will want to rebuild PMM whenever there are changes in at least one of its components. All components of PMM are gathered together in one repository - `github.com/percona-lab/pmm-submodules` (or `pmm-submodules`). Therefore, you can run `build.sh` as often as those changes need to be factored in to the next build.
+
+Once the build is finished, you can proceed with launching a new instance of PMM Server, or installing a freshly built PMM Client, and testing the changes.
+
+
+## The `rpmbuild` image and docker cache
+
+We use a special docker image to build various PMM artifacts - `perconalab/rpmbuild:3`. It comes provisioned with tools which are required to build PMM artifacts, for example RPM packages. As a build tool, it offers a number of benefits, two most obvious of which are:
+
+- it frees the user from installing dependencies on their host machine
+- it leverages a very powerful docker caching system, which results in reduced build times
+
+During the first run, `build.sh` will create a few directories on the host machine, which are necessary to make use of docker cache. Please be aware, that the docker container's user needs to be able to write to these directories. The docker container's user is `builder` with uid 1000 and gid 1000. You need to make sure that the directories we create on the host are owned by a user with the same uid and gid. If the build fails, this is the first thing to check.
+
+
+## Avoiding unnecessary builds
+
+Sometimes, the changes you make affect only PMM Client. Other times, they affect only PMM Server. Therefore, you may want to skip building parts of PMM. The `build.sh` script offers several parameters to help control what you want to build.
+
+* --no-update: run the build tasks without pulling the changes from `pmm-submodules` repository
+* --update-only: pull changes from the repo without building PMM
+* --no-client: do not build the client, use the cached PMM Client artifacts
+* --no-client-docker: skip building PMM Client docker container
+* --no-server-rpm: skip building PMM Server RPM artifacts
+* --log-file <path>: change the path of the build log file
+
+It's important to note, however, that once all changes are made and tested, you most probably want to re-build both PMM Client and Server to test them together.
+
+
+## Target environments
+
+Currently, local builds target the following environments:
+- PMM Client
+  - tarball - virtually any amd64 Linux environment
+  - RPM - RHEL9-compatible environments
+  - docker image - docker and Kubernetes environments (amd64)
+- PMM Server
+  - docker image - docker and Kubernetes environments (amd64)
+

build/local/build.sh

@@ -9,6 +9,8 @@ NO_SERVER_RPM=0
 NO_SERVER_DOCKER=0
 START_TIME=$(date +%s)
 LOG_FILE="/tmp/build.log"
+BASE_NAME=$(basename $0)
+USAGE="Usage: $BASE_NAME [--no-update | --update-only] [--no-client] [--no-client-docker] [--no-server-rpm] [--log-file <path>] [--help | -h]"
 
 while test "$#" -gt 0; do
   case "$1" in
@@ -46,9 +48,15 @@ while test "$#" -gt 0; do
       fi
       LOG_FILE="$1"
       ;;
+    --help | -h)
+      shift
+      echo "$USAGE"
+      echo
+      exit 0
+      ;;
     *)
       echo "Unknown argument: $1"
-      echo "Usage: $0 [--no-update | --update-only] [--no-client] [--no-client-docker] [--no-server-rpm] [--log-file <path>]"
+      echo "$USAGE"
       echo
       exit 1
       ;;
@@ -236,12 +244,7 @@ init() {
   PATH_TO_SCRIPTS="sources/pmm/src/github.com/percona/pmm/build/scripts"
   export RPMBUILD_DOCKER_IMAGE=perconalab/rpmbuild:3
 
-  # We use a special docker image to build various PMM artifacts - `perconalab/rpmbuild:3`.
-  # Important: the docker container's user needs to be able to write to these directories.
-  # The docker container's user is `builder` with uid 1000 and gid 1000. You need to make sure
-  # that the directories we create on the host are owned by a user with the same uid and gid.
-
-  # Create cache directories.
+  # Create cache directories. Read more in the section about `rpmbuild`.
   test -d "${root_dir}/go-path" || mkdir -p "go-path"
   test -d "${root_dir}/go-build" || mkdir -p "go-build"
   test -d "${root_dir}/yarn-cache" || mkdir -p "yarn-cache"