From fbd93cbc0316074eaa5c16a54a2eff65b3e8cfc8 Mon Sep 17 00:00:00 2001
From: "B. Gibbons" <38017514+bmg817@users.noreply.github.com>
Date: Thu, 23 Feb 2023 13:08:45 -0800
Subject: [PATCH] docs: update readme installation guide (#792)

1. Added information about Homebrew installation (based off this
information [here](https://formulae.brew.sh/formula/luau#default))
2. Added details related to installing binary files that are downloaded
3. Rearranged and added titles for easier reading

Fixes #791.

Co-authored-by: Arseny Kapoulkine <arseny.kapoulkine@gmail.com>
---
 README.md | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 2b44c89a..a0ce6f76 100644
--- a/README.md
+++ b/README.md
@@ -17,12 +17,21 @@ Luau is an embeddable language, but it also comes with two command-line tools by
 
 `luau-analyze` is a command-line type checker and linter; given a set of input files, it produces errors/warnings according to the file configuration, which can be customized by using `--!` comments in the files or [`.luaurc`](https://github.com/Roblox/luau/blob/master/rfcs/config-luaurc.md) files. For details please refer to [type checking]( https://luau-lang.org/typecheck) and [linting](https://luau-lang.org/lint) documentation.
 
-You can download the binaries from [a recent release](https://github.com/Roblox/luau/releases).
+# Installation
 
+You can install and run Luau by downloading the compiled binaries from [a recent release](https://github.com/Roblox/luau/releases); note that `luau` and `luau-analyze` binaries from the archives will need to be added to PATH or copied to a directory like `/usr/local/bin` on Linux/macOS.
 
-# Building
+Alternatively, you can use one of the packaged distributions (note that these are not maintained by Luau development team):
 
-To build Luau tools or tests yourself, you can use CMake on all platforms:
+- macOS: [Install Homebrew](https://docs.brew.sh/Installation) and run `brew install luau`
+- Arch Linux: Run `pacman -S luau`
+- Alpine Linux: [Enable community repositories](https://wiki.alpinelinux.org/w/index.php?title=Enable_Community_Repository) and run `apk add luau`
+
+After installing, you will want to validate the installation was successful by running the test case [here](https://luau-lang.org/getting-started).
+
+## Building
+
+On all platforms, you can use CMake to run the following commands to build Luau binaries from source:
 
 ```sh
 mkdir cmake && cd cmake
@@ -31,13 +40,13 @@ cmake --build . --target Luau.Repl.CLI --config RelWithDebInfo
 cmake --build . --target Luau.Analyze.CLI --config RelWithDebInfo
 ```
 
-Alternatively, on Linux/macOS you can use make:
+Alternatively, on Linux/macOS you can use `make`:
 
 ```sh
 make config=release luau luau-analyze
 ```
 
-To integrate Luau into your CMake application projects, at the minimum you'll need to depend on `Luau.Compiler` and `Luau.VM` projects. From there you need to create a new Luau state (using Lua 5.x API such as `lua_newstate`), compile source to bytecode and load it into the VM like this:
+To integrate Luau into your CMake application projects as a library, at the minimum you'll need to depend on `Luau.Compiler` and `Luau.VM` projects. From there you need to create a new Luau state (using Lua 5.x API such as `lua_newstate`), compile source to bytecode and load it into the VM like this:
 
 ```cpp
 // needs lua.h and luacode.h