[docs] Refreshes development.md #3932

bjacobgordon · 2024-12-23T23:15:48Z

tweak confusing portions
update stale instructions
fix typos
restructure to be more linear/sequential
found while going through Turbine Camp

bjacobgordon · 2024-12-23T23:16:47Z

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!

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

stellaraccident · 2024-12-24T00:06:51Z

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.

docs/development.md

bjacobgordon · 2025-01-28T20:33:57Z

Okay, @marbre, I think we're almost there! How's it look now?

marbre

Just a quick review, traveling, but leaving a few comments.

marbre · 2025-01-30T14:10:23Z

docs/development.md


-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.
+    - Some older pip installs may not be able to handle the recent PyTorch deps


Suggested change

- Some older pip installs may not be able to handle the recent PyTorch deps

Some older pip installs may not be able to handle the recent PyTorch deps

I don't see the need for a bullet point here. Same at some places below.

This phrase was originally a comment in the block above the shell command, very subtle. How do we communicate "you can gloss over this line"? Maybe prepending "NOTE:" instead of having the bullet point?

marbre · 2025-01-30T14:12:14Z

docs/development.md

+          -DPython3_FIND_VIRTUALENV=ONLY \
+          -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
+          -DLLVM_TARGETS_TO_BUILD=host \
+          \


Suggested change

\

The additional line looks odd to me.

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?

marbre · 2025-01-30T14:13:36Z

docs/development.md

-cmake --build build --target check-torch-mlir
+        ```shell
+        cmake -GNinja -Bbuild \
+          `# Enables "--debug" and "--debug-only" flags for the "torch-mlir-opt" tool` \


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

marbre · 2025-01-30T14:14:05Z

docs/development.md

+          -DPython3_FIND_VIRTUALENV=ONLY \
+          -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
+          -DLLVM_TARGETS_TO_BUILD=host \
+          \


Suggested change

\

docs/development.md

marbre · 2025-01-30T14:15:30Z

docs/development.md

+1. **If you anticipate needing to frequently rebuild LLVM**, append:
+
+    ```shell
+      \


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?

marbre · 2025-01-30T14:16:15Z

docs/development.md

+1. **If you need to enable local end-to-end tests**, append:
+
+    ```shell
+      \


Suggested change

\

docs/development.md

bjacobgordon · 2025-02-24T14:53:35Z

Stacked onto #4048

…ails - Makes the "in-tree" and "out-of-tree" variants adjacent to each other

…y of "in-tree" vs "out-of-tree"

…plified Build" section

- emphasizes the common options between "in-tree extended", "in-of-tree base", and "out-of-tree"

…uild using base options

- tweaks existing headers to communicate command construction rather than immediate execution - adds new header to indicate when the command should actually be executed

- was repeated 3 times!

…rst subheader

…tion

… section

- the use-case for this doc leans more toward "development" rather than "release"

- leverages numbering and indentation to reduce cognitive load

…ions

…fore configuring with CMake

CMake issued a warning upon fresh build: > Manually-specified variables were not used by the project: > LIBTORCH_CACHE > LIBTORCH_SRC_BUILD > LIBTORCH_VARIANT

…re building

… to numbered list

…arate code blocks - makes them individually copyable from GitHub

… Build" - makes it so that the GitHub copy button only grabs the code snippet itself

…er "Initiate Build" section

- less repetitive - emphasizes that the targets can be chained

bjacobgordon · 2025-03-07T14:55:50Z

Stacked onto #4081

bjacobgordon marked this pull request as draft December 23, 2024 23:16

bjacobgordon force-pushed the docs-refreshes-development-md branch from bd16189 to 0927acd Compare January 2, 2025 14:48

marbre self-requested a review January 2, 2025 18:12

bjacobgordon marked this pull request as ready for review January 3, 2025 18:08

bjacobgordon changed the title ~~Refreshes docs/development.md~~ [docs] Refreshes development.md Jan 3, 2025

