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] Restructure CMake configuration section in development.md #3932

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

[docs] Restructure CMake configuration section in development.md #3932

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
94a36c2
docs(development.md): removes unused libtorch options for cmake config
bjacobgordon Apr 9, 2025
0a0a33c
docs(development.md): updates cmake options for specifying linker
bjacobgordon Apr 9, 2025
8a7d0cc
docs(development.md): moves "base options" to be first "in-tree" command
bjacobgordon Apr 1, 2025
9caefb2
docs(development.md): tweaks headers to communicate mutual exclusivit…
bjacobgordon Dec 19, 2024
da43d0a
docs(development.md): clarifies "configure" headers
bjacobgordon Dec 20, 2024
a588652
docs(development.md): extracts common CMake options into first subheader
bjacobgordon Dec 20, 2024
767ad5b
docs(development.md): extracts common "in-tree" CMake options into fi…
bjacobgordon Dec 20, 2024
48d372a
docs(development.md): extracts build optimization options into h5 header
bjacobgordon Dec 20, 2024
7ef1621
docs(development.md): simplifies section about CMake options for LLVM
bjacobgordon Dec 20, 2024
aedfa1a
docs(development.md): converts headers under CMake to numbered list
bjacobgordon Apr 9, 2025
893ca6e
docs(development.md): combines common options with mandatory LLVM opt…
bjacobgordon Jan 28, 2025
1855168
docs(development.md): adds reminder to activate python environment be…
bjacobgordon Dec 20, 2024
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
158 changes: 63 additions & 95 deletions docs/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,105 +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

If you do anticipate needing to frequently rebuild LLVM "in-tree", run:

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

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

###### ...Base Options

If you don't anticipate needing to frequently rebuild LLVM "in-tree", run:

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

###### [About MLIR debugging](https://mlir.llvm.org/getting_started/Debugging/)

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

?

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

To enable local end-to-end tests, append:
- 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:

```shell
-DTORCH_MLIR_ENABLE_PYTORCH_EXTENSIONS=ON \
-DTORCH_MLIR_ENABLE_JIT_IR_IMPORTER=ON \
```
```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
```

- NOTE: The JIT IR importer depends on the native PyTorch extension features and defaults to `ON` if not changed.
- 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