[docs] Refreshes development.md

[bjacobgordon]

First PR, super stoked! 🥳

Context

As part of Turbine Camp, I was referred to this doc to build Torch-MLIR on my Linux VM. It has a lot of potential, and I decided to nudge it in a productive direction a bunch of times as I read and used the doc.

Approach

I tried to make the commits here "atomic", i.e. each one is a singular unit of work such that the file "works better"/"makes more sense" post-commit than pre-commit.

The majority of the commits in this PR is the story of how I "refactored" the doc step by step to look the way it does. I wrote them with Future Us™ in mind! Each commit should have useful information of the changes made that IDEs like VSCode should be able to surface, so please don't squash haha.

Ready when you are, @marbre!

[bjacobgordon]

@marbre The only thing I'm unsure about is removing the libtorch flags

[stellaraccident]

Thanks! Marius/Jacob, please review and land as you see fit. I'll have a closer look when I'm back and can contribute any adjustments then.

[marbre]

Thanks for working through the documentation. I certainly understand that this needs improvement and should be restructured in some way. However, I am not sure if that is the structure we should aim for. Maybe we should split out some things, like the formatting, and land this separately. Next we could iterate on the docs, maybe in smaller chunks, before restructuring to much at once. Just thinking loud and other approaches have their benefits as well.

[marbre]

This "runs" and does not "appends" as there is no \ at the last line. I still find the append / run a little confusing. Maybe having multiple blocks that "just work" is easier, even if it adds redundancy. I could image that @zjgarvey or @ScottTodd might have an opinion on this.

[ScottTodd]

A page like https://llvm.org/docs/CMake.html may be useful to study and replicate, for consistency within LLVM.

• Start with the minimal command
• Call out frequently used variables
• List all other variables

In the IREE docs we have some recommended recipes at https://iree.dev/building-from-source/getting-started/. If the list of options gets longer and continues to branch based on usage style, I'd recommend looking at CMake presets or toolchain files.

[bjacobgordon]

@marbre Yeah, one caveat is that it assumes you're going to use the code block copy button provided by GitHub! If you use that, it works great. You copy-paste, copy-paste, copy-paste all the parts you need and then run at the end.

@ScottTodd I definitely think some kind of preset would be super useful here! Will search on my end, but do you have any links handy?

[ScottTodd]

Presets:

• https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
• https://github.com/iree-org/iree/tree/main/build_tools/cmake/presets

Toolchain files can look similar (collections of settings in a file) but are load bearing for cross compilation:

• https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html
• https://github.com/iree-org/iree/blob/main/build_tools/cmake/riscv.toolchain.cmake

[bjacobgordon]

@ScottTodd Would this allow us to build a macro to specify stuff like

• llvm in-tree: yes/no
• frequent rebuilds: yes/no
• enable tests: yes/no
  such that it'll just use the relevant options given the flags?

[ScottTodd]

Sorta. Presets are a bit clunky when you get that far into the weeds though. They are good for high level switches that are mutually exclusive with one another.

[bjacobgordon]

@marbre 3 flags with 2 states each yields 8 separate combinations, meaning 8 separate (but closely related) code blocks. Because of this, I'm hesitant to go the "premade" route over the "composition" route. Maybe we could word it in a way that more effectively communicates how clusters of cmake options should be "tacked on"?

@ScottTodd Or maybe we just make a shell script for it until someone else has a chance to come along and make a decent preset for it?

[marbre]

That is just one reason why I think the previous structure wasn't too bad. A rather complete command + a simplified one. All other options described separately and if you need those, you'd need to adjust your configuration command. In contrast the patch forces users to always copy paste multiple blocks to get a working configuration.

[ScottTodd]

A page like https://llvm.org/docs/CMake.html may be useful to study and replicate, for consistency within LLVM.

• Start with the minimal command
• Call out frequently used variables
• List all other variables

In the IREE docs we have some recommended recipes at https://iree.dev/building-from-source/getting-started/. If the list of options gets longer and continues to branch based on usage style, I'd recommend looking at CMake presets or toolchain files.

