Skip to content

Commit

Permalink
Additional Docker help and split README for easier reading (onnx#1084)
Browse files Browse the repository at this point in the history 
* initial docker documentation

Signed-off-by: Alexandre Eichenberger <[email protected]>

* split README with no redundant place for info

Signed-off-by: Alexandre Eichenberger <[email protected]>

* update

Signed-off-by: Alexandre Eichenberger <[email protected]>

* update

Signed-off-by: Alexandre Eichenberger <[email protected]>

* update

Signed-off-by: Alexandre Eichenberger <[email protected]>

* update

Signed-off-by: Alexandre Eichenberger <[email protected]>

* update

Signed-off-by: Alexandre Eichenberger <[email protected]>

* respond to suggestions

Signed-off-by: Alexandre Eichenberger <[email protected]>

* specify that onnx-mlir.py script generates only code suitable to be exec in Linux and/or Docker env

Signed-off-by: Alexandre Eichenberger <[email protected]>

* fix checkdocs

Signed-off-by: Alexandre Eichenberger <[email protected]>

* responded to review suggestion on onnx-mlir --help

Signed-off-by: Alexandre Eichenberger <[email protected]>

* use ONNX-MLIR everywhere

Signed-off-by: Alexandre Eichenberger <[email protected]>
  • Loading branch information
@AlexandreEichenberger
AlexandreEichenberger authored Jan 11, 2022
1 parent 745e5b9 commit 938e3ac
Show file tree
Hide file tree
Showing 26 changed files with 512 additions and 379 deletions.
2 changes: 1 addition & 1 deletion .azure-pipelines/Windows-CI.yml
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Builds and tests ONNX MLIR
# Builds and tests ONNX-MLIR
# Downloads MLIR artifact if it exists for the current LLVM commit, otherwise builds MLIR and publishes artifact

trigger:
Expand Down
2 changes: 1 addition & 1 deletion .circleci/config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ jobs:
paths:
- llvm-project
- run:
name: Install ONNX MLIR
name: Install ONNX-MLIR
command: source onnx-mlir/utils/install-onnx-mlir.sh
- run:
name: Run End-To-End Tests
Expand Down
2 changes: 1 addition & 1 deletion CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ cmake_minimum_required(VERSION 3.13.4)

project(onnx-mlir)

option(ONNX_MLIR_BUILD_TESTS "Build ONNX MLIR test executables. If OFF, just generate build targets." ON)
option(ONNX_MLIR_BUILD_TESTS "Build ONNX-MLIR test executables. If OFF, just generate build targets." ON)
option(ONNX_MLIR_SUPPRESS_THIRD_PARTY_WARNINGS "Suppress warning in third_party code." ON)

set(CMAKE_CXX_STANDARD 14)
Expand Down
378 changes: 40 additions & 338 deletions README.md
View file

Large diffs are not rendered by default.

31 changes: 31 additions & 0 deletions docs/BuildONNX.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!--- SPDX-License-Identifier: Apache-2.0 -->

# Installing `third_party ONNX` for Backend Tests or Rebuilding ONNX Operations

Backend tests are triggered by `make check-onnx-backend` in the build directory and require a few preliminary steps to run successfully. Similarily, rebuilding the ONNX operations in ONNX-MLIR from their ONNX descriptions is triggered by `make OMONNXOpsIncTranslation`.

You will need to install python 3.x if its not default in your environment, and possibly set the cmake `PYTHON_EXECUTABLE` varialbe in your top cmake file.

You will also need `pybind11` which may need to be installed (mac: `brew install pybind11` for example) and you may need to indicate where to find the software (Mac, POWER, possibly other platforms: `export pybind11_DIR=<your path to pybind>`). Then install the `third_party/onnx` software (Mac: `pip install -e third_party/onnx`) typed in the top directory.

## Known issues

On Macs/POWER and possibly other platforms, there is currently an issue that arises when installing ONNX. If you get an error during the build, try a fix where you edit the top CMakefile as reported in this PR: `https://github.com/onnx/onnx/pull/2482/files`.

While running `make check-onnx-backend` on a Mac you might encouter the following error:

```shell
Fatal Python error: Aborted

Current thread 0x0000000107919e00 (most recent call first):
File "/usr/local/Cellar/[email protected]/3.9.7/Frameworks/Python.framework/Versions/3.9/lib/python3.9/urllib/request.py", line 2632 in getproxies_macosx_sysconf
File "/usr/local/Cellar/[email protected]/3.9.7/Frameworks/Python.framework/Versions/3.9/lib/python3.9/urllib/request.py", line 2650 in getproxies
File "/usr/local/Cellar/[email protected]/3.9.7/Frameworks/Python.framework/Versions/3.9/lib/python3.9/urllib/request.py", line 795 in __init__
...
```

A known workaround is to export the `no_proxy` environment variable in your shell as follow, and rerun the tests.

```shell
% export no_proxy="*"
```
86 changes: 86 additions & 0 deletions docs/BuildOnLinuxOSX.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
<!--- SPDX-License-Identifier: Apache-2.0 -->

# Installation of ONNX-MLIR on Linux / OSX

We provide here directions to insall ONNX-MLIR on Linux and OSX.
On Mac, there are a couple of commands that are different.
These differences will be listed in the explanation below, when relevant.

## MLIR

Firstly, install MLIR (as a part of LLVM-Project):

[same-as-file]: <> (utils/clone-mlir.sh)
``` bash
git clone https://github.com/llvm/llvm-project.git
# Check out a specific branch that is known to work with ONNX-MLIR.
cd llvm-project && git checkout 0bf230d4220660af8b2667506f8905df2f716bdf && cd ..
```

[same-as-file]: <> (utils/build-mlir.sh)
``` bash
mkdir llvm-project/build
cd llvm-project/build
cmake -G Ninja ../llvm \
-DLLVM_ENABLE_PROJECTS=mlir \
-DLLVM_TARGETS_TO_BUILD="host" \
-DCMAKE_BUILD_TYPE=Release \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DLLVM_ENABLE_RTTI=ON

cmake --build . -- ${MAKEFLAGS}
cmake --build . --target check-mlir
```

## ONNX-MLIR (this project)

### Build

The following environment variables can be set before building onnx-mlir (or alternatively, they need to be passed as CMake variables):
- `MLIR_DIR` should point to the mlir cmake module inside an llvm-project build or install directory (e.g., llvm-project/build/lib/cmake/mlir).

This project uses lit ([LLVM's Integrated Tester](http://llvm.org/docs/CommandGuide/lit.html)) for unit tests. When running CMake, we can also specify the path to the lit tool from LLVM using the LLVM_EXTERNAL_LIT define but it is not required as long as MLIR_DIR points to a build directory of llvm-project. If MLIR_DIR points to an install directory of llvm-project, LLVM_EXTERNAL_LIT is required.

To build ONNX-MLIR, use the following commands:

[same-as-file]: <> ({"ref": "utils/install-onnx-mlir.sh", "skip-doc": 2})
```bash
git clone --recursive https://github.com/onnx/onnx-mlir.git

# Export environment variables pointing to LLVM-Projects.
export MLIR_DIR=$(pwd)/llvm-project/build/lib/cmake/mlir

mkdir onnx-mlir/build && cd onnx-mlir/build
if [[ -z "$pythonLocation" ]]; then
cmake -G Ninja -DCMAKE_CXX_COMPILER=/usr/bin/c++ ..
else
cmake -G Ninja -DCMAKE_CXX_COMPILER=/usr/bin/c++ -DPython3_ROOT_DIR=$pythonLocation ..
fi
cmake --build .

# Run lit tests:
export LIT_OPTS=-v
cmake --build . --target check-onnx-lit
```

Since OSX Big Sur, add the `-DCMAKE_CXX_COMPILER=/usr/bin/c++` option to the above `cmake ..` command due to changes in default compilers.

The environment variable `$pythonLocation` may be used to specify the base directory of the Python compiler.

After the above commands succeed, an `onnx-mlir` executable should appear in the `Debug/bin` or `Release/bin` directory.

### Known MacOS Issues

There is a known issue when building onnx-mlir. If you see a error of this sorts:

``` shell
Cloning into '/home/user/onnx-mlir/build/src/Runtime/jni/jsoniter'...

[...]

make[2]: *** [src/Runtime/jni/CMakeFiles/jsoniter.dir/build.make:74: src/Runtime/jni/jsoniter/target/jsoniter-0.9.23.jar] Error 127
make[1]: *** [CMakeFiles/Makefile2:3349: src/Runtime/jni/CMakeFiles/jsoniter.dir/all] Error 2
make: *** [Makefile:146: all] Error 2.
```

The suggested workaround until jsoniter is fixed is as follows: install maven (e.g. `brew install maven`) and run `alias nproc="sysctl -n hw.logicalcpu"` in your shell.
101 changes: 101 additions & 0 deletions docs/BuildOnWindows.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
<!--- SPDX-License-Identifier: Apache-2.0 -->

# Installation of ONNX-MLIR on Windows

Building onnx-mlir on Windows requires building some additional prerequisites that are not available by default.

Note that the instructions in this file assume you are using [Visual Studio 2019 Community Edition](https://visualstudio.microsoft.com/downloads/) with ninja.
It is recommended that you have the **Desktop development with C++** and **Linux development with C++** workloads installed.
This ensures you have all toolchains and libraries needed to compile this project and its dependencies on Windows.

Run all the commands from a shell started from **"Developer Command Prompt for VS 2019"**.

## Protobuf
Build protobuf as a static library.

[same-as-file]: <> (utils/install-protobuf.cmd)
```shell
git clone --recurse-submodules https://github.com/protocolbuffers/protobuf.git
REM Check out a specific branch that is known to work with ONNX-MLIR.
REM This corresponds to the v3.11.4 tag
cd protobuf && git checkout d0bfd5221182da1a7cc280f3337b5e41a89539cf && cd ..

set root_dir=%cd%
md protobuf_build
cd protobuf_build
call cmake %root_dir%\protobuf\cmake -G "Ninja" ^
-DCMAKE_INSTALL_PREFIX="%root_dir%\protobuf_install" ^
-DCMAKE_BUILD_TYPE=Release ^
-Dprotobuf_BUILD_EXAMPLES=OFF ^
-Dprotobuf_BUILD_SHARED_LIBS=OFF ^
-Dprotobuf_BUILD_TESTS=OFF ^
-Dprotobuf_MSVC_STATIC_RUNTIME=OFF ^
-Dprotobuf_WITH_ZLIB=OFF

call cmake --build . --config Release
call cmake --build . --config Release --target install
```

Before running CMake for onnx-mlir, ensure that the bin directory to this protobuf is before any others in your PATH:
```shell
set PATH=%root_dir%\protobuf_install\bin;%PATH%
```

#### MLIR
Install MLIR (as a part of LLVM-Project):

[same-as-file]: <> (utils/clone-mlir.sh)
```shell
git clone https://github.com/llvm/llvm-project.git
# Check out a specific branch that is known to work with ONNX-MLIR.
cd llvm-project && git checkout 0bf230d4220660af8b2667506f8905df2f716bdf && cd ..
```

[same-as-file]: <> (utils/build-mlir.cmd)
```shell
set root_dir=%cd%
md llvm-project\build
cd llvm-project\build
call cmake %root_dir%\llvm-project\llvm -G "Ninja" ^
-DCMAKE_INSTALL_PREFIX="%root_dir%\llvm-project\build\install" ^
-DLLVM_ENABLE_PROJECTS=mlir ^
-DLLVM_TARGETS_TO_BUILD="host" ^
-DCMAKE_BUILD_TYPE=Release ^
-DLLVM_ENABLE_ASSERTIONS=ON ^
-DLLVM_ENABLE_RTTI=ON ^
-DLLVM_ENABLE_ZLIB=OFF ^
-DLLVM_INSTALL_UTILS=ON

call cmake --build . --config Release
call cmake --build . --config Release --target install
call cmake --build . --config Release --target check-mlir
```

## ONNX-MLIR (this project)

### Build
The following environment variables can be set before building onnx-mlir (or alternatively, they need to be passed as CMake variables):
- MLIR_DIR should point to the mlir cmake module inside an llvm-project build or install directory (e.g., c:/repos/llvm-project/build/lib/cmake/mlir).

This project uses lit ([LLVM's Integrated Tester](http://llvm.org/docs/CommandGuide/lit.html)) for unit tests. When running CMake, we can specify the path to the lit tool from LLVM using the LLVM_EXTERNAL_LIT define, as in the example below. If MLIR_DIR points to an install directory of llvm-project, LLVM_EXTERNAL_LIT is required and %lit_path% should point to a valid lit. It is not required if MLIR_DIR points to a build directory of llvm-project, which will contain lit.

To build ONNX-MLIR, use the following commands:

[same-as-file]: <> ({"ref": "utils/build-onnx-mlir.cmd", "skip-doc": 2})
```shell
git clone --recursive https://github.com/onnx/onnx-mlir.git

set root_dir=%cd%

md onnx-mlir\build
cd onnx-mlir\build
call cmake %root_dir%\onnx-mlir -G "Ninja" ^
-DCMAKE_BUILD_TYPE=Release ^
-DCMAKE_PREFIX_PATH=%root_dir%\protobuf_install ^
-DLLVM_EXTERNAL_LIT=%lit_path% ^
-DLLVM_LIT_ARGS=-v ^
-DMLIR_DIR=%root_dir%\llvm-project\build\lib\cmake\mlir

call cmake --build . --config Release --target onnx-mlir
```
After the above commands succeed, an `onnx-mlir` executable should appear in the `Debug/bin` or `Release/bin` directory.
149 changes: 149 additions & 0 deletions docs/Docker.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
<!--- SPDX-License-Identifier: Apache-2.0 -->

# Building and Developping ONNX-MLIR using Docker

## Prebuilt Containers

An easy way to get started with ONNX-MLIR is to use a prebuilt docker image.
These images are created as a result of a successful merge build on the trunk.
This means that the latest image represents the tip of the trunk.
Currently there are both Release and Debug mode images for `amd64`, `ppc64le` and `s390x` saved in Docker Hub as, respectively, [onnxmlirczar/onnx-mlir](https://hub.docker.com/r/onnxmlirczar/onnx-mlir) and [onnxmlirczar/onnx-mlir-dev](https://hub.docker.com/r/onnxmlirczar/onnx-mlir-dev).
To use one of these images either pull it directly from Docker Hub, launch a container and run an interactive bash shell in it, or use it as the base image in a dockerfile.
The onnx-mlir image just contains the built compiler and you can use it immediately to compile your model without any installation.

## Easy Script to Compile a Model

A python convenience script is provided to allow you to run ONNX-MLIR inside a docker container as if running the ONNX-MLIR compiler directly on the host.
The resulting output is an Linux ELF library implemening the ONNX model.
The `onnx-mlir.py` script is located in the [docker](../docker) directory. For example, compiling a mninst model can be done as follows.
```
# docker/onnx-mlir.py -O3 --EmitLib mnist/model.onnx
505a5a6fb7d0: Pulling fs layer
505a5a6fb7d0: Verifying Checksum
505a5a6fb7d0: Download complete
505a5a6fb7d0: Pull complete
Shared library model.so has been compiled.
```

The script will pull the onnx-mlir image if it's not available locally, mount the directory containing the `model.onnx` into the container, and compile and generate the `model.so` in the same directory.

This script takes the same option as the normal `onnx-mlir` command used to compile a ONNX model. Typical options are `-O0` (default) or `-O3` to define an optimization level and `--EmitLib` (default) or `--EmitJNI` to generate a dynamic library or a jar file.
A complete list of options is provided by using the traditional `--help` option.

This script generates codes that can be executed on a Linux system or within a Docker container.

## Building ONNX-MLIR in a docker environment

The onnx-mlir-dev image contains the full build tree including the prerequisites and a clone of the source code.
The source can be modified and `onnx-mlir` can be rebuilt from within the container, so it is possible to use it as a development environment.
New pull requests can be generated, and the repository can be updated to the latest using git commands.
It is also possible to attach vscode to the running container.
An example Dockerfile useful for development and vscode configuration files can be seen in the [docs/docker-example](docker-example) folder.
If the workspace directory and the vscode files are not present in the directory where the Docker build is run, then the lines referencing them should be commented out or deleted.

The Dockerfile is shown here, and should be modified according to one's need. The file below includes debugging tools as well as pytorch, which can be used to train the mnist model in our end-to-end example provided in the [docs/mnist_example](mnist_example) directory.

[same-as-file]: <> (docs/docker-example/Dockerfile)
```
FROM onnxmlirczar/onnx-mlir-dev
WORKDIR /workdir
ENV HOME=/workdir
# 1) Install packages.
ENV PATH=$PATH:/workdir/bin
RUN apt-get update
RUN apt-get install -y python-numpy
RUN apt-get install -y python3-pip
RUN python -m pip install --upgrade pip
RUN apt-get install -y gdb
RUN apt-get install -y lldb
# 2) Instal optional packages, comment/uncomment/add as you see fit.
RUN apt-get install -y vim
RUN apt-get install -y emacs
RUN apt-get install -y valgrind
RUN apt-get install -y libeigen3-dev
RUN apt-get install -y clang-format
RUN python -m pip install wheel
RUN python -m pip install numpy
RUN python -m pip install torch==1.6.0+cpu torchvision==0.7.0+cpu -f https://download.pytorch.org/whl/torch_stable.html
RUN git clone https://github.com/onnx/tutorials.git
# Install clang
RUN apt-get install -y lsb-release wget software-properties-common
RUN bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
# 3) When using vscode, copy your .vscode in the Dockerfile dir and
# uncomment the two lines below.
# WORKDIR /workdir/.vscode
# ADD .vscode /workdir/.vscode
# 4) When using a personal workspace folder, set your workspace sub-directory
# in the Dockerfile dir and uncomment the two lines below.
# WORKDIR /workdir/workspace
# ADD workspace /workdir/workspace
# 5) Fix git by reattaching head and making git see other branches than main.
WORKDIR /workdir/onnx-mlir
RUN git remote rename origin upstream
RUN git checkout main
RUN git fetch --unshallow
# Add optional personal fork and disable pushing to upstream (best practice).
# RUN git remote add origin https://github.com/<<GitID>>/onnx-mlir.git
# RUN git remote set-url --push upstream no_push
# 6) Set the PATH environment vars for make/debug mode. Replace Debug
# with Release in the PATH below when using Release mode.
WORKDIR /workdir
ENV MLIR_DIR=/workdir/llvm-project/build/lib/cmake/mlir
ENV NPROC=4
ENV PATH=$PATH:/workdir/onnx-mlir/build/Debug/bin/:/workdir/onnx-mlir/build/Debug/lib:/workdir/llvm-project/build/bin
```

### Developping with Docker in VSCode

The first step is to copy the [docs/ocker-example](docker-example) directory to another directory outside of the repo, say `~/DockerOnnxMlir`.

Then, the `Dockerfile` in the copied directory should then be modified to suit one's need. In particuliar, we recommend developpers to use their own fork for development. Uncomment the lines associated with git (Step 5 in the file) and substitute the appropriate GitHub Id in the commented out directives.
The lines associated with VSCode (Step 3 in the file) should be also uncommented when using VSCode.
Finally, we recommend creating a subdirectory named `workspace` that contains test examples you would like to have in your Docker Image and Container.
If so, uncomment the lines associated with copying a personal workspace folder (Step 4 in the file), and that subdirectory's contend will be copied over to the Docker Image.

The next step is to create a Docker imange. This step can be performed using the `docker build --tag imageName .` shell command. Once this command is successful, we must start a container. This can be done by a command line (e.g. `docker run -it imageName`) or by opening the Docker Dashboard, locating the Image Tab, and clicking the `run` button associated with the image just created (e.g. `imageName` above).

These steps are summarized here.
``` shell
# Starting in the onnx-mlir directory, copy the Docker example directory.
cp -prf docs/docker-example ~/DockerOnnxMlir
cd ~/DockerOnnxMlir
# Edit the Docker file.
vi Dockerfile
# Build the Docker image.
docker build --tag onnx-mlir-dev
# Start a container using the Docker dashboard or a docker run command.
```

The next step is to open VSCode, load the Docker Extension if not already present, and then open the docker tab on the left pane. Locate the container that was just started in the previous step, right click on it, and select the `Attach Visual Studio Code` option.
This will open a new VSCode window. Open a local folder on the `workdir` directory, this will give you access to all of the ONNX/MLIR/LLVM code as well as the `workspace` subdirectory.

You may then open a shell, go to the `onnx-mlir` subdirectory, and check that all of the git is properly setup.

If you opted to add your own fork, it will be listed under `origin` with `upstream` being the official ONNX-MLIR repo. For example:
``` shell
git remote -v
#origin https://github.com/AlexandreEichenberger/onnx-mlir.git (fetch)
#origin https://github.com/AlexandreEichenberger/onnx-mlir.git (push)
#upstream https://github.com/onnx/onnx-mlir.git (fetch)
#upstream no_push (push)
```

Now, you may fetch your own branches using `git fetch origin`, and switch to one of your branch (say `my-opt`) using the `git checkout --track origin/my-opt` command. The `--track` option is recommended as `upstream` was cloned and `origin` was added as remote. Once you want to push your changes, you should use `git push -u origin my-opt`, using the `-u` option to link the local branch with the `origin` remote repo.

The `main` branch will default to the upstream repo. If you prefer it to be associated with your own fork's `main` branch, you may update your main branch to the latest and associate the local main branch with `origin` using the commands listed below.
``` shell
git checkout main
git branch --unset-upstream
git push --set-upstream origin main
```

A docker container can be used to investigate a bug, or to develop a new feature. Some like to create a new images for each new version of ONNX-MLIR; others prefer to create one image and use git to update the main branch and use git to switch between multiple branches. Both are valid approaches.

Loading

0 comments on commit 938e3ac

Please sign in to comment.