From e5aa12c77515a687a0d5534bf0d206175b1052cd Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Wed, 16 Apr 2025 14:37:55 +0000 Subject: [PATCH 01/10] docs(development.md): prefers "flags" over "options" when describing cmake arguments - Some arguments may or may not be "optional", so avoiding the term "options" prevents confusion. --- docs/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index 35730628b4dd..d39f46520806 100644 --- a/docs/development.md +++ b/docs/development.md @@ -173,7 +173,7 @@ cmake -GNinja -Bbuild \ ###### [About MLIR debugging](https://mlir.llvm.org/getting_started/Debugging/) -##### Options to run end-to-end tests +##### Flags for enabling end-to-end tests To enable local end-to-end tests, append: From 6d16cf9f56c4e1d1153f4238ffd687496022e402 Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Wed, 16 Apr 2025 15:04:13 +0000 Subject: [PATCH 02/10] docs(development.md): labels optional groups of cmake flags --- docs/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index d39f46520806..16492e980be9 100644 --- a/docs/development.md +++ b/docs/development.md @@ -173,7 +173,7 @@ cmake -GNinja -Bbuild \ ###### [About MLIR debugging](https://mlir.llvm.org/getting_started/Debugging/) -##### Flags for enabling end-to-end tests +##### (Optional) Flags for enabling end-to-end tests To enable local end-to-end tests, append: From f8f9d90753f2c450a7ec4583170f07b0bd670a53 Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Wed, 16 Apr 2025 14:44:15 +0000 Subject: [PATCH 03/10] docs(development.md): makes optional flags easier to append after copy --- docs/development.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index 16492e980be9..14a22b239a51 100644 --- a/docs/development.md +++ b/docs/development.md @@ -178,8 +178,9 @@ cmake -GNinja -Bbuild \ To enable local end-to-end tests, append: ```shell + \ -DTORCH_MLIR_ENABLE_PYTORCH_EXTENSIONS=ON \ - -DTORCH_MLIR_ENABLE_JIT_IR_IMPORTER=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. From 64e4d10d8006f8b07bc5679dbd4ebf058c3224c6 Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Fri, 20 Dec 2024 21:29:28 +0000 Subject: [PATCH 04/10] docs(development.md): isolates flags for leveraging quicker builds - makes it more obvious that these apply to the "out-of-tree" path as well --- docs/development.md | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/development.md b/docs/development.md index 14a22b239a51..c1e24e9d6e57 100644 --- a/docs/development.md +++ b/docs/development.md @@ -117,18 +117,9 @@ cmake -GNinja -Bbuild \ 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` \ - -DCMAKE_LINKER_TYPE=lld + -DLLVM_EXTERNAL_TORCH_MLIR_SOURCE_DIR="$PWD" ``` -- This 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: @@ -167,12 +158,30 @@ cmake -GNinja -Bbuild \ . ``` -- 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/) +##### (Optional) Flags for leveraging quicker builds + +If you anticipate needing to frequently rebuild LLVM, append: + +```shell + \ + `# 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 +``` + +- This requires [the enablement mentioned earlier](#optional-enable-quicker-builds). +- If these flags cause issues, just skip them for now. + ##### (Optional) Flags for enabling end-to-end tests To enable local end-to-end tests, append: From 4a34b7143a66a0ec98dc15e2407d9516c6b908c4 Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Tue, 1 Apr 2025 15:31:10 +0000 Subject: [PATCH 05/10] docs(development.md): deduplicates "in-tree" CMake options --- docs/development.md | 27 ++------------------------- 1 file changed, 2 insertions(+), 25 deletions(-) diff --git a/docs/development.md b/docs/development.md index c1e24e9d6e57..939657bca118 100644 --- a/docs/development.md +++ b/docs/development.md @@ -97,32 +97,9 @@ sudo apt install clang ccache lld 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... +##### ...with LLVM "in-tree" -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" -``` - -###### ...Base Options - -If you don't anticipate needing to frequently rebuild LLVM "in-tree", run: +The following command generates 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. ```shell cmake -GNinja -Bbuild \ From dc6c5b98c44a8b41f93456a942f160e3e6e77f75 Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Tue, 15 Apr 2025 14:48:59 +0000 Subject: [PATCH 06/10] docs(development.md): moves note about "in-tree" to bottom of section --- docs/development.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/development.md b/docs/development.md index 939657bca118..f3abd5c3b509 100644 --- a/docs/development.md +++ b/docs/development.md @@ -99,8 +99,6 @@ Two setups are possible to build: in-tree and out-of-tree. The in-tree setup is ##### ...with LLVM "in-tree" -The following command generates 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. - ```shell cmake -GNinja -Bbuild \ `# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \ @@ -116,6 +114,7 @@ cmake -GNinja -Bbuild \ -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. ##### ...with LLVM "out-of-tree" From bdbc6403ba2c96eb6335e784b6b020f523d42114 Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Thu, 19 Dec 2024 22:57:26 +0000 Subject: [PATCH 07/10] docs(development.md): tweaks headers to communicate mutual exclusivity of "in-tree" vs "out-of-tree" --- docs/development.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/development.md b/docs/development.md index f3abd5c3b509..0482eedc9881 100644 --- a/docs/development.md +++ b/docs/development.md @@ -93,11 +93,11 @@ 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 -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. +##### Choose command relevant to LLVM setup: -##### ...with LLVM "in-tree" +###### If building "in-tree", run: ```shell cmake -GNinja -Bbuild \ @@ -116,9 +116,7 @@ cmake -GNinja -Bbuild \ - NOTE: uses external/llvm-project/llvm as the main build, so LLVM will be built in additional to torch-mlir and its sub-projects. -##### ...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: +###### If using "out-of-tree" build, run: ```shell cmake -GNinja -Bbuild \ From f893374d3fdc4b4e97046cf3fead5422a712dc0f Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Wed, 9 Apr 2025 14:01:04 +0000 Subject: [PATCH 08/10] docs(development.md): converts "Configure for Building" section to numbered list --- docs/development.md | 127 ++++++++++++++++++++------------------------ 1 file changed, 59 insertions(+), 68 deletions(-) diff --git a/docs/development.md b/docs/development.md index 0482eedc9881..2ca7532cf13b 100644 --- a/docs/development.md +++ b/docs/development.md @@ -95,78 +95,69 @@ sudo apt install clang ccache lld #### Configure for Building -##### Choose command relevant to LLVM setup: +1. Choose command relevant to LLVM setup: + 1. **If building "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" + ``` + + - 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: + + ```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/" + ``` + + - 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/) +1. **If you anticipate needing to frequently rebuild LLVM**, leverage quicker builds by appending: -###### If building "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" -``` - -- NOTE: uses external/llvm-project/llvm as the main build, so LLVM will be built in additional to torch-mlir and its sub-projects. - -###### If using "out-of-tree" build, 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 "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`. -- 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/) - -##### (Optional) Flags for leveraging quicker builds - -If you anticipate needing to frequently rebuild LLVM, append: - -```shell - \ - `# 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 -``` - -- This requires [the enablement mentioned earlier](#optional-enable-quicker-builds). -- If these flags cause issues, just skip them for now. - -##### (Optional) Flags for enabling end-to-end tests + ```shell + \ + `# 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 flags cause issues, just skip them for now. +1. **If you're developing changes**, enable local end-to-end tests by appending: -```shell - \ - -DTORCH_MLIR_ENABLE_PYTORCH_EXTENSIONS=ON \ - -DTORCH_MLIR_ENABLE_JIT_IR_IMPORTER=ON -``` + ```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. + - NOTE: The JIT IR importer depends on the native PyTorch extension features and defaults to `ON` if not changed. #### Initiate Build From 53fd9dbc7231071a96b8d7c88177a13a286f1e0f Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Fri, 20 Dec 2024 23:06:02 +0000 Subject: [PATCH 09/10] docs(development.md): adds reminder to activate python environment before configuring with CMake --- docs/development.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/development.md b/docs/development.md index 2ca7532cf13b..c95bede74e0b 100644 --- a/docs/development.md +++ b/docs/development.md @@ -95,6 +95,7 @@ sudo apt install clang ccache lld #### Configure for Building +1. [Activate the Python environment](#set-up-the-python-environment) 1. Choose command relevant to LLVM setup: 1. **If building "in-tree"**, run: From 9e7c38819364f6538be2b9d4c6383dd997b302c7 Mon Sep 17 00:00:00 2001 From: Jacob Gordon Date: Tue, 28 Jan 2025 20:21:29 +0000 Subject: [PATCH 10/10] docs(development.md): adds explicit step to run cmake config command after choosing flags --- docs/development.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/development.md b/docs/development.md index c95bede74e0b..9dad71c14fd7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -97,7 +97,7 @@ sudo apt install clang ccache lld 1. [Activate the Python environment](#set-up-the-python-environment) 1. Choose command relevant to LLVM setup: - 1. **If building "in-tree"**, run: + 1. **If building "in-tree"**, run/append: ```shell cmake -GNinja -Bbuild \ @@ -115,7 +115,7 @@ sudo apt install clang ccache lld ``` - 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: + 1. **If using "out-of-tree" build**, run/append: ```shell cmake -GNinja -Bbuild \ @@ -159,6 +159,7 @@ sudo apt install clang ccache lld ``` - 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 flags pertaining to your workflow) #### Initiate Build