Skip to content

Commit 83f7de1

Browse files
bjacobgordonbjacobgordon
authored
[docs]: Make steps under "Configure for Building" easier to see (#4175)
- prefer numbered list over nesting of headers
1 parent 1682ce2 commit 83f7de1

File tree

1 file changed

+59
-72
lines changed

1 file changed

+59
-72
lines changed

‎docs/development.md

Lines changed: 59 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -95,82 +95,69 @@ sudo apt install clang ccache lld
9595

9696
#### Configure for Building
9797

98-
##### Choose command relevant to LLVM setup:
98+
1. Choose command relevant to LLVM setup:
99+
1. **If you want the more straightforward option**, run the "in-tree" setup:
100+
101+
```shell
102+
cmake -GNinja -Bbuild \
103+
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
104+
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
105+
-DLLVM_ENABLE_ASSERTIONS=ON \
106+
-DPython3_FIND_VIRTUALENV=ONLY \
107+
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
108+
-DLLVM_TARGETS_TO_BUILD=host \
109+
`# For building LLVM "in-tree"` \
110+
externals/llvm-project/llvm \
111+
-DLLVM_ENABLE_PROJECTS=mlir \
112+
-DLLVM_EXTERNAL_PROJECTS="torch-mlir" \
113+
-DLLVM_EXTERNAL_TORCH_MLIR_SOURCE_DIR="$PWD"
114+
```
115+
116+
- NOTE: uses external/llvm-project/llvm as the main build, so LLVM will be built in addition to torch-mlir and its sub-projects.
117+
1. **If you want to use a separate build of LLVM from another directory**, run the "out-of-tree" setup:
118+
119+
```shell
120+
cmake -GNinja -Bbuild \
121+
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
122+
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
123+
-DLLVM_ENABLE_ASSERTIONS=ON \
124+
-DPython3_FIND_VIRTUALENV=ONLY \
125+
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
126+
-DLLVM_TARGETS_TO_BUILD=host \
127+
`# For building LLVM "out-of-tree"` \
128+
-DMLIR_DIR="$LLVM_INSTALL_DIR/lib/cmake/mlir/" \
129+
-DLLVM_DIR="$LLVM_INSTALL_DIR/lib/cmake/llvm/"
130+
```
131+
132+
- Be sure to have built LLVM with `-DLLVM_ENABLE_PROJECTS=mlir`.
133+
- Be aware that the installed version of LLVM needs in general to match the committed version in `externals/llvm-project`. Using a different version may or may not work.
134+
135+
- [About MLIR debugging](https://mlir.llvm.org/getting_started/Debugging/)
136+
1. **If you anticipate needing to frequently rebuild LLVM**, leverage quicker builds by appending:
99137

100-
###### If you want the more straightforward option
101-
102-
Run the "in-tree" setup:
103-
104-
```shell
105-
cmake -GNinja -Bbuild \
106-
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
107-
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
108-
-DLLVM_ENABLE_ASSERTIONS=ON \
109-
-DPython3_FIND_VIRTUALENV=ONLY \
110-
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
111-
-DLLVM_TARGETS_TO_BUILD=host \
112-
`# For building LLVM "in-tree"` \
113-
externals/llvm-project/llvm \
114-
-DLLVM_ENABLE_PROJECTS=mlir \
115-
-DLLVM_EXTERNAL_PROJECTS="torch-mlir" \
116-
-DLLVM_EXTERNAL_TORCH_MLIR_SOURCE_DIR="$PWD"
117-
```
118-
119-
- NOTE: uses external/llvm-project/llvm as the main build, so LLVM will be built in addition to torch-mlir and its sub-projects.
120-
121-
###### If you want to use a separate build of LLVM from another directory
122-
123-
Run the "out-of-tree" setup:
124-
125-
```shell
126-
cmake -GNinja -Bbuild \
127-
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
128-
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
129-
-DLLVM_ENABLE_ASSERTIONS=ON \
130-
-DPython3_FIND_VIRTUALENV=ONLY \
131-
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
132-
-DLLVM_TARGETS_TO_BUILD=host \
133-
`# For building LLVM "out-of-tree"` \
134-
-DMLIR_DIR="$LLVM_INSTALL_DIR/lib/cmake/mlir/" \
135-
-DLLVM_DIR="$LLVM_INSTALL_DIR/lib/cmake/llvm/"
136-
.
137-
```
138-
139-
- Be sure to have built LLVM with `-DLLVM_ENABLE_PROJECTS=mlir`.
140-
- Be aware that the installed version of LLVM needs in general to match the committed version in `externals/llvm-project`. Using a different version may or may not work.
141-
142-
###### [About MLIR debugging](https://mlir.llvm.org/getting_started/Debugging/)
143-
144-
##### (Optional) Flags for leveraging quicker builds
145-
146-
If you anticipate needing to frequently rebuild LLVM, append:
147-
148-
```shell
149-
\
150-
`# use clang`\
151-
-DCMAKE_C_COMPILER=clang \
152-
-DCMAKE_CXX_COMPILER=clang++ \
153-
`# use ccache to cache build results` \
154-
-DCMAKE_C_COMPILER_LAUNCHER=ccache \
155-
-DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
156-
`# use LLD to link in seconds, rather than minutes` \
157-
-DCMAKE_LINKER_TYPE=lld
158-
```
159-
160-
- This requires [the enablement mentioned earlier](#optional-enable-quicker-builds).
161-
- If these flags cause issues, just skip them for now.
162-
163-
##### (Optional) Flags for enabling end-to-end tests
138+
```shell
139+
\
140+
`# use clang`\
141+
-DCMAKE_C_COMPILER=clang \
142+
-DCMAKE_CXX_COMPILER=clang++ \
143+
`# use ccache to cache build results` \
144+
-DCMAKE_C_COMPILER_LAUNCHER=ccache \
145+
-DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
146+
`# use LLD to link in seconds, rather than minutes` \
147+
-DCMAKE_LINKER_TYPE=lld
148+
```
164149

165-
To enable local end-to-end tests, append:
150+
- This requires [the enablement mentioned earlier](#optional-enable-quicker-builds).
151+
- If these flags cause issues, just skip them for now.
152+
1. **If you're developing changes**, enable local end-to-end tests by appending:
166153
167-
```shell
168-
\
169-
-DTORCH_MLIR_ENABLE_PYTORCH_EXTENSIONS=ON \
170-
-DTORCH_MLIR_ENABLE_JIT_IR_IMPORTER=ON
171-
```
154+
```shell
155+
\
156+
-DTORCH_MLIR_ENABLE_PYTORCH_EXTENSIONS=ON \
157+
-DTORCH_MLIR_ENABLE_JIT_IR_IMPORTER=ON
158+
```
172159
173-
- NOTE: The JIT IR importer depends on the native PyTorch extension features and defaults to `ON` if not changed.
160+
- NOTE: The JIT IR importer depends on the native PyTorch extension features and defaults to `ON` if not changed.
174161
175162
#### Initiate Build
176163

0 commit comments

Comments
 (0)