Slice up the development environment setup by mcrosson · Pull Request #437 · zmkfirmware/zmk

mcrosson · 2020-11-27T23:50:28Z

Give a brief overview of docker+vscode vs native os
Dedicated page for docker+vscode setup
Dedicated page for native os setup
Dedicated page for setting up zmk sources for development

docs/docs/development/setup/setup.md

docs/docs/development/setup/zmk.md

docs/docs/development/setup/setup.md

docs/docs/development/setup/zmk.md

mcrosson · 2020-11-30T01:21:25Z

Updated and pushed new rev based on feedback

joelspadin

See also the unresolved comments from my earlier review, but this revision does seem easier to follow.

docs/docs/development/setup/docker-vscode.md

docs/docs/development/setup/setup.md

docs/docs/development/setup/zmk.md

docs/docs/development/setup/setup.md

mcrosson · 2020-12-02T14:18:16Z

Updated and pushed per feedback.

Will squash as last step before merge

innovaker · 2020-12-11T14:13:10Z

@mcrosson, I think this PR needs a health check?

mcrosson · 2020-12-11T16:15:56Z

@mcrosson, I think this PR needs a health check?

Health check?

okke-formsma · 2021-01-30T20:42:21Z

@mcrosson Would you mind rebasing again? I'd like to merge some of these old docs PRs.

mcrosson · 2021-01-30T20:44:48Z

@mcrosson Would you mind rebasing again? I'd like to merge some of these old docs PRs.

I can but I'd prefer the others be merged ahead of this as this update will likely cause a ton of other conflits with other doc updates.

Would that work?

okke-formsma · 2021-01-30T21:13:23Z

Sure. Is there a way to keep track of what PR are blocking other PRs in github?

mcrosson · 2021-01-30T21:25:05Z

Sure. Is there a way to keep track of what PR are blocking other PRs in github?

I'm not sure offhand. There is a box towards that says "Linked issues" but i can't make changes

If nothing else we can reference the others from this one and just keep tabs on things for a bit

mcrosson · 2021-03-01T05:11:47Z

bump?

anyone willing to review this if i fixup the conflicts

we are getting more folks interested in windows + vscode + docker and i think this set of updates will be helpful for folks

idan · 2021-03-01T05:55:32Z

@mcrosson I'm happy to!

idan

This looks fantastic! I did a scan for language and offered some suggested improvements, going to check this PR out and see how the docs look like built

idan · 2021-03-01T06:22:54Z

docs/docs/development/setup/docker-vscode.md

+---
+
+:::danger
+The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU.


Probably worth calling out apple silicon here as well

Suggested change

The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU.

The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU.

idan · 2021-03-01T06:26:29Z

docs/docs/development/setup/docker-vscode.md

+:::
+
+:::note Windows Users
+Please note the zmk builds can run slower with Docker on Windows if you don't use the WSL2 filesystem to store files. Build times can take 3-5 minutes on slower hardware without using the WSL2 filesystem. If you run into performance problems you can checkout the zmk sources inside a WSL2 environment and use `code .` inside the WSL2 environment to open the sources. This can make builds run as fast as 20s.


If the path of least resistance is installing Docker for Windows and letting that work the WSL2 magic behind the scenes, maybe we ought to recommend the happiest path upfront. Can also link to a section at the end that talks about the finer points of WSL and IO perf.

I think we can leave this note but move it after the setup steps.

@innovaker was the one driving this add initially and I don't think it detracts from the rest of the information on the page.

idan · 2021-03-01T06:27:31Z

docs/docs/development/setup/getting-started.md

+
+## Environment Setup
+
+There are two ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially.


Suggested change

There are two ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially.

