Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Refreshes development.md #3932

Draft
wants to merge 15 commits into
base: main
Choose a base branch
from
Draft

[docs] Refreshes development.md #3932

Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
4f280a5
docs(development.md): moves notes to bottom of build optimization sec…
bjacobgordon Dec 20, 2024
356226d
docs(development.md): clarifies deciding factor between "in-tree" opt…
bjacobgordon Dec 19, 2024
b802ca3
docs(development.md): moves "base options" to be first "in-tree" command
bjacobgordon Apr 1, 2025
a38a4b0
docs(development.md): tweaks headers to communicate mutual exclusivit…
bjacobgordon Dec 19, 2024
4794876
docs(development.md): clarifies "configure" headers
bjacobgordon Dec 20, 2024
dfb2d2e
docs(development.md): extracts common CMake options into first subheader
bjacobgordon Dec 20, 2024
a540075
docs(development.md): extracts common "in-tree" CMake options into fi…
bjacobgordon Dec 20, 2024
63d67b2
docs(development.md): extracts build optimization options into h5 header
bjacobgordon Dec 20, 2024
4be0503
docs(development.md): simplifies section about CMake options for LLVM
bjacobgordon Dec 20, 2024
b1ea9d8
docs(development.md): moves notes to bottom of CMake end-to-end tests…
bjacobgordon Dec 20, 2024
f41690d
docs(development.md): converts headers under CMake to numbered list
bjacobgordon Dec 20, 2024
d972ebe
docs(development.md): combines common options with mandatory LLVM opt…
bjacobgordon Jan 28, 2025
0c7910d
docs(development.md): adds reminder to activate python environment be…
bjacobgordon Dec 20, 2024
9b99c62
docs(development.md): removes unused libtorch variables
bjacobgordon Dec 17, 2024
0fa9618
docs(development.md): simplifies options for specifying linker
bjacobgordon Jan 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 63 additions & 89 deletions docs/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,99 +93,73 @@ sudo apt install clang ccache lld
1. Set up Developer PowerShell [for Visual Studio](https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022#start-in-visual-studio)
1. Ensure that the compiler and linker binaries are in the `PATH` variable.

#### Configure for Building...
#### Configure for Building

1. [Activate the Python environment](#set-up-the-python-environment)
1. Choose command with relevant LLVM options:
1. **If building "in-tree"**, run/append:

```shell
cmake -GNinja -Bbuild \
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm guessing this is not what you had in mind haha. I'll need a little more direction here, which parts seem odd?

-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DPython3_FIND_VIRTUALENV=ONLY \
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
-DLLVM_TARGETS_TO_BUILD=host \
\
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
\

The additional line looks odd to me.

Copy link
Contributor Author

@bjacobgordon bjacobgordon Jan 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. Wanting to somehow communicate at-a-glance "this chunk of options is the key difference between the two otherwise-identical code blocks". What's another way we could do that?

`# For building LLVM "in-tree"` \
externals/llvm-project/llvm \
-DLLVM_ENABLE_PROJECTS=mlir \
-DLLVM_EXTERNAL_PROJECTS="torch-mlir" \
-DLLVM_EXTERNAL_TORCH_MLIR_SOURCE_DIR="$PWD"
```

- NOTE: uses external/llvm-project/llvm as the main build, so LLVM will be built in additional to torch-mlir and its sub-projects.
1. **If using "out-of-tree" build**, run/append:

```shell
cmake -GNinja -Bbuild \
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DPython3_FIND_VIRTUALENV=ONLY \
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
-DLLVM_TARGETS_TO_BUILD=host \
\
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
\

`# For building LLVM "out-of-tree"` \
-DMLIR_DIR="$LLVM_INSTALL_DIR/lib/cmake/mlir/" \
-DLLVM_DIR="$LLVM_INSTALL_DIR/lib/cmake/llvm/"
```

- Be sure to have built LLVM with `-DLLVM_ENABLE_PROJECTS=mlir`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would rephrase to, make enable building MLIR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couldn't remember at first, but it looks like all I did was move it to a different spot haha. It's worded the same way it was on main.

Could we save rephrasing this for a subsequent PR?

- 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.

- [About MLIR debugging](https://mlir.llvm.org/getting_started/Debugging/)
1. **If you anticipate needing to frequently rebuild LLVM**, append:

Two setups are possible to build: in-tree and out-of-tree. The in-tree setup is the most straightforward, as it will build LLVM dependencies as well.

##### ...with LLVM "in-tree" using...

The following commands generate configuration files to build the project *in-tree*, that is, using llvm/llvm-project as the main build. This will build LLVM as well as torch-mlir and its subprojects.

###### ...Base + Optimization Options
This will build `libtorch` / `PyTorch` wheels from source and requires [the enablement mentioned earlier](#optional-enable-quicker-builds). If you encounter issues when you run this, try the [simplified build command](#base-options) instead.

```shell
cmake -GNinja -Bbuild \
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DPython3_FIND_VIRTUALENV=ONLY \
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
-DLLVM_TARGETS_TO_BUILD=host \
`# For building LLVM "in-tree"` \
externals/llvm-project/llvm \
-DLLVM_ENABLE_PROJECTS=mlir \
-DLLVM_EXTERNAL_PROJECTS="torch-mlir" \
-DLLVM_EXTERNAL_TORCH_MLIR_SOURCE_DIR="$PWD" \
`# use clang`\
-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
`# use ccache to cache build results` \
-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
`# use LLD to link in seconds, rather than minutes` \
`# if using clang <= 13, replace --ld-path=ld.lld with -fuse-ld=lld` \
-DCMAKE_EXE_LINKER_FLAGS_INIT="--ld-path=ld.lld" \
-DCMAKE_MODULE_LINKER_FLAGS_INIT="--ld-path=ld.lld" \
-DCMAKE_SHARED_LINKER_FLAGS_INIT="--ld-path=ld.lld" \
`# Enabling libtorch binary cache instead of downloading the latest libtorch everytime.` \
`# Testing against a mismatched version of libtorch may cause failures` \
-DLIBTORCH_CACHE=ON \
`# Enable an experimental path to build libtorch (and PyTorch wheels) from source,` \
`# instead of downloading them` \
-DLIBTORCH_SRC_BUILD=ON \
`# Set the variant of libtorch to build / link against. (shared|static and optionally cxxabi11)` \
-DLIBTORCH_VARIANT=shared
```

###### ...Base Options

If you're running into issues with the above build command, consider using the following:

```shell
cmake -GNinja -Bbuild \
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DPython3_FIND_VIRTUALENV=ONLY \
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
-DLLVM_TARGETS_TO_BUILD=host \
`# For building LLVM "in-tree"` \
externals/llvm-project/llvm \
-DLLVM_ENABLE_PROJECTS=mlir \
-DLLVM_EXTERNAL_PROJECTS="torch-mlir" \
-DLLVM_EXTERNAL_TORCH_MLIR_SOURCE_DIR="$PWD"
```


##### ...with LLVM "out-of-tree"

If you have built llvm-project separately in the directory `$LLVM_INSTALL_DIR`, you can also build the project *out-of-tree* using the following command as template:
```shell
cmake -GNinja -Bbuild \
`# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DPython3_FIND_VIRTUALENV=ONLY \
-DMLIR_ENABLE_BINDINGS_PYTHON=ON \
-DLLVM_TARGETS_TO_BUILD=host \
`# For building LLVM "out-of-tree"` \
-DMLIR_DIR="$LLVM_INSTALL_DIR/lib/cmake/mlir/" \
-DLLVM_DIR="$LLVM_INSTALL_DIR/lib/cmake/llvm/"
.
```
The same QoL CMake flags can be used to enable clang, ccache, and lld. Be sure to have built LLVM with `-DLLVM_ENABLE_PROJECTS=mlir`.

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.
```shell
\
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is what you had meant, right? All you need to get going is copying, pasting and running one of the "base" commands. Tacking this on before running is optional, right?

`# use clang`\
-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
`# use ccache to cache build results` \
-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
`# use LLD to link in seconds, rather than minutes` \
-DCMAKE_LINKER_TYPE=lld
```

###### [About MLIR debugging](https://mlir.llvm.org/getting_started/Debugging/)
- This requires [the enablement mentioned earlier](#optional-enable-quicker-builds).
- If these options cause issues, just skip them for now.
1. **If you need to enable local end-to-end tests**, append:

##### Options to run end-to-end tests
```shell
\
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
\

-DTORCH_MLIR_ENABLE_PYTORCH_EXTENSIONS=ON \
-DTORCH_MLIR_ENABLE_JIT_IR_IMPORTER=ON
```

Running the end-to-end execution tests locally requires enabling the native PyTorch extension features and the JIT IR importer, which depends on the
former and defaults to `ON` if not changed:
```shell
-DTORCH_MLIR_ENABLE_PYTORCH_EXTENSIONS=ON \
-DTORCH_MLIR_ENABLE_JIT_IR_IMPORTER=ON \
```
- NOTE: The JIT IR importer depends on the native PyTorch extension features and defaults to `ON` if not changed.
1. Run assembled command (once you've appended the options pertaining to your workflow)

#### Initiate Build

Expand Down
Loading