[install.sh, README.md] New installation script, README.md update.

README.md

@@ -21,6 +21,22 @@ If you use *DeepMind Lab2D* in your research and would like to cite it, we
 suggest you cite the
 [accompanying whitepaper](https://arxiv.org/abs/2011.07027).
 
+## Installation
+
+[![PyPI version](https://img.shields.io/pypi/v/dmlab2d.svg)](https://pypi.python.org/pypi/dmlab2d)
+
+[*DeepMind Lab2d* is available on PyPI](https://pypi.python.org/pypi/dmlab2d)
+and can be installed using:
+
+```shell
+pip install dmlab2d
+```
+
+`dmlab2d` is distributed as pre-built wheels for Linux and macOS. If there is no
+appropriate wheel for your platform, you will need to build it from source. See
+[`install.sh`](install.sh) for an example installation script that can be
+adapted to your setup.
+
 ## Getting started
 
 We provide an example "random" agent in `python/random_agent`, which performs
@@ -33,22 +49,23 @@ bazel run -c opt dmlab2d/random_agent -- --level_name=clean_up
 
 ## External dependencies, prerequisites and porting notes
 
-*DeepMind Lab2D* currently ships as source code only. It depends on a few
-external software libraries, which we ship in several different ways:
+*DeepMind Lab2D* depends on a few external software libraries, which we ship in
+several different ways:
 
  * The `dm_env`, `eigen`, `luajit`, `lua5.1`, `lua5.2`, `luajit`, `png`
    and `zlib` libraries are referenced as external Bazel sources, and Bazel
    BUILD files are provided. The dependent code itself should be fairly
-   portable, but the BUILD rules we ship are specific to Linux on x86. To build
-   on a different platform you will most likely have to edit those BUILD files.
+   portable, and the BUILD rules we ship are specific to Linux x86 and
+   MacOS (x86 and arm64). To build on a different platform you will most likely
+   have to edit those BUILD files.
 
  * A "generic reinforcement learning API" is included in
    [`//third_party/rl_api`](third_party/rl_api).
 
  * Several additional libraries are required but are not shipped in any form;
    they must be present on your system:
 
-   * `Python 3.6` or above with `NumPy`, `PyGame`, and `packaging`.
+   * `Python 3.8` or above with `NumPy`, `PyGame`, and `packaging`.
 
 The build rules are using a few compiler settings that are specific to
 GCC/Clang. If some flags are not recognized by your compiler (typically those

install.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+#
+# Copyright 2023 DeepMind Technologies Limited.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Installs dmlab2d from source on Linux/macOS.
+
+set -euxo pipefail
+
+function check_version_gt() {
+  local required="$1"
+  local input lowest
+  input="$(grep -Eo '[0-9]+\.[0-9]+' /dev/stdin | head -n 1)"
+  lowest="$(printf "${required}\n${input}" | sort -V | head -n 1)"
+  [[ ${lowest} == ${required} ]]
+}
+
+function check_setup() {
+  echo -e "\nChecking OS is Linux or macOS..."
+  uname -a
+  [[ "$(uname -s)" =~ (Linux|Darwin) ]]
+
+  echo -e "\nChecking python version..."
+  python --version | tee /dev/stdout | check_version_gt '3.8'
+
+  echo -e "\nChecking pip version..."
+  pip install --upgrade pip
+  pip --version | tee /dev/stdout | check_version_gt '20.3'
+
+  echo -e "\nChecking clang version ..."
+  clang --version | tee /dev/stdout | check_version_gt '14.0'
+
+  echo -e "\nChecking bazel version..."
+  bazel --version | tee /dev/stdout | check_version_gt '6.2'
+}
+
+function install_dmlab2d() {
+  echo -e "\nInstalling dmlab2d requirements..."
+  pip install packaging
+
+  echo -e "\nBuilding dmlab2d wheel..."
+  case "$(uname -srp)" in
+    Linux*)
+      local -r EXTRA_CONFIG=(
+          --linkopt=-fuse-ld=lld
+      )
+      ;;
+    'Darwin 22.'*arm)
+      local -r EXTRA_CONFIG=(
+          --config=libc++
+          --config=macos_arm64
+          --repo_env=PY_PLATFORM_OVERRIDE=macosx_13_0_arm64
+      )
+      ;;
+    'Darwin 21.'*arm)
+      local -r EXTRA_CONFIG=(
+          --config=libc++
+          --config=macos_arm64
+          --repo_env=PY_PLATFORM_OVERRIDE=macosx_12_0_arm64
+      )
+      ;;
+    Darwin*i386)
+      local -r EXTRA_CONFIG=(
+          --config=libc++
+          --config=macos
+      )
+      ;;
+    *)
+      echo "ERROR: no supported config for ${platform}..." >&2
+      exit 1
+      ;;
+  esac
+  C=clang CXX=clang++ bazel --bazelrc=.bazelrc build \
+      --compilation_mode=opt \
+      --dynamic_mode=off \
+      --config=luajit \
+      "${EXTRA_CONFIG[@]}" \
+      --subcommands \
+      --verbose_failures \
+      --experimental_ui_max_stdouterr_bytes=-1 \
+      --sandbox_debug \
+      //dmlab2d:dmlab2d_wheel
+
+  echo -e "\nInstalling dmlab2d..."
+  pip install -vvv --find-links=bazel-bin/dmlab2d dmlab2d
+}
+
+function test_dmlab2d() {
+  echo -e "\nTesting dmlab2d..."
+  python dmlab2d/dmlab2d_test.py
+}
+
+function main() {
+  check_setup
+  install_dmlab2d
+  test_dmlab2d
+}
+
+main "$@"