bjacobgordon force-pushed the docs-refreshes-development-md branch 4 times, most recently from 304b07f to a7275ff Compare January 13, 2025 15:21

bjacobgordon force-pushed the docs-refreshes-development-md branch 2 times, most recently from 05ea09d to 7f23d36 Compare January 20, 2025 14:47

marbre reviewed Jan 20, 2025

View reviewed changes

docs/development.md Outdated Show resolved Hide resolved

docs/development.md Outdated Show resolved Hide resolved

docs/development.md Outdated Show resolved Hide resolved

docs/development.md Outdated Show resolved Hide resolved

docs/development.md Outdated Show resolved Hide resolved

bjacobgordon force-pushed the docs-refreshes-development-md branch from 7f23d36 to d4b0153 Compare January 21, 2025 17:47

marbre reviewed Jan 21, 2025

View reviewed changes

docs/development.md Outdated Show resolved Hide resolved

marbre reviewed Jan 21, 2025

View reviewed changes

docs/development.md Outdated Show resolved Hide resolved

ScottTodd reviewed Jan 21, 2025

View reviewed changes

docs/development.md Outdated Show resolved Hide resolved

docs/development.md Outdated Show resolved Hide resolved

docs/development.md Outdated Show resolved Hide resolved

docs/development.md Outdated Show resolved Hide resolved

bjacobgordon force-pushed the docs-refreshes-development-md branch 3 times, most recently from 2daa32c to ef8e61b Compare January 28, 2025 20:29

bjacobgordon requested a review from marbre January 28, 2025 20:33

marbre reviewed Jan 30, 2025

View reviewed changes

bjacobgordon force-pushed the docs-refreshes-development-md branch from ef8e61b to 7825aa4 Compare January 30, 2025 21:56

bjacobgordon force-pushed the docs-refreshes-development-md branch from 7825aa4 to 3d6994c Compare February 10, 2025 15:43

bjacobgordon force-pushed the docs-refreshes-development-md branch from 3d6994c to 62b5045 Compare February 24, 2025 14:43

bjacobgordon mentioned this pull request Feb 24, 2025

[docs] clarify headers in development.md #4048

Merged

bjacobgordon force-pushed the docs-refreshes-development-md branch from 62b5045 to 1fd9140 Compare February 25, 2025 15:13

bjacobgordon mentioned this pull request Mar 4, 2025

[docs] Add "Enable Quicker Builds" section to development.md #4074

Merged

bjacobgordon force-pushed the docs-refreshes-development-md branch from 12a2a81 to ca99afb Compare March 5, 2025 14:44

bjacobgordon added 25 commits March 7, 2025 14:50

docs(development.md): moves optional command addendums after LLVM det…

3df144f

…ails - Makes the "in-tree" and "out-of-tree" variants adjacent to each other

docs(development.md): tweaks headers to communicate mutual exclusivit…

9da0ec0

…y of "in-tree" vs "out-of-tree"

docs(development.md): adds missing DLLVM_ENABLE_ASSERTIONS under "Sim…

93abcad

…plified Build" section

docs(development.md): rearranges cmake configuration options

e04bdc0

- emphasizes the common options between "in-tree extended", "in-of-tree base", and "out-of-tree"

docs(development.md): clarifies rationale for configuring "in-tree" b…

5002543

…uild using base options

docs(development.md): moves "base options" to be first "in-tree" command

f020a57

docs(development.md): clarifies "configure" headers

a24d47b

- tweaks existing headers to communicate command construction rather than immediate execution - adds new header to indicate when the command should actually be executed

docs(development.md): extracts common CMake options into first subheader

7fa51cc

- was repeated 3 times!

docs(development.md): extracts common "in-tree" CMake options into fi…

993dc9f

…rst subheader

docs(development.md): extracts build optimization options into h5 header

e769344

