diff --git a/README.md b/README.md index a78ba48..a0f2684 100644 --- a/README.md +++ b/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,14 +49,15 @@ 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). @@ -48,7 +65,7 @@ external software libraries, which we ship in several different ways: * 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 diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..98c04af --- /dev/null +++ b/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 "$@"