[ScottTodd]

Echoing some of the other comments about individual code blocks and appending, here I would spell out of the full command for easier copy/paste

Suggested change

	1. **If you want to...**
	- **...build _just_ torch-mlir (not all of LLVM)**, append:
	```shell
	--target tools/torch-mlir/all
	```
	1. **If you want to...**
	- **...build _just_ torch-mlir (not all of LLVM)**:
	```shell
	cmake --build build --target tools/torch-mlir/all
	```

same with the other examples

[bjacobgordon]

I had tried that initially, but it didn't really convey that you could add all three targets, one on top of the other.

If I wanna run unit tests and regression tests, I can copy-paste to get:
cmake --build build --target check-torch-mlir --target check-torch-mlir-python

From there, I can recall from command line history as much as I need!

But having them in separate blocks required me to click-drag-copy-paste.

What cmake wizardry do you recommend?

[ScottTodd]

What cmake wizardry do you recommend?

For any high productivity setup (and not just validating that some set of options works or casually testing a project), I configure Visual Studio Code. My examples here are for IREE, but they should also apply for other projects like torch-mlir.

• JSON workspace/settings files let you track all of your options, toggling lines commented out as you want to flip between sets

  // iree.code-workspace
  {
      "folders": [
  	    {
  		    "path": ".."
  	    }
      ],
      "settings": {
  	    "cmake.automaticReconfigure": false,
  	    "cmake.buildDirectory": "${workspaceFolder}/../iree-build",
  	    "cmake.configureArgs": [
  		    "-DIREE_BUILD_PYTHON_BINDINGS=OFF",
  		    // "-DIREE_BUILD_PYTHON_BINDINGS=ON",
  		    "-DPython3_EXECUTABLE=${workspaceFolder}/.venv/bin/python",
  		    //
  		    "-DIREE_HAL_DRIVER_CUDA=ON",
  		    "-DIREE_HAL_DRIVER_HIP=ON",
  		    "-DIREE_HAL_DRIVER_LOCAL_SYNC=ON",
  		    "-DIREE_HAL_DRIVER_LOCAL_TASK=ON",
  		    "-DIREE_HAL_DRIVER_METAL=OFF",
  		    "-DIREE_HAL_DRIVER_NULL=ON",
  		    "-DIREE_HAL_DRIVER_VULKAN=ON",
  		    //
  		    "-DIREE_TARGET_BACKEND_VMVX=ON",
  		    "-DIREE_TARGET_BACKEND_LLVM_CPU=ON",
  		    "-DIREE_TARGET_BACKEND_LLVM_CPU_WASM=ON",
  		    "-DIREE_TARGET_BACKEND_METAL_SPIRV=ON",
  		    "-DIREE_TARGET_BACKEND_VULKAN_SPIRV=ON",
  		    "-DIREE_TARGET_BACKEND_ROCM=ON",
  		    "-DIREE_TARGET_BACKEND_CUDA=ON",
  		    //
  		    "-DIREE_HIP_TEST_TARGET_CHIP=gfx1100",
  		    //
  		    // ccache: https://ccache.dev/
  		    "-DCMAKE_C_COMPILER_LAUNCHER=ccache",
  		    "-DCMAKE_CXX_COMPILER_LAUNCHER=ccache",
  		    //
  		    "-DIREE_ENABLE_LLD=ON",
  	    ],
  	    "cmakeExplorer.buildDir": "${workspaceFolder}/../iree-build",
  	    "cmakeExplorer.suiteDelimiter": "/",
  	    "cmakeExplorer.extraCtestRunArgs": "--verbose",
      }
  }

• GUI lets you select which target, including meta targets like all, to build
  

• Test explorer lets you choose which tests to run, including all tests under a given package/namespace
  

[bjacobgordon]

@ScottTodd That looks great!

The development.md doc doesn't really specify anything for IDE config, probably because it's a "nice to have". Is that the direction we wanna go? Or are we just wanting to get new contributors going with the "need to have" items?