Merge pull request #88 from GrammaticalFramework/build-binary-packages

Build binary packages

10 files changed, 322 insertions, 188 deletions

diff --git a/.github/workflows/build-all-versions.yml b/.github/workflows/build-all-versions.yml
index 52db74850..df71f0ac0 100644
--- a/.github/workflows/build-all-versions.yml
+++ b/.github/workflows/build-all-versions.yml
@@ -13,16 +13,16 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, macOS-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest, windows-latest]
         cabal: ["3.2"]
         ghc:
           - "8.6.5"
           - "8.8.3"
           - "8.10.1"
         exclude:
-          - os: macOS-latest
+          - os: macos-latest
             ghc: 8.8.3
-          - os: macOS-latest
+          - os: macos-latest
             ghc: 8.6.5
           - os: windows-latest
             ghc: 8.8.3
@@ -92,4 +92,4 @@ jobs:
 
     # - name: Test
     #   run: |
-    #     stack test --system-ghc
\ No newline at end of file
+    #     stack test --system-ghc
diff --git a/.github/workflows/build-binary-packages.yml b/.github/workflows/build-binary-packages.yml
new file mode 100644
index 000000000..e33022e6e
--- /dev/null
+++ b/.github/workflows/build-binary-packages.yml
@@ -0,0 +1,173 @@
+name: Build Binary Packages
+
+on:
+  workflow_dispatch:
+  release:
+
+jobs:
+
+# ---
+
+  ubuntu:
+    name: Build Ubuntu package
+    runs-on: ubuntu-18.04
+    # env:
+    #   LC_ALL: C.UTF-8
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Install build tools
+      run: |
+        sudo apt update
+        sudo apt install -y \
+          make \
+          dpkg-dev \
+          debhelper \
+          haskell-platform \
+          libghc-json-dev \
+          python-dev \
+          default-jdk \
+          libtool-bin
+
+    - name: Build Debian package
+      run: |
+        make deb
+
+    - name: Copy package
+      run: |
+        cp ../gf_*.deb dist/
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v2
+      with:
+        name: gf-${{ github.sha }}-ubuntu
+        path: dist/gf_*.deb
+        if-no-files-found: error
+
+# ---
+
+  macos:
+    name: Build macOS package
+    runs-on: macos-10.15
+    strategy:
+      matrix:
+        ghc: ["8.6.5"]
+        cabal: ["2.4"]
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Setup Haskell
+      uses: actions/setup-haskell@v1
+      id: setup-haskell-cabal
+      with:
+        ghc-version: ${{ matrix.ghc }}
+        cabal-version: ${{ matrix.cabal }}
+
+    - name: Install build tools
+      run: |
+        brew install \
+          automake
+        cabal v1-install alex happy
+
+    - name: Build macOS package
+      run: |
+        sudo mkdir -p /Library/Java/Home
+        sudo ln -s /usr/local/opt/openjdk/include /Library/Java/Home/include
+        make pkg
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v2
+      with:
+        name: gf-${{ github.sha }}-macos
+        path: dist/gf-*.pkg
+        if-no-files-found: error
+
+# ---
+
+  windows:
+    name: Build Windows package
+    runs-on: windows-2019
+    strategy:
+      matrix:
+        ghc: ["8.6.5"]
+        cabal: ["2.4"]
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Setup MSYS2
+      uses: msys2/setup-msys2@v2
+      with:
+        install: >-
+          base-devel
+          gcc
+          python-devel
+
+    - name: Prepare dist folder
+      shell: msys2 {0}
+      run: |
+        mkdir /c/tmp-dist
+        mkdir /c/tmp-dist/c
+        mkdir /c/tmp-dist/java
+        mkdir /c/tmp-dist/python
+
+    - name: Build C runtime
+      shell: msys2 {0}
+      run: |
+        cd src/runtime/c
+        autoreconf -i
+        ./configure
+        make
+        make install
+        cp /mingw64/bin/libpgf-0.dll /c/tmp-dist/c
+        cp /mingw64/bin/libgu-0.dll /c/tmp-dist/c
+
+    - name: Build Java bindings
+      shell: msys2 {0}
+      run: |
+        export PATH="${PATH}:/c/Program Files/Java/jdk8u275-b01/bin"
+        cd src/runtime/java
+        make \
+          JNI_INCLUDES="-I \"/c/Program Files/Java/jdk8u275-b01/include\" -I \"/c/Program Files/Java/jdk8u275-b01/include/win32\" -I \"/mingw64/include\" -D__int64=int64_t" \
+          WINDOWS_LDFLAGS="-L\"/mingw64/lib\" -no-undefined"
+        make install
+        cp .libs//msys-jpgf-0.dll /c/tmp-dist/java/jpgf.dll
+        cp jpgf.jar /c/tmp-dist/java
+
+    - name: Build Python bindings
+      shell: msys2 {0}
+      env:
+        EXTRA_INCLUDE_DIRS: /mingw64/include
+        EXTRA_LIB_DIRS: /mingw64/lib
+      run: |
+        cd src/runtime/python
+        python setup.py build
+        python setup.py install
+        cp /usr/lib/python3.8/site-packages/pgf* /c/tmp-dist/python
+
+    - name: Setup Haskell
+      uses: actions/setup-haskell@v1
+      id: setup-haskell-cabal
+      with:
+        ghc-version: ${{ matrix.ghc }}
+        cabal-version: ${{ matrix.cabal }}
+
+    - name: Install Haskell build tools
+      run: |
+        cabal install alex happy
+
+    - name: Build GF
+      run: |
+        cabal install --only-dependencies -fserver
+        cabal configure -fserver
+        cabal build
+        copy dist\build\gf\gf.exe C:\tmp-dist
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v2
+      with:
+        name: gf-${{ github.sha }}-windows
+        path: C:\tmp-dist\*
+        if-no-files-found: error
diff --git a/.github/workflows/build-debian-package.yml b/.github/workflows/build-debian-package.yml
deleted file mode 100644
index 09719aaa8..000000000
--- a/.github/workflows/build-debian-package.yml
+++ /dev/null
@@ -1,49 +0,0 @@
-name: Build Debian Package
-
-on: [push, pull_request]
-
-jobs:
-  build:
-    name: Build on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: true
-      matrix:
-        os: [ubuntu-18.04]
-    env:
-      LC_ALL: C.UTF-8
-
-    steps:
-    - uses: actions/checkout@v1
-
-    - name: Install build tools
-      run: |
-        sudo apt update
-        sudo apt install -y \
-          make \
-          dpkg-dev \
-          debhelper \
-          haskell-platform \
-          libghc-json-dev \
-          python-dev \
-          default-jdk \
-          libtool-bin \
-          txt2tags \
-          pandoc
-
-    - name: Checkout RGL
-      run: |
-        git clone --depth 1 https://github.com/GrammaticalFramework/gf-rgl.git ../gf-rgl
-
-    - name: Build Debian package
-      run: |
-        make deb
-
-    - name: Copy packages
-      run: |
-        mkdir debian/dist
-        cp ../gf_*.deb debian/dist/
-
-    - uses: actions/upload-artifact@v2
-      with:
-        path: debian/dist
diff --git a/.github/workflows/build-python-package.yml b/.github/workflows/build-python-package.yml
index 921da9fb5..6326821dc 100644
--- a/.github/workflows/build-python-package.yml
+++ b/.github/workflows/build-python-package.yml
@@ -1,6 +1,10 @@
 name: Build & Publish Python Package
 
