Adds MacOS support to run_lit.sh and adds MacOS getting started.
This puts MacOS at a point where all but 8 of the core IREE tests are passing on Bazel. Both the Bazel and Cmake builds complete successfully on my laptop.
The getting started documentation include disclaimers that we do not actively support MacOS.
Python3 numpy is added as a dependency to the Linux and MacOS Bazel builds to reflect the effects of using `python3 configure_bazel.py`.
This change also adds a lot of small fixes to the getting started docs more broadly, as they were requested by reviewers.
Closes https://github.com/google/iree/pull/2201
COPYBARA_INTEGRATE_REVIEW=https://github.com/google/iree/pull/2201 from phoenix-meadowlark:getting-started-macos a683048d31ede75e3a26bf3d83cf7b213f594f0a
PiperOrigin-RevId: 316941443
diff --git a/build_tools/cmake/build_docs.sh b/build_tools/cmake/build_docs.sh
index 256371b..4aea054 100755
--- a/build_tools/cmake/build_docs.sh
+++ b/build_tools/cmake/build_docs.sh
@@ -71,5 +71,7 @@
cp docs/GetStarted/getting_started_linux_bazel.md ${BUILD_DIR}/doc/GetStarted/
cp docs/GetStarted/getting_started_linux_cmake.md ${BUILD_DIR}/doc/GetStarted/
cp docs/GetStarted/getting_started_linux_vulkan.md ${BUILD_DIR}/doc/GetStarted/
+cp docs/GetStarted/getting_started_macos_bazel.md ${BUILD_DIR}/doc/GetStarted/
+cp docs/GetStarted/getting_started_macos_cmake.md ${BUILD_DIR}/doc/GetStarted/
cp docs/GetStarted/getting_started_python.md ${BUILD_DIR}/doc/GetStarted/
cp docs/GetStarted/generic_vulkan_env_setup.md ${BUILD_DIR}/doc/GetStarted/
diff --git a/docs/GetStarted/getting_started_linux_bazel.md b/docs/GetStarted/getting_started_linux_bazel.md
index 687a84a..738a365 100644
--- a/docs/GetStarted/getting_started_linux_bazel.md
+++ b/docs/GetStarted/getting_started_linux_bazel.md
@@ -6,12 +6,13 @@
* This document should be __simple__ and cover essential items only.
Notes for optional components should go in separate files.
- * This document parallels getting_started_windows_bazel.md.
+ * This document parallels getting_started_windows_bazel.md and
+ getting_started_macos_bazel.md
Please keep them in sync.
-->
This guide walks through building the core compiler and runtime parts of IREE
-from source. Auxilary components like the Python bindings and Vulkan driver are
+from source. Auxiliary components like the Python bindings and Vulkan driver are
documented separately, as they require further setup.
## Prerequisites
@@ -19,7 +20,7 @@
### Install Bazel
Install Bazel version > 2.0.0 (see
-[.bazelversion](https://github.com/google/iree/blob/master/.bazelversion) for
+[`.bazelversion`](https://github.com/google/iree/blob/master/.bazelversion) for
the specific version IREE uses) by following the
[official docs](https://docs.bazel.build/versions/master/install.html).
@@ -31,13 +32,19 @@
$ sudo apt install clang
```
-Set environment variables:
+Set environment variables for Bazel:
```shell
export CC=clang
export CXX=clang++
```
+### Install python3 numpy
+
+```shell
+$ python3 -m pip install numpy
+```
+
## Clone and Build
### Clone
@@ -76,7 +83,7 @@
You can put a user.bazelrc at the root of the repository and it will be ignored
by git. The recommended contents for Linux are:
-```
+```shell
build --disk_cache=/tmp/bazel-cache
# Use --config=debug to compile iree and llvm without optimizations
@@ -109,7 +116,8 @@
and execute a function in the compiled module:
```shell
-$ ./bazel-bin/iree/tools/iree-run-mlir ./iree/tools/test/simple.mlir -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
+$ ./bazel-bin/iree/tools/iree-run-mlir ./iree/tools/test/simple.mlir \
+ -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
```
### Further Reading
diff --git a/docs/GetStarted/getting_started_linux_cmake.md b/docs/GetStarted/getting_started_linux_cmake.md
index e31a95a..190ce9a 100644
--- a/docs/GetStarted/getting_started_linux_cmake.md
+++ b/docs/GetStarted/getting_started_linux_cmake.md
@@ -6,12 +6,13 @@
* This document should be __simple__ and cover essential items only.
Notes for optional components should go in separate files.
- * This document parallels getting_started_windows_cmake.md.
+ * This document parallels getting_started_windows_cmake.md and
+ getting_started_macos_bazel.md
Please keep them in sync.
-->
This guide walks through building the core compiler and runtime parts of IREE
-from source. Auxilary components like the Python bindings and Vulkan driver are
+from source. Auxiliary components like the Python bindings and Vulkan driver are
documented separately, as they require further setup.
## Prerequisites
@@ -76,8 +77,8 @@
> Tip:<br>
> The root
-> [CMakeLists.txt](https://github.com/google/iree/blob/master/CMakeLists.txt) file
-> has options for configuring which parts of the project to enable.
+> [CMakeLists.txt](https://github.com/google/iree/blob/master/CMakeLists.txt)
+> file has options for configuring which parts of the project to enable.
Build all targets:
@@ -101,7 +102,8 @@
and execute a function in the compiled module:
```shell
-$ ./build/iree/tools/iree-run-mlir $PWD/iree/tools/test/simple.mlir -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
+$ ./build/iree/tools/iree-run-mlir $PWD/iree/tools/test/simple.mlir \
+ -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
```
### Further Reading
diff --git a/docs/GetStarted/getting_started_macos_bazel.md b/docs/GetStarted/getting_started_macos_bazel.md
new file mode 100644
index 0000000..a169f8d
--- /dev/null
+++ b/docs/GetStarted/getting_started_macos_bazel.md
@@ -0,0 +1,134 @@
+# Getting Started on macOS with Bazel
+
+<!--
+Notes to those updating this guide:
+
+ * This document should be __simple__ and cover essential items only.
+ Notes for optional components should go in separate files.
+
+ * This document parallels getting_started_linux_bazel.md and
+ getting_started_windows_bazel.md
+ Please keep them in sync.
+-->
+
+This guide walks through building the core compiler and runtime parts of IREE
+from source. Auxiliary components like the Python bindings and Vulkan driver are
+not documented for macOS at this time.
+
+IREE is not officially supported on macOS at this time. It may work, but it is
+not a part of our open source CI, and may be intermittently broken.
+Contributions related to macOS support and documentation are welcome however.
+
+## Prerequisites
+
+### Install Homebrew
+
+This guide uses [Homebrew](https://brew.sh/) to install IREE's dependencies.
+
+```shell
+$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+```
+
+### Install Bazel
+
+Install Bazel via Homebrew:
+
+```shell
+$ brew install bazel
+```
+
+Note: when you first run `bazel` to build IREE, it will prompt you to copy and
+run a shell command to select the right version.
+
+### Install python3 numpy
+
+```shell
+$ python3 -m pip install numpy --user
+```
+
+## Clone and Build
+
+### Clone
+
+Clone the repository, initialize its submodules and configure:
+
+```shell
+$ git clone https://github.com/google/iree.git
+$ cd iree
+$ git submodule update --init
+$ python3 configure_bazel.py
+```
+
+> Tip:<br>
+> Editors and other programs can also clone the
+> repository, just make sure that they initialize the submodules.
+
+### Build
+
+Run all core tests that pass on our OSS CI:
+
+```shell
+$ bazel test -k //iree/... \
+ --test_env=IREE_VULKAN_DISABLE=1 \
+ --build_tag_filters="-nokokoro" \
+ --test_tag_filters="--nokokoro,-driver=vulkan"
+```
+
+> Tip:<br>
+> Not all tests are passing on macOS, but the build does
+> complete successfully at the time of writing.
+
+In general, build artifacts will be under the `bazel-bin` directory at the top
+level.
+
+## Recommended user.bazelrc
+
+You can put a user.bazelrc at the root of the repository and it will be ignored
+by git. The recommended contents for Linux/macOS are:
+
+```shell
+build --disk_cache=/tmp/bazel-cache
+
+# Use --config=debug to compile iree and llvm without optimizations
+# and with assertions enabled.
+build:debug --config=asserts --compilation_mode=opt '--per_file_copt=iree|llvm@-O0' --strip=never
+
+# Use --config=asserts to enable assertions in iree and llvm.
+build:asserts --compilation_mode=opt '--per_file_copt=iree|llvm@-UNDEBUG'
+```
+
+## What's next?
+
+### Take a Look Around
+
+Build all of IREE's 'tools' directory:
+
+```shell
+$ bazel build iree/tools/...
+```
+
+Check out what was built:
+
+```shell
+$ ls bazel-bin/iree/tools/
+$ ./bazel-bin/iree/tools/iree-translate --help
+```
+
+Translate a
+[MLIR file](https://github.com/google/iree/blob/master/iree/tools/test/simple.mlir)
+and execute a function in the compiled module:
+
+```shell
+$ ./bazel-bin/iree/tools/iree-run-mlir ./iree/tools/test/simple.mlir \
+ -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
+```
+
+### Further Reading
+
+* For an introduction to IREE's project structure and developer tools, see
+ [Developer Overview](../developer_overview.md) <!-- TODO: Link to macOS
+ versions of these guides once they are developed.
+* To target GPUs using Vulkan, see
+ [Getting Started on Linux with Vulkan](getting_started_linux_vulkan.md)
+* To use IREE's Python bindings, see
+ [Getting Started with Python](getting_started_python.md) -->
diff --git a/docs/GetStarted/getting_started_macos_cmake.md b/docs/GetStarted/getting_started_macos_cmake.md
new file mode 100644
index 0000000..1fc6777
--- /dev/null
+++ b/docs/GetStarted/getting_started_macos_cmake.md
@@ -0,0 +1,117 @@
+# Getting Started on macOS with CMake
+
+<!--
+Notes to those updating this guide:
+
+ * This document should be __simple__ and cover essential items only.
+ Notes for optional components should go in separate files.
+
+ * This document parallels getting_started_linux_cmake.md and
+ getting_started_windows_cmake.md
+ Please keep them in sync.
+-->
+
+This guide walks through building the core compiler and runtime parts of IREE
+from source. Auxiliary components like the Python bindings and Vulkan driver are
+not documented for macOS at this time.
+
+IREE is not officially supported on macOS at this time. It may work, but it is
+not a part of our open source CI, and may be intermittently broken.
+Contributions related to macOS support and documentation are welcome however.
+
+## Prerequisites
+
+### Install Homebrew
+
+This guide uses [Homebrew](https://brew.sh/) to install IREE's dependencies.
+
+```shell
+$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+```
+
+### Install CMake
+
+IREE uses [CMake](https://cmake.org/) version `>= 3.13`. Brew ships the latest
+release.
+
+```shell
+$ brew install cmake
+$ cmake --version # >= 3.13
+```
+
+### Install Ninja
+
+[Ninja](https://ninja-build.org/) is a fast build system that you can use as a
+CMake generator.
+
+```shell
+$ brew install ninja
+```
+
+## Clone and Build
+
+### Clone
+
+Clone the repository and initialize its submodules:
+
+```shell
+$ git clone https://github.com/google/iree.git
+$ cd iree
+$ git submodule update --init
+```
+
+> Tip:<br>
+> Editors and other programs can also clone the
+> repository, just make sure that they initialize the submodules.
+
+### Build
+
+Configure:
+
+```shell
+$ cmake -G Ninja -B build/ .
+```
+
+Note: this should use `Clang` by default on macOS. `GCC` is not fully supported
+by IREE.
+
+> Tip:<br>
+> The root
+> [CMakeLists.txt](https://github.com/google/iree/blob/master/CMakeLists.txt)
+> file has options for configuring which parts of the project to enable.
+
+Build all targets:
+
+```shell
+$ cmake --build build/
+```
+
+## What's next?
+
+### Take a Look Around
+
+Check out the contents of the 'tools' build directory:
+
+```shell
+$ ls build/iree/tools
+$ ./build/iree/tools/iree-translate --help
+```
+
+Translate a
+[MLIR file](https://github.com/google/iree/blob/master/iree/tools/test/simple.mlir)
+and execute a function in the compiled module:
+
+```shell
+$ ./build/iree/tools/iree-run-mlir $PWD/iree/tools/test/simple.mlir \
+ -input-value="i32=-2" -iree-hal-target-backends=vmla -print-mlir
+```
+
+### Further Reading
+
+* For an introduction to IREE's project structure and developer tools, see
+ [Developer Overview](../developer_overview.md) <!-- TODO: Link to macOS
+ versions of these guides once they are developed.
+* To target GPUs using Vulkan, see
+ [Getting Started on Linux with Vulkan](getting_started_linux_vulkan.md)
+* To use IREE's Python bindings, see
+ [Getting Started with Python](getting_started_python.md) -->
diff --git a/docs/GetStarted/getting_started_windows_bazel.md b/docs/GetStarted/getting_started_windows_bazel.md
index c90223a..3eb660d 100644
--- a/docs/GetStarted/getting_started_windows_bazel.md
+++ b/docs/GetStarted/getting_started_windows_bazel.md
@@ -6,12 +6,13 @@
* This document should be __simple__ and cover essential items only.
Notes for optional components should go in separate files.
- * This document parallels getting_started_linux_bazel.md.
+ * This document parallels getting_started_linux_bazel.md and
+ getting_started_macos_bazel.md
Please keep them in sync.
-->
This guide walks through building the core compiler and runtime parts of IREE
-from source. Auxilary components like the Python bindings and Vulkan driver are
+from source. Auxiliary components like the Python bindings and Vulkan driver are
documented separately, as they require further setup.
## Prerequisites
@@ -24,7 +25,7 @@
### Install Bazel
Install Bazel version > 2.0.0 (see
-[.bazelversion](https://github.com/google/iree/blob/master/.bazelversion) for
+[`.bazelversion`](https://github.com/google/iree/blob/master/.bazelversion) for
the specific version IREE uses) by following the
[official docs](https://docs.bazel.build/versions/master/install-windows.html).
diff --git a/docs/GetStarted/getting_started_windows_cmake.md b/docs/GetStarted/getting_started_windows_cmake.md
index 071dd01..445d790 100644
--- a/docs/GetStarted/getting_started_windows_cmake.md
+++ b/docs/GetStarted/getting_started_windows_cmake.md
@@ -6,12 +6,13 @@
* This document should be __simple__ and cover essential items only.
Notes for optional components should go in separate files.
- * This document parallels getting_started_linux_cmake.md.
+ * This document parallels getting_started_linux_cmake.md and
+ getting_started_macos_cmake.md
Please keep them in sync.
-->
This guide walks through building the core compiler and runtime parts of IREE
-from source. Auxilary components like the Python bindings and Vulkan driver are
+from source. Auxiliary components like the Python bindings and Vulkan driver are
documented separately, as they require further setup.
## Prerequisites
@@ -74,8 +75,8 @@
> Tip:<br>
> The root
-> [CMakeLists.txt](https://github.com/google/iree/blob/master/CMakeLists.txt) file
-> has options for configuring which parts of the project to enable.
+> [CMakeLists.txt](https://github.com/google/iree/blob/master/CMakeLists.txt)
+> file has options for configuring which parts of the project to enable.
Build all targets:
diff --git a/iree/tools/run_lit.sh b/iree/tools/run_lit.sh
index 60aa4a8..704c7cc 100755
--- a/iree/tools/run_lit.sh
+++ b/iree/tools/run_lit.sh
@@ -30,7 +30,10 @@
function find_executables() {
set -e
local p="$1"
- if [ -z "$cygpath" ]; then
+ if [ "$(uname)" == "Darwin" ]; then
+ # For macOS, xtype isn't avaliable and perm can't use `/u=x,g=x,o=x` syntax.
+ find "${p}" -type l -perm +111
+ elif [ -z "$cygpath" ]; then
# For non-windows, use the perm based executable check, which has been
# supported by find for a very long time.
find "${p}" -xtype f -perm /u=x,g=x,o=x -print
diff --git a/packaging/python/common_setup.py b/packaging/python/common_setup.py
index a34f493..cbaf1d1 100644
--- a/packaging/python/common_setup.py
+++ b/packaging/python/common_setup.py
@@ -123,7 +123,7 @@
# Need to include platform specific extensions binaries:
# Windows: .pyd
- # MacOS: .dylib
+ # macOS: .dylib
# Other: .so
# Unfortunately, bazel is imprecise and scatters .so files around, so
# need to be specific.
diff --git a/scripts/prepare_doc_publication.py b/scripts/prepare_doc_publication.py
index 7423f43..b32b590 100755
--- a/scripts/prepare_doc_publication.py
+++ b/scripts/prepare_doc_publication.py
@@ -54,6 +54,8 @@
'getting_started_windows_bazel.md': 'Windows with Bazel',
'getting_started_windows_cmake.md': 'Windows with CMake',
'getting_started_windows_vulkan.md': 'Windows with Vulkan',
+ 'getting_started_macos_bazel.md': 'macOS with Bazel',
+ 'getting_started_macos_cmake.md': 'macOS with CMake',
'generic_vulkan_env_setup.md': 'Generic Vulkan Setup',
'getting_started_python.md': 'Python',
'op_coverage.md': 'XLA HLO Operation Coverage',
@@ -76,6 +78,8 @@
'getting_started_windows_bazel.md': 'GetStarted/WindowsBazel',
'getting_started_windows_cmake.md': 'GetStarted/WindowsCMake',
'getting_started_windows_vulkan.md': 'GetStarted/WindowsVulkan',
+ 'getting_started_macos_cmake.md': 'GetStarted/macOSCMake',
+ 'getting_started_macos_vulkan.md': 'GetStarted/macOSVulkan',
'generic_vulkan_env_setup.md': 'GetStarted/GenericVulkanSetup',
'getting_started_python.md': 'GetStarted/Python',
'developer_overview.md': 'DeveloperOverview',
@@ -110,8 +114,10 @@
'getting_started_windows_cmake.md': 4,
'getting_started_windows_bazel.md': 5,
'getting_started_windows_vulkan.md': 6,
- 'getting_started_python.md': 7,
- 'generic_vulkan_env_setup.md': 8,
+ 'getting_started_macos_cmake.md': 7,
+ 'getting_started_macos_bazel.md': 8,
+ 'getting_started_python.md': 9,
+ 'generic_vulkan_env_setup.md': 10,
}
# A dictionary containing source directory to section tile mappings.
