Update documentation

documentation/docs/user_guide/installation.md

@@ -11,11 +11,11 @@ To install CABLE you need to have the following already installed on your system
 ``` mermaid
 graph TD
     
-    A(Clone CABLE with git):::UserAction -->|Serial?| B(Run `offline/build3.sh`):::UserAction;
+    A(Clone CABLE with git):::UserAction -->|Serial?| B(Run `./build.bash`):::UserAction;
     B --> D[load modules, set compiler flags, create .tmp/ directory];
     D -->|Serial?| E[Run `make`];
     E --> G[executable `cable`]:::Output;
-    A -->|Parallel?| C(Run `offline/build3.sh mpi`):::UserAction;
+    A -->|Parallel?| C(Run `./build.bash --mpi`):::UserAction;
     C --> D;   
     D -->|Parallel?| F[Run `make mpi`];
     F --> H[executable `cable_mpi`]:::Output;
@@ -74,58 +74,45 @@ CABLE supports both serial and parallel applications.
 ???+ tip "Multiprocessor for global simulations"
     For global (or regional) offline simulations, CABLE can still be run in serial mode (about 15 minutes/year for GSWP global run at 1x1 degree resolution). However, running on multiple processors speeds up the simulation considerably.
 
-CABLE can be built using the BASH script [build3.sh][build3] in the **offline/** directory.
+CABLE can be built using the BASH script [build.bash][build.bash] in the project root directory.
 
 ???+ tip "Build on other HPC"
-    The function *host_gadi* in the build script shows the appropriate configuration to build on Gadi.
-    This may be of use as a template building CABLE on another Linux/HPC system.
+    Gadi specific configuration is guarded by a check on the current hostname (see [here][build.bash-hostname-check]). This may be of use as a template for building CABLE on another Linux/HPC system.
 
-Both the serial and parallel executable for CABLE offline are built in the `offline/` directory by executing
-the build script.
+Executables are built in the `<project_root>/build` directory. Once built successfully, they are then installed in the `<project_root>/bin` directory.
 
 To build the serial model execute:
 
-    ./build3.sh
+    ./build.bash
 
-To build the parallel model execute the same build script but with the argument **mpi**.
+To build the parallel model execute the same build script but with the `--mpi` flag.
 
-    ./build3.sh mpi
+    ./build.bash --mpi
+
+Run `./build.bash --help` to see all supported options provided by the build script.
 
 ???+ warning
     If you need to switch between a serial compilation and a parallel compilation, you need to completely [clean the previous build][clean-build] first.
 
 ### Description of the build process
 
-The build script:
-
-1. loads modules for the Fortran compiler and the netCDF library
-2. sets the compiler flags
-3. creates a hidden temporary directory (`.tmp/`) in which it then compiles CABLE.  
-4. executes `make` in the hidden temporary directory
-
-The [Makefile][makefile] compiles the serial executable by default (via `make`) and compiles the MPI executable via the `mpi` target (via `make mpi`).
-
-The hidden `.tmp/` directory is really only needed for technical reasons and you should never need to go
-into the `.tmp/` directory. However, if for some reason you want the **.o** object files created by the compiler, they persist in this directory. Alternatively, it is sometimes useful to verify that the files you want to compile are actually making it into this directory. This is particularly relevant if you are adding new files to CABLE.
-
-???+ warning "Do not change files under `.tmp/`"
-    If you change the files in `.tmp/` directly, the next build will not pick up these changes and will overwrite them.
+For CABLE offline applications, the underlying build system is [CMake](https://cmake.org) based. CMake is widely used in the C, C++ and Fortran communities and there are many great resources out there on the web, in particular:
 
-One of the features of the build process is that only source files which are
-modified are re-built, followed by their dependents. This is possible because the `.tmp/` directory is
-overwritten by the build script, preserving timestamps of the source files from their original location.
+- [Effective Modern CMake](https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1)
+- [Creating a CMake project (with Fortran)](https://fortran-lang.org/learn/building_programs/build_tools/#creating-a-cmake-project)
+- [An Introduction to Modern CMake](https://cliutils.gitlab.io/modern-cmake/)
 
 ### Cleaning the build
 
 From time to time, it might be useful to clean a previous build completely and restart the build from scratch. This is required when switching between serial and parallel builds.
 
-To clean the build, you need to run:
+To clean the previous build prior to compiling, specify the `--clean` flag to `build.bash`.
 
-    ./build3.sh clean
+    ./build.bash --clean
 
 [cable-github]: https://github.com/CABLE-LSM/cable.git
 [NCI]: https://nci.org.au
 [registration]: https://trac.nci.org.au/trac/cable/wiki/CABLE_Registration
-[build3]: https://github.com/CABLE-LSM/CABLE/blob/main/src/offline/build3.sh
-[makefile]: https://github.com/CABLE-LSM/CABLE/blob/main/src/offline/Makefile
+[build.bash]: https://github.com/CABLE-LSM/CABLE/blob/188-cmake-based-build-system/build.bash
+[build.bash-hostname-check]: https://github.com/CABLE-LSM/CABLE/blob/188-cmake-based-build-system/build.bash#L45-L55
 [clean-build]: installation.md/#cleaning-the-build

documentation/docs/user_guide/uber_quick_guide.md

@@ -5,15 +5,15 @@ Assuming you have computing resources on gadi@NCI, installing and running CABLE
 1. Clone the source code:
 
         git clone https://github.com/CABLE-LSM/CABLE.git
-        cd CABLE/offline
+        cd CABLE
 
 1. Build a serial version of CABLE
 
-        ./build3.sh
+        ./build.bash
 
 1. Execute this serial version of CABLE
 
-        ./cable
+        ./bin/cable
 
 ## In slightly more detail