-on: [push, pull_request]
+# Trigger the workflow on push or pull request, but only for the master branch
+on:
+  pull_request:
+  push:
+    branches: [master]
 
 jobs:
   build_wheels:
@@ -9,7 +13,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        os: [ubuntu-18.04, macos-latest]
+        os: [ubuntu-18.04, macos-10.15]
 
     steps:
     - uses: actions/checkout@v1
diff --git a/.gitignore b/.gitignore
index 10968810e..01b58ccb4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,12 @@
 *.jar
 *.gfo
 *.pgf
+debian/.debhelper
+debian/debhelper-build-stamp
+debian/gf
+debian/gf.debhelper.log
+debian/gf.substvars
+debian/files
 dist/
 dist-newstyle/
 src/runtime/c/.libs/
diff --git a/RELEASE.md b/RELEASE.md
index 131a37b5d..3a771b78d 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,6 +1,8 @@
 # GF Core releases
 
-🚨 WARNING! The information here is preliminary!
+**Note:**
+The RGL is now released completely separately from GF Core.
+See the [RGL's RELEASE.md](https://github.com/GrammaticalFramework/gf-rgl/blob/master/RELEASE.md).
 
 ## Creating a new release
 
@@ -9,39 +11,54 @@
 **Web pages**
 
 1. Create `download/index-X.Y.md` with installation instructions.
-1. Create `download/release-X.Y.md` with changelog information.
-1. Update `download/index.html` to redirect to the new version.
-1. Add announcement in news section in `index.html`
+2. Create `download/release-X.Y.md` with changelog information.
+3. Update `download/index.html` to redirect to the new version.
+4. Add announcement in news section in `index.html`.
 
 **Version numbers**
 
-1. Update version number in `gf.cabal` (ommitting `-git` suffix)
-1. Add a new line in `debian/changelog`
+1. Update version number in `gf.cabal` (ommitting `-git` suffix).
+2. Add a new line in `debian/changelog`.
 
 ### 2. Create GitHub release
 
-1. When the above changes are committed to the `master` branch in the repository,
-   check that all builds are successful:
-  - https://github.com/GrammaticalFramework/gf-core/actions
-  - https://travis-ci.org/github/GrammaticalFramework/gf-core
-1. Create a GitHub release here: https://github.com/GrammaticalFramework/gf-core/releases/new
-  with a tag format `RELEASE-X.Y`
+1. When the above changes are committed to the `master` branch in the repository
+  and pushed, check that all CI workflows are successful (fixing as necessary):
+  - <https://github.com/GrammaticalFramework/gf-core/actions>
+  - <https://travis-ci.org/github/GrammaticalFramework/gf-core>
+2. Create a GitHub release [here](https://github.com/GrammaticalFramework/gf-core/releases/new):
+  - Tag version format `RELEASE-X.Y`
+  - Title: "GF X.Y"
+  - Description: mention major changes since last release
+3. Publish the release to trigger the building of the binary packages (below).
 
 ### 3. Binary packages
 
-Build and attach binaries to the release by running the relevant GitHub Actions workflows (TODO):
+The binaries will be built automatically by GitHub Actions when the release is created,
+but the generated _artifacts_ must be manually attached to the release as _assets_.
 
-1. Go to https://github.com/GrammaticalFramework/gf-rgl/actions
-1. Click "Build [platform] package" under _Workflows_
-1. Click "Run workflow" and specify the tag `RELEASE-X.Y`
+1. Go to the [actions page](https://github.com/GrammaticalFramework/gf-core/actions) and click "Build Binary Packages" under _Workflows_.
+2. Choose the workflow run corresponding to the newly created release.
+3. Download the artifacts locally. Extract the Ubuntu and macOS ones to get the `.deb` and `.pkg` files.
+4. Go back to the [releases page](https://github.com/GrammaticalFramework/gf-core/releases) and click to edit the release information.
+5. Add the downloaded artifacts as release assets, giving them names with format `gf-X.Y-PLATFORM.EXT` (e.g. `gf-3.11-macos.pkg`).
 
 ### 4. Upload to Hackage
 
 1. Run `make sdist`
-1. Visit `https://hackage.haskell.org/upload` and upload the file `dist/gf-X.Y.tar.gz`,
-   OR upload directly with Cabal (≥2.4): `cabal upload dist/gf-X.Y.tar.gz`
-1. If the documentation-building fails on the Hackage server, do:
+2. Upload the package, either:
+    1. **Manually**: visit <https://hackage.haskell.org/upload> and upload the file `dist/gf-X.Y.tar.gz`
+    2. **via Cabal (≥2.4)**: `cabal upload dist/gf-X.Y.tar.gz`
+3. If the documentation-building fails on the Hackage server, do:
 ```
 cabal v2-haddock --builddir=dist/docs --haddock-for-hackage --enable-doc
 cabal upload --documentation dist/docs/*-docs.tar.gz
 ```
+
+## Miscellaneous
+
+### What is the tag `GF-3.10`?
+
+For GF 3.10, the Core and RGL repositories had already been separated, however
+the binary packages still included the RGL. `GF-3.10` is a tag that was created
+in both repositories ([gf-core](https://github.com/GrammaticalFramework/gf-core/releases/tag/GF-3.10) and [gf-rgl](https://github.com/GrammaticalFramework/gf-rgl/releases/tag/GF-3.10)) to indicate which versions of each went into the binaries.
diff --git a/bin/build-binary-dist.sh b/bin/build-binary-dist.sh
index 7f6ca5d72..4ea1c31a3 100755
--- a/bin/build-binary-dist.sh
+++ b/bin/build-binary-dist.sh
@@ -1,15 +1,18 @@
 #! /bin/bash
 
-### This script builds a binary distribution of GF from the source
-### package that this script is a part of. It assumes that you have installed
-### a recent version of the Haskell Platform.
-### Two binary package formats are supported: plain tar files (.tar.gz) and
-### OS X Installer packages (.pkg).
+### This script builds a binary distribution of GF from source.
+### It assumes that you have Haskell and Cabal installed.
+### Two binary package formats are supported (specified with the FMT env var):
+### - plain tar files (.tar.gz)
+### - macOS installer packages (.pkg)
 
 os=$(uname)     # Operating system name (e.g. Darwin or Linux)
 hw=$(uname -m)  # Hardware name (e.g. i686 or x86_64)
 
-# GF version number:
+cabal="cabal v1-" # Cabal >= 2.4
+# cabal="cabal " # Cabal <= 2.2
+
+## Get GF version number from Cabal file
 ver=$(grep -i ^version: gf.cabal | sed -e 's/version://' -e 's/ //g')
 
 name="gf-$ver"
@@ -29,6 +32,7 @@ set -x                             # print commands before executing them
 pushd src/runtime/c
 bash setup.sh configure --prefix="$prefix"
 bash setup.sh build
+bash setup.sh install prefix="$prefix" # hack required for GF build on macOS
 bash setup.sh install prefix="$destdir$prefix"
 popd
 
@@ -38,11 +42,11 @@ if which >/dev/null python; then
     EXTRA_INCLUDE_DIRS="$extrainclude" EXTRA_LIB_DIRS="$extralib" python setup.py build
     python setup.py install --prefix="$destdir$prefix"
     if [ "$fmt" == pkg ] ; then
-	# A hack for Python on OS X to find the PGF modules
-	pyver=$(ls "$destdir$prefix/lib" | sed -n 's/^python//p')
-	pydest="$destdir/Library/Python/$pyver/site-packages"
-	mkdir -p "$pydest"
-	ln "$destdir$prefix/lib/python$pyver/site-packages"/pgf* "$pydest"
+        # A hack for Python on macOS to find the PGF modules
+        pyver=$(ls "$destdir$prefix/lib" | sed -n 's/^python//p')
+        pydest="$destdir/Library/Python/$pyver/site-packages"
+        mkdir -p "$pydest"
+        ln "$destdir$prefix/lib/python$pyver/site-packages"/pgf* "$pydest"
     fi
     popd
 else
@@ -55,54 +59,40 @@ if which >/dev/null javac && which >/dev/null jar ; then
     rm -f libjpgf.la # In case it contains the wrong INSTALL_PATH
     if make CFLAGS="-I$extrainclude -L$extralib" INSTALL_PATH="$prefix"
     then
-	make INSTALL_PATH="$destdir$prefix" install
+        make INSTALL_PATH="$destdir$prefix" install
     else
-	echo "*** Skipping the Java binding because of errors"
+        echo "Skipping the Java binding because of errors"
     fi
     popd
 else
     echo "Java SDK is not installed, so the Java binding will not be included"
 fi
 
-## To find dynamic C run-time libraries when running GF below
+## To find dynamic C run-time libraries when building GF below
 export DYLD_LIBRARY_PATH="$extralib" LD_LIBRARY_PATH="$extralib"
 
-
 ## Build GF, with C run-time support enabled
-cabal install -w "$ghc" --only-dependencies -fserver -fc-runtime $extra
-cabal configure -w "$ghc" --prefix="$prefix" -fserver -fc-runtime $extra
-cabal build
-  # Building the example grammars will fail, because the RGL is missing
-cabal copy --destdir="$destdir"  # create www directory
-
-## Build the RGL and copy it to $destdir
-PATH=$PWD/dist/build/gf:$PATH
-export GF_LIB_PATH="$(dirname $(find "$destdir" -name www))/lib"   # hmm
-mkdir -p "$GF_LIB_PATH"
-pushd ../gf-rgl
-make build
-make copy
-popd
-
-# Build GF again, including example grammars that need the RGL
-cabal build
+${cabal}install -w "$ghc" --only-dependencies -fserver -fc-runtime $extra
+${cabal}configure -w "$ghc" --prefix="$prefix" -fserver -fc-runtime $extra
+${cabal}build
 
 ## Copy GF to $destdir
-cabal copy --destdir="$destdir"
+${cabal}copy --destdir="$destdir"
 libdir=$(dirname $(find "$destdir" -name PGF.hi))
-cabal register --gen-pkg-config=$libdir/gf-$ver.conf
+${cabal}register --gen-pkg-config="$libdir/gf-$ver.conf"
 
 ## Create the binary distribution package
 case $fmt in
     tar.gz)
-	targz="$name-bin-$hw-$os.tar.gz"     # the final tar file
-	tar -C "$destdir/$prefix" -zcf "dist/$targz" .
-	echo "Created $targz, consider renaming it to something more user friendly"
-	;;
+        targz="$name-bin-$hw-$os.tar.gz"     # the final tar file
+        tar --directory "$destdir/$prefix" --gzip --create --file "dist/$targz" .
+        echo "Created $targz"
+        ;;
     pkg)
-	pkg=$name.pkg
-	pkgbuild --identifier org.grammaticalframework.gf.pkg --version "$ver" --root "$destdir" --install-location / dist/$pkg
-	echo "Created $pkg"
+        pkg=$name.pkg
+        pkgbuild --identifier org.grammaticalframework.gf.pkg --version "$ver" --root "$destdir" --install-location / dist/$pkg
+        echo "Created $pkg"
 esac
 
+## Cleanup
 rm -r "$destdir"
diff --git a/debian/control b/debian/control
index a07187983..12eb6b9d9 100644
--- a/debian/control
+++ b/debian/control
@@ -3,14 +3,14 @@ Section: devel
 Priority: optional
 Maintainer: Thomas Hallgren <hallgren@chalmers.se>
 Standards-Version: 3.9.2
-Build-Depends: debhelper (>= 5), haskell-platform (>= 2011.2.0.1), libghc-haskeline-dev, libghc-mtl-dev, libghc-json-dev, autoconf, automake, libtool-bin, python-dev, java-sdk, txt2tags, pandoc
+Build-Depends: debhelper (>= 5), haskell-platform (>= 2011.2.0.1), libghc-haskeline-dev, libghc-mtl-dev, libghc-json-dev, autoconf, automake, libtool-bin, python-dev, java-sdk
 Homepage: http://www.grammaticalframework.org/
 
 Package: gf
 Architecture: any
 Depends: ${shlibs:Depends}
 Description: Tools for GF, a grammar formalism based on type theory
- Grammatical Framework (GF) is a grammar formalism based on type theory. 
+ Grammatical Framework (GF) is a grammar formalism based on type theory.
  It consists of a special-purpose programming language,
  a compiler of the language, and a generic grammar processor.
  .
diff --git a/debian/rules b/debian/rules
index 917801826..8bd3c1f85 100755
--- a/debian/rules
+++ b/debian/rules
@@ -1,6 +1,6 @@
 #!/usr/bin/make -f
 
-%: 
+%:
 	+dh $@
 
 #dh_shlibdeps has a problem finding which package some of the Haskell
@@ -26,14 +26,10 @@ override_dh_auto_build:
 	cd src/runtime/python && EXTRA_INCLUDE_DIRS=$(CURDIR)/src/runtime/c EXTRA_LIB_DIRS=$(CURDIR)/src/runtime/c/.libs python setup.py build
 	cd src/runtime/java && make CFLAGS="-I$(CURDIR)/src/runtime/c -L$(CURDIR)/src/runtime/c/.libs" INSTALL_PATH=/usr
 	echo $(SET_LDL)
-	-$(SET_LDL) cabal build # builds gf, fails to build example grammars
-	export $(SET_LDL); PATH=$(CURDIR)/dist/build/gf:$$PATH && make -C ../gf-rgl build
-	GF_LIB_PATH=$(CURDIR)/../gf-rgl/dist $(SET_LDL) cabal build # have RGL now, ok to build example grammars
-	make html
+	-$(SET_LDL) cabal build
 
 override_dh_auto_install:
-	$(SET_LDL) cabal copy --destdir=$(CURDIR)/debian/gf # creates www directory
-	export GF_LIB_PATH="$$(dirname $$(find "$(CURDIR)/debian/gf" -name www))/lib" && echo "GF_LIB_PATH=$$GF_LIB_PATH" && mkdir -p "$$GF_LIB_PATH" && make -C ../gf-rgl copy
+	$(SET_LDL) cabal copy --destdir=$(CURDIR)/debian/gf
 	cd src/runtime/c && bash setup.sh copy prefix=$(CURDIR)/debian/gf/usr
 	cd src/runtime/python && python setup.py install --prefix=$(CURDIR)/debian/gf/usr
 	cd src/runtime/java && make INSTALL_PATH=$(CURDIR)/debian/gf/usr install
diff --git a/download/index-3.11.md b/download/index-3.11.md
index 4e225f631..78b6af4bc 100644
--- a/download/index-3.11.md
+++ b/download/index-3.11.md
@@ -2,56 +2,60 @@
 title: Grammatical Framework Download and Installation
 ...
 
-**GF 3.11** was released on ? December 2020.
+**GF 3.11** was released on ... December 2020.
 
 What's new? See the [release notes](release-3.11.html).
 
-## Binary packages
+#### Note: GF core and RGL
 
-Unlike previous versions, these binary packages include only the GF core (compiler and runtime).
+The following instructions explain how to install **GF core**, i.e. the compiler, shell and run-time systems.
+Obtaining the **Resource Grammar Library (RGL)** is done separately; see the section at the bottom of this page.
 
-| Platform        | Download                                           | Features       | How to install                   |
-|:----------------|:---------------------------------------------------|:---------------|:---------------------------------|
-| macOS           | [gf-3.11.pkg](gf-3.11.pkg)                         | GF, S, C, J, P | Double-click on the package icon |
-| Ubuntu (32-bit) | [gf\_3.11\_i386.deb](gf_3.11_i386.deb)             | GF, S, C, J, P | `sudo dpkg -i gf_3.11_i386.deb`  |
-| Ubuntu (64-bit) | [gf\_3.11\_amd64.deb](gf_3.11_amd64.deb)           | GF, S, C, J, P | `sudo dpkg -i gf_3.11_amd64.deb` |
-| Windows         | [gf-3.11-bin-windows.zip](gf-3.11-bin-windows.zip) | GF, S          | `unzip gf-3.11-bin-windows.zip`  |
+## Installing from a binary package
 
-**Features**
+Binary packages are available for Debian/Ubuntu, macOS, and Windows and include:
 
-- GF = GF shell and grammar compiler
-- S = `gf -server` mode
-- C = C run-time system
-- J/P = Java/Python binding to the C run-time system
+- GF shell and grammar compiler
+- `gf -server` mode
+- C run-time system
+- Java & Python bindings to the C run-time system
 
-### Notes
+Unlike in previous versions, the binaries **do not** include the RGL.
+
+[Binary packages on GitHub](https://github.com/GrammaticalFramework/gf-core/releases/tag/RELEASE-3.11)
+
+### Debian/Ubuntu
+
+To install the package use:
+```
+sudo dpkg -i gf_3.11.deb
+```
+
+The Ubuntu `.deb` packages should work on Ubuntu 16.04, 18.04 and similar Linux distributions.
+
+### macOS
 
-The Windows package is installed by just unpacking it anywhere. You will
-probably need to set the `PATH` and `GF_LIB_PATH` environment variables,
-see Inari's notes on [Installing GF on Windows](http://www.grammaticalframework.org/~inari/gf-windows.html#toc3).
+To install the package, just double-click it and follow the installer instructions.
 
-The Ubuntu `.deb` packages should work on Ubuntu 16.04 and 18.04 and
-similar Linux distributions. The `.deb` packages were updated
-to version 3.10-2 after the release of GF 3.10.
-(Because of a packaging bug the Resource Grammar Library was missing
-in the 3.10-1 packages.)
+The packages should work on at least 10.13 (High Sierra) and 10.14 (Mojave).
 
-The packages for macOS (Mac OS X) should work on at least 10.13 and
-10.14 (High Sierra and Mojave)
+### Windows
+
+To install the package, unpack it anywhere.
+
+You will probably need to update the `PATH` environment variable to include your chosen install location.
+<!-- see Inari's notes on [Installing GF on Windows](http://www.grammaticalframework.org/~inari/gf-windows.html#toc3). -->
 
 ## Installing the latest release from source
 
 [GF is on Hackage](http://hackage.haskell.org/package/gf), so under
 normal circumstances the procedure is fairly simple:
 
-1.  Install a recent version of the [Haskell
-    Platform](http://hackage.haskell.org/platform) (see note below)
+1.  Install a recent version of the [Haskell Platform](http://hackage.haskell.org/platform) (see note below)
 2.  `cabal update`
 3.  On Linux: install some C libraries from your Linux distribution (see note below)
 4.  `cabal install gf`
 
-This installs the GF executable and Haskell libraries, but **does not include the RGL**.
-
 You can also download the source code release from [GitHub](https://github.com/GrammaticalFramework/gf-core/releases),
 and follow the instructions below under **Installing from the latest developer source code**.
 
@@ -59,22 +63,14 @@ and follow the instructions below under **Installing from the latest developer s
 
 **Installation location**
 
-The above steps installs GF for a single user. The executables are put
-in `$HOME/.cabal/bin` (or, with recent versions of the Haskell platform
-on Mac OS X, in `$HOME/Library/Haskell/bin`), so it is a good idea to
-put a line in your `.bash_profile` or `.profile` to add that directory
-to you path:
+The above steps installs GF for a single user.
+The executables are put in `$HOME/.cabal/bin` (or on macOS in `$HOME/Library/Haskell/bin`),
+so you might want to add this directory to your path (in `.bash_profile` or similar):
 
 ```
 PATH=$HOME/.cabal/bin:$PATH
 ```
 
-or
-
-```
-PATH=$HOME/Library/Haskell/bin:$PATH
-```
-
 **Build tools**
 
 In order to compile GF you need the build tools **Alex** and **Happy**.
@@ -98,8 +94,7 @@ Here is one way to do this:
 
 **GHC version**
 
-The GF source code has been updated to compile with GHC 8.4.
-Using older versions of GHC (e.g. 8.2, 8.0 and 7.10) should still work too.
+The GF source code has been updated to compile with GHC versions 7.10 through to 8.8.
 
 ## Installing from the latest developer source code
 
@@ -131,39 +126,41 @@ The above notes for installing from source apply also in these cases.
 For more info on working with the GF source code, see the
 [GF Developers Guide](../doc/gf-developers.html).
 
-## Installing the RGL from source
+## Installing the Python bindings from PyPI
 
-To install the RGL from source,
-you can download a release from [GitHub](https://github.com/GrammaticalFramework/gf-rgl/releases)
-or get the latest version by cloning the repository:
+The Python library is available on PyPI as `pgf`, so it can be installed using:
 
 ```
-git clone https://github.com/GrammaticalFramework/gf-rgl.git
+pip install pgf
 ```
 
-In both cases, once you have the RGL sources you can install them by running:
+We provide binary wheels for Linux and macOS, which include the C runtime and are ready-to-go.
+If there is no binary distribution for your platform, this will install the source tarball,
+which will attempt to build the binding during installation,
+and requires the GF C runtime to be installed on your system.
 
-```
-make
-```
+---
 
-in the RGL folder.
-This assumes that you already have GF installed.
-For more details about building the RGL, see the [RGL README](https://github.com/GrammaticalFramework/gf-rgl/blob/master/README.md).
+## Installing the RGL from a binary release
 
-## Installing the Python bindings from PyPI
+Binary releases of the RGL are made available on [GitHub](https://github.com/GrammaticalFramework/gf-rgl/releases).
+In general the steps to follow are:
 
-The Python library is available on PyPI as `pgf`, so it can be installed using:
+1. Download a binary release and extract it somewhere on your system.
+2. Set the environment variable `GF_LIB_PATH` to point to wherever you extracted the RGL.
 
-```
-pip install pgf
-```
+## Installing the RGL from source
 
-We provide binary wheels for Linux and OSX (with Windows missing so far), which
-include the C runtime and a ready-to-go.  If there is no binary distribution for
-your platform, this will install the source tarball, which will attempt to build
-the binding during installation, and requires the GF C runtime to be installed on
-your system.
+To compile the RGL, you will need to have GF already installed and in your path.
+
+1. Obtain the RGL source code, either by:
+  - cloning with `git clone https://github.com/GrammaticalFramework/gf-rgl.git`
+  - downloading a source archive [here](https://github.com/GrammaticalFramework/gf-rgl/archive/master.zip)
+2. Run `make` in the source code folder.
+
+For more options, see the [RGL README](https://github.com/GrammaticalFramework/gf-rgl/blob/master/README.md).
+
+---
 
 ## Older releases