Feature/mac os install inst

docs/gcc_macos.md

@@ -1 +1,114 @@
-**TODO**
+# Building the HIP CPU Runtime and Client Applications GCC C++ #
+
+This tutorial shows how to use the GCC C++ Compiler on MacOS to
+build the HIP CPU Runtime. It does not delve into the details of HIP, the
+C++ language, the GCC toolset or the MacOS ecosystem.
+
+If you encounter any difficulties, [please create an issue](https://github.com/ROCm-Developer-Tools/HIP-CPU/issues/new/choose)
+for this tutorial.
+
+## Prerequisites ##
+
+To successfully complete this tutorial, the following steps are necessary:
+
+1. Install [Homebrew](https://brew.sh):
+   - LLVM at the moment does not have parallel algorithm support. However,
+     it is available in GNU G++. Homebrew provides a straightforward package
+	 manager for MacOS, which allows both the GNU G++ compiler, and Intel
+	 TBB on which HIP-CPU depends. One can also consider other package managers
+	 such as MacPorts, but we will focus on Homebrew here.
+
+   - go to [The Homebrew Site](https://brew.sh) and follow the installation 
+     instructions there:
+	 ```bash
+	 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+	 ```
+	 You may or may not get messages about needing to install the XCode command line
+	 utilities if these are not yet installed. Follow the appropriate installation
+	 instructions on the Homebrew site.
+
+2. Install [GNU G++][(https://gcc.gnu.org)
+	 - Using Homebrew:
+	   ```bash
+	   brew install gcc@10
+	   ```
+   - to avoid confusion with the system GCC (which is actually Clang), homebrew will name the
+     executables as gcc-10 and g++-10
+
+3. Install [Intel TBB](https://github.com/oneapi-src/oneTBB):
+   - At this time this is a pre-requisite for HIP-CPU(makefiles depend on it)
+     as it used to be a prerequisite for parallel algorithms for G++ on Linux.
+	 Under MacOS, with the Homebrew installation, I successfully compiled a simple
+	 parallel C++-17 parallel algorithm test from [here](https://solarianprogrammer.com/2019/05/09/cpp-17-stl-parallel-algorithms-gcc-intel-tbb-linux-macos/)
+	 without TBB. However it is very easy to install using Homebrew:
+	 ```bash
+	 brew install tbb
+	 ```
+
+2. Install latest CMake
+   - Homebrew makes this super easy also:
+     ```bash
+     brew install cmake
+     ```
+
+   - Alternatively, [download and execute the installer](https://cmake.org/download/).
+3. Install Git
+   - This can be done from Homebrew:
+     ```bash
+     brew install git
+	 ```
+   - alternatively a Git client can be installed from [The Git Website](https://git-scm.com)`
+
+Ensure that `/usr/local/bin` is on your PATH -- this is where Homebrew installs all its tools.
+
+## Ensure GCC is Installed ##
+
+To verify whether GCC is installed and of a sufficiently recent version, open a
+Terminal window and enter the following command:
+
+```bash
+gcc-10 -v
+```
+
+## Clone and build the HIP CPU Runtime ##
+
+```bash
+git clone https://github.com/ROCm-Developer-Tools/HIP-CPU.git
+cd HIP-CPU
+mkdir build
+cd build
+cmake -DCMAKE_CXX_COMPILER=g++-10 ,,/
+cmake --build ./
+```
+
+If you want to later install the HIP CPU Runtime in non standard folder you can
+specify the install location to the `cmake` command 
+
+```bash
+cmake -DCMAKE_CXX_COMPILER=g++-10 -DCMAKE_INSTALL_PREFIX=<location to install the runtime> 
+```
+
+## **OPTIONAL** Install the HIP CPU Runtime ##
+
+```bash
+# Assumes that you are in the build folder created in the build step.
+cmake --build ./ --target install
+```
+
+## Verify the build by running the unit tests ##
+
+```bash
+# Assumes that you are in the build folder created in the build step.
+ctest --output-on-failure
+```
+
+## Use the HIP CPU Runtime in your code ##
+
+To use any of the HIP public interfaces include the `hip/hip_runtime.h` header.
+
+- If you are working with CMake, link against the convenience `INTERFACE` target
+  `hip_cpu_rt::hip_cpu_rt`, which is exported by the HIP CPU Runtime, which can
+  be queried by `find_package(hip_cpu_rt)`;
+- If you are not working with CMake, add either
+  `/path_where_you_cloned_the_hip_cpu_runtime/include` or, if you installed it,
+  `/path_where_you_installed_the_hip_cpu_runtime/include` to your include path.