docs: unify user journey and clarify build and early deployment flow

Author: GandholiSarat

api/docs/building.dox

@@ -34,7 +34,7 @@
  ****************************************************************************
 \page page_building Building from Source
 
-\section build_quick Quick Start: First Build
+\section build_quick Quick Start
 
 If you don't need to modify DR and just need a recent build, you can download [weekly package builds](@ref page_weekly_builds).
 
@@ -55,10 +55,16 @@ To build DynamoRIO on Linux, use the following commands as a guide.  This builds
   $ cmake ..
   # Build.
   $ make -j
+  # Run echo under DR to see if it works.  If you configured for a debug or 32-bit
+  # build, your path will be different.  For example, a 32-bit debug build would
+  # put drrun in ./bin32/ and need -debug flag to run debug build.
+  $ ./bin64/drrun echo hello world
+  hello world
   ```
 
 To validate a build by running a target under DynamoRIO, see \ref page_deploy.
 
+
 \subsection build_quick_windows Windows
 
 To build DynamoRIO on Windows, first install the following software.
@@ -85,10 +91,17 @@ To build 64-bit DynamoRIO in release mode, launch the `Visual Studio 2022 > x64
   # Studio and build from there.  You must pass --config to work around a cmake
   # bug.  (http://www.cmake.org/Bug/view.php?id=11830)
   $ cmake --build . --config RelWithDebInfo
+  # Run notepad under DR to see whether it worked.
+  $ bin64\drrun.exe notepad.exe
   ```
 
 To validate a build by running a target under DynamoRIO, see \ref page_deploy.
 
+For 32-bit builds, alternative prompts, and Ninja guidance, see
+\ref build_windows_variants.
+
+----------------
+
 \section build_install Install and Build Outputs
 
 This section describes where build artifacts are produced and how the layout
@@ -172,6 +185,13 @@ $ CFLAGS=-m32 CXXFLAGS=-m32 cmake -DDEBUG=ON ..
 $ make -j
 ```
 
+\subsection build_install_local Installing from a Local Build
+
+To mirror the layout and functionality of an official released package, build the `install` target.  The `CMAKE_INSTALL_PREFIX` cmake variable controls the destination of the installation.
+
+Once you've installed locally, you can now point at the installation just like you'd point at a release package for the purposes of building separate clients.
+
+
 \subsection build_windows_variants Windows Build Variants
 
 If you need a 32-bit build, choose `x86 Native Tools Command Prompt` and pass
@@ -391,7 +411,7 @@ Support for aarch64-on-x86 on Windows is not yet finished; nor is support for ot
 
 \subsection build_windows_details Details for Building on Windows
 
-## Compiler
+\subsubsection build_windows_compiler Compiler
 
 First, you need the compiler, linker, and associated tools.
 Install Visual Studio 2022 which is the version used by our automated tests.
@@ -410,7 +430,7 @@ environment to use the x64 tools.  As mentioned above, you can launch the
 command prompt from the Visual Studio Start menu folder, or run the
 "vcvarsall.bat amd64" script.
 
-## CMake
+\subsubsection build_windows_cmake CMake
 
 You need CMake (version 3.14+) for Windows (*not* for Cygwin, as we need to pass paths
 with drive letters to our compiler).  You can download a binary installation here:
@@ -419,7 +439,7 @@ with drive letters to our compiler).  You can download a binary installation her
 
 Install CMake and put its bin directory on the path for your shell.
 
-## Other Tools
+\subsubsection build_windows_other_tools Other Tools
 
 In order to build you must have a version of perl.  It can be either a
 Cygwin perl or a native Windows perl.
@@ -431,7 +451,7 @@ In order to build the documentation, you will additionally need:
 These can be either Cygwin packages or native Windows.
 TH`.
 
-## Using Cygwin
+\subsubsection build_windows_cygwin Using Cygwin
 
 If you wish to run your build commands in a Cygwin bash shell, you will need to
 set up your environment the way that Visual Studio sets up the environment.

api/docs/deployment.dox

@@ -244,8 +244,8 @@ bin32/drrun.exe -c samples/bin32/bbsize.dll -- notepad
 \endcode
 
 Alternatively, you can first run \c notepad.exe, and then use \c drrun
-to attach to it.  Attaching is an experimental feature and is not yet as
-well-supported as launching a new process:
+to attach to it, but please note that attaching is an experimental
+feature and is not yet as well-supported as launching a new process:
 \code
 bin32/drrun.exe -attach <notepad_pid> -c samples/bin32/bbsize.dll
 \endcode
@@ -351,8 +351,8 @@ under DynamoRIO with the bbsize sample client:
 \endcode
 
 Alternatively, you can first run the target, and then use \c drrun
-to attach to it.  Attaching is an experimental feature and is not yet as
-well-supported as launching a new process.
+to attach to it, but please note that attaching is an experimental
+feature and is not yet as well-supported as launching a new process.
 In particular, if the application is in the middle of a blocking syscall,
 DynamoRIO will wait for that to finish.  To instead force interruption of
 the syscall, additionally pass -skip_syscall.