There are two ways to setup the zmk development environment: Docker+VS Code (`Docker` in the rest of the documentation) and using the operating system directly (`native` in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially.

idan · 2021-03-01T06:27:59Z

docs/docs/development/setup/getting-started.md

+Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup.
+
+:::danger
+The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU.


Suggested change

The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU.

The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU.

idan · 2021-03-01T06:28:13Z

docs/docs/development/setup/getting-started.md

+sudo apt update
+```
+
+These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows).


Suggested change

These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows).

These commands should be run in a terminal such as Bash (Linux/MacOS/Docker), PowerShell, or Command Prompt (Windows).

idan · 2021-03-01T06:31:45Z

docs/docs/development/setup/zmk.md

+![VS Code Dev Container Configuration Alert](../../assets/dev-setup/vscode_devcontainer.png)
+
+Click `Reopen in Container` in order to reopen the VS Code with the running container.
+


Also cmd-shift-p and invoking Remote: Show Remote Menu displays the remotes menu

- Give a brief overview of docker+vscode vs native os - Dedicated page for docker+vscode setup - Dedicated page for native os setup - Dedicated page for setting up zmk sources for development

…ns. Expand some notes and caution boxes so some pitfalls and ways to improve performance are more clear to users

mcrosson · 2021-03-02T19:25:05Z

@idan TY for the suggestions, i've added them except for the last item with the screen shots. I'm not sure what you were suggesting in that last item and left it off. Would you be willing to provide some additional clarity?

mcrosson · 2021-03-04T01:58:20Z

bump? i'd like to get this in before some of the other churn for the docs pops up...

idan · 2021-03-05T23:32:12Z

Apologies — yeah the screenshots were just referencing the two ways of getting at it, didn't mean them for inclusion.

@mcrosson If you're okay with the content, I'd say and we can always add screenshots there later

mcrosson · 2021-03-06T00:30:59Z

Apologies — yeah the screenshots were just referencing the two ways of getting at it, didn't mean them for inclusion.

@mcrosson If you're okay with the content, I'd say and we can always add screenshots there later

i'm 100% good with content but i can't merge. That's gotta be @okke-formsma / @petejohanson / @innovaker / @Nicell

Nicell

A few more suggestions, but I'd like to get this in soon. Doesn't need to be perfect. I think we need to consider if anywhere links to the old "Basic Setup" URL. We could probably set up a Netlify redirect for that.

Nicell · 2021-03-06T01:53:31Z

docs/docs/development/setup/getting-started.md

+
+## Environment Setup
+
+There are two ways to setup the zmk development environment: Docker+VS Code (`Docker` in the rest of the documentation) and using the operating system directly (`native` in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially.


Suggested change

There are two ways to setup the zmk development environment: Docker+VS Code (`Docker` in the rest of the documentation) and using the operating system directly (`native` in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially.

There are two ways to setup the ZMK development environment: Docker+VS Code (`Docker` in the rest of the documentation) and using the operating system directly (`native` in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially.

Nicell · 2021-03-06T01:55:35Z

docs/docs/development/setup/getting-started.md

+:::danger
+The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU.


Suggested change

:::danger

The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU.

:::caution

The Docker environment will **NOT** run on ARM CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an ARM CPU.

Nicell · 2021-03-06T01:58:18Z

docs/docs/development/setup/docker-vscode.md

+The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU.
+:::
+
+This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use.


This action is deprecated now. Our actions now just use this docker image as the base image, so I think this first sentence isn't necessary or could be reworded to something like This setup leverages the same [Docker image used when building ZMK on GitHub](https://github.com/zmkfirmware/zmk-docker/). Also not quite sure how the dev/prod parity stuff fits into this discussion.

It's there to be clear that the container used for local dev is the same as used by the github build system.

Basically a signal that if you want to be guaranteed what you do locally (dev) is the same as on the upstream build stuff (prod) you should be using the docker container for builds.

This should stand IMO for folks (like me) who want to use the same environment locally as is used by the build system to ensure there aren't surprises.

Nicell · 2021-03-06T02:05:12Z

docs/docs/development/setup/docker-vscode.md

+3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+:::note Windows Users
+Please note the zmk builds can run slower with Docker on Windows if you don't use the WSL2 filesystem to store files. Build times can take 3-5 minutes on slower hardware without using the WSL2 filesystem. If you run into performance problems you can checkout the zmk sources inside a WSL2 environment and use `code .` inside the WSL2 environment to open the sources. This can make builds run as fast as 20s.


Suggested change

Please note the zmk builds can run slower with Docker on Windows if you don't use the WSL2 filesystem to store files. Build times can take 3-5 minutes on slower hardware without using the WSL2 filesystem. If you run into performance problems you can checkout the zmk sources inside a WSL2 environment and use `code .` inside the WSL2 environment to open the sources. This can make builds run as fast as 20s.

Please note the ZMK builds run slower (up to 3-5 minutes on slower hardware) with Docker on Windows if you don't use the WSL2 filesystem to store files. If you run into performance problems you can checkout the ZMK sources inside a WSL2 environment and run `code .` to open the sources. This can make builds run at near-native speed.

mcrosson · 2021-03-06T20:48:42Z

@Nicell incorporated your suggestions, i think this should be good to go?

mcrosson · 2021-03-10T18:54:37Z

bump @petejohanson / @Nicell

Nicell · 2021-03-10T19:02:59Z

@mcrosson I'm good with these changes, but I still want to make sure we don't have any broken URLs. Could we add a redirect from development/setup to development/setup/getting-started? Netlify uses a _redirects file for this, or maybe @petejohanson has a suggestion since he has dashboard access.

mcrosson · 2021-03-10T19:08:58Z

@mcrosson I'm good with these changes, but I still want to make sure we don't have any broken URLs. Could we add a redirect from development/setup to development/setup/getting-started? Netlify uses a _redirects file for this, or maybe @petejohanson has a suggestion since he has dashboard access.

I don't see a redirects file in the sources...

@petejohanson probably has to be involved at this point

Nicell · 2021-03-10T19:17:42Z

I don't see a redirects file in the sources...

You can add a _redirects file to the /docs/static/ folder. See here: https://docs.netlify.com/routing/redirects/#rule-processing-order

mcrosson · 2021-03-10T23:14:51Z

Added the _redirects file based on the docs ; i hope its right 🤞

mcrosson · 2021-03-18T06:22:16Z

bump @petejohanson

nmunnich · 2024-06-02T08:31:33Z

This pull request can now be closed as it was subsumed by #2272 which is now merged.

joelspadin reviewed Nov 28, 2020

View reviewed changes

innovaker added documentation Improvements or additions to documentation enhancement New feature or request labels Nov 28, 2020

joelspadin requested changes Dec 1, 2020

View reviewed changes

joelspadin reviewed Dec 1, 2020

View reviewed changes

docs/docs/development/setup/setup.md Outdated Show resolved Hide resolved

innovaker requested a review from Nicell January 5, 2021 20:26

idan reviewed Mar 1, 2021

View reviewed changes

KemoNine added 5 commits March 2, 2021 19:06

Slice up the development environment setup some included changes:

fa39132

- Give a brief overview of docker+vscode vs native os - Dedicated page for docker+vscode setup - Dedicated page for native os setup - Dedicated page for setting up zmk sources for development

Fixup broken URLs based on CI feedback

23dad0a

Cleanup documentation to read easier and have more readable conventio…

dbf4e05

…ns. Expand some notes and caution boxes so some pitfalls and ways to improve performance are more clear to users

Additional updates and tuning per PR feedback

4f6a2a6

docs(setup): misc updates for verbiage from @idan

d32cccd

mcrosson mentioned this pull request Mar 4, 2021

Update Basic Setup information #715

Closed

Nicell reviewed Mar 6, 2021

View reviewed changes

docs(cleanup): minor tweaks based on @Nicell feedback

776a6be

mcrosson requested a review from Nicell March 6, 2021 20:48

docs(misc): add redirects to prevent broken links

ff4d628

mcrosson closed this Mar 10, 2021

mcrosson reopened this Mar 10, 2021

Nicell approved these changes Mar 11, 2021

View reviewed changes

nmunnich mentioned this pull request May 12, 2024

feat(docs): Improve the toolchain setup page #2272

Merged

caksoylar closed this Jun 2, 2024

	The Docker environment will NOT run on arm CPUs like the Raspberry Pi. You must use the native environment if using an arm CPU.
	The Docker environment will NOT run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU.


		## Environment Setup

		There are two ways to setup the zmk development environment: Docker+VS Code (Docker in the rest of the documentation) and using the operating system directly (native in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially.

	These commands should be run in a terminal such as Bash (Linux/macOS/Docker), PowerShell, or Command Prompt (Windows).
	These commands should be run in a terminal such as Bash (Linux/MacOS/Docker), PowerShell, or Command Prompt (Windows).

		![VS Code Dev Container Configuration Alert](../../assets/dev-setup/vscode_devcontainer.png)

		Click `Reopen in Container` in order to reopen the VS Code with the running container.

		:::danger
		The Docker environment will NOT run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU.

Uh oh!

Conversation

mcrosson commented Nov 27, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcrosson commented Nov 30, 2020

Uh oh!

joelspadin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcrosson commented Dec 2, 2020

Uh oh!

innovaker commented Dec 11, 2020

Uh oh!

mcrosson commented Dec 11, 2020

Uh oh!

okke-formsma commented Jan 30, 2021

Uh oh!

mcrosson commented Jan 30, 2021

Uh oh!

okke-formsma commented Jan 30, 2021

Uh oh!

mcrosson commented Jan 30, 2021

Uh oh!

mcrosson commented Mar 1, 2021

Uh oh!

idan commented Mar 1, 2021

Uh oh!

idan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcrosson commented Mar 2, 2021

Uh oh!

mcrosson commented Mar 4, 2021

Uh oh!

idan commented Mar 5, 2021

Uh oh!

mcrosson commented Mar 6, 2021

Uh oh!

Nicell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!