docs: add macOS development guide for issue #1465#1564
docs: add macOS development guide for issue #1465#1564AAdIprog wants to merge 1 commit intokmesh-net:mainfrom
Conversation
|
@AAdIprog: The label(s) DetailsIn response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Welcome @AAdIprog! It looks like this is your first PR to kmesh-net/kmesh 🎉 |
Summary of ChangesHello @AAdIprog, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a detailed macOS Developer Guide for Kmesh, addressing the inherent challenge of Kmesh's dependency on Linux kernel's eBPF/BPF features. The guide provides clear recommendations for setting up a suitable development environment, primarily focusing on virtualization with UTM and Ubuntu, or dual-booting Ubuntu for optimal performance. It also clarifies the scope of development possible directly on macOS and offers cloud-based alternatives, ensuring macOS users can effectively contribute to Kmesh. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Mac's sleek, but BPF Needs Linux, strong and true, to Make Kmesh truly fly. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a comprehensive macOS developer guide, which is a great addition for developers on that platform. The guide is well-structured and covers various setup options. I've found a few incorrect commands and some confusing instructions in the documentation that could prevent users from successfully setting up their environment. My review includes suggestions to correct these issues.
| golangci-lint run | ||
|
|
||
| # Generate documentation | ||
| make gen-docs |
There was a problem hiding this comment.
The command make gen-docs is incorrect as this target does not exist in the project's Makefile. The correct target for generating documentation appears to be gen-kmeshctl-doc. Please update the command to ensure users can successfully generate the documentation.
| make gen-docs | |
| make gen-kmeshctl-doc |
| # Install virtiofs support | ||
| sudo apt install -y virtiofsd |
There was a problem hiding this comment.
The command sudo apt install -y virtiofsd is incorrect for the guest VM. virtiofsd is a daemon that runs on the host, which UTM manages. The guest VM only needs to mount the shared filesystem. On recent Ubuntu versions with a modern kernel, the necessary virtiofs module should be included, and no extra packages are needed. This installation step is unnecessary and should be removed.
|
|
||
| # Run Kmesh BPF tests | ||
| cd kmesh | ||
| make test-bpf |
There was a problem hiding this comment.
The command make test-bpf is incorrect as the test-bpf target does not exist in the Makefile. Based on the Makefile and helper scripts, the correct target for running BPF unit tests is ebpf_unit_test.
| make test-bpf | |
| make ebpf_unit_test |
| ```bash | ||
| # For UTM with VirtioFS | ||
| sudo apt install -y spice-vdagent spice-webdavd | ||
|
|
||
| # Restart the VM after installation | ||
| ``` |
There was a problem hiding this comment.
The troubleshooting advice for shared folders is confusing. It suggests installing SPICE guest tools (spice-vdagent, spice-webdavd), but the setup guide in "Step 7: Shared Folders (Optional)" describes using VirtioFS. These are two different methods for folder sharing. To avoid confusion, this section should provide troubleshooting steps relevant to VirtioFS, not SPICE. For example, it could mention checking dmesg for virtio_fs errors or verifying mount options.
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation to help macOS developers set up a proper development environment for Kmesh, which requires Linux kernel eBPF/BPF features that are not available on macOS.
Changes:
- Added a new macOS Developer Guide with multiple virtualization options and their tradeoffs
- Documented known limitations of Lima and Docker Desktop for BPF development
- Provided step-by-step setup instructions for UTM with Ubuntu VM and dual-boot configurations
- Included troubleshooting guidance and development workflow tips
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Install Go (check https://go.dev/dl/ for latest version) | ||
| wget https://go.dev/dl/go1.21.5.linux-arm64.tar.gz # For ARM64 | ||
| # OR | ||
| wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz # For AMD64 | ||
|
|
||
| sudo rm -rf /usr/local/go | ||
| sudo tar -C /usr/local -xzf go1.21.*.tar.gz |
There was a problem hiding this comment.
The Go version specified (1.21.5) may be outdated. Consider either referencing a more recent version or using a version variable that can be easily updated. The comment on line 163 mentions checking the official Go downloads page, but having a more recent version here would be helpful for users who follow the instructions directly.
| # Install Go (check https://go.dev/dl/ for latest version) | |
| wget https://go.dev/dl/go1.21.5.linux-arm64.tar.gz # For ARM64 | |
| # OR | |
| wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz # For AMD64 | |
| sudo rm -rf /usr/local/go | |
| sudo tar -C /usr/local -xzf go1.21.*.tar.gz | |
| # Install Go (set GO_VERSION based on https://go.dev/dl/) | |
| GO_VERSION=1.22.5 # Replace with the latest stable version if different | |
| wget https://go.dev/dl/go${GO_VERSION}.linux-arm64.tar.gz # For ARM64 | |
| # OR | |
| wget https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz # For AMD64 | |
| sudo rm -rf /usr/local/go | |
| sudo tar -C /usr/local -xzf go${GO_VERSION}.linux-*.tar.gz |
AAdIprog
force-pushed
the
docs/macos-development-guide-1465
branch
from
f722043 to
f5f4797
Compare
Signed-off-by: AAdIprog <aadishah132@gmail.com>
AAdIprog
force-pushed
the
docs/macos-development-guide-1465
branch
from
f5f4797 to
af109c2
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| mount | grep bpf | ||
|
|
||
| # If not mounted, mount it | ||
| sudo mount -t bpf bpf /sys/fs/bpf |
There was a problem hiding this comment.
The mount command is incorrect. Based on the project's codebase (build/docker/start_kmesh.sh and test/e2e/run_test.sh), the correct command should be 'mount -t bpf none /sys/fs/bpf', not 'mount -t bpf bpf /sys/fs/bpf'. The device argument should be 'none', not 'bpf'.
| sudo mount -t bpf bpf /sys/fs/bpf | |
| sudo mount -t bpf none /sys/fs/bpf |
|
|
||
| # Add Go to PATH | ||
| echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc | ||
| echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc |
There was a problem hiding this comment.
Using single quotes prevents shell variable expansion. The command 'echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc' will literally write the string '$(go env GOPATH)' to .bashrc without expanding it. Either use double quotes for the echo command or use a separate command to evaluate and export GOPATH.
| echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc | |
| echo "export PATH=\$PATH:$(go env GOPATH)/bin" >> ~/.bashrc |
LiZhenCheng9527
left a comment
LiZhenCheng9527
left a comment
There was a problem hiding this comment.
Have you actually run Kmesh on macOS? Or this guide may well have been generated by AI?
| | **Lima** | ❌ Limited | Good | Easy | ❌ No | | ||
| | **Docker Desktop** | ❌ None | Good | Easy | ❌ No | | ||
|
|
||
| ## ⚠️ Known Limitations |
There was a problem hiding this comment.
Is better to me if you can delete unnecessary emoji.
| cd kmesh | ||
|
|
||
| # Run non-BPF unit tests (some tests will be skipped) | ||
| go test ./pkg/... -v -short |
There was a problem hiding this comment.
Some unit tests under the pkg directory require BPF.
| sudo apt install -y build-essential git curl wget | ||
|
|
||
| # Install Go (check https://go.dev/dl/ for latest version) | ||
| wget https://go.dev/dl/go1.21.5.linux-arm64.tar.gz # For ARM64 |
There was a problem hiding this comment.
why go 1.21.5? Kmesh use go 1.24.2.
What type of PR is this?
/kind documentation
What this PR does / why we need it:
This PR adds a comprehensive macOS Developer Guide for Kmesh. Since Kmesh relies heavily on eBPF/BPF features that require a Linux kernel, macOS developers need guidance on setting up a proper development environment.
The guide covers:
Which issue(s) this PR fixes:
Fixes #1465
Special notes for your reviewer:
This guide is based on practical experience setting up Kmesh development on macOS. Key highlights:
Does this PR introduce a user-facing change?: