Updated QirRuntime/README.md, build/test instructions

README.md

@@ -57,6 +57,28 @@ To build on other platforms:
 1. Install the pre-reqs:
     * Install [CMake](https://cmake.org/install/)
     * Install [.NET Core 3 SDK](https://dotnet.microsoft.com/download)
+    * On [WSL](https://docs.microsoft.com/en-us/windows/wsl/)/Linux:
+      * Install `g++` (e.g. in Ubuntu 20.04 `sudo apt-get install g++`).
+      * The build does not accept `dotnet-*-5.0` packages, install `dotnet-*-3.1`
+        (`sudo apt-get install dotnet-sdk-3.1`). The possible result can be:
+
+```sh
+qsharp-runtime$ dpkg -l *dotnet*
+Desired=Unknown/Install/Remove/Purge/Hold
+| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
+|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
+||/ Name                      Version      Architecture Description
++++-=========================-============-============-=================================================================
+un  dotnet                    <none>       <none>       (no description available)
+ii  dotnet-apphost-pack-3.1   3.1.13-1     amd64        Microsoft.NETCore.App.Host 3.1.13
+ii  dotnet-host               5.0.4-1      amd64        Microsoft .NET Host - 5.0.4
+ii  dotnet-hostfxr-3.1        3.1.13-1     amd64        Microsoft .NET Core Host FX Resolver - 3.1.13 3.1.13
+un  dotnet-nightly            <none>       <none>       (no description available)
+ii  dotnet-runtime-3.1        3.1.13-1     amd64        Microsoft .NET Core Runtime - 3.1.13 Microsoft.NETCore.App 3.1.13
+ii  dotnet-runtime-deps-3.1   3.1.13-1     amd64        dotnet-runtime-deps-3.1 3.1.13
+ii  dotnet-sdk-3.1            3.1.407-1    amd64        Microsoft .NET Core SDK 3.1.407
+ii  dotnet-targeting-pack-3.1 3.1.0-1      amd64        Microsoft.NETCore.App.Ref 3.1.0
+```
 2. Run [bootstrap.ps1](./bootstrap.ps1)
     * The script might install additional tools (a specific compiler, build tools, etc)
     * Then it builds release flavor of the native (C++) full-state simulator and debug flavor of the Simulation solution.

src/QirRuntime/README.md

@@ -1,8 +1,9 @@
 # The Native QIR Runtime
 
-This folder contains QIR runtime project, which includes implementation of the
+This folder contains the Quantum Intermediate Representation (QIR) Runtime project. The QIR is a subset of the [LLVM](https://llvm.org/) Intermediate Representation.
+The QIR runtime includes an implementation of the
  [QIR specification](https://github.com/microsoft/qsharp-language/tree/main/Specifications/QIR) and the bridge to
- compile QIR to be run against the native full state simulator.
+ run QIR against the native full state simulator.
 
 - `public` folder contains the public headers
 - `lib` folder contains the implementation of the runtime and the simulators.
@@ -11,24 +12,19 @@ This folder contains QIR runtime project, which includes implementation of the
 
 ## Build
 
-The QirRuntime project is using CMake (3.17) + Ninja(1.10.0) + Clang++(11.0.0). Other versions of the tools might work
- but haven't been tested. Only x64 architecture is supported.
-
-You can use CMake directly. For example, to produce a release build:
-
-1. navigate into QirRuntime folder
-2. mkdir build
-3. cd build
-4. cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
-5. cmake --build .
-
-Or you can run `build-qir-runtime.ps1` script from QirRuntime folder. The script will place the build artifacts into `build/[Debug|Release]` folder. We strongly recommend doing local builds using the build script because it also runs clang-tidy if it is installed.
+### Prerequisites
 
-CI builds and tests are enabled for this project. The build for `test/QIR-static/qsharp/qir-gen.csproj` has project dependencies on other parts of the runtime and may trigger a build for those components, while some of the tests depend on `Microsoft.Quantum.Simulator.Runtime` dynamic library built from.
+The QirRuntime project is using CMake (3.17) + Ninja(1.10.0) + Clang++(11.0.0). Other versions of the tools might work
+ but haven't been tested. Only x64 architecture is supported.  
+For running the PowerShell scripts below use 
+[PowerShell Core or PowerShell 7+ (`pwsh`)](https://github.com/PowerShell/PowerShell), not the inbox PowerShell.
 
-To install prerequisite tools for building the QIR runtime, you can set the `ENABLE_QIRRUNTIME` environment variable to the string `"true"` and run `prerequisites.ps1` or manually install pre-reqs with the steps listed below (Windows script relies on [Chocolatey](https://chocolatey.org/) for installation).
+To install prerequisite tools for building the QIR runtime, you can set the `ENABLE_QIRRUNTIME` environment variable to the string `"true"` 
+and run [`prerequisites.ps1`](prerequisites.ps1), or manually install pre-reqs with the steps listed below.
+Note that on Windows, this script relies on the [Chocolatey package manager](https://chocolatey.org/),
+while on macOS, `prerequisites.ps1` relies on the [`brew` package manager](https://brew.sh).
 
-### Windows pre-reqs
+#### Windows pre-reqs
 
 1. Install Clang 11, Ninja and CMake from the public distros.
 1. Add all three to your/system `%PATH%`.
@@ -39,7 +35,7 @@ To install prerequisite tools for building the QIR runtime, you can set the `ENA
 *Building from Visual Studio and VS Code is **not** supported.
 Running cmake from the editors will likely default to MSVC or clang-cl and fail.*
 
-### Linux via WSL pre-reqs
+#### Linux via WSL pre-reqs
 
 1. On the host Windows machine [enable WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) and install
  Ubuntu 20.04 LTS.
@@ -55,35 +51,35 @@ Running cmake from the editors will likely default to MSVC or clang-cl and fail.
 
 See [https://code.visualstudio.com/docs/remote/wsl] on how to use VS Code with WSL.
 
-## Test
+#### Other Prerequisites
 
-Some of the tests depend on Microsoft.Quantum.Simulator.Runtime library. To run them make sure to build Native simulator
- from this repository or provide your own version of the library in a folder the OS would search during dynamic library
- lookup.
+The build depends on `Microsoft.Quantum.Simulator.Runtime` dynamic library built at a higher level of the directory tree.
+To build that library follow the instructions in [`qsharp-runtime/README.md`](../../README.md#building-from-source)
+(up to and including the step `Simulation.sln`).
 
-Some of the tests use generated QIR (*.ll) files as build input. Currently the files are checked-in as part of the project
- but in the future they will be replaced by automatic generation during build. To regenerate the files, run generateqir.py
- or build/test scripts without specifying `noqirgen`. To use the checked-in files without regenerating them, run build/test
- scripts with `noqirgen` argument.
 
-### Running tests with test.py
+### Build Commands
 
-To execute all tests locally run `test.py` from the project's root folder:
+To build QirRuntime you can run [`build-qir-runtime.ps1`](build-qir-runtime.ps1) script from QirRuntime folder:
+```batch
+pwsh build-qir-runtime.ps1
+```
+
+The script will create the `build/{Debug|Release}` folder and place the build artifacts in it. The configuration `Debug|Release`
+is specified with the `BUILD_CONFIGURATION` environment variable.
+If the variable is not set then the default is specified in [`set-env.ps1`](../../build/set-env.ps1).  
 
-- (Windows) `python test.py [nobuild] [debug/release]`
-- (Linux) `python3 test.py [nobuild] [debug/release]`
+## Tests
 
-The script will trigger an incremental build unless `nobuild` options is specified. Tests from the "[skip]" category
- won't be run.
+### Running All Tests
 
-### Running tests with CTest
+```powershell
+# Navigate to QirRuntime folder.
 
-All native tests, including QIR, use catch2 and are fully integrated with CTest. Navigate into
- `build/[Windows|Linux]/[Debug|Release]` folder and run `ctest`. No configuration options required. The results will be
- logged into the corresponding `build/[Windows|Linux]/[Debug|Release]/<target_path>/<test_binary_name>_results.xml` file.
- Tests from the "[skip]" category won't be run.
+pwsh test-qir-runtime.ps1
+```
 
-### Running test binaries individually
+### Running Test Binaries Individually
 
 `<test_binary> -help` provides details on how to run a subset of the tests and other options. For example, you can
  filter tests from the "[skip]" category out by `<test_binary> ~[skip]`.