Clarify the download and install processes

Only mention downloading (of pre-built releases) on the entry README,
and move the "build from source" documentation to its own file, with
additional clarification about the result of the build (the 'inst'
directory) and how to install it.  Add some of this clarification to
the Makefile as well.  And install a README into the 'inst' release,
clarifying how to use the directory.

5 files changed, 357 insertions, 215 deletions

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index bf6ae250..145637d9 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -57,14 +57,14 @@ jobs:
         run: |
           ccache --zero-stats --max-size 250M
           export PATH=/usr/lib/ccache:$PATH
-          make -j3 GHCJOBS=2 GHCRTSFLAGS='+RTS -M5G -A128m -RTS'
+          make -j3 GHCJOBS=2 GHCRTSFLAGS='+RTS -M5G -A128m -RTS' install-src
           tar czf inst.tar.gz inst
       - name: CCache stats
         env:
           CCACHE_DIR: ${{ GITHUB.WORKSPACE }}/ccache
         run: ccache --show-stats
       - name: Smoketest
-        run: "make check"
+        run: "make check-smoke"
       # Check that .ghci has all the right flags to load the source.
       # This is important for text editor integration & tools like ghcid
       # NB stp, yices and htcl must be built first, so do this after Build.
@@ -133,14 +133,14 @@ jobs:
           # binary.
           rm -f /usr/local/include/tcl.h
 
-          make -j3 GHCJOBS=2 GHCRTSFLAGS='+RTS -M4500M -A128m -RTS' MACOSX_DEPLOYMENT_TARGET=10.13
+          make -j3 GHCJOBS=2 GHCRTSFLAGS='+RTS -M4500M -A128m -RTS' MACOSX_DEPLOYMENT_TARGET=10.13 install-src
           tar czf inst.tar.gz inst
       - name: CCache stats
         env:
           CCACHE_DIR: ${{ GITHUB.WORKSPACE }}/ccache
         run: ccache --show-stats
       - name: Smoketest
