Readme.md

@@ -1,71 +1,116 @@
 ------
-**DISCLAIMER: This project is very much a Work In Progress. We're making it accessible in this very early state so that participants to the [Wheel Reinvention Jam 2023](https://handmade.network/jam/2023) can try it out and maybe use it as their jamming platform. Expect bugs, missing and/or incomplete features, unstable APIs, and sparse documentation. Some current issues might be a show stopper for you, so make sure you can build and run the sample apps before jumping in.**
+**DISCLAIMER: This project is very much a Work In Progress. We are making it accessible in this very early state so that participants in the [2023 Wheel Reinvention Jam](https://handmade.network/jam/2023) can try it out and possibly use it as their jamming platform. Expect bugs, missing and/or incomplete features, unstable APIs, and sparse documentation. Some current issues might be a show stopper for you, so make sure you can build and run the sample apps before jumping in.**
 
-**If you do choose to try out Orca anyway, well thanks! We'll do our best to answer your questions, and we'd really appreciate to hear your feedback!**
+**If you do choose to try out Orca anyway, thank you! We'll do our best to answer your questions, and we'd really appreciate your feedback!**
 
 ------
 
 # Orca
----
 
-Orca is a devlopment platform and runtime environment for cross-platform, sandboxed graphical WebAssembly applications. In this early MVP you can:
+Orca is a development platform and runtime environment for cross-platform, sandboxed graphical WebAssembly applications. In this early MVP you can:
 
-- Receive mouse and keyboard input
+- Receive mouse and keyboard input.
 - Draw paths, images and text using a 2D vector graphics API.
 - Draw 2D/3D graphics using OpenGL ES 3.1 (minus a few features)
 - Build user interfaces using our UI API and default widgets.
-- Read and write files using a capability based API. 
+- Read and write files using a capability-based API.
 
 ## Installing
 
-_//TODO: Ben can you complete this section?_
+The Orca command-line tools must be installed to your system in order to use them in your own projects.
 
-Clone the repo: `git clone git@git.handmade.network:hmn/orca.git`.
+**At this early stage, you must build Orca yourself - in the future, this installation process will be streamlined.**
 
-Cd to the orca directory and build the Orca runtime:
+### Requirements
+
+- Windows or Mac (Linux is not yet supported)
+- [Python 3](https://www.python.org/) (for command line tools)
+- Clang
+	- **Windows users:** `clang` can be installed via the Visual Studio installer. Search for "C++ Clang Compiler".
+	- **Mac users:** Apple's built-in `clang` does not support WebAssembly. We recommend installing `clang` via [Homebrew](https://brew.sh/) with `brew install clang`.
+- MSVC (Visual Studio 2022 17.5 or newer) (Windows only)
+	- This can be installed through the [Visual Studio Community](https://visualstudio.microsoft.com/) installer.
+	- Please note the version requirement! Orca requires C11 atomics, which were only added to MSVC in late 2022.
+
+### Installation instructions
+
+Clone the repo, then `cd` into the `orca` directory:
 
 ```
+git clone git@git.handmade.network:hmn/orca.git
 cd orca
+```
+
+Build the Orca runtime:
+
+```
 ./orca dev build-runtime
 ```
 
-Install the orca dev tools:
+Install the Orca dev tools. If on Windows, the tool can automatically add `orca` to your PATH. Otherwise, you must manually add the Orca install directory to your PATH, e.g. by updating `.zshrc` or `.bashrc`.
 
 ```
 ./orca dev install
 ```
 
-### Building the sample Orca apps
-
-Cd to the sample project directory and run its build script:
+Finally, verify that Orca is successfully installed by running the `orca version` command. Note the lack of `./`!
 
 ```
-cd samples/pong
+orca version
+```
+
+If you encounter any errors, see the FAQ below.
+
+Once the `orca` tools are installed, you can use them from anywhere to
+
+### Building the sample Orca apps
+
+The `samples` directory contains several sample apps that demonstrate various Orca features. To build one, `cd` to a sample project's directory and run its build script. For example, for the `breakout` sample:
+
+```
+cd samples/breakout
+# Windows
+build.bat
+# Mac
 ./build.sh
 ```
 
-On macOS this creates a `Pong.app` bundle in `samples/pong` that you can double click to run. On Windows this creates a `Pong` directory in `samples/pong`. You can launch the app by running `Pong/bin/Pong.exe`.
+On Windows this creates a `Breakout` directory in `samples/breakout`. You can launch the app by running `Breakout/bin/Breakout.exe`. On macOS this creates a `Breakout.app` bundle in `samples/breakout` that you can double-click to run.
 
 ## Writing an Orca app
 
-The following documents can help you write an application using the Orca APIs:
+Orca apps are WebAssembly modules that use the Orca APIs. The process for creating an Orca application is:
+
+1. Compile a WebAssembly module using your language and toolchain of choice.
+2. Bundle the WebAssembly module into a native executable using the Orca command-line tools.
+
+For a more thorough overview, please read the [Quick Start Guide](./doc/QuickStart.md), which will walk you through building a simple application.
+
+The following additional resources may also help you familiarize yourself with Orca and its APIs:
 
-- The [Quick Start Guide](./doc/QuickStart.md) will walk you through writing and building a simple example application.
 - The [samples folder](./samples) contains sample applications that show various aspects of the Orca API and support library:
-	- [clock](./samples/clock) is a simple clock showcasing vector graphics and the time API. 
-	- [breakout](./samples/breakout) is a mini breakout game making use of the vector graphics API.
-	- 	[triangle](./samples/triangle) shows how to draw a spining triangle using the GLES API.
-	-  [fluid](./samples/fluid) is a fluid simulation using a more complex GLES setup.
-	-  [ui](./samples/ui) showcases the UI API and Orca's default UI widgets.  
+	- [`breakout`](./samples/breakout) is a small breakout game making use of the vector graphics API.
+	- [`clock`](./samples/clock) is a simple clock showcasing vector graphics and the time API.
+	- [`triangle`](./samples/triangle) shows how to draw a spinning triangle using the GLES API.
+	- [`fluid`](./samples/fluid) is a fluid simulation using a more complex GLES setup.
+	- [`ui`](./samples/ui) showcases the UI API and Orca's default UI widgets.  
 - The [API Cheatsheets](./doc/cheatsheets) provide a list of Orca API functions, grouped by topic.
 
-## Building and bundling an Orca app
+## FAQ
 
-_//TODO: Ben, can you complete this section? Or should that be in the QuickStart guide?_
+**What languages can I use with Orca?**
 
-You must compile your application along with the Orca support code, into a WebAssembly module. The command `orca src cflags` can help you set up your compiler's flags to do so.
+In principle, you can use any language and toolchain that can produce an Orca-compatible WebAssembly module. However, several important parts of Orca, such as the UI, are provided as part of the support library, which is written in C. Therefore, at this early stage, it may be difficult to use any language other than C.
 
-Once you have built your WebAssembly module, you can invoke the command `orca bundle` to bundle it with your apps resources and the Orca runtime to produce an application.
+We look forward to expanding the number of officially-supported languages in the future.
+
+**I am getting errors about atomics when building the runtime on Windows.**
+
+Please ensure that you have the latest version of Visual Studio and MSVC installed. The Orca runtime requires the use of C11 atomics, which were not added to MSVC until late 2022.
+
+**I am getting errors saying that `orca` is not found.**
+
+Please ensure that you have installed Orca to your system per the installation instructions above. Please also ensure that the Orca install directory is on your PATH. The installation path is printed when running `./orca dev install`.
 
 ## License
 
@@ -75,4 +120,3 @@ Orca is distributed under the terms of the GNU Affero General Public License ver
 - You can distribute your application's WebAssembly modules under the terms of your choice, and are not required to license them under the terms of the AGPLv3.
 
 Copyright and License details can be found in [LICENSE.txt](./LICENSE.txt)
-