Update README.md

scripts/README.md

@@ -1,33 +1,87 @@
-All scripts can be built fully by entering the appropriate directory and doing:
+## Building MATAR with Anaconda
+It is advised to use the Anaconda package manager to build the MATAR examples as follows:
+
+1. Create an environment and activate:
+```
+conda create --name MATAR
+conda activate MATAR
+```
+
+2. Install needed packages:
+
+If building MATAR examples and tests for a CPU backend in Kokkos, then the following packages are needed
+```
+conda install -c conda-forge cxx-compiler 
+conda install -c conda-forge fortran-compiler
+conda install cmake
+```
+
+To build examples for an Nvidia GPU, then install the following packages (and do not install anything shown in the CPU instructions above here),
 ```
-source build-it.sh <arg1> <arg2> ... <argn>
+conda install -c conda-forge "cxx-compiler=1.5.2" 
+conda install -c conda-forge "fortran-compiler=1.5.2"
+conda install cmake 
 ```
-build-it.sh can take up to 3 arguments (minimum of 2)
+Here, the conda compiler version 1.5.2 is used, which will install gcc version 11.0. Omitting 1.5.2 will install gcc version 12 (at this time). We encourage users who are interested in running with the CUDA backend to use a gcc version with 1 number less than the CUDA library version. Now the CUDA libraries must be installed.
 ```
-source build-it.sh <environment type> <parallelism> <build directory name (optional)>
+ conda install -c conda-forge cudatoolkit      
+ conda install -c conda-forge cudatoolkit-dev
+```
+
+At this point, all necessary dependencies and third-party libraries are installed in the Conda environment (for the Kokkos CPU or NVidia GPU backends). 
 
-environment has two options: 'hpc' or 'macos'
-hpc: builds by loading modules and can perform parallel builds (make -j)
-macos: does not load anything externally and expects the environment to be set up on your mac. Additionally, the builds will be done serially (make)
-parallelism has four options: 'cuda', 'hip', 'openmp', 'none'
-Note - all builds use Kokkos. The 'none' option will still use Kokkos, however only utilizing the Kokkos Serial build
-        cuda: loads cuda module and a working gcc module pairing (these can be changed, more info later)
-        hip: loads hip module and a working clang module pairing
-        openmp: loads gcc module and sets openmp environment variables
-        none: loads gcc module
-build directory is an optional argument which will create the name of the build directory
+3. Go to the scripts folder in the MATAR directory.  Then run the build script as:
 ```
-All other scripts will be called with the appropriate arguments as a result of running build-it.
+source build-matar.sh --help
+```
+
+Which outputs:
 
-If you need to simply rebuild the app and not get a new kokkos installation, simply
 ```
-source cmake_build.sh <args>
+Usage: source build-matar.sh [OPTION]
+Required arguments:
+  none
+
+Optional arguments:
+  --execution=<examples|test>. Default is 'all'
+  --kokkos_build_type=<serial|openmp|pthreads|cuda|hip>.  Default is 'serial'
+  --build_action=<full-app|set-env|install-kokkos|install-matar|matar>. Default is 'full-app'
+  --machine=<darwin|chicoma|linux|mac> (default: none)
+  --num_jobs=<number>: Number of jobs for 'make' (default: 1, on Mac use 1)
+  --build_cores=<Integers greater than 0>. Default is set 1
+  --help: Display this help message
 ```
-with the same arguments you would with build-it.sh
+
+To build MATAR with a kokkos backend you would need to provide `--kokkos_build_type` option. The command below builds the examples in MATAR using the serial version (which is the default) of Kokkos:
+
+```
+source build-matar.sh --kokkos_build_type=serial
+```
+
+This will build examples and tests in the folder `build-matar_serial`. The binaries for the examples are in bin folder inside that folder.
+
+To build MATAR with the openMP parallel backend, use `--kokkos_build_type=openmp` option. 
+
+```
+source build-matar.sh --kokkos_build_type=openmp
+```
+The same logic applies to building the examples with the other Kokkos backends.
+
+## Building MATAR without Anaconda
+The user must install compilers and thirdparty libraries on a linux machine using `sudo app-get install`, or on a Mac using homebrew, or on an HPC maching by loading modules.  As part of the build script, we call scripts (inside the machines folder) to configure the enviroment variables. A note of caution when building on a Mac, the cmake outside anaconda is rescricted to serial compulation, use the default value of 1 and only use -j1 when recompiling the code.  For parallel compulation on a Mac, use the anaconda cmake.
+
+If you need to simply rebuild the app and not get a new kokkos installation, simply type
+```
+source cmake_build_<example/test>.sh <args>
+```
+with the same arguments you would use with the build-matar.sh
 
 If you log onto a machine for the first time (or get a new allocation) you will need to run
 ```
 source setup-env.sh <args>
 ```
-with the same arguments you would with build-it.sh
-
+with the same arguments you would with build-mater.sh
+
+
+## Building a simple project with MATAR
+To use MATAR in your simple project with the serial Kokkos backend, you can copy paste all the `.h` files in `/src/include` into your local directory where your code is compiled.  Building a Kokkos backend requires using cmake and one the above approaches.