docs(development.md): simplifies section about CMake options for LLVM

6fb7e5f

docs(development.md): moves notes to bottom of build optimization sec…

0e8584a

…tion

docs(development.md): moves notes to bottom of CMake end-to-end tests…

cae34b5

… section

docs(development.md): updates DCMAKE_BUILD_TYPE to "RelWithDebInfo"

9b582d6

- the use-case for this doc leans more toward "development" rather than "release"

docs(development.md): converts headers under CMake to numbered list

a036e37

- leverages numbering and indentation to reduce cognitive load

docs(development.md): combines common options with mandatory LLVM opt…

94cfac4

…ions

docs(development.md): adds reminder to activate python environment be…

c5996f4

…fore configuring with CMake

docs(development.md): removes unused libtorch variables

7727257

CMake issued a warning upon fresh build: > Manually-specified variables were not used by the project: > LIBTORCH_CACHE > LIBTORCH_SRC_BUILD > LIBTORCH_VARIANT

docs(development.md): enunciates CMake configuration is required befo…

5ec3bf5

…re building

docs(development.md): converts details under "Initiate Build" section…

dc8dd0f

… to numbered list

docs(development.md): splits commands under "Initiate Build" into sep…

647227b

…arate code blocks - makes them individually copyable from GitHub

docs(development.md): extracts comments from commands under "Initiate…

7318410

… Build" - makes it so that the GitHub copy button only grabs the code snippet itself

docs(development.md): moves vanilla build command to first bullet und…

d607f54

…er "Initiate Build" section

docs(development.md): restructures the "Initiate Build" section

398db4f

- less repetitive - emphasizes that the targets can be chained

docs(development.md): simplifies options for specifying linker

84d17b6

bjacobgordon force-pushed the docs-refreshes-development-md branch from ca99afb to 84d17b6 Compare March 7, 2025 14:50

bjacobgordon mentioned this pull request Mar 7, 2025

[docs] Move extra cmake command options in development.md #4081

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Refreshes development.md #3932

[docs] Refreshes development.md #3932

bjacobgordon commented Dec 23, 2024 •

edited

Loading

bjacobgordon commented Dec 23, 2024 •

edited

Loading

stellaraccident commented Dec 24, 2024

marbre left a comment

bjacobgordon commented Jan 28, 2025

marbre left a comment

marbre Jan 30, 2025

bjacobgordon Jan 30, 2025 •

edited

Loading

marbre Jan 30, 2025

bjacobgordon Jan 30, 2025 •

edited

Loading

marbre Jan 30, 2025

bjacobgordon Jan 30, 2025

marbre Jan 30, 2025

marbre Jan 30, 2025

bjacobgordon Jan 30, 2025

marbre Jan 30, 2025

bjacobgordon commented Feb 24, 2025

bjacobgordon commented Mar 7, 2025


		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.
		- Some older pip installs may not be able to handle the recent PyTorch deps

	- Some older pip installs may not be able to handle the recent PyTorch deps
	Some older pip installs may not be able to handle the recent PyTorch deps

[docs] Refreshes development.md #3932

Are you sure you want to change the base?

[docs] Refreshes development.md #3932

Conversation

bjacobgordon commented Dec 23, 2024 • edited Loading

bjacobgordon commented Dec 23, 2024 • edited Loading

Context

Approach

stellaraccident commented Dec 24, 2024

marbre left a comment

Choose a reason for hiding this comment

bjacobgordon commented Jan 28, 2025

marbre left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bjacobgordon Jan 30, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bjacobgordon Jan 30, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bjacobgordon commented Feb 24, 2025

bjacobgordon commented Mar 7, 2025

bjacobgordon commented Dec 23, 2024 •

edited

Loading

bjacobgordon commented Dec 23, 2024 •

edited

Loading

bjacobgordon Jan 30, 2025 •

edited

Loading

bjacobgordon Jan 30, 2025 •

edited

Loading