-        run: "make check"
+        run: "make check-smoke"
       # Check that .ghci has all the right flags to load the source.
       # This is important for text editor integration & tools like ghcid
       # NB stp, yices and htcl must be built first, so do this after Build.
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 00000000..b6956ed7
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,242 @@
+# Compiling BSC from source
+
+Source code for the Bluespec toolchain can currently be built on Linux
+and MacOS. It may compile for other flavors of Unix, but likely will need
+additional if/else blocks in source code or Makefiles.
+
+The core of BSC is written in Haskell, with some libraries in C/C++.
+
+---
+
+## Overview
+
+The following sections describe the requirements and commands for building
+BSC.  Running the build commands will result in the creation of a directory
+(named 'inst' by default) that contains an _installation_ of BSC.  This
+directory can be moved to anywhere on your system, but it is best for the
+files to remain in their relative positions within the directory.
+
+We recommend renaming the `inst` directory to `bsc-<VERSION>` and placing
+it in a subdirectory of `/opt/`, `${HOME}/`, `/usr/share/`, or similar
+location.  For example:
+
+    $ mkdir -p /opt/tools/bsc
+    $ mv inst /opt/tools/bsc/bsc-4.0.0
+    $ cd /opt/tools/bsc
+    $ ln -s bsc-4.0.0 latest
+
+The 'inst' directory has a 'bin' subdirectory, where the executables
+for the tools are found.  To use the tools, just add that directory to
+your `PATH`:
+
+    $ export PATH=/opt/tools/bsc/latest/bin:$PATH
+
+These executables will make use of other files found within the `inst`
+directory, locating them relatively from the `bin` directory.  That is
+why the directory must be kept together.
+
+If you are packaging BSC for an OS (for example, into a `.deb` or `.rpm`
+file), your package can't simply move the `bin` files to `/usr/bin/`
+and the `lib` files to `/usr/lib/` and so on.  We recommend placing the
+`inst` directory at `/usr/share/bsc/bsc-<VERSION>` and then creating
+symlinks in `/usr/bin/` that point to the executables in
+`/usr/share/bsc/bsc-<VERSION>/bin/`.
+
+---
+
+## Install the Haskell compiler (GHC)
+
+You will need the standard Haskell compiler `ghc` which is available for Linux,
+macOS and Windows, along with some additional Haskell libraries. These are
+available as standard packages in most Linux distributions. For example, on
+Debian and Ubuntu systems, you can say:
+
+    $ apt-get install ghc
+    $ apt-get install \
+        libghc-regex-compat-dev \
+        libghc-syb-dev \
+        libghc-old-time-dev \
+        libghc-split-dev
+
+The second command will install the Haskell libraries `regex-compat`, `syb`,
+`old-time`, and `split`, as well as some libraries that they depend on.
+
+If you wish to do profiling builds of the compiler itself, you will also need
+to install versions of the Haskell libraries built using the profiling flags.
+On Debian and Ubuntu, this can be done with:
+
+    $ apt-get install \
+        ghc-prof \
+        libghc-regex-compat-prof \
+        libghc-syb-prof \
+        libghc-old-time-prof \
+        libghc-split-prof
+
+You can do the analogous package-install on other Linux distributions using
+their native package mechanisms, and on macOS using Homebrew or Macports. Full details
+can be found at <https://www.haskell.org/>, and in particular `ghcup` is a popular
+installer for recent Haskell releases <https://www.haskell.org/ghcup/>.
+
+On some systems, you may need to use the `cabal` command to install Haskell
+libraries.  This tool is installed by `ghcup` but is also available as a package
+for many distributions.
+If you are using cabal 3.0 or later, you will need to use the legacy `v1-`
+commands to install Haskell libraries.
+
+For cabal v2.x:
+
+    $ cabal update
+    $ cabal install regex-compat syb old-time split
+
+For cabal v3.x:
+
+    $ cabal update
+    $ cabal v1-install regex-compat syb old-time split
+
+Bluespec compiler builds are tested with GHC 7.10.1 and greater, and older
+GHC releases are not supported.
+
+Beyond that, any version up to 8.10.1 (the latest at the time of writing) will
+work, since the source code has been written with extensive preprocessor macros
+to support every minor release since.
+
+## Additional requirements
+
+For building and using the Bluespec Tcl shell (`bluetcl`),
+you will need the `tcl` library:
+
+    $ apt-get install tcl-dev
+
+Building BSC also requires standard Unix shell and Makefile utilities.
+
+The repository for [the Yices SMT Solver](https://github.com/SRI-CSL/yices2) is
+cloned as a submodule of this repository. Building the BSC tools will recurse
+into this directory and build the Yices library for linking into BSC and
+Bluetcl. Yices currently requires `autoconf` and the `gperf` perfect hashing
+library to compile:
+
+    $ apt-get install \
+        autoconf \
+        gperf
+
+Building the BSC tools will also recurse into a directory for the STP SMT
+solver. This is currently an old snapshot of the STP source code, including the
+code for various libraries that it uses. In the future, this may be replaced
+with a submodule instantiation of the repository for [the STP SMT
+solver](https://github.com/stp/stp). When that happens, additional requirements
+from that repository will be added. The current snapshot requires Perl, to
+generate two source files. It also needs flex and bison:
+
+    $ apt-get install flex bison
+
+The `check` target runs a test using an external Verilog simulator, which is
+[Icarus Verilog] by default. You can install Icarus on Debian/Ubuntu with:
+
+    $ apt-get install iverilog
+
+[Icarus Verilog]: http://iverilog.icarus.com
+
+The `install-doc` target builds PDF documentation from LaTeX source files
+that rely on a few standard style files.  The following Debian/Unbuntu
+packages install sufficient tools to build the documentation:
+
+    $ apt-get install \
+        texlive-latex-base \
+        texlive-latex-recommended \
+        texlive-latex-extra \
+        texlive-font-utils \
+        texlive-fonts-extra
+
+## Clone the repository
+
+Clone this repository by running:
+
+    $ git clone --recursive https://github.com/B-Lang-org/bsc
+
+That will clone this repository and all of the submodules that it depends on.
+If you have cloned the repository without the `--recursive` flag, you can setup
+the submodules later with a separate command:
+
+    $ git clone https://github.com/B-Lang-org/bsc
+    $ git submodule update --init --recursive
+
+## Build and test the toolchain
+
+At the root of the repository:
+
+    $ make install
+    $ make check
+
+This will create a directory called `inst` containing an installation of the
+compiler toolchain. It will then run a smoke test to ensure the compiler and
+simulator work properly. This `inst` directory can later be moved to another
+location; the tools do not hard-code the install location.
+
+If you wish, you can install into another location by assigning the variable
+`PREFIX` in the environment:
+
+    $ make PREFIX=/opt/tools/bsc/bsc-<VERSION>
+
+However, note that the `clean` target will delete the `PREFIX` directory!
+
+An unoptimized, debug, or profiling build can be done using one of:
+
+    $ make BSC_BUILD=NOOPT
+    $ make BSC_BUILD=DEBUG
+    $ make BSC_BUILD=PROF
+
+For more extensive testing, see the [testsuite README](testsuite/README.md)
+in the `testsuite` subdirectory.
+
+### Choosing a Verilog simulator
+
+The Makefile in `examples/smoke_test` shows how you can point the default
+`check` target at other Verilog simulators such as VCS and VCSI (Synopys),
+NC-Verilog & NCsim (Cadence), ModelSim (Mentor), and CVC.
+
+Many people also use [Verilator][] to compile and simulate `bsc`-generated
+Verilog -- but you must write your own C++ harness for your design in order to
+use it.
+
+[Verilator]: https://www.veripool.org/wiki/verilator
+
+## Build documentation
+
+To build and install the PDF documentation, you can add the following:
+
+    $ make install-doc
+
+This will install into the same `inst` or `PREFIX` directory.
+The installed documents include the BSC User Guide and the BSC Libraries
+Reference Guide.
+
+---
+
+## Using the Bluespec compiler
+
+The installation contains a `bin` directory. To run the BSC tools, you only
+need to add the `bin` directory to your path (or provide that path on the
+command line). The executables in that directory will expect to find other
+files in sibling directories within that same parent installation directory. If
+you just built the compiler, you can quickly test it like so:
+
+    $ export PATH=$(pwd)/inst/bin:$PATH
+
+> **NOTE**: Earlier versions of BSC required that the environment variable
+> `BLUESPECDIR` be set to point into the installation directory; this is no
+> longer necessary, as the executables will figure out their location and
+> determine the installation location on their own.
+
+Run the following to see command-line options on the executable:
+
+    $ bsc -help
+
+Additional flags of use to developers can be displayed with the
+following command:
+
+    $ bsc -help-hidden
+
+More details on using BSC, Bluesim, and Bluetcl can be found in the User Guide
+(built in this repository).
+Language documentation, training, and tutorials can be found in the
+[BSVlang repository](https://github.com/BSVLang/Main).
diff --git a/Makefile b/Makefile
index 69402a9d..d6e01e9d 100644
--- a/Makefile
+++ b/Makefile
@@ -4,8 +4,25 @@ TOP := $(PWD)
 PREFIX   ?= $(TOP)/inst
 BUILDDIR ?= $(TOP)/build
 
-.PHONY: all
-all: install
+.PHONY: help
+help:
+	@echo 'This Makefile will create an installation of the Bluespec Compiler tools,'
+	@echo 'in a directory named "inst".  This directory can be moved anywhere, but'
+	@echo 'the contents should remain in the same relative locations.  Intermediate'
+	@echo 'files are stored in a directory named "build".  The "clean" target will'
+	@echo 'delete the "build" directory; the "full_clean" target will delete both'
+	@echo 'the "build" and "inst" directories.'
+	@echo
+	@echo '    make  release      Build a release dir with the tools and docs'
+	@echo
+	@echo '    make  install-src  Build and install just the tools'
+	@echo '    make  install-doc  Build and install just the documentation'
+	@echo
+	@echo '    make  check-smoke  Run a quick smoke test'
+	@echo '    make  check-suite  Run the test suite (this will take time!)'
+	@echo
+	@echo '    make  clean        Remove intermediate build-files unnecessary for execution'
+	@echo '    make  full_clean   Restore to pristine state (pre-building anything)'
 
 # -------------------------
 
@@ -19,27 +36,38 @@ rem_build:
 
 # -------------------------
 
-.PHONY: install
-install:
+.PHONY: install-src
+install-src:
 	$(MAKE)  -C src  PREFIX=$(PREFIX)  install
 
 .PHONY: install-doc
 install-doc:
 	$(MAKE)  -C doc  PREFIX=$(PREFIX)  install
 
-# In the future, this will be much more expansive, and run the actual test
-# suite once it's open sourced.
-#
+.PHONY: install-README
+	cp release/tarball-README $(PREFIX)/README
+
+# -------------------------
+
+.PHONY: release
+release: install-src install-doc install-README
+
+# -------------------------
+
 # NOTE: We have to do things in a subshell and set PATH there, because the
 # generated bluesim .exe is a shell script that expects 'bluetcl' to be located
 # in $PATH. it's not enough to just set bsc...
-.PHONY: check
-check:
+.PHONY: check-smoke
+check-smoke:
 	@(export PATH=$(PREFIX)/bin:$(PATH); $(MAKE) -C examples/smoke_test smoke_test)
 
+.PHONY: check-suite
+check-suite:
+	$(MAKE) -C testsuite
+
 # -------------------------
 
-clean: rem_inst rem_build
+clean: rem_build
 	-$(MAKE)  -C src  clean
 	-$(MAKE)  -C doc  clean
 
diff --git a/README.md b/README.md
index ec93c26e..46580590 100644
--- a/README.md
+++ b/README.md
@@ -2,20 +2,19 @@
 
 # Bluespec Compiler
 
-![Version] [![Build Status]](https://github.com/b-lang-org/bsc/actions?query=workflow%3ACI+event%3Apush)
+![Version] [![License]](./COPYING) [![Build Status]](https://github.com/b-lang-org/bsc/actions?query=workflow%3ACI+event%3Apush)
 
-[![Documentation]][Doc page]
-[![License]](./COPYING)
-
-[Doc page]:       https://github.com/B-Lang-org/bsc
-[Documentation]:  https://img.shields.io/badge/docs-Manual-orange.svg?logo=markdown
 [License]:        https://img.shields.io/badge/license-BSD%203-blueviolet.svg
 [Version]:        https://img.shields.io/badge/release-2020.02,%20"Open%20Source%20Release"-red.svg?logo=v
 [Build Status]:   https://github.com/b-lang-org/bsc/workflows/CI/badge.svg?branch=main&event=push
 
-<strong>
-  <a href="https://github.com/B-Lang-org/bsc">Homepage</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;<a href="https://github.com/B-Lang-org/bsc">Get Started</a>
-</strong>
+**[Community] &bull; [Download] &bull; [Documentation] &bull; [Build] &bull; [Test]**
+
+[Community]: #community
+[Download]: #download
+[Documentation]: #documentation
+[Build]: ./INSTALL.md
+[TEST]: ./testsuite/README.md
 
 ---
 
@@ -87,209 +86,36 @@ Feel free to give it a try and see if it can be useful to our community.
 
 ---
 
-## Compiling BSC from source
-
-Binaries for the Bluespec toolchain are currently unavailable, so you must
-build them from source code. The source code can currently be built on Linux
-and MacOS. It may compile for other flavors of Unix, but likely will need
-additional if/else blocks in source code or Makefiles.
-
-The core of BSC is written in Haskell, with some libraries in C/C++.
-
-### Install the Haskell compiler (GHC)
-
-You will need the standard Haskell compiler `ghc` which is available for Linux,
-macOS and Windows, along with some additional Haskell libraries. These are
-available as standard packages in most Linux distributions. For example, on
-Debian and Ubuntu systems, you can say:
-
-    $ apt-get install ghc
-    $ apt-get install \
-        libghc-regex-compat-dev \
-        libghc-syb-dev \
-        libghc-old-time-dev \
-        libghc-split-dev
-
-The second command will install the Haskell libraries `regex-compat`, `syb`,
-`old-time`, and `split`, as well as some libraries that they depend on.
-
-If you wish to do profiling builds of the compiler itself, you will also need
-to install versions of the Haskell libraries built using the profiling flags.
-On Debian and Ubuntu, this can be done with:
-
-    $ apt-get install \
-        ghc-prof \
-        libghc-regex-compat-prof \
-        libghc-syb-prof \
-        libghc-old-time-prof \
-        libghc-split-prof
-
-You can do the analogous package-install on other Linux distributions using
-their native package mechanisms, and on macOS using Homebrew or Macports. Full details
-can be found at <https://www.haskell.org/>, and in particular `ghcup` is a popular
-installer for recent Haskell releases <https://www.haskell.org/ghcup/>.
-
-On some systems, you may need to use the `cabal` command to install Haskell
-libraries.  This tool is installed by `ghcup` but is also available as a package
-for many distributions.
-If you are using cabal 3.0 or later, you will need to use the legacy `v1-`
-commands to install Haskell libraries.
-
-For cabal v2.x:
-
-    $ cabal update
-    $ cabal install regex-compat syb old-time split
-
-For cabal v3.x:
-
-    $ cabal update
-    $ cabal v1-install regex-compat syb old-time split
-
-
-Bluespec compiler builds are tested with GHC 7.10.1 and greater, and older
-GHC releases are not supported.
-
-Beyond that, any version up to 8.10.1 (the latest at the time of writing) will
-work, since the source code has been written with extensive preprocessor macros
-to support every minor release since.
-
-### Additional requirements
-
-For building and using the Bluespec Tcl shell (`bluetcl`),
-you will need the `tcl` library:
-
-    $ apt-get install tcl-dev
-
-Building BSC also requires standard Unix shell and Makefile utilities.
-
-The repository for [the Yices SMT Solver](https://github.com/SRI-CSL/yices2) is
-cloned as a submodule of this repository. Building the BSC tools will recurse
-into this directory and build the Yices library for linking into BSC and
-Bluetcl. Yices currently requires `autoconf` and the `gperf` perfect hashing
-library to compile:
-
-    $ apt-get install \
-        autoconf \
-        gperf
-
-Building the BSC tools will also recurse into a directory for the STP SMT
-solver. This is currently an old snapshot of the STP source code, including the
-code for various libraries that it uses. In the future, this may be replaced
-with a submodule instantiation of the repository for [the STP SMT
-solver](https://github.com/stp/stp). When that happens, additional requirements
-from that repository will be added. The current snapshot requires Perl, to
-generate two source files. It also needs flex and bison:
-
-    $ apt-get install flex bison
+## Download
 
-The `check` target runs a test using an external Verilog simulator, which is
-[Icarus Verilog] by default. You can install Icarus on Debian/Ubuntu with:
+For the following systems, the Bluespec toolchain is available
+as a package that can be installed with the standard package manager:
 
-    $ apt-get install iverilog
+* Nix/NixOS: [`bluespec`](https://search.nixos.org/packages?channel=20.09&from=0&size=50&sort=relevance&query=bluespec)
 
-[Icarus Verilog]: http://iverilog.icarus.com
+If a package exists for your system, we recommend installing that.
+Otherwise, a tar-archive may be available for download from our
+[Releases](https://github.com/B-Lang-org/bsc/releases) page.
+Install instructions can be found inside the tar-file.
 
-The `install-doc` target builds PDF documentation from LaTeX source files
-that rely on a few standard style files.  The following Debian/Unbuntu
-packages install sufficient tools to build the documentation:
-
-    $ apt-get install \
-        texlive-latex-base \
-        texlive-latex-recommended \
-        texlive-latex-extra \
-        texlive-font-utils \
-        texlive-fonts-extra
-
-### Clone the repository
-
-Clone this repository by running:
-
-    $ git clone --recursive https://github.com/B-Lang-org/bsc
-
-That will clone this repository and all of the submodules that it depends on.
-If you have cloned the repository without the `--recursive` flag, you can setup
-the submodules later with a separate command:
-
-    $ git clone https://github.com/B-Lang-org/bsc
-    $ git submodule update --init --recursive
-
-### Build and test the toolchain
-
-At the root of the repository:
-
-    $ make install
-    $ make check
-
-This will create a directory called `inst` containing an installation of the
-compiler toolchain. It will then run a smoke test to ensure the compiler and
-simulator work properly. This `inst` directory can later be moved to another
-location; the tools do not hard-code the install location.
-
-If you wish, you can install into another location by assigning the variable
-`PREFIX` in the environment:
-
-    $ make PREFIX=/tools/bluespec
-
-An unoptimized, debug, or profiling build can be done using one of:
-
-    $ make BSC_BUILD=NOOPT
-    $ make BSC_BUILD=DEBUG
-    $ make BSC_BUILD=PROF
-
-For more extensive testing, see the [testsuite README](testsuite/README.md)
-in the `testsuite` subdirectory.
-
-#### Choosing a Verilog simulator
-
-The Makefile in `examples/smoke_test` shows how you can point the default
-`check` target at other Verilog simulators such as VCS and VCSI (Synopys),
-NC-Verilog & NCsim (Cadence), ModelSim (Mentor), and CVC.
-
-Many people also use [Verilator][] to compile and simulate `bsc`-generated
-Verilog -- but you must write your own C++ harness for your design in order to
-use it.
-
-[Verilator]: https://www.veripool.org/wiki/verilator
-
-### Build documentation
-
-To build and install the PDF documentation, you can add the following:
-
-    $ make install-doc
-
-This will install into the same `inst` or `PREFIX` directory.
-The installed documents include the BSC User Guide and the BSC Libraries
-Reference Guide.
+If a pre-built tar-file does not exist for your system,
+you will need to [compile BSC from source](INSTALL.md).
 
 ---
 
-## Using the Bluespec compiler
-
-The installation contains a `bin` directory. To run the BSC tools, you only
-need to add the `bin` directory to your path (or provide that path on the
-command line). The executables in that directory will expect to find other
-files in sibling directories within that same parent installation directory. If
-you just built the compiler, you can quickly test it like so:
-
-    $ export PATH=$(pwd)/inst/bin:$PATH
-
-> **NOTE**: Earlier versions of BSC required that the environment variable
-> `BLUESPECDIR` be set to point into the installation directory; this is no
-> longer necessary, as the executables will figure out their location and
-> determine the installation location on their own.
-
-Run the following to see command-line options on the executable:
+## Documentation
 
-    $ bsc -help
+More details on using BSC, Bluesim, and Bluetcl can be found in the
+_BSC User Guide_.
 
-Additional flags of use to developers can be displayed with the
-following command:
+The standard libraries that come with BSC are documented in the
+_BSC Libraries Reference Guide_.
 
-    $ bsc -help-hidden
+The sources for both of these documents are found in the `doc`
+directory of this repo.  Pre-built PDF files can be downloaded from
+the [Releases](https://github.com/B-Lang-org/bsc/releases) page.
 
-More details on using BSC, Bluesim, and Bluetcl can be found in the User Guide
-(built in this repository).
-Training and tutorials can be found in the
+Language documentation, training, and tutorials can be found in the
 [BSVlang repository](https://github.com/BSVLang/Main).
 
 ---
diff --git a/release/tarball-README b/release/tarball-README
new file mode 100644
index 00000000..e3a184f1
--- /dev/null
+++ b/release/tarball-README
@@ -0,0 +1,46 @@
+This directory contains an installation of the Bluespec Compiler tools.
+
+For more information, visit https://github.com/B-Lang-org/bsc
+
+-------------------------
+
+This directory can be moved to anywhere on your system, but it is best
+for the files to remain in their relative positions within the
+directory.
+
+We recommend placing this directory under `/opt`, `${HOME}/`,
+`/usr/share/`, or similar location.  For example:
+
+    $ mkdir -p /opt/tools/bsc
+    $ mv bsc-<VERSION> /opt/tools/bsc/bsc-<VERSION>
+    $ cd /opt/tools/bsc
+    $ ln -s bsc-<VERSION> latest
+
+This directory has a 'bin' subdirectory, where the executables for the
+tools are found.  To use the tools, just add that directory to your
+`PATH`:
+
+    $ export PATH=/opt/tools/bsc/latest/bin:$PATH
+
+These executables will make use of other files found within this
+directory, locating them relatively from the `bin` directory.  That is
+why the directory must be kept together.
+
+-------------------------
+
+Run the following to see command-line options on the executable:
+
+    $ bsc -help
+
+Additional flags of use to developers can be displayed with the
+following command:
+
+    $ bsc -help-hidden
+
+More details on using BSC, Bluesim, and Bluetcl can be found in the
+BSC User Guide, in the `doc` subdirectory.
+
+Links to more documentation can be found on the BSC website:
+https://github.com/B-Lang-org/bsc
+
